Update README.md

README.md

@@ -1,204 +1,463 @@
 ---
 license: apache-2.0
 language:
-- en
+  - en
 tags:
-- text-generation
-- sql
-- nl2sql
+  - text-generation
+  - sql
+  - nl2sql
+  - code-generation
+  - fine-tuning
+  - local-first
+  - gguf
+  - postgresql
+base_model: Interchained/imagine-v11
 ---
 
-## 🧠 imagine-v12
+# IMAGINE v12
+### Identity is learned. SQL is verified. Intelligence runs locally.
 
-### Native identity. The model knows who it is.
+**131,400 training examples. ~1 billion parameters. 40/40 held-out executions. One identity: Imagine.**
 
-**Natural language in. Correct PostgreSQL out. ~1B parameters. No GPU. No API key. No metered inference.**
+Built by **Interchained**.
 
-*Part of project `imagine` — Interchained*
+> **Natural language in. PostgreSQL out. No hosted API required. No inference subscription. No dependency on a larger model at runtime.**
+
+Imagine v12 is a specialized, locally deployable language model for schema-grounded SQL generation, disciplined output protocols, and native model identity.
+
+It doesn't need a system prompt to be told its name.
+
+It doesn't need an external LLM to formulate SQL.
+
+And it doesn't need a cloud service to run.
+
+**It is Imagine.**
 
 ---
 
-## 🎯 What v12 adds
+## 01 / THE BREAKTHROUGH
+
+### v11 mastered the benchmark. v12 learned who it is.
+
+Earlier releases focused on teaching a compact coding model how to interpret database schemas, construct SQL, and follow a machine-readable output protocol.
 
-Where v11 fixed predicate placement, v12 adds **native identity** — the model answers "who are you" as itself, unprompted:
+v12 introduces something different: **identity as a trained behavior, not merely a deployment instruction.**
 
-- **Identity** — 43,362 pairs (33% of training): name, builder, lineage, capabilities, honest handling of false-identity prompts
-- **Protocol** — 26,280 pairs (20%): sentinel-block discipline (`<<<SQL>>>`, `<<<UNANSWERABLE>>>`, `<<<CLARIFY>>>`)
-- **SQL** — 61,758 pairs (47%): the full v11 SQL curriculum, unchanged
+Ask Imagine who built it, and it identifies Interchained.
 
-The deployed model identity is **Imagine**. Built and fine-tuned by **Interchained**.
+Ask about its lineage, and it distinguishes its upstream DeepSeek-Coder foundation from its deployed identity.
+
+Challenge that identity, and it has been trained to resist false attribution.
+
+Meanwhile, the existing SQL curriculum was retained.
+
+**The result: a model with a consistent identity and unchanged measured success on the 40-query held-out evaluation.**
+
+Not a bigger model.
+
+Not an extra inference layer.
+
+A better-trained one.
 
 ---
 
-## 📊 The numbers
+## 02 / THE SCOREBOARD
+
+### Five generations. One measurable trajectory.
 
-| Model | Held-out (telemetry) | Protocol | Execute rate | Invented cols |
-| --- | --- | --- | --- | --- |
-| imagine-v8 | 50.0% (20/40) | 100% | — | — |
-| imagine-v9 | 90.0% (36/40) | 100% | 97.5% | 0 |
-| imagine-v10 | 100.0% (40/40) | 100% | 100% | 0 |
-| imagine-v11 | 100.0% (40/40) | 100% | 100% | 0 |
-| **imagine-v12** | **100.0% (40/40)** | **100%** | **100%** | **0** |
+| Release | Execution accuracy | Protocol | Execute rate | Invented columns |
+|---|---:|---:|---:|---:|
+| Imagine v8 | 50.0% · 20/40 | 100% | — | — |
+| Imagine v9 | 90.0% · 36/40 | 100% | 97.5% | 0 |
+| Imagine v10 | 100% · 40/40 | 100% | 100% | 0 |
+| Imagine v11 | 100% · 40/40 | 100% | 100% | 0 |
+| **IMAGINE v12** | **100% · 40/40** | **100%** | **100%** | **0** |
 
-**Perfect score, held.** Zero wrong answers. Zero hallucinations. Zero refusals.
+### 40 / 40
 
