# ما يحتاج AI آخر معرفته — مشروع أثر (HTR للمخطوطات العربية)

## البنية
- **Backend:** FastAPI بـ`backend/run.py` على المنفذ **8001** (Kraken v3، CUDA+FP16 على RTX 4050).
- **Frontend:** PWA على `http://127.0.0.1:8001/app/` — تبويبات: تحقيق المخطوطات / تحليل الكتب / قص يدوي / فهرس.
- **فرع التثبيت الحالي:** `fix/pipeline-quality` — عليه رحلة المتصفح والتصدير
  ومكتبة المصادر. `feature/phoenix-ai-demo` لقطة أقدم، ولم يُدمج الفرعان بعد.

## التشغيل (حتماً)
```bash
cd backend && .venv\Scripts\python.exe run.py
```
- **يجب** بيثون `backend/.venv` (**3.10** فيها kraken+slowapi+torch-cuda). بيثون النظام 3.14 ينقصه kraken.
- إن كسر venv: أعد `pyvenv.cfg` (`home = C:\Users\aiden\AppData\Local\Python\pythoncore-3.10-64`).
- فحص: `GET http://127.0.0.1:8001/api/health` → يجب أن يحوي `Kraken v3 (HTR CUDA+FP16 ...)`.

## الميزات المُنفَّذة (كلها تعمل، لا تُعيد بناءها)
1. **راوتر تخطيط**: كشف إطار (cf>0.92) → مسار المنطق. غير مؤطّرة → مسار عام. الإصلاح المهم: القص/التعرّف = logic **فقط مع frame_box مؤكّد**.
2. **بوابة LM**: عتبة ثقة 0.95 · `char8_visual.lm` (train فقط) · α=0.5,
   β=0.3, beam=10 · سقف تغيير 0.5. `char8_trainval.lm` رأى val، فلا يُستخدم
   لضبط أو قياس عليها. الحارس في `lm_split_guard.py` يطبع الزوج والبصمات.
3. **قص يدوي / PAGE-XML**: تبويب «✂️ قص يدوي» — رفع صورة + رسم مربعات أو استيراد PAGE-XML (eScriptorium). النتيجة تُنقل تلقائياً للتبويب الأول.
4. **فصل المتن/الحاشية**: `_classify_columns` بكشف الأعمدة (متن/يمين/يسار/أعلى/أسفل). يعمل جيداً مع قص XML الدقيق فقط.
5. **مساعِد LLM سياقي**: OpenAI GPT-5 (`gpt-5.4-mini` سهل، `gpt-5.5` صعب). ميزات: شرح مصطلحات، شرح صفحة، بدائل قراءة (مع تعليل)، استخراج كيانات. **كاش LRU** لتلافي إعادة الاستدعاء.
6. **RAC (التصحيح بالاسترجاع)**: مكتبة محلية قابلة للتوسعة: 4 كتب / 9,450
   موضعاً (قرآن، بخاري، معجب، النجاة). اختيار المصادر محفوظ لكل مخطوطة،
   والإسناد المتكرر يُعرض ملتبساً لا مرجعاً قطعياً.
7. **الإنسان في الحلقة**: قائمة مراجعة سريعة، لوحة أدلة، سجل قبل/بعد، وتراجع
   يضيف قيداً ولا يمحو التاريخ. 32/32 مربّع سطر قابل للفتح، مع قائمة عند التداخل.
8. **المخرجات**: PAGE-XML بمضلعات وbaselines، TEI، وحزمة تدريب لا يدخلها
   إلا ما اعتمده الباحث. OpenITI وIIIF موصولان مع معاينة وحماية شبكة.
9. **الفهرس** (35,632 عمل): بحث بترتيب الصلة (token+IDF+عنوان كامل+تجريد «ال»). `GET /api/catalog/search?q=...`.

## المفاتيح والـLLM
- `backend/.env` (**مُستثنى من git، لا تلمسه**): `OPENAI_API_KEY` + `LLM_MODEL_EASY=gpt-5.4-mini` + `LLM_MODEL_HARD=gpt-5.5`.
- GPT-5 يستخدم `max_completion_tokens` + `reasoning_effort` **بلا temperature**. عند 402: نفد الرصيد.

## الملفات المهمّة
- الإعدادات: `backend/app/core/config.py` (النماذج، LM، المسار الآمن).
- OCR الجوهر: `backend/app/services/ocr/kraken_service.py` (الراوتر + `_classify_columns` + `recognize_manual`).
- التحليل: `backend/app/api/endpoints/analysis_api.py` (بدائل، شرح، RAC، بحث، كيانات).
- الاسترجاع: `backend/app/services/retrieval_service.py` (RAC).
- الفهرس: `backend/app/services/catalog_service.py`.

## المسار الآمن للتعرّف (لا تُغيّره)
- **رمادي L** (لا nlbin، لا enhance، لا resize، لا deskew). nlbin يشوّه نماذج L.
- النماذج (في `نماذج/`):
  - عام: `seg_finetuned_v4` + `transcription_finetuned_best`
  - منطق: `logic_philosophy_v2_seg` + `logic_philosophy_v2_rec`
  - LM: `char8_visual.lm` (عام، train فقط) · `char8_logic_selftrained.lm` (منطق)

## القياس — حالة المجموعات أهم من الرقم
- `experiment_4/data/val` و`experiment_4/data/test` استُخدمتا في الضبط أو
  اختيار النماذج؛ لا تُعرض أرقامهما أداءً مستقلاً. `rac_holdout` مستبدلة بعد
  إصلاح أمان الاسترجاع، و`top_15` مرجعها آلي.
- المصدر الملزم للحالة: `reports/split_manifest.json`. أي مجموعة مجهولة
  الحالة لا تُفترض مستقلة، وأي تجاوز تشخيصي يحمل `INVALID_FOR_CLAIMS`.
- أرقام 6.76% و8.68% تاريخية ببروتوكولاتها، وليست رقماً نهائياً للنسخة الحالية.
- **مبدأ الأمانة:** غير المقيس = `Not measured`. لا رقم مخترع.

## آخر تثبيت متصفح
- `scripts/final_stabilization_playwright.py`: 5/5، و32/32 سطراً، وزر إلغاء
  الإثراء، وبطاقات 4 مصادر، وصفر أخطاء JavaScript.
- النتائج واللقطات: `output/playwright/final/`.

## أخطاء Windows + مسار عربي (مهم)
- `PYTHONIOENCODING=utf-8` دائماً.
- لأوامر بايثون معقّدة: **اكتب ملف `.py`** بدل inline (فشل curl/inline مع مسار عربي).
- PowerShell + `Start-Process -WorkingDirectory` مع مسار عربي **يفشل** — استخدم env var قبل Start-Process.

## قواعد لا تكسرها
- **لا تُغيّر `.env`** (المفاتيح).
- **لا تُبطل الديمو المستقرّ** — كل تغيير في `feature/phoenix-ai-demo` يجب أن يُختبر أولاً.
- **لا تُدرّب نموذجاً** بلا استئذان — التدريب يتم في حاوية Docker `escriptorium-celery-gpu-1`.
- **لا تلمس PAGE-XML/GT** — تُستخدم للتقييم فقط.
- **لا تخلط المجموعات الثلاث** (GT/manual/auto) في جدول واحد.

## الورقة البحثية
- `paper_v2/PAPER_v2.docx` (5 صفحات، A4، Times New Roman، 4 جداول، 3 أشكال).
- المصدر: `paper_v2/PAPER_v2.md` + `_build_docx.py` + `figures/`.
- اسم المشروع النهائي: **أثر**.