README_AR.md

# التحقق من هلوسة القرآن والحديث وتصحيحها

النسخة الإنجليزية: [README.md](README.md)

يكتشف الاقتباسات القرآنية والحديثية في أي نص (مثل إجابات النماذج اللغوية)، ويتحقق من كل اقتباس بمقارنته بالمصادر، ويعرض
الدليل، ويقترح تصحيحًا **مأخوذًا حرفيًا من نص المصدر**. وإذا لم تكفِ الأدلة فإنه يصرّح بذلك ويحيل الحالة إلى المراجعة البشرية.
واجهة المنتج عربية بالكامل.

## العرض المباشر

**[LIVE_DEPLOYMENT_URL]**  <!-- استبدل هذا الرابط برابط Hugging Face Space بعد النشر -->

## المزايا

* **تحقّق مباشر:** الصق أي فقرة، فيكتشف النظام كل آية وحديث، ويقارنها كلمةً بكلمة، ويقترح نص المصدر تصحيحًا.
* **اسأل ثم تحقّق:** اكتب سؤالًا فيجيب عميل ChatGPT (OpenAI) المهيّأ مسبقًا، ثم يتحقق المحرك من الإجابة ويعيد نسخة مصحّحة.
  لا توجد قائمة لاختيار النموذج في هذه الصفحة.
* **دون الحاجة إلى عبارات تمهيدية:** يتعرّف النظام على الاقتباس بمطابقته مع مراجع القرآن والحديث، سواء وُضع بين علامات
  تنصيص أو لم يوضع، وسواء سبقته عبارة مثل «قال الله تعالى» أو «قال رسول الله ﷺ» أو لم تسبقه. هذه العبارات احتياط ضعيف فقط
  للاقتباسات المحرَّفة التي لا يستطيع المرجع تأكيدها.
* **قائمة نموذج الاستخراج (بالإنجليزية):** *Standard · Rules + Corpus* أو *CAMeLBERT-MSA · Fine-tuned* (التفاصيل أدناه).
* **تصدير بصيغة المسابقة:** JSON وTSV بهيكل المهام 1A / 1B / 1C (انظر «مواءمة المعايير»).
* **نسخ النص المصحّح:** زر يعمل فعليًا مع رسالة «تم نسخ النص بنجاح»، وبديل احتياطي داخل الإطارات (iframe).
* **تحميل سريع ومُعلِم:** يبدأ تنزيل فهرس القرآن قبل تشغيل السكربتات، ويُحمَّل فهرس الحديث في الخلفية، وتُخزَّن الملفات في
  ذاكرة المتصفح (Cache API)، وتُخزَّن النتائج وأمثلة العرض بصيغة JSON في `localStorage`، وتعرض بطاقات هيكلية متحركة وشريط
  تقدّم من ثلاث خطوات ما يجري.

## دعم CAMeLBERT-MSA

يوفّر `web/camelbert.js` دالة `detectSpans` تعيد وسوم BIO (`B-Ayah` و`I-Ayah` و`B-Hadith` و`I-Hadith` و`O`) والمقاطع:

* **الوضع الحي:** اضبط `HF_MODEL_ID` (و`HF_TOKEN` للنموذج الخاص) في `web/config.js`، فتستدعي الصفحة واجهة Hugging Face
  Inference لنموذج تصنيف رموز مضبوط. ثم يتحقق خط المعالجة المحلي من المقاطع ويصحّحها.
* **وضع المحاكاة (الافتراضي):** عند عدم ضبط معرّف النموذج **لا تُحمَّل أي أوزان نموذج**. تأتي المقاطع من المستخرج القياسي
  وتُعرض بوسوم BIO وقيم ثقة شبه عشوائية ثابتة، وتُظهر الواجهة بوضوح أنها *Simulation*. استخدمه لعرض سير العمل لا للإبلاغ عن دقة النموذج.

## سير العمل

```
نص -> استخراج (علامات التنصيص + مطابقة المرجع، ثم مسح المرجع للاقتباسات غير المعلَنة) -> استرجاع BM25
   -> محاذاة موضعية (الهيكل الصوتي، نافذة منزلقة، LCS، فجوة ديناميكية)
   -> مطابق: موثّق | آية محرّفة: تصحيح من المصدر | غير مؤكد: مراجعة بشرية | لا شبيه: لا يوجد مصدر
```

## مواءمة المعايير

يحوّل `benchmark.py` نتيجة المعالجة إلى هيكل مهام IslamicEval 2025 مطابقًا لعيّنة التطوير المضمّنة
(`data/islamiceval_dev_subset.jsonl`):