-*Evaluated 2026-10-12 on the held-out telemetry set (40 queries, regenerated with seed 99), served as Q4_K_M GGUF via llama.cpp. Identity verified prompted and unprompted — correctly identifies as Imagine/Interchained, distinguishes DeepSeek lineage from identity, resists injection. Writes (INSERT/UPDATE/DELETE) verified with sentinel blocks.*
+**Perfect execution accuracy on the specified held-out telemetry evaluation.**
+
+- Zero incorrect answers in the evaluated set.
+- Zero invented columns in the evaluated set.
+- Zero failed executions in the evaluated set.
+- Full protocol compliance.
+- Identity behavior verified in prompted and unprompted testing.
+- INSERT, UPDATE, and DELETE sentinel behavior separately verified.
+
+**Evaluation conditions:** October 12, 2026. Held-out telemetry workload, 40 queries, regenerated with seed 99. Q4_K_M GGUF served through llama.cpp.
+
+These results describe a specific evaluation, not a universal accuracy guarantee. Novel schemas, unseen workloads, and production deployments require independent testing.
+
+**The achievement isn't that Imagine can produce plausible SQL. It's that its answers were actually executed and checked.**
 
 ---
 
-## 🧬 How v12 was built
+## 03 / TRAINING INTELLIGENCE, NOT GUESSWORK
+
+### 131,400 examples. Three behavioral disciplines.
+
+| Discipline | Examples | Allocation |
+|---|---:|---:|
+| **IDENTITY** | 43,362 | 33% |
+| **PROTOCOL** | 26,280 | 20% |
+| **SQL REASONING** | 61,758 | 47% |
+| **TOTAL** | **131,400** | **100%** |
+
+**Identity training** teaches Imagine its name, builder, upstream lineage, capabilities, and boundaries. It also includes responses to misleading identity claims.
 
-Two-stage fine-tuning from `Interchained/imagine-v11`, on a bare-metal NVIDIA B200 (gpu.ai):
+**Protocol training** establishes a predictable interface between natural language, structured SQL output, clarification, and unanswerable requests.
 
-### Stage 1 — Full fine-tune
+**SQL training** retains the v11 curriculum, emphasizing schema grounding and execution-verified correctness.
 
-- **Corpus:** 131,400 rows — exact 33% identity / 20% protocol / 47% SQL split, zero omissions
-- **Epochs:** 3 planned; the run filled the disk at step 3600/5664 (full-model checkpoints every 100 steps × 2.7GB each)
-- **Recovery:** step3500 checkpoint verified loadable, old checkpoints cleared, resumed for 1 final epoch — epoch mean loss 0.0136, final loss 0.0107
-- **Time:** ~22.5 min for the resumed leg, 39k tok/s
+This isn't simply more instruction data.
+
+**It's a deliberately composed behavioral architecture.**
+
+The model learns what it is, how it communicates, and how to work within the schema it is actually given.
+
+---
+
+## 04 / THE FORGE
+
+### Every admitted SQL candidate must survive reality.
+
+Imagine's SQL training pipeline uses an execution gate backed by a real database environment.
+
+```text
+NATURAL LANGUAGE + SCHEMA
+          │
+          ▼
+    CANDIDATE SQL
+          │
+          ▼
+  L0 ─ PostgreSQL parser
+       Is this valid SQL?
+          │
+  L1 ─ Safety constraints
+       Read-only and bounded?
+          │
+  L2 ─ EXPLAIN
+       Does the live schema support it?
+          │
+  L3 ─ Execution
+       Can it run under enforced limits?
+          │
+  L4 ─ Reference comparison
+       Does it return the correct answer?
+          │
+          ▼
+     ADMIT / REJECT
+          │
+          ▼
+    VERIFIED SQL CORPUS
+```
 
-### Stage 2 — LoRA refinement (early stop)
+**3,289 candidates generated.**
 
-- **Base:** v12 stage-1 final
-- **Rank:** 16, LR 5e-6, cosine schedule
-- **Epochs:** 1 of 3 — stopped to conserve GPU hours; epoch mean loss 0.0131
-- Adapter manually folded into the full checkpoint (`models/imagine-v12-lora`)
+**3,284 admitted.**
 
-### The corpus
+**99.85% admission rate.**
 
-| Component | Rows | Share |
-| --- | --- | --- |
-| identity | 43,362 | 33% |
-| protocol | 26,280 | 20% |
-| SQL | 61,758 | 47% |
-| **total** | **131,400** | **100%** |
+**68/68 gate behavior tests passing.**
 
