README.md

```
╔══════════════════════════════════════════════════════════════════════════════╗
║                                                                              ║
║   ⬡  S U M M O N                                                            ║
║                                                                              ║
║   ▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓                                ║
║   Build your own weights. Name your own model.                               ║
║   Sovereign fine-tuning framework · pip install summon                       ║
║   ▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓▓                                ║
║                                                                              ║
║   ⬡ Ω ↺ Ψ Δ Λ Σ Φ α  — WORM SEALED AT EVERY STEP                          ║
║                                                                              ║
╚══════════════════════════════════════════════════════════════════════════════╝
```

Summon is a pip-installable Python framework for building sovereign fine-tuned language models. It wraps HuggingFace PEFT + TRL + bitsandbytes into a single fluent chain: `Summon.begin("YourModel")` → `.base()` → `.corpus()` → `.constitutional()` → `.license()` → `.train()` → `.push()`. The API is designed in the functional / immutable style — every method returns a new `SovereignModel` instance; nothing mutates in place. The `Corpus` builder is equally composable: stack named layers from JSONL files or raw string lists, then `.seal()` to freeze them. A SHA-256 WORM chain runs through every step of both pipelines, producing a verifiable manifest of exactly what data, what base, and what constitution went into your weights. Training is QLoRA (4-bit NF4 quantization via bitsandbytes, `r=16 lora_alpha=32`, target modules `q_proj/v_proj/k_proj/o_proj`) using HuggingFace `SFTTrainer`. Supported base models include Nemotron Mini 4B, Llama 3 8B/70B, Mistral 7B, Phi-3 Mini, Qwen2 7B, Gemma2 9B, and Falcon 7B — or pass any HuggingFace ID directly.

## Architecture

```mermaid
flowchart LR
    subgraph Corpus Builder
        C0([Corpus.layer 0\ngenesis.jsonl])
        C1([Corpus.layer 1\nenochian.jsonl])
        C2([Corpus.layer N\n...])
        CS([.seal\nWORM hash])
        C0 --> C1 --> C2 --> CS
    end

    subgraph SovereignModel Chain
        M0([Summon.begin\nname]) --> M1
        M1([.base\nnominate HF model]) --> M2
        M2([.corpus\nlayers / Corpus obj]) --> M3
        M3([.constitutional\nprinciples list]) --> M4
        M4([.license\nsovereign-source-v1]) --> M5
        M5([.train\nQLoRA 4-bit]) --> M6
        M6([.push\nHuggingFace Hub])
    end

    CS -->|corpus_obj| M2

    subgraph Trainer
        T0[Load base model\nBitsAndBytesConfig NF4]
        T1[Apply LoraConfig\nr=16 alpha=32]
        T2[SFTTrainer\nepochs · batch · lr]
        T3[save_model\nwrite model card]
        T0 --> T1 --> T2 --> T3
    end

    M5 --> Trainer

    subgraph WORM Chain
        W0[GENESIS] --> W1[BASE seal]
        W1 --> W2[CORPUS seal]
        W2 --> W3[CONSTITUTION seal]
        W3 --> W4[LICENSE seal]
        W4 --> W5[TRAIN seal]
        W5 --> W6[PUSH seal]
    end

    M1 -.->|SHA-256| W1
    M2 -.->|SHA-256| W2
    M3 -.->|SHA-256| W3
    M4 -.->|SHA-256| W4
    M5 -.->|SHA-256| W5
    M6 -.->|SHA-256| W6
```

## File Tree

```
summon/
├── summon/
│   ├── __init__.py             # Summon class — .begin() and .corpus() entry points
│   ├── identity/
│   │   ├── __init__.py
│   │   └── model.py            # SovereignModel — fluent chain (.base/.corpus/.constitutional/.license/.train/.push/.manifest)
│   ├── corpus/
│   │   ├── __init__.py
│   │   └── builder.py          # Corpus — layered JSONL builder (.layer/.layer_raw/.seal/.export/.summary)
│   └── train/
│       ├── __init__.py
│       └── runner.py           # Trainer — QLoRA fine-tuning (validate/run/_write_model_card)
├── examples/
│   └── build_my_model.py       # Three usage patterns: full pipeline, corpus-first, dry run
├── setup.py                    # pip packaging (extras: [train] and [hub])
└── README.md
```