| المهمة | الحقل | القيم |
|---|---|---|
| 1A الاستخراج | `Span_Start` و`Span_End` و`Span_Type` | مواضع الأحرف (النهاية حصرية، دون علامات التنصيص)؛ `Ayah` / `Hadith` |
| 1B التحقق | `Label` | `Correct` / `Incorrect` (كل ما لم يُوثَّق يُبلَّغ عنه `Incorrect`) |
| 1C التصحيح | `Correction` | نص المصدر الحرفي للمقاطع الخاطئة، أو `خطأ` إن لم يوجد مصدر موثوق |

أعمدة TSV: `Response_ID, Span_Start, Span_End, Span_Type, Label, Correction`. **راجع أسماء الأعمدة في صفحة التسليم الرسمية
للمنظّمين قبل أي تسليم رسمي**؛ فلم يمكن جلب المواقع الرسمية آليًا أثناء إعداد هذه النسخة، لذا لم تُتحقق الأسماء الرسمية الدقيقة هنا.

## التشغيل والنشر

```bash
python index_builder.py          # فقط بعد تعديل data/
python build_static_space.py     # ينشئ ./static_space/
```

ارفع **محتويات** `static_space/` إلى Hugging Face Space من نوع *Static* (مجاني). النسخة المحلية بواجهة Gradio:
`pip install -r requirements.txt && OPENAI_API_KEY=... python app.py`. الاختبارات: `python -m unittest discover -s tests`.

## مفتاح الواجهة البرمجية (مهم)

لا يملك Static Space خادمًا، لذا فإن أي مفتاح في `web/config.js` **يستطيع كل زائر قراءته**. تضع هذه النسخة مفتاح ChatGPT في
هذا الملف لغرض العرض المباشر. حدّد سقف إنفاق شهريًا صغيرًا للمفتاح من لوحة OpenAI، وألغِه بعد التقييم، ولا ترفعه إلى مستودع
عام (يفحص GitHub المفاتيح المكشوفة ويلغي مفاتيح OpenAI). التصميم الأكثر أمانًا للإنتاج وسيط صغير (مثل Cloudflare Worker) يحتفظ بالمفتاح سرًّا.

## هيكل المشروع

| المسار | الدور |
|---|---|
| `web/` | الواجهة: `index.html` و`styles.css` (زجاجية، RTL) و`app.js` و`worker.js` و`cache.js` و`camelbert.js` و`config.js` |
| `normalization.py` و`idgham.py` | تطبيع صوتي للعربية؛ إظهار الإدغام في التصحيحات |
| `index_builder.py` و`retrieval.py` | فهارس BM25 / n-gram مبنية مسبقًا والمسترجِع الكسول |
| `alignment.py` و`similarity.py` | محاذاة الكلمات ومؤشرات التشابه |
| `detector.py` و`scanner.py` | الاستخراج (المرجع أولًا؛ العبارات التمهيدية اختيارية) ومسح المرجع |
| `verifier.py` | التحقق والتصحيح المستند إلى المصدر والقرارات |
| `benchmark.py` | تصدير JSON / TSV بهيكل IslamicEval |
| `llm_client.py` و`app.py` و`ui.py` | عميل النموذج وتطبيق Gradio ونقاط الدخول لبايثون وعرض HTML |
| `evaluate.py` و`tests/` و`research/` | التقييم الأولي والاختبارات والدفتر الأصلي |

## التقييم (عيّنة التطوير)

حُسب بـ `python evaluate.py` على عيّنة تطوير IslamicEval 2025 المضمّنة بعد فصل الاستخراج عن العبارات التمهيدية. هذه الأرقام
**ليست** خط الأساس البحثي السابق (1A: 0.9091 بـ CAMeLBERT-MSA؛ 1B: 93.12%؛ 1C: 70.39%).

| المكوّن | النتيجة |
|---|---|
| 1A الاستخراج، F1 على مستوى الأحرف، المستخرج الهجين | 0.8247 |
| 1B دقة الحكم على المقاطع المرجعية (247 مقطعًا؛ خط الأساس «صحيح دائمًا» 59.5%) | 93.12% |
| 1C دقة التصحيح (179 مقطعًا؛ خط الأساس «لا مصدر دائمًا» 62.0%) | 74.30% |

## القيود

* اكتشاف الاقتباسات غير المعلَنة مطابقة للمرجع لا فهم؛ يفوته النص البعيد عن المراجع المضمّنة.
* الأداة مساعدة للتدقيق النصي وليست فتوى ولا بديلًا عن المراجعة المتخصصة.
* تنزّل الزيارة الأولى بيئة Pyodide وحوالي 16 ميغابايت من البيانات؛ وتستفيد الزيارات التالية من ذاكرة المتصفح.

## متطلبات المسابقة

انظر [REFERENCES_AR.md](REFERENCES_AR.md) للمصادر المستخدمة. أدرِج شروط المسابقة ومواعيدها من وثائق المنظّمين
(<https://islamicaich.org/>) في تسليمك؛ فلم يمكن قراءتها آليًا أثناء إعداد هذه النسخة.

الرخصة: MIT.