docs: add comprehensive Model Card with Classical Arabic Manṭiq documentation

README.md

@@ -0,0 +1,146 @@
+---
+language:
+- en
+- ar
+license: apache-2.0
+tags:
+- code
+- qwen2.5-coder
+- gguf
+- mantiq
+- logic
+- arabic
+- epistemology
+- reasoning
+- chain-of-thought
+- aynengine
+base_model: Qwen/Qwen2.5-Coder-1.5B
+pipeline_tag: text-generation
+---
+
+# 🏛️ AynCoding: Sovereign Epistemic Classical Arabic Logic (Manṭiq) & Morphology 1.5B
+
+**AynCoding** (`ayncoding-qwen2.5-coder-1.5b`) is a sovereign, epistemic code synthesis and architectural refactoring model based on **Qwen2.5-Coder-1.5B**, conditioned and aligned with **Classical Arabic Logic (*Manṭiq*)** and **Morphological Root Lexicography (*Ishtiqāq*)**.
+
+Unlike standard LLMs trained on unstructured, messy GitHub repositories, **AynCoding** natively engages an epistemic Chain-of-Thought reasoning block (`<ayn_mantiq> ... </ayn_mantiq>`) prior to code generation. It analyzes software requirements through ontological definitions (*Al-Ḥadd*), eliminates logical fallacies (*Dafʿ al-Dawr*, *Dafʿ al-Tasalsul*, *ʿAdam al-Tanāquḍ*), and maps software engineering domains to classical tri-consonantal roots.
+
+---
+
+## 🌟 Governing Classical Authorities
+
+AynCoding is grounded in seven classical Arabic masterpieces:
+
+1. **Abū Ḥāmid al-Ghazālī** (*Miʿyār al-ʿIlm fī Fann al-Manṭiq* & *Miḥakk al-Naẓar*):
+   - **Al-Ḥadd bi al-Dhātiyyāt (Real Definition by Essence)**: Every class, struct, and routine must be defined by its essential constitutive attributes, not superficial symptoms.
+   - **Dafʿ al-Dawr (Elimination of Circularity)**: Complete prohibition of circular dependencies, circular imports, and mutual deadlocks.
+   - **Dafʿ al-Tasalsul (Elimination of Infinite Regress)**: Strictly bounded recursion, guaranteed loop termination, and timeout bounds.
+   - **ʿAdam al-Tanāquḍ (Law of Non-Contradiction)**: Mutually exclusive state FSMs; elimination of contradictory states and silent exception swallowing.
+2. **Fakhr al-Dīn al-Rāzī** (*Al-Mulakhkhaṣ fī al-Ḥikmah wa al-Manṭiq*): Proof theory, syllogistic validation, and formal deductive rigor.
+3. **Al-Khalīl ibn Aḥmad al-Farāhīdī** (*Kitāb al-ʿAyn*):
+   - **Atomic Primitive Decomposition**: Decomposing complex software architectures into orthogonal, irreducible primitives.
+4. **Ibn Manẓūr** (*Lisān al-ʿArab*):
+   - **Exhaustive Error Taxonomy & State-Space Coverage**: Zero unhandled match arms, zero silent `except Exception: pass`, and complete lifecycle modeling (`INITIALIZING` -> `ACTIVE` -> `DEGRADED` -> `CLOSED` -> `FAILED`).
+5. **Al-Rāghib al-Iṣfahānī** (*Al-Mufradāt fī Gharīb al-Qurʾān*):
+   - **Ontological Domain Modeling & Teleology (*Ghāyah*)**: Absolute ban on amorphous, vague identifiers (`data`, `temp`, `val`, `mgr`, `helper`). Every token represents its distinct purpose.
+6. **Al-Zamakhsharī** (*Asās al-Balāghah*):
+   - **Abstraction Integrity & Rhetorical Eloquence (*Ḥaqīqah* vs *Majāz*)**: Distinguishing physical hardware reality (memory, CPU caches, IO) from metaphors. Zero leaky abstractions.
+7. **Sībawayh** (*Al-Kitāb*):
+   - **Syntactic Governance (*Al-ʿĀmil wa al-Maʿmūl*)**: Strict caller-callee hierarchy, rigorous static typing, and guaranteed AST integrity.
+
+---
+
+## 🧠 Cognitive Chain-of-Thought Format (`<ayn_mantiq>`)
+
+Before producing code, AynCoding generates an epistemic reasoning block:
+
+```xml
+<ayn_mantiq>
+🏛️ AYN-ENGINE EPISTEMIC LOGIC & MORPHOLOGY REASONING:
+- Classical Root & Morphology (الجذر والتصريف): [e.g. ق-ف-ل for locking / mutual exclusion]
+- Real Definition & Essence (الحد بالذاتيات - معيار العلم للغزالي): [Essential attributes and invariants]
+- Epistemic Fallacy Invariants (دفع الدور والتسلسل ونفي التناقض): [Circularity, regress, and contradiction guards]
+- Lexicographical Teleology (الغاية وبلاغة التجريد - المفردات والأساس): [Pure purpose, zero vague abstractions]
+- Syntactic Governance (العامل والمعمول - كتاب سيبويه): [Strict type contracts, caller-callee hierarchy]
+</ayn_mantiq>
+```
+
+---
+
+## 📊 Head-to-Head Epistemic Benchmark vs. Frontier AI
+
+Evaluated blindly and deterministically using the **5-Pillar Static Epistemic Auditor** across 3 canonical systems challenges:
+
+| Challenge | Classical Domain & Roots | AynCoding 1.5B (Local CPU) | Frontier Cloud Model |
+| :--- | :--- | :---: | :---: |
+| **1. Monotonic Ring Buffer** | Concurrency & Ordering (`ر-ت-ب` / `ح-ف-ظ`) | **89.6% (Grade: B+)** *(17.5s)* | **98.0% (Grade: A+)** |
+| **2. Epistemic Circuit Breaker** | FSM Governance & Safety (`ح-ك-م` / `س-ل-م`) | **100.0% (Grade: A+)** *(16.9s)* | **98.0% (Grade: A+)** |
+| **3. Atomic WAL with CRC32** | Persistence & Contracts (`ح-ف-ظ` / `ع-ق-د`) | **93.0% (Grade: A)** *(17.5s)* | **94.0% (Grade: A)** |
+| **Overall Macro Epistemic Average** | **Composite Score** | **94.2% (Grade: A)** | **96.7% (Grade: A+)** |
+
+*AynCoding 1.5B running on pure CPU trails the frontier cloud AI by only **2.5%** while achieving a perfect 100% on finite-state governance.*
+
+---
+
+## 🚀 Quickstart: Running with Ollama
+
+1. **Download the GGUF model and Modelfile:**
+   ```bash
+   huggingface-cli download enver/ayncoding-qwen2.5-coder-1.5b ayncoding-qwen2.5-coder-1.5b.gguf Modelfile --local-dir ./ayncoding
+   cd ayncoding
+   ```
+
+2. **Register with Ollama:**
+   ```bash
+   ollama create ayncoding-model -f Modelfile
+   ```
+
+3. **Run Inference:**
+   ```bash
+   ollama run ayncoding-model "Write a thread-safe token bucket rate limiter in Python"
+   ```
+
+---
+
+## 💻 Python / Transformers & llama.cpp Usage
+
+### With llama-cpp-python:
+```python
+from llama_cpp import Llama
+
+llm = Llama(
+    model_path="ayncoding-qwen2.5-coder-1.5b.gguf",
+    n_ctx=8192,
+    n_threads=16  # Pin to single socket for dual-Xeon CPU optimization
+)
+
+output = llm.create_chat_completion(
+    messages=[
+        {"role": "user", "content": "Implement an in-memory ring buffer with atomic sequence counters in Python."}
+    ],
+    temperature=0.2,
+    max_tokens=4096
+)
+
+print(output["choices"][0]["message"]["content"])
+```
+
+---
+
+## 🛠️ Included Tools in Repository
+
+- `Modelfile`: Sovereign Ollama definition with the 5 classical Arabic pillars and epistemic system prompt.
+- `dataset/ayn_mantiq_epistemic_dataset_50.jsonl`: 50 AST-validated training samples across 10 classical software engineering domains with explicit `<ayn_mantiq>` CoT reasoning.
+- `adapter/adapter_manifest.json`: CPU LoRA fine-tuning configuration manifest (Rank 16, Alpha 32).
+- `training/train_mantiq_lora.py`: PyTorch PEFT CPU fine-tuning script with NUMA thread optimization.
+- `tools/core/mantiq_purifier.py`: Automated code sanitizer purging amorphous variables (`data`, `temp`, `val`, `mgr`) and silent bare `except:` clauses.
+- `tools/core/mantiq_engine.py`: Classical Arabic Logic fallacy engine detecting *Dawr*, *Tasalsul*, and *Tanāquḍ*.
+
+---
+
+## 📜 Citation & Heritage
+
+If you use this model or dataset, please cite the classical authorities:
+- Abū Ḥāmid al-Ghazālī, *Miʿyār al-ʿIlm fī Fann al-Manṭiq* (Criterion of Knowledge in Logic).
+- Al-Khalīl ibn Aḥmad al-Farāhīdī, *Kitāb al-ʿAyn* (The First Arabic Lexicon).
+- Al-Rāghib al-Iṣfahānī, *Al-Mufradāt fī Gharīb al-Qurʾān* (Ontological Lexicon).
+- Sībawayh, *Al-Kitāb* (The Foundation of Arabic Grammar & Governance).