README.md

---
language:
- en
- ar
license: gemma
tags:
- code
- gemma2
- google
- gguf
- mantiq
- logic
- arabic
- epistemology
- reasoning
- chain-of-thought
- aynengine
base_model: google/gemma-2-2b-it
pipeline_tag: text-generation
---

# 🏛️ AynCoding-Gemma2: Sovereign Epistemic Classical Arabic Logic (Manṭiq) 2.6B

**AynCoding-Gemma2** (`ayncoding-gemma2-2b`) is a sovereign, epistemic code synthesis and architectural refactoring model based on **Google's flagship Gemma 2 2B** architecture (`google/gemma-2-2b-it`), aligned and conditioned with **Classical Arabic Logic (*Manṭiq*)** and **Morphological Root Lexicography (*Ishtiqāq*)**.

Built upon Google DeepMind's distilled Gemma 2 architecture, **AynCoding-Gemma2** marries cutting-edge model distillation with 1,200 years of classical Arabic epistemological rigor. It natively engages a structured **Chain-of-Thought reasoning block (`<ayn_mantiq> ... </ayn_mantiq>`)** prior to code generation, analyzing software specifications through real essential definitions (*Al-Ḥadd bi al-Dhātiyyāt*), eliminating logical fallacies (*Dafʿ al-Dawr*, *Dafʿ al-Tasalsul*, *ʿAdam al-Tanāquḍ*), and mapping domain concepts to authentic tri-consonantal roots.

---

## 🌟 The 5 Classical Arabic Epistemic Pillars

AynCoding-Gemma2 is strictly governed by the foundational canons of classical Arabic scholarship:

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)**: Entities are defined by their constitutive essential attributes, never accidental symptoms.
   - **Dafʿ al-Dawr (Elimination of Circularity)**: Zero circular dependencies, cyclic callbacks, or self-referential ungrounded types.
   - **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 states are unrepresentable simultaneously.
2. **Al-Khalīl ibn Aḥmad al-Farāhīdī** (*Kitāb al-ʿAyn*) & **Ibn Manẓūr** (*Lisān al-ʿArab*):
   - **Tri-Consonantal Root Decomposition & Combinatorial Safety**: Complex systems are decomposed into orthogonal, irreducible primitives anchored in authentic semantic roots (`قفل`, `حفظ`, `نقل`, `عقد`, `حسب`, `رتب`, `سلم`, `حكم`).
   - **Exhaustive State-Space Coverage**: Zero unhandled match arms and zero silent exception swallowing (`except Exception: pass` is prohibited).
3. **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 symbol reflects its distinct teleological purpose.
4. **Al-Zamakhsharī** (*Asās al-Balāghah*):
   - **Abstraction Integrity & Rhetorical Eloquence (*Ḥaqīqah* vs *Majāz*)**: Delineating physical machine reality (memory, CPU caches, IO) from software abstractions. Zero leaky abstractions.
5. **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 Protocol (`<ayn_mantiq>`)

Before emitting production code, AynCoding-Gemma2 executes its epistemic reasoning:

```xml
<ayn_mantiq>
🏛️ AYN-ENGINE EPISTEMIC LOGIC & MORPHOLOGY REASONING:
- Classical Root & Morphology (الجذر والتصريف): [Root e.g. ق-ف-ل, linguistic significance]
- 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>
```

---

## 🧪 Benchmark & Dynamic Evaluation

In live benchmark evaluations using the **5-Pillar Static Epistemic Auditor**:

* **Sliding Window Rate Limiter:**
  * **Overall Epistemic Score:** **87.8% (Grade: B+)**
  * **AST Syntax Integrity:** 100% Valid ✅
  * **Banned Placeholders:** 0 (Zero-Loss Complete) ✅
  * **Asās al-Balāghah (Eloquence):** **10.0 / 10**
  * **Kitāb al-ʿAyn (Decomposition):** **10.0 / 10**
  * **Sībawayh (Governance):** **10.0 / 10**
  * **Dynamic Execution:** Automatically evicted oldest items in $O(1)$ under real multi-threaded execution!

---

## 🚀 Quickstart: Running with Ollama

1. **Download the GGUF model and Modelfile:**
   ```bash
   huggingface-cli download enver/ayncoding-gemma2-2b ayncoding-gemma2-2b.gguf Modelfile --local-dir ./ayncoding-gemma2
   cd ayncoding-gemma2
   ```

2. **Register with Ollama:**
   ```bash
   ollama create ayncoding-gemma2 -f Modelfile
   ```

3. **Run Inference:**
   ```bash
   ollama run ayncoding-gemma2 "Write a thread-safe sliding window rate limiter in Python"
   ```

---

## 💻 Python (`llama-cpp-python`) Usage

```python
from llama_cpp import Llama

llm = Llama(
    model_path="ayncoding-gemma2-2b.gguf",
    n_ctx=8192,
    n_threads=16  # NUMA optimization
)

output = llm.create_chat_completion(
    messages=[
        {"role": "user", "content": "Explain how Ghazalian logic eliminates circularity in software architecture."}
    ],
    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 hyperparameter tuning.
- `dataset/ayn_mantiq_epistemic_dataset_50.jsonl`: 50 AST-validated training samples across 10 classical domains with `<ayn_mantiq>` CoT reasoning.
- `tools/core/mantiq_engine.py`: Classical Logic fallacy detection engine (*Dawr*, *Tasalsul*, *Tanāquḍ*).
- `tools/core/mantiq_purifier.py`: Automated code sanitizer purging amorphous variables and silent bare `except:` clauses.
- `tools/bin/ayncode`: Sovereign CLI developer tool for code synthesis, auditing, and purification.

---

## 📜 Heritage & Citations

- Google DeepMind, *Gemma 2: Improving Open Language Models at a Practical Size*.
- Abū Ḥāmid al-Ghazālī, *Miʿyār al-ʿIlm fī Fann al-Manṭiq*.
- Al-Khalīl ibn Aḥmad al-Farāhīdī, *Kitāb al-ʿAyn*.
- Al-Rāghib al-Iṣfahānī, *Al-Mufradāt fī Gharīb al-Qurʾān*.
- Ibn Manẓūr, *Lisān al-ʿArab*.
- Sībawayh, *Al-Kitāb*.