Update README.md

README.md

@@ -1,43 +1,114 @@
 ---
+license: apache-2.0
 library_name: transformers
+pipeline_tag: text-generation
 tags:
-- trl
+- qwen3
 - sft
+- trl
+- topological-knowledge-distillation
+- disc
+- convergent-intelligence
+base_model: Qwen/Qwen3-1.7B
 ---
 
+# TopologicalQwen
+
+**Topology-Aware Knowledge Distillation from Qwen3-30B-A3B → 1.7B**
 
-## Convergent Intelligence Portfolio
+*Convergent Intelligence LLC: Research Division*
 
-*Part of the [Topological Series](https://huggingface.co/reaperdoesntknow) by [Convergent Intelligence LLC: Research Division](https://huggingface.co/reaperdoesntknow)*
+---
 
+## What This Is
 
-### Top Models from Our Lab
+TopologicalQwen is a 1.7B parameter model distilled from Qwen3-30B-A3B using **Topological Knowledge Distillation (TKD)** — a methodology that treats the teacher's output distribution over a concatenated token stream as a bounded variation (BV) function and decomposes knowledge transfer into three channels via the Mesh Fundamental Identity:
 
-| Model | Downloads |
-|-------|-----------|
-| [Qwen3-1.7B-Thinking-Distil](https://huggingface.co/reaperdoesntknow/Qwen3-1.7B-Thinking-Distil) | 501 |
-| [LFM2.5-1.2B-Distilled-SFT](https://huggingface.co/reaperdoesntknow/LFM2.5-1.2B-Distilled-SFT) | 342 |
-| [Qwen3-1.7B-Coder-Distilled-SFT](https://huggingface.co/reaperdoesntknow/Qwen3-1.7B-Coder-Distilled-SFT) | 302 |
-| [Qwen3-0.6B-Distilled-30B-A3B-Thinking-SFT-GGUF](https://huggingface.co/reaperdoesntknow/Qwen3-0.6B-Distilled-30B-A3B-Thinking-SFT-GGUF) | 203 |
-| [Qwen3-1.7B-Coder-Distilled-SFT-GGUF](https://huggingface.co/reaperdoesntknow/Qwen3-1.7B-Coder-Distilled-SFT-GGUF) | 194 |
+1. **Smooth distillation (AC component)** — Standard KL divergence over regions where the teacher's distribution varies continuously. This is what every other KD method does and stops at.
+2. **Jump corrections (D^j f)** — Explicit correction terms at conceptual boundaries where the teacher's distribution exhibits discontinuities. These are the points where topic, register, or reasoning mode shifts — standard KD smears across them, losing structural information.
+3. **Drift corrections (D^c f)** — The Cantor/singular-continuous component capturing gradual distributional drift that neither the smooth nor jump terms account for. This is the residual structure that emerges in generation quality.
 
-**Total Portfolio: 41 models | 2,781 total downloads**
+Standard knowledge distillation only handles term (1). TKD captures all three.
 
+## Architecture
 
-*Last updated: 2026-03-28 12:56 UTC*
+| Parameter | Value |
+|-----------|-------|
+| Architecture | Qwen3ForCausalLM |
+| Parameters | ~2.03B (1.7B effective) |
+| Hidden Size | 2048 |
+| Layers | 28 |
+| Attention Heads | 16 (Q) / 8 (KV) — GQA |
+| Intermediate | 6144 |
+| Context Length | 40,960 tokens |
+| Vocabulary | 151,936 |
+| Precision | FP32 training, BF16/FP16 inference |
 
-<!-- CIX-CROSSLINK-START -->
+## Training Methodology
 
----
+The TKD pipeline has four phases:
 
-## From the Convergent Intelligence Portfolio
+**Phase 1 — Teacher logit caching:** Single forward pass through the teacher (Qwen3-30B-A3B) with top-k logit compression to disk. One pass, no repeated teacher inference.
 
-**[DistilQwen Collection](https://huggingface.co/collections/reaperdoesntknow/distilqwen-69bf40ec669117e3f069ef1c)** — Proof-weighted distillation from Qwen3-30B-A3B → 1.7B and 0.6B. Three teacher variants (Instruct, Thinking, Coder), nine models, 2,788 combined downloads. Structure beats scale.
+**Phase 2 — DISC topology pass:** Vectorized discrepancy operator maps the knowledge manifold, identifying where the teacher's distribution has structural features (jumps, drift, curvature).
 
-Top model: [Qwen3-1.7B-Coder-Distilled-SFT](https://huggingface.co/reaperdoesntknow/Qwen3-1.7B-Coder-Distilled-SFT) — 508 downloads
+**Phase 3 — Topology-guided adaptive windowing:** Training windows cut at low-discrepancy positions rather than fixed stride. The topology tells you where to cut without losing information across boundaries.
+
+**Phase 4 — Curriculum-ordered continuous KD:** Belt-fed training with proof-weighted loss. 55% cross-entropy with decaying proof weights (2.5× → 1.5×), 45% KL divergence at T=2.0. Proof weights amplify loss on reasoning-critical tokens.
 
 Full methodology: [Structure Over Scale (DOI: 10.57967/hf/8165)](https://doi.org/10.57967/hf/8165)
 
-*Convergent Intelligence LLC: Research Division*
+## Usage
+
+```python
+from transformers import AutoModelForCausalLM, AutoTokenizer
+
+model = AutoModelForCausalLM.from_pretrained(
+    "reaperdoesntknow/TopologicalQwen",
+    torch_dtype="auto",
+    device_map="auto"
+)
+tokenizer = AutoTokenizer.from_pretrained("reaperdoesntknow/TopologicalQwen")
+
+messages = [{"role": "user", "content": "Derive the Euler-Lagrange equation from the principle of stationary action."}]
+text = tokenizer.apply_chat_template(messages, tokenize=False, add_generation_prompt=True)
+inputs = tokenizer(text, return_tensors="pt").to(model.device)
+output = model.generate(**inputs, max_new_tokens=1024, temperature=0.7, top_p=0.9)
+print(tokenizer.decode(output[0], skip_special_tokens=True))
+```
+
+## Why Topology Matters
 
-<!-- CIX-CROSSLINK-END -->
+Every knowledge distillation method in the literature treats the teacher's output as a smooth function and minimizes KL divergence globally. This works for the easy parts — regions where the teacher's distribution varies slowly. But language has structure: topic shifts, reasoning mode transitions, register changes. At these boundaries, the teacher's distribution jumps. Standard KD averages across these jumps, teaching the student a blurred version of the teacher's actual knowledge.
+
+TKD uses the DISC (Discrepancy Calculus) framework to detect these structural features before training, then allocates capacity and loss weight accordingly. The result is a student that preserves the teacher's structural understanding, not just its surface statistics.
+
+The empirical evidence: this model at 1.7B consistently produces responses with structural reasoning quality that standard distillation at the same parameter count does not achieve.
+
+## Related Models
+
+| Model | Description | Downloads |
+|-------|-------------|-----------|
+| [Qwen3-1.7B-Thinking-Distil](https://huggingface.co/reaperdoesntknow/Qwen3-1.7B-Thinking-Distil) | TKD with Thinking teacher | 687 |
+| [LFM2.5-1.2B-Distilled-SFT](https://huggingface.co/reaperdoesntknow/LFM2.5-1.2B-Distilled-SFT) | Cross-architecture TKD (LFM → Qwen) | 544 |
+| [Qwen3-1.7B-Coder-Distilled-SFT](https://huggingface.co/reaperdoesntknow/Qwen3-1.7B-Coder-Distilled-SFT) | TKD with Coder teacher | 508 |
+
+**[DistilQwen Collection](https://huggingface.co/collections/reaperdoesntknow/distilqwen-69bf40ec669117e3f069ef1c)** — Full proof-weighted distillation series (9 models)
+
+## Citation
+
+```bibtex
+@misc{colca2026topologicalqwen,
+  title={TopologicalQwen: Topology-Aware Knowledge Distillation via Bounded Variation Decomposition},
+  author={Colca, Roy S.},
+  year={2026},
+  publisher={HuggingFace},
+  url={https://huggingface.co/reaperdoesntknow/TopologicalQwen},
+  note={Convergent Intelligence LLC: Research Division}
+}
+```
+
+---
+
+*Convergent Intelligence LLC: Research Division*
+*"Where classical analysis fails to see, we begin."*