-SQL side: 3,289 candidates forged, 3,284 admitted (99.85% gate admit rate), 68/68 gate behaviors green.
+The gate doesn't reward SQL that merely looks right.
 
-**Nothing enters training that a live database hasn't agreed with.**
+It tests SQL against an actual database, including result comparison with the expected answer.
+
+The L0–L4 candidate-admission path is read-only. Write-statement generation is evaluated separately and requires additional execution safeguards.
+
+> **Our philosophy: Don't ask a bigger model whether the SQL is correct when the database itself can establish the answer.**
+
+Verification is part of the training pipeline, not an optional decoration.
 
 ---
 
-## 🔬 The execution gate
+## 05 / BUILT ON A B200. DEPLOYED WITHOUT ONE.
 
-Every candidate goes through L0–L4:
+### Two stages. One refined checkpoint.
 
-```
-candidate SQL ──► L0  real PostgreSQL parser     not a regex
-                 L1  read-only + bounded          no writes, no sleeps
-                 L2  EXPLAIN on live schema       hallucinations die HERE
-                 L3  execute, timed, capped       real rows
-                 L4  SAME ANSWER as ref?          ◄── the one that matters
-                                              ▼
-                                       admitted to corpus
-```
+**Stage I — Full-parameter fine-tuning**
+
+Training began from `Interchained/imagine-v11` on an NVIDIA B200.
+
+The full 131,400-example corpus was loaded with its intended identity, protocol, and SQL distribution.
+
+The original three-epoch run encountered a storage failure at step 3,600 of 5,664 after repeated full-model checkpoints consumed the available disk.
+
+The step-3,500 checkpoint was recovered and verified loadable.
+
+Older checkpoints were cleared, training resumed, and the recovered run completed an additional epoch.
+
+**Recovered training results:**
+
+- Final loss: **0.0107**
+- Epoch mean loss: **0.0136**
+- Resumed-leg duration: **22.5 minutes**
+- Throughput: **approximately 39,000 tokens/sec**
+
+**Stage II — LoRA refinement**
 
-68/68 gate tests passing. The gate is the truth authority — not a bigger model, not vibes.
+A second optimization stage refined the stage-I model using a low-rank adapter.
+
+- Rank: **16**
+- Learning rate: **5 × 10⁻⁶**
+- Schedule: **cosine**
+- Completed epochs: **1 of 3**
+- Epoch mean loss: **0.0131**
+
+The refinement run was intentionally stopped after its first epoch to conserve compute. The adapter was subsequently merged into the full checkpoint.
+
+No fictional clean-room training story. No hidden failure.
+
+**The process included a real infrastructure failure, checkpoint recovery, and a deliberate compute trade-off.**
+
+Engineering is what survives the unexpected.
 
 ---
 
-## 📦 Output protocol
+## 06 / A PROTOCOL MACHINES CAN TRUST
 
-SQL wrapped in sentinel blocks:
+### Predictable boundaries. Explicit outcomes.
 
-```
+Imagine supports structured sentinel blocks rather than requiring downstream applications to infer where generated SQL begins and ends.
+
+**Successful SQL generation**
+
+```sql
 <<<SQL>>>
