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*