AGENTS.md

# تعليمات تشغيل المشروع (لأي AI)

مشروع HTR للمخطوطات العربية: FastAPI backend + PWA frontend، تعرّف بـ Kraken.

## بيئة التشغيل (مهم — أخطأ فيها سابقاً)
- **الخادم:** المنفذ **8001** عبر `backend/run.py` (uvicorn reload=True).
- **يجب** استخدام بايثون البيئة الافتراضية: `backend/.venv/Scripts/python.exe` (**Python 3.10**، فيها kraken+slowapi+torch).
  بايثون النظام (`C:\Python314`) **ينقصه kraken+slowapi** → البدء يتعطّل بـ `ModuleNotFoundError: slowapi`.
- إن فُقد `backend/.venv/pyvenv.cfg` تصير البيئة «مكسورة» (تتراجع لبايثون النظام). أعد كتابته:
  ```

  home = C:\Users\aiden\AppData\Local\Python\pythoncore-3.10-64

  include-system-site-packages = false

  version = 3.10.11

  ```
- التشغيل: من `backend/` شغّل `.venv\Scripts\python.exe run.py`. الفحص: `GET http://127.0.0.1:8001/api/health`.

## مفاتيح وLLM
- `backend/.env` (**مُستثنى من git — لا تَرفعه أبداً**) فيه `OPENAI_API_KEY` + `LLM_MODEL_EASY=gpt-5.4-mini` + `LLM_MODEL_HARD=gpt-5.5`.
- الخدمة `app/services/llm_service.py` = OpenAI Chat Completions. طبقتان: سهل (شرح/مصطلحات/كلمة) وصعب `hard=True` (تصحيح سطر سياقي = gpt-5.5).
- خصوصية GPT‑5: `max_completion_tokens` + `reasoning_effort`، **بلا temperature**.
- ميزات LLM تحتاج مفتاحاً صالحاً برصيد؛ عند الفشل تظهر 401/402/429.

## Docker (للتجارب الثقيلة: تدريب/تقييم Kraken)
- الحاوية: `escriptorium-celery-gpu-1` (فيها kraken+torch+GPU). تشغيلها إن توقفت عبر Docker Desktop.
- `/tmp` داخلها يبقى عبر إعادة تشغيل Docker. انسخ الملفات بـ `docker cp`.
- جهاز ketos: `-d cuda:0` على مجموعة `ketos` الأمّ لا `ketos train`.

## الفروع
- `feature/phoenix-ai-demo` = **النسخة المستقرة (العرض)** — لا تكسرها.
- `research/lm-experiments` = التجارب البحثية (LM/reranking) معزولة.

## الإعدادات
- كل ما يغيّر مخرجات OCR في `app/core/config.py` (النماذج، LM، المعالجة). المسار الآمن: رمادي L، بلا nlbin/enhance/resize/deskew.
- النماذج في مجلد `نماذج/` (أخت المشروع).

## ملاحظات Windows + مسار عربي
- استخدم `PYTHONIOENCODING=utf-8`. لأوامر python المعقّدة: اكتب ملف `.py` بدل inline (الـ inline يفشل أحياناً مع cwd العربي).
- نتائج CER/WER على **ثلاث مجموعات منفصلة** (GT يدوي / auto / سهل) — لا تخلطها في جدول واحد.