## Quick Start

```bash
# Install (core — no GPU deps)
pip install summon

# Install with training deps
pip install "summon[train]"          # torch, transformers, peft, trl, datasets, bitsandbytes, accelerate

# Install with HuggingFace Hub push support
pip install "summon[train,hub]"
```

**Full pipeline:**

```python
from summon import Summon

model = (
    Summon.begin("AhmadMeta-v1")
    .base("nemotron-mini-4b")           # or full HF ID: "nvidia/Minitron-4B-Base"
    .corpus(layers=[
        "data/the_book.jsonl",
        "data/enoch.jsonl",
        "data/circle7.jsonl",
    ])
    .constitutional(["truth", "sovereignty", "evidence", "no_deception"])
    .license("sovereign-source-v1")
    .train(device="cuda", epochs=3, batch_size=4, learning_rate=2e-4)
    .push("my-org/AhmadMeta-v1")
)

model.manifest()    # print WORM-sealed manifest, optionally write to file
```

**Corpus builder separately:**

```python
from summon import Summon

corpus = (
    Summon.corpus()
    .layer(0, "data/genesis.jsonl",   name="genesis")
    .layer(1, "data/enoch.jsonl",     name="enochian")
    .layer_raw(2, ["raw text line 1", "raw text line 2"], name="inline")
    .seal()
)

model = (
    Summon.begin("JessicaLM-v1")
    .base("llama3-8b")
    .corpus(corpus_obj=corpus)       # pass the sealed Corpus object
    .constitutional(["truth", "care", "sovereignty"])
    .license("apache-2.0")
    .train(device="cuda", epochs=5)
    .push("jessica-org/JessicaLM-v1")
)
```

**Dry run (validate config, no GPU):**

```python
model = (
    Summon.begin("TestModel-v1")
    .base("phi3-mini")
    .corpus(layers=["data/sample.jsonl"])
    .constitutional(["truth"])
    .train(dry_run=True)    # validates, does not launch training
)
```

## Key Features

- **Single fluent chain** — `Summon.begin("name").base().corpus().constitutional().license().train().push()` — the entire pipeline in one expression
- **Functional / immutable API** — every method returns a new `SovereignModel` instance; state never mutates; safe to branch at any point
- **Layered Corpus builder** — stack named JSONL layers with `.layer()` (from file) or `.layer_raw()` (from string list); `.seal()` freezes and WORM-stamps the corpus; `.export()` merges all layers to a single JSONL for training
- **QLoRA fine-tuning** — 4-bit NF4 quantization via bitsandbytes, LoRA rank 16, alpha 32, targets `q_proj/v_proj/k_proj/o_proj`, `SFTTrainer` with gradient accumulation and fp16; auto-writes a HuggingFace model card with WORM seal
- **Constitutional principles** — `.constitutional(["truth","sovereignty","evidence"])` bakes your principles into the model manifest and model card; shapes RLHF/preference data generation
- **Eight supported base models** — Nemotron Mini 4B, Llama 3 8B/70B, Mistral 7B, Phi-3 Mini, Qwen2 7B, Gemma2 9B, Falcon 7B — or pass any HuggingFace model ID directly
- **WORM chain on every step** — SHA-256 hash chain from `GENESIS` through `BASE → CORPUS → CONSTITUTION → LICENSE → TRAIN → PUSH`; final hash in `.manifest()` proves exact provenance
- **`.manifest()` output** — prints and optionally writes a JSON document with name, base, corpus layers, constitution, license, output path, WORM head hash, and creation timestamp
- **HuggingFace Hub push** — `.push("org/model")` calls `HfApi().upload_folder()` with optional `private=True`; warns if `.train()` was not called first

---

*Apache 2.0 · SnapKitty Collective 2026 · Evidence or Silence*