FOR_NEXT_AI.md

ما يحتاج 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 لقطة أقدم، ولم يُدمج الفرعان بعد.

التشغيل (حتماً)

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/.
• اسم المشروع النهائي: أثر.