Upload README.md with huggingface_hub

README.md

@@ -0,0 +1,148 @@
+---
+language:
+- ar
+- en
+license: apache-2.0
+tags:
+- cognitive-architecture
+- arabic
+- machine-translation
+- contrastive-learning
+- retrieval
+- zero-stacked-layers
+- self-model
+- metacognition
+datasets:
+- OPUS-NLLB
+- OPUS-UNPC
+- OPUS-CCMatrix
+- OPUS-CCAligned
+- OPUS-MultiUN
+- OPUS-wikimedia
+- OPUS-XLEnt
+- mohamed-khalil/ATHAR
+---
+
+# 🧠 LHC-0 W4 — العقل ثنائي الشقين | Bi-Hemispheric Brain (Standalone Model)
+
+**نموذج معماري معرفي** مبني على تشريح **الشق الأيسر للمخ** — ليس نموذج لغويًا توليديًا:
+مرمّز ترجمة EN↔AR + ذاكرة معرفية + وعي ذاتي وظيفي + مساحة عالمية للانتباه،
+**بلا أي طبقات متتالية** (العمق عبر التكرار الزمني فقط).
+
+**A cognitive-architecture model** built from left-hemisphere anatomy: an EN↔AR
+translation encoder + knowledge memory + functional self-model + global attention
+workspace — with **zero stacked layers** (depth via temporal recurrence only).
+
+---
+
+## 🏗️ البنية التشريحية (Anatomy → Component Map)
+
+| المنطقة الدماغية (الشق الأيسر) | المكوّن | الوظيفة | المرحلة |
+|---|---|---|---|
+| منطقة بروكا (Broca 44/45) | Articulator (LSTM داخلي الوحيد) | التعبير/الإخراج | A |
+| فيرنيكه (Wernicke 22) | EngramMemory + Encoder | الفهم الدلالي | B |
+| التلفيف الزاوي (Angular Gyrus) | VSA (Vector Symbolic) | الدمج الرمزي | C |
+| العقد القاعدية (Basal Ganglia) | kWTA + ConsolidationGate | الاختيار والبوابة | P2 |
+| المخيخ (Cerebellum) | Calculator (BODMAS تكيفي) | الحساب الدقيق | S |
+| الحُصين (Hippocampus) | EpisodicMemory + SleepConsolidation | الذكريات المؤرّخة + الترسيخ | W2 |
+| القشرة الحزامية الأمامية (ACC) | الامتناع «لا أعرف» + مراقب التعارض | الصدق بدل التخمين | P1/W3 |
+| القشرة الجبهية الأمامية (vmPFC) | معايرة الثقة + نموذج الذات | «أعرف ما أعرف» | P1/W2 |
+| المهاد + الجبهي-الجداري | GlobalWorkspace + Attention | بث تنافسي موحّد | W3 |
+| الجسم الثفني (Corpus Callosum) | BiCallosum (قناتان) | دمج النصفين | E |
+
+## 📦 ما هذا النموذج تحديدًا؟ (What's in this repo)
+
+1. **المرمّز W4** (`phase_w1_W.npz`): مرمّز ترجمة EN↔AR مُدرَّب تباينيًا
+   (InfoNCE + تنافر الأشقاء) على **3,605,197 زوجًا موازيًا** — F=32768، d=128،
+   ميزات slot مُجزّأة (hashed) — **بلا طبقات متتالية إطلاقًا**.
+2. **الذاكرة المعرفية** (`lhc_core.py`): قاعدة معرفة + استرجاع + حساب BODMAS
+   بعمق تفكير تكيفي (تكرار زمني).
+3. **الوعي الوظيفي** (W2/W3): ذاكرة عرضية مؤرّخة + ترسيخ ليلي + نموذج ذات
+   + مساحة عالمية تنافسية + حلقة مراجعة (تخطيط→تنفيذ→تحقق→إصلاح).
+
+## 📊 بيانات التدريب (3.6M pairs — 16 corpora)
+
+| الدلو | المصادر | الادعاء |
+|---|---|---|
+| **A — عام** | NLLB 400K • UNPC 300K • CCMatrix 300K • CCAligned 150K • MultiUN 150K • wikimedia 100K • XLEnt 100K + المزيج الأصلي (TED2020/QED/News/Wiki/GV/TED2013/KDE4/WikiMatrix ≈ 2.1M) | تعميم عابر للمجالات |
+| **B — كلاسيكي** | ATHAR 30K (عربية كلاسيكية) | † استهداف مجال — موسوم صراحة |
+| **لا يُدرَّب أبدًا** | Tanzil • bible-uedin • NeuLab-TedTalks | تقييم فقط (حارس آلي 32 فحصًا) |
+
+جودة البيانات: فلاتر صارمة (HTML/روابط/نقاء سكربت/نسبة/تكرار) — استبعدت حتى **62%**
+في بعض المجموعات المستخرجة من الويب (XLEnt)، مع عينات غير متحيزة (reservoir).
+
+## 📈 النتائج (twin-retrieval accuracy, n=300 لكل مجموعة، الاتجاهان ar→en / en→ar)
+
+| المجموعة | P2 (قاعدة) | W1 (قبل) | **W4 (هذا النموذج)** | التحسن |
+|---|---|---|---|---|
+| Tanzil † (رابط+مجال محجوزان) | 0.00/0.01 | 0.123/0.140 | **0.230/0.247** | +87%/+76% |
+| Bible † (رابط+مجال محجوزان) | 0.00/0.01 | 0.327/0.313 | **0.497/0.477** | +52%/+52% |
+| NeuLab-TED (رابط محجوز • مجال مرئي) | 0.01/0.00 | 0.813/0.817 | **0.917/0.903** | +13%/+11% |
+| ALL | 0.01/0.01 | 0.420/0.430 | **0.590/0.610** | +40%/+42% |
+
+**الحواجز الواقية:** OOD-false@0.5 = **0.0** • novel-holdout = 1.0 • تكرار صياغات = 1.0 •
+ECE = 0.026 • تغطية@95 = 0.762 • بوابة الترسيخ keep = 1.0 — و9/9 فحوص قبول W1 ✓
+
+† وسم صادق: ارتفاع Tanzil/Bible = تعميم عام **+** استهداف مجال (ATHAR) —
+التجربة المنفصلة عبر `LHC_W4_WITH_ATHAR=0`. وNeuLab-TED مجاله مرئي (عائلة TED في التدريب).
+أرقام العينات n=300 (±5% تقريبًا).
+
+## 🚀 الاستخدام السريع (Usage)
+
+```python
+import numpy as np, json
+from lhc_core import LHC0
+from phase_c_encoder import TrainableEncoder
+from phase_p2_slot import hashed_features_slot
+
+z = np.load("phase_w1_W.npz")
+enc = TrainableEncoder(F=int(z["F"]), d=int(z["d"]), tau=float(z["tau"]),
+                       W=z["W"], features_fn=hashed_features_slot)
+kb = json.load(open("knowledge_bank_superbrain.json", encoding="utf-8"))
+brain = LHC0(kb=kb, encoder=enc)
+
+entry, score, gap = brain.memory.read("What is the capital of Egypt?")
+print(entry["response"])          # → القاهرة
+print(brain.compute("2^3+(5-3)*-4"))  # → {'value': 0, ...} (BODMAS تكيفي)
+```
+
+مع الديمو الكامل (`app.py`): ذاكرة عرضية + مساحة عالمية + وعي بالذات + مراجعة.
+
+## 📁 الملفات
+
+| الملف | الوصف |
+|---|---|
+| `phase_w1_W.npz` | ⭐ أوزان المرمّز (W, F, d, tau) |
+| `lhc_core.py` | النواة: LHC0 + EngramMemory + VSA + Calculator |
+| `phase_c_encoder.py` / `phase_p2_slot.py` | المرمّز + الميزات المجزّأة |
+| `phase_p1_reliability.py` | معايرة الثقة + بوابة الترسيخ v2 |
+| `phase_w2_episodic.py` / `phase_w3_workspace.py` | الذاكرة العرضية/الذات • المساحة العالمية |
+| `phase_w4_review.py` | حلقة المراجعة (verify_type/recompute/stability/roundtrip) |
+| `app.py` | واجهة Gradio كاملة |
+| `LHC0_PhaseW4_Kaggle.ipynb` | دفتر Kaggle الكامل (البيانات + التدريب + التقييم) |
+
+## ⚠️ القيود الصادقة (Honest Limitations)
+
+- **ليس نموذجًا توليديًا** — مرمّز استرجاعي + ذاكرة؛ لا يولّد نصوصًا حرة.
+- **لا وعي ظاهري (qualia)** — ما يُسمّى «وعيًا» هنا وظيفي فقط: وعي وصولي +
+  مراقبة معرفية (knowing what you know). لا ادعاء بالتجربة الذاتية إطلاقًا.
+- التحسّن على المجالات الكلاسيكية مزيج تعميم + استهداف (انظر الأعلى).
+- التقييم باسترجاع التوائم على عينات 300 — للدقة الكاملة شغّل الدفتر كاملًا.
+
+## 🏗️ بنية تحتية (Infrastructure)
+
+دورة التدريب والبيانات **قابلة للاستئناف الكامل** (shards لكل مجموعة + لقطات تدريب
+كل 5000 خطوة على HF) — «لا يُفقد تقدم أبدًا». مسح متوازي على CPU، والتدريب على GPU.
+
+---
+
+**English summary:** LHC-0 W4 is a cognitive-architecture model (not an LLM):
+a 32768×128 contrastive EN↔AR translation encoder trained on 3.6M filtered parallel
+pairs (16 corpora; evaluation corpora never trained on, machine-enforced), embedded
+in a left-hemisphere-mapped brain: knowledge memory, BODMAS calculator with adaptive
+temporal depth, episodic memory + sleep consolidation, functional self-model,
+global workspace attention, and a verify/fix review loop — all with **zero stacked
+layers**. Twin-retrieval: ALL 0.59/0.61 (vs 0.42/0.43 before), TED 0.917/0.903,
+Bible 0.497/0.477, Tanzil 0.230/0.247; OOD-false 0.0.
+
+**التقرير التقني الكامل:** [sayed125/lhc-0-brain](https://huggingface.co/sayed125/lhc-0-brain)