quran-detector

مكتبة لاكتشاف آيات القرآن الكريم ومقاطع الآيات داخل النصوص العربية (تغريدات، مقالات، كتب) مع واجهة Python بسيطة وواجهة سطر أوامر (CLI).

المصدر العلمي

تعتمد الخوارزمية على الورقة البحثية:

“QDetect: An Intelligent Tool for Detecting Quranic Verses in any Text”
Samhaa R. El-Beltagy and Ahmed Rafea, Procedia Computer Science 189 (2021) 374–381.
Paper link: https://www.sciencedirect.com/science/article/pii/S1877050921012321

وهذه الحزمة هي إعادة كتابة حديثة للمستودع القديم:

https://github.com/SElBeltagy/Quran_Detector

مميزات quran-detector

• اكتشاف الآيات والمقاطع داخل نص عربي طويل بكفاءة.
• دعم تصحيح أخطاء إملائية بسيطة (Levenshtein=1) واكتشاف كلمات ناقصة (اختياري).
• واجهة Python صغيرة: detect و annotate و Settings.
• CLI جاهز للاستخدام: quran-detector.
• موارد القرآن مرفقة داخل الحزمة وتُحمّل عبر importlib.resources.
• اختبارات انحدار تعتمد على ملفات golden لضمان ثبات السلوك.

متطلبات الاستخدام

• Python بإصدار 3.12 أو أحدث.

تثبيت quran-detector

من خلال uv (موصى به)

داخل مشروعك:

uv add quran-detector

إضافات التطوير (للمساهمين):

uv add --dev "quran-detector[dev]"

من خلال pip

python -m pip install quran-detector

إضافات التطوير:

python -m pip install "quran-detector[dev]"

من خلال الشيفرة المصدرية

• قم بتنزيل المستودع: git clone git@github.com:ieasybooks/quran-detector.git
• توجّه إلى مجلد المشروع: cd quran-detector
• ثبّت الاعتماديات: uv sync --extra dev

إذا كنت تستخدم Mise:

mise exec python@3.12 -- uv sync --extra dev

استخدام quran-detector

الاستخدام من خلال سطر الأوامر (CLI)

• اكتشاف (JSON): quran-detector detect --input input.txt > matches.json
• وسم: quran-detector annotate --input input.txt > annotated.txt
• قراءة من stdin: cat input.txt | quran-detector detect --stdin

مثال لتغيير الإعدادات:

quran-detector detect --stdin --no-find-errors --no-find-missing --allowed-error-pct 0.5 --min-match 5

الاستخدام من خلال الشيفرة (Python API)

الواجهة العامة صغيرة ومقصودة:

• quran_detector.detect(text: str, settings: Settings = Settings()) -> list[dict]
• quran_detector.annotate(text: str, settings: Settings = Settings()) -> str
• quran_detector.Settings

مثال: الوسم (Annotate)

from quran_detector import Settings, annotate

text = "قال تعالى: وَاصْبِرْ وَمَا صَبْرُكَ إِلَّا بِاللَّهِ"
print(annotate(text, settings=Settings(find_missing=False)))

ملاحظة: خيار find_missing قد يكون عدوانيًا في بعض النصوص العامة (قد يضم كلمات قبل الآية ضمن التطابق). لواجهات المستخدم يُنصح غالبًا بإيقافه: Settings(find_missing=False).

مثال: الاكتشاف (Detect)

from quran_detector import Settings, detect

text = "وَاصْبِرْ وَمَا صَبْرُكَ إِلَّا بِاللَّهِ"
matches = detect(text, settings=Settings(find_missing=False))
print(matches)

الإعدادات (Settings)

كائن Settings يتحكم في سلوك المطابقة (وخيارات CLI تُطابقه):

• find_errors: تفعيل تصحيح أخطاء الإملاء (Levenshtein=1).
• find_missing: تفعيل اكتشاف الكلمات الناقصة (مكلف وقد يكون عدوانيًا).
• allowed_error_pct: أقصى نسبة أخطاء مسموحة مقارنة بطول التطابق.
• min_match: الحد الأدنى لعدد الكلمات في المقطع.
• delimiters: تعبير Regex للفصل/التنظيف قبل المطابقة.

صيغة الخرج

خرج detect()

الدالة detect() تُرجع list[dict] قابلة للتحويل إلى JSON، حيث يحتوي كل سجل على:

• surah_name: اسم السورة
• aya_start و aya_end: رقم الآية أو نطاق الآيات
• verses: المقاطع المطابقة (بعد التطبيع)
• errors: تفاصيل التصحيحات (إن وجدت)
• start_in_text و end_in_text: فهارس كلمات بالنسبة لـ text.split()

ملاحظة: الفهارس هنا هي مواقع كلمات (وليست إزاحات حروف).

خرج annotate()

الدالة annotate() تُرجع النص بعد استبدال المقاطع المطابقة بالنص الأصلي للقرآن مع إضافة مرجع:

"<quran text>" (سورة:آية[-آية])

ملاحظة حول الالتباس: بعض المقاطع الشائعة جدًا قد تتطابق مع أكثر من موضع/آية، وقد توجد أكثر من نتيجة صحيحة في حالات معيّنة. اختبارات golden الخاصة بالوسم تتحقق من الحالات غير الملتبسة (unambiguous) فقط.

لمحة عن الخوارزمية

على مستوى عالٍ، الخوارزمية تقوم بـ:

1. تطبيع النص
   • تطبيع بعض أشكال الحروف العربية (مثل: أشكال الألف → ا، و ة → ه، و ى/ی → ي).
   • إزالة التشكيل لأغراض المطابقة.
2. فهرسة القرآن
   • بناء بنية trie (“linked hash tables” في الورقة) على جميع سوابق/لواحق مقاطع الآيات (بحد أدنى 3 كلمات).
   • تتبع حالات terminal و abs-terminal لدعم “أطول تطابق”.
3. مسح النص
   • مسح النص كلمة بكلمة ومحاولة تمديد التطابق قدر الإمكان.
   • اختياريًا: تصحيح خطأ إملائي بحرف واحد + اكتشاف كلمة ناقصة.
4. ترشيح النتائج
   • تطبيق حد أدنى للطول (min_match) وحد نسبة الأخطاء (allowed_error_pct) وقواعد إضافية للمقاطع القصيرة.

البيانات / الموارد

الحزمة ترفق الموارد المطلوبة داخل src/quran_detector/data/:

• quran-simple.txt (نص القرآن)
• quran-index.xml (بيانات السور)
• non-terminals.txt (قائمة الكلمات/الوقف)

يتم تحميل الموارد عبر importlib.resources لتعمل داخل wheels وعمليات التثبيت المضغوطة.

التطوير

pre-commit

• ruff (lint + ترتيب الاستيرادات)
• ruff format (تنسيق)
• mypy (فحص الأنواع)

تثبيت hooks:

pre-commit install

تشغيلها على كل الملفات:

pre-commit run --all-files

الاختبارات

الاختبارات تستخدم fixtures مرفقة داخل tests/fixtures/ (بدون الاعتماد على مجلدات خارجية).

تشغيل الاختبارات كأوامر منفصلة:

pytest -q tests/test_tweets_eval.py
pytest -q tests/test_golden_outputs.py -k 'match_all_against_golden'
pytest -q tests/test_golden_outputs.py -k 'annotate_txt_against_golden'

ملاحظة: مجموعات golden ثقيلة عمدًا وقد تأخذ حوالي 30–40 دقيقة لكل مجموعة على جهاز محمول.