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/` | التقييم الأولي والاختبارات والدفتر الأصلي |

## تدريب CAMeLBERT-MSA (المهمة 1A)

`research/train_camelbert.py` هو المدرِّب المحسَّن (بيانات مولَّدة بأسلوب النماذج اللغوية مع العبارات التمهيدية وبدونها، وزيادة وزن
البيانات الحقيقية، ومدخلات بلا تشكيل مع تحويل دقيق للمواضع، وخسارة موزونة بالفئات، وتناقص معدل التعلم حسب الطبقات، واختيار أفضل
حقبة بمقياس F1 الرسمي على مستوى الأحرف، وفك BIO نظيف، ودمج اختياري مع مستخرج القواعد والمرجع). يحتاج التدريب إلى GPU غير متوفر
في المشروع، فشغّله على Colab أو Kaggle T4 المجاني.

```bash
pip install torch transformers
python research/train_camelbert.py --holdout 10 --out models/camelbert_check        # تقدير صادق؛ يطبع F1 للنموذج والهجين والقواعد
python research/train_camelbert.py --holdout 0 --epochs 6 --push-to-hub YOUR_USER/camelbert-msa-islamiceval-1a --out models/camelbert_1a
```

ثم ضع `HF_MODEL_ID` (أو `HF_ENDPOINT_URL` لنقطة استدلال مخصصة) في `web/config.js`. لا تُضمَن أي نتيجة؛ قارن F1 المطبوع بمستخرج
القواعد والمرجع (`python evaluate.py`). لم يُختبر في هذه النسخة الاستدعاء الحي لنموذج مستضاف من المتصفح؛ والمحاكاة هي الافتراضي.

## جرّب هذه المدخلات

| المدخل | النتيجة المتوقعة |
|---|---|
| `قال الله تعالى: "فَاسْتَقِمْ كَمَا أُمِرْتَ وَمَنْ تَابَ مَعَكَ".` | آية، موثّقة |
| `قال الله تعالى: "إن الله لا يغفر أن يشرك به ويغفر ما دون ذلك لمن يريد".` | آية، غير مطابقة مع نص المصدر الصحيح |
| `من أعظم ما يثبّت القلب قوله إِنَّ مَعَ الْعُسْرِ يُسْرًا فلا تيأس.` (بلا عبارة ولا تنصيص) | آية، موثّقة |
| `إنما الأعمال بالنيات وإنما لكل امرئ ما نوى.` (بلا عبارة ولا تنصيص) | حديث، موثّق |
| `قال رسول الله ﷺ: "من قرأ سورة الإخلاص ألف مرة دخل الجنة بغير حساب ولا عقاب".` | حديث، لا يوجد مصدر مطابق |
| `قال الله تعالى: "إن الله مع الصابرين والمحسنين في كل حين".` | آية، تحتاج مراجعة بشرية (آية مختلقة) |

هذه الأمثلة نفسها أزرار داخل الصفحة.

## حل مشاكل «اسأل ثم تحقّق»

تعرض الصفحة السبب الدقيق الذي أبلغت عنه OpenAI. رسالة «تجاوز حد الاستخدام أو الرصيد» (الرمز 429 و`insufficient_quota`) تعني أن حساب
OpenAI المرتبط بالمفتاح لا رصيد فيه أو أن الفوترة غير مفعّلة: أضِف رصيدًا من Billing أو ضع مفتاحًا آخر في `web/config.js`. لا يمكن
للكود إصلاح ذلك. وإلى حين حلّه تعرض الصفحة إجابة تجريبية مضمّنة ليستمر عرض مسار التحقق.

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

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

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

## القيود

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

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

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

الرخصة: MIT.