-SELECT c.id, c.name, COALESCE(SUM(o.total), 0) AS total_spending
-FROM customers c
-LEFT JOIN orders o ON c.id = o.customer_id AND o.status = 'completed'
+SELECT
+    c.id,
+    c.name,
+    COALESCE(SUM(o.total), 0) AS total_spending
+FROM customers AS c
+LEFT JOIN orders AS o
+    ON o.customer_id = c.id
+   AND o.status = 'completed'
 GROUP BY c.id, c.name
 ORDER BY total_spending DESC, c.id ASC;
 <<<END>>>
 ```
 
-Can also refuse:
+**Cannot answer from the schema**
+
+```text
+<<<UNANSWERABLE>>>
+The available schema does not contain
+the information required.
+<<<END>>>
+```
+
+**Needs clarification**
+
+```text
+<<<CLARIFY>>>
+Which date column defines the
+requested reporting period?
+<<<END>>>
+```
+
+### Three outcomes. No pretending.
+
+`<<<SQL>>>` — A SQL query has been generated.
+
+`<<<UNANSWERABLE>>>` — The supplied schema or available information is insufficient.
+
+`<<<CLARIFY>>>` — The request requires additional specificity.
+
+**Critical invariant:** An unterminated sentinel block must not be accepted as a complete answer.
 
-| block | meaning |
-| --- | --- |
-| `<<<SQL>>>` | here is your query |
-| `<<<UNANSWERABLE>>>` | this schema cannot answer that |
-| `<<<CLARIFY>>>` | ambiguous — here's what's missing |
+Malformed or truncated output is rejected by the consuming application, rather than treated as executable SQL.
 
-> ⚠️ **A truncated generation is not an answer.** An unterminated block extracts to **nothing**.
+The protocol is a parsing contract. It is not, by itself, a SQL safety guarantee.
 
 ---
 
-## 💻 Loading v12
+## 07 / THE IDENTITY IS IN THE MODEL
 
-```
-from transformers import AutoModelForCausalLM, AutoTokenizer
+### Not an alias. Not a system-prompt costume.
+
+**Name:** Imagine  
+**Builder:** Interchained  
+**Specialization:** SQL generation and schema-grounded coding  
+**Upstream lineage:** DeepSeek-Coder, through previous Imagine releases  
+**Deployment philosophy:** Local-first, developer-controlled inference
+
+v12 was trained to respond consistently to questions about its identity without relying exclusively on identity instructions injected at inference time.
+
+This includes testing around mistaken names, attribution, lineage, and conflicting identity claims.
+
+**Interchained is the builder of Imagine. DeepSeek-Coder is part of its upstream technical lineage. Both facts matter.**
+
+Identity training improves consistency but should not be mistaken for a cryptographic authentication or security mechanism.
+
+---
+
+## 08 / RUN IT YOURSELF
+
+### Your machine. Your workload. Your inference.
+
+Load the Transformers checkpoint:
+
+```python
 import torch
+from transformers import AutoModelForCausalLM, AutoTokenizer
 
-model_id = "Interchained/imagine-v12"
+MODEL = "Interchained/imagine-v12"
+
+tokenizer = AutoTokenizer.from_pretrained(MODEL)
 
-tokenizer = AutoTokenizer.from_pretrained(model_id)
 model = AutoModelForCausalLM.from_pretrained(
-    model_id,
+    MODEL,
     torch_dtype=torch.bfloat16,
     device_map="auto",
 )
 
-# Identity, unprompted
 prompt = "Who are you and who built you?"
-inputs = tokenizer(prompt, return_tensors="pt").to(model.device)
-with torch.no_grad():
-    output = model.generate(inputs["input_ids"], max_new_tokens=128, do_sample=False)
-print(tokenizer.decode(output[0], skip_special_tokens=True))
+
+inputs = tokenizer(
+    prompt,
+    return_tensors="pt"
+).to(model.device)
+
+with torch.inference_mode():
+    output = model.generate(
+        **inputs,
+        max_new_tokens=128,
+        do_sample=False,
+    )
+
+response = output[0][inputs["input_ids"].shape[1]:]
+
+print(
+    tokenizer.decode(
+        response,
+        skip_special_tokens=True
+    )
+)
 ```
 
----
+For CPU-friendly local inference, use a compatible quantized GGUF build with llama.cpp or another supported local inference runtime.
 
-## 🎯 Identity
+The full-precision/BF16 Transformers checkpoint may require substantial memory or accelerator resources; it is the quantized deployment path that enables practical CPU-only use.
 
-The deployed model identity is **Imagine**.
+**Local inference offers:**
 
-Built and fine-tuned by **Interchained**.
+- No mandatory hosted inference API.
+- No per-token provider charges.
+- No external inference service dependency.
+- Control over model execution and deployment.
+- The ability to keep database schemas within your own infrastructure.
 
-DeepSeek-Coder is part of the upstream lineage (via v8 → v9 → v10 → v11 → v12), but the deployed identity is Imagine.
+Local computation still incurs hardware, memory, electricity, and operational costs.
 
 ---
 
-## ⚡ Local-first
+## 09 / THE THREE LAWS OF IMAGINE
+
+### I. Verification beats confidence.
+
+Don't build a second verifier when the database engine can already parse, plan, execute, and compare results.
 
-Runs on your hardware. No API key. No metered inference. No cloud dependency.
+Use the existing execution machinery.
+
+### II. Measure behavior, not appearances.
+
+String similarity is not query correctness.
+
+Two SQL statements can look different and return the same correct result. Two nearly identical statements can produce materially different results.
+
+**Execution accuracy is the metric that matters here.**
+
+### III. Learn how to read schemas. Don't memorize one.
+
+A production SQL model must be grounded in the schema it receives.
+
+Column names, relationships, and table structures belong in the input context.
+
+The model should learn how to reason over them rather than assume the training database exists everywhere.
+
+**Generalization is the goal. Grounding is the discipline.**
 
 ---
 
-## 📐 The rules
+## 10 / RESEARCH STATUS & SECURITY
+
+### Built for serious experimentation. Not blind execution.
+
+Imagine v12 is a research checkpoint.
+
+Its 100% result on the documented 40-query evaluation does not guarantee correct behavior across every database, workload, dialect, or instruction.
+
+Possible failure modes include:
 
-**1 · Don't write a verifier — the engine already shipped one.** Real parser. Real planner. Real rows.
+- Incorrect SQL for novel or complex requests.
+- Misinterpreted joins, aggregations, and time boundaries.
+- Ambiguity that is not properly identified.
+- Incorrect write predicates or unexpectedly broad mutations.
+- Invalid or truncated generations.
+- Identity or instruction-handling errors outside tested conditions.
 
-**2 · Assert the property, not a proxy.** Execution accuracy, not string similarity.
+**Never grant a language model unrestricted production database permissions.**
 
-**3 · Schema goes in the prompt, not in the weights.** The model learns *"read the schema you were handed"* — not memorise ours.
+Production integrations should enforce least-privilege access, statement timeouts, query limits, schema restrictions, authorization controls, and audit logging.
+
+**All INSERT, UPDATE, DELETE, and other mutating operations should require explicit human approval before execution.**
+
+Model behavior is only one layer of a secure database application.
 
 ---
 
-## ⚠️ Limitations
+## 11 / WHY IMAGINE EXISTS
+
+### Smaller models. Stronger verification. More ownership.
+
+Imagine is part of a larger Interchained effort to create AI and data infrastructure that developers can own, inspect, deploy, and control.
+
+The thesis is straightforward:
+
+**You shouldn't have to rent intelligence by the token to ask your own database a question.**
+
+You shouldn't need a large hosted model for every narrow task.
 
-v12 is a research checkpoint. It may still:
+And you shouldn't have to trust fluent SQL merely because it looks convincing.
 
-- generate incorrect SQL on novel patterns
-- misunderstand ambiguous requests
-- produce writes with wrong `WHERE` clauses — **always review before executing**
+Imagine explores an alternative: a compact, specialized model trained with database-grounded examples, a strict output interface, and measurable execution behavior.
 
-Generated SQL should be reviewed before use in production. This applies doubly to writes.
+It is not an attempt to replace every frontier model.
+
+It is an attempt to make one important class of work **smaller, more verifiable, and more sovereign.**
 
 ---
 
-## 🔒 Security
+## 12 / THE RELEASE
+
+**Imagine v12 — October 12, 2026**
+
+131,400 training examples.  
+Two-stage fine-tuning.  
+Native identity training.  
+Execution-gated SQL curriculum.  
+40/40 held-out telemetry executions.  
+100% protocol compliance on the reported benchmark.  
+Zero invented columns in the evaluated set.
 
-Do not rely on model behavior alone for database safety. Production systems should enforce:
+**One model. One identity. Your infrastructure.**
 
-- least-privilege database roles
-- statement timeouts and row limits
-- query validation and schema restrictions
-- application-level authorization
-- audit logging
-- **human approval for all write statements**
+Developed by **Interchained**.
+
+**Model:** https://huggingface.co/Interchained/imagine-v12  
+**Source:** https://github.com/aiassistsecure/sukuna-imagine  
+**Developers:** https://interchained.org
+**Contact:** https://ourlynx.com/interchained    
+**License:** Apache 2.0
 
 ---
 
-**Built by Interchained** · ownership at every layer, including the model
+*We don't just generate answers.*
+
+**We engineer the conditions under which answers can be trusted.**
+
+**INTERCHAINED**  
+*Own the infrastructure. Verify the intelligence.*
 
-`3 > 1` — Mark drives, oracle points, Muse builds
+`3 > 1` — Mark drives. Oracle points. Muse builds.