# هيكل المشروع | Project Structure

## نظرة عامة

هذا المستودع (**diac-api-project / testApp**) هو غلاف تطبيقي حول مكتبة البحث [rufaelfekadu/Diac](https://github.com/rufaelfekadu/Diac).  
كود التدريب والبحث الأصلي (`train_lightning.py`, `inference_hf.py`, …) يبقى في المستودع الأصلي ويُثبَّت كحزمة Python عبر `pip`.

## المجلدات الرئيسية

| المسار | الوظيفة |
|--------|---------|
| `backend/app/main.py` | تطبيق FastAPI والمسارات |
| `backend/app/services/model_service.py` | تحميل النموذج مرة واحدة واستدعاء `predict_text` |
| `backend/app/schemas.py` | نماذج Pydantic للطلبات والاستجابات |
| `backend/app/config.py` | إعدادات من متغيرات البيئة |
| `backend/scripts/run_local.py` | تشغيل محلي من سطر الأوامر |
| `frontend/` | واجهة React + Vite (عربية، RTL) |
| `constants/` | ملفات الترميز المطلوبة لـ `from_pretrained(..., tokenizer_constants_path="constants/")` |
| `app/main.py` | نقطة دخول قديمة متوافقة مع الإصدارات السابقة |
| `docker/` | Dockerfile للخلفية |
| `docs/` | توثيق إضافي |

## المستودع الأصلي Diac (للبحث)

| الملف | الوظيفة |
|-------|---------|
| `train_lightning.py` | تدريب PyTorch Lightning |
| `train.py` | تدريب بديل |
| `inference.py` | استنتاج من checkpoint محلي + YAML |
| `inference_hf.py` | استنتاج من Hugging Face |
| `src/diac/models/diacritization_model.py` | `DiacritizationModule` |
| `configs/*.yml` | إعدادات النماذج |
| `scripts/*.sh` | سكربتات التجارب |

## تحميل النموذج من Hugging Face

```python
from diac.models import DiacritizationModule

model = DiacritizationModule.from_pretrained(
    "rufaelfekadu/diac-transformer-text-asr-tashkeela-clartts",
    tokenizer_constants_path="constants/",
)
```

يجب أن يكون مجلد `constants/` موجودًا في مسار العمل (يحتوي `constants.json` وملفات `.pickle`).

## صيغ المدخلات والمخرجات

### API

- **طلب واحد:** `{"text": "كتب الطالب الدرس"}`
- **استجابة:** `{"input": "...", "diacritized": "..."}`
- **دفعة:** `{"texts": ["...", "..."]}` → `{"results": [{"input","diacritized"}, ...]}`

### `inference_hf.py` (الأصلي)

- **مدخل:** ملف `.txt` (سطر = جملة) أو `.tsv` (نص + ASR)
- **مخرج:** ملف نصي عند `--output_path` (افتراضي `outputs/hf_inference_output.txt`)

### CLI المحلي

- `--text` → طباعة النص المشكّل
- `--file` → قراءة أسطر، الكتابة إلى `outputs/local_diacritized.txt` (أو `--output`)

## تغيير اسم النموذج

```bash
export MODEL_NAME="rufaelfekadu/diac-transformer-text-only-tashkeela"
```

أو في `.env` / `docker-compose.yml`.

## ملاحظات

- النموذج الافتراضي `text+asr` يتوقع إعداد `INFERENCE.USE_ASR` من ملف config المحمّل مع الـ checkpoint؛ للنص فقط قد تحتاج نموذج `text-only`.
- أول تحميل يحمّل الـ checkpoint من Hugging Face وقد يستغرق دقائق ويتطلب مساحة قرص وذاكرة كافية.