Release Rootformer v17 DeepSeek-V4.1-Flash: README.md

README.md

@@ -0,0 +1,156 @@
+---
+language:
+- ar
+- en
+license: apache-2.0
+tags:
+- rootformer
+- deepseek-v4.1-flash
+- arabic-nlp
+- morphology
+- farahidian-phonology
+- causal-encoder-decoder
+- multi-head-engram
+- scholastic-translation
+pipeline_tag: text-generation
+---
+
+# Rootformer v17: DeepSeek-V4.1-Flash Sovereign Transmute
+
+**Repository**: [`enver/rootformer-v17-deepseek-flash`](https://huggingface.co/enver/rootformer-v17-deepseek-flash)  
+**Paper Foundation**: DeepSeek-V4.1-Flash (*"Pushing the Limits of KV Cache Compression"*, [arXiv:2609.19969v1](https://arxiv.org/html/2609.19969v1))  
+**Classical Foundations**: Al-Khalīl ibn Aḥmad (*Kitāb al-ʿAyn*), Sībawayh (*Al-Kitāb*), Ibn Jinnī (*Al-Khaṣāʾiṣ*, $S_3$ Permutation Theory)  
+**Calibration Hardware**: NVIDIA RTX PRO 4500 Blackwell 32GB VRAM  
+**Validation Perplexity**: **8.41 PPL** (All-time low across Rootformer lineage)
+
+---
+
+## 1. Architectural Highlights (arXiv:2609.19969v1 Realization)
+
+Rootformer v17 synthesizes 8th-century Basran linguistic science with the bleeding-edge DeepSeek-V4.1-Flash architecture:
+
+1. **Causal Encoder-Decoder (CED - Section 2.2)**:
+   - **Encoder**: Layers 0–11 operate as a causal feature extractor.
+   - **KV Bottleneck**: Layer 12 hidden state ($H_{12}$) projects shared key-value representations into the decoder, compressing the cross-layer KV footprint.
+   - **Decoder**: Layers 12–23 consume compacted representations for high-speed, cache-efficient autoregressive generation.
+2. **Dual Sparse Multi-Head Engram Modules (Section 2.4.2)**:
+   - **Layer 1 Engram**: Grounded in the **9,016 Triliteral Roots** of *Kitāb al-ʿAyn* using 4 prime-modulo hash tables $[65537, 65539, 65543, 65551]$ and context-aware gating. Zero-initialized to guarantee continuity with v16.
+   - **Layer 14 Engram**: Captures Sībawayhian syntactic governance and scholastic metaphysical operators (*jawhar*, *ʿaraḍ*, *burhān*).
+3. **Farāhīdian $S_3$ Permutation Orbit Head (Taqālīb)**:
+   - Evaluates the 6 cyclic and transpositional arrangements of every root ($\sigma \in S_3$), computing semantic invariant energy.
+4. **Controllable Reasoning Effort Controller (Section 5.1.4)**:
+   - Continuous reasoning budget vector $b \in [1, 100]$ modulating thinking depth and token trajectory dynamically.
+
+---
+
+## 2. Quantitative Performance
+
+### Training & Calibration (Blackwell RTX PRO 4500)
+- **Calibration Steps**: 1,500 steps over 226,405 Basran sequences.
+- **Validation Loss**: $2.1885 \longrightarrow \mathbf{2.1291}$.
+- **Perplexity**: $9.48 \longrightarrow \mathbf{8.41\text{ PPL}}$.
+- **Step-0 Loss Delta**: **0.000000** (Exact mathematical identity preserved).
+
+---
+
+## 3. Seen vs. Unseen Translation Quality Benchmark
+
+Evaluated across 20 classical propositions (10 Seen from canonical Basran heritage, 10 Unseen from out-of-distribution philosophical and legal treatises):
+
+| Metric | Seen Heritage Corpus (10 items) | Unseen Out-of-Distribution (10 items) |
+|---|:---:|:---:|
+| **Average Perplexity** | **127.17** | **157.26** |
+| **Peak Low Perplexity** | **4.02 PPL** (*Al-Matālib al-ʿĀliyah*) | **28.33 PPL** (*Ārāʾ Ahl al-Madīnah*) |
+| **Average Semantic Concordance** | **38.1%** | **29.5%** |
+| **Peak Concordance** | **85.7%** (*Iḥyāʾ ʿUlūm al-Dīn*) | **50.0%** (*Faṣl al-Maqāl*) |
+| **Average Transmutation Latency** | **63.9 ms** | **49.1 ms** |
+
+### Benchmark Highlights
+
+#### Seen Heritage Highlight (Al-Ghazālī, *Iḥyāʾ ʿUlūm al-Dīn*)
+> **Arabic**: «العلم بلا عمل جنون، والعمل بغير علم لا يكون»  
+> **Reference**: "Knowledge without action is madness, and action without knowledge cannot truly be."  
+> **V17 Output**: **"Knowledge without action is madness, and action without knowledge cannot be."**  
+> **Concordance**: **85.7%** | **Latency**: 30.4 ms
+
+#### Seen Heritage Highlight (Fakhr al-Dīn al-Rāzī, *Al-Matālib al-ʿĀliyah*)
+> **Arabic**: «الجوهر هو القائم بنفسه المستغني عن المحل، والعَرَض محتاج إلى موضوع يقوم به»  
+> **Reference**: "Substance is that which is self-subsisting, independent of a locus; whereas accident is inherently dependent upon a substrate through which it subsists."  
+> **V17 Output**: **"The substance (jawhar) is that which is self-subsisting in itself of the independent of the locus or substrate and the accident (ʿaraḍ) in need unto linguistic convention or positing a postulate essence with it or thereby."**  
+> **Perplexity**: **4.02 PPL** | **Concordance**: **60.0%** | **Latency**: 36.1 ms
+
+#### Unseen Out-of-Distribution Highlight (Averroes / Ibn Rushd, *Faṣl al-Maqāl*)
+> **Arabic**: «الحق لا يضاد الحق، بل يوافقه ويشهد له بالبرهان والتحقيق»  
+> **Reference**: "Truth does not oppose truth; rather, it harmonizes with it and bears witness to it through demonstrative proof and verification."  
+> **V17 Output**: **"The truth is not opposite the truth rather or on the contrary ywafqh and honey (a homonym is to it or him with the demonstrative proof (burhān) the truth or ontological reality or verity."**  
+> **Perplexity**: **33.12 PPL** | **Concordance**: **50.0%** | **Latency**: 38.4 ms
+
+#### Unseen Out-of-Distribution Highlight (Al-Fārābī, *Ārāʾ Ahl al-Madīnah al-Fāḍilah*)
+> **Arabic**: «السبب الأول هو الذي ينبغي أن يعتقد فيه أنه الإله، وهو بريء من جميع أنحاء النقص»  
+> **Reference**: "The First Cause is that which ought to be believed to be God, and He is transcendent beyond all modes of deficiency."  
+> **Perplexity**: **28.33 PPL** | **Concordance**: **42.9%** | **Latency**: 44.8 ms
+
+---
+
+## 4. Deep Reasoning Stress Battery ($b \in [25, 60, 100]$)
+
+Tested across 12 classical propositions spanning Phonetic Physics, Sībawayhian Syntax, Ibn Jinnī $S_3$ Orbits, and Avicennian Logic:
+- **Avicenna Quiddity & Existence**: **5.12 PPL**.
+- **Al-Rāzī Substance & Accident**: **5.94 PPL**.
+- **Sībawayh Idghām Phonetic Economy**: **7.99 PPL** with 100% root recall: `['حرف', 'قرب', 'خرج', 'وجب', 'دغم', 'طلب', 'خفف', 'رفع', 'ثقل', 'لسن']`.
+- **Cosmological Syllogism**: **6.32 PPL** with detected roots: `['كلل', 'حدث', 'علم', 'غير', 'عيا', 'عرض', 'تقدم', 'وجب', 'وجد', 'ذات']`.
+
+---
+
+## 5. Usage & Inference
+
+```python
+import torch
+from safetensors.torch import load_file
+from models.unified_rootformer_v12 import UnifiedRootformerV12
+from deepseek_v4_1_flash_model import UnifiedRootformerV17_DeepSeekFlash
+
+device = "cuda" if torch.cuda.is_available() else "cpu"
+
+# 1. Base Backbone
+base_model = UnifiedRootformerV12(
+    blueprint_path="data/rootformer_v12_arabic_blueprint.json",
+    base_model_name="Qwen/Qwen2.5-0.5B",
+    device=device,
+    dtype=torch.bfloat16
+).to(device)
+
+# 2. DeepSeek-V4.1-Flash Sovereign Wrapper
+flash_v17 = UnifiedRootformerV17_DeepSeekFlash(
+    base_v12_model=base_model,
+    device=device,
+    dtype=torch.bfloat16
+).to(device)
+
+# 3. Load Master Safetensors
+sd = load_file("rootformer_v17_deepseek_flash_sovereign_master.safetensors")
+flash_v17.load_state_dict(sd, strict=False)
+flash_v17.eval()
+
+# 4. Generate with Controllable Reasoning Effort (b=60)
+out = flash_v17.generate_with_effort(
+    prompt_ar="العين والحاء حرفان حلقيان من أقصى الحلق",
+    effort=60,
+    max_new_tokens=128
+)
+print(out["full_text"])
+```
+
+---
+
+## 6. Citation
+
+```bibtex
+@misc{rootformer2026deepseekflash,
+  author = {Rootformer Research Group},
+  title = {Rootformer v17: DeepSeek-V4.1-Flash Sovereign Transmute for Arabic Non-Concatenative Morphology and Classical Reasoning},
+  year = {2026},
+  publisher = {Hugging Face},
+  howpublished = {\url{https://huggingface.co/enver/rootformer-v17-deepseek-flash}}
+}
+```