quran-detector 0.0.2

Detect Quranic verses and verse fragments in Arabic text (QDetect rewrite)

quran-detector

مكتبة لاكتشاف آيات القرآن الكريم ومقاطع الآيات داخل النصوص العربية (تغريدات، مقالات، كتب) اعتمادًا على خوارزمية مبنية على الورقة البحثية التالية:

“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
Legacy implementation repo: https://github.com/SElBeltagy/Quran_Detector

هذا المشروع هو إعادة كتابة حديثة للمشروع القديم Quran_Detector مع واجهة Python واضحة، وأداة سطر أوامر (CLI)، وملفات بيانات مرفقة (نص القرآن وقوائم الكلمات)، واختبارات انحدار (golden files) لضمان ثبات السلوك.

التثبيت

باستخدام uv (موصى به)

داخل مشروعك:

uv add quran-detector

للتطوير (يضيف ruff و mypy و pre-commit):

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

باستخدام pip

python -m pip install quran-detector

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

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

تهيئة المستودع محليًا (هذا المستودع)

هذا المستودع يحتوي على uv.lock لذلك يمكنك تشغيل:

uv sync --extra dev

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

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

بداية سريعة

واجهة Python

from quran_detector import Settings, detect, annotate

text = "وَاصْبِرْ وَمَا صَبْرُكَ إِلَّا بِاللَّهِ"

records = detect(text, settings=Settings())
annotated = annotate(text, settings=Settings())

أداة سطر الأوامر (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

الواجهة العامة (Public API)

الواجهة العامة مقصودة لتكون صغيرة وبسيطة:

• quran_detector.detect(text: str, settings: Settings = Settings()) -> list[dict]
• quran_detector.annotate(text: str, settings: Settings = Settings()) -> str
• quran_detector.Settings (كائن إعدادات)

داخليًا، يتم إنشاء كائن Engine وحيد (singleton) عند أول استدعاء بشكل كسول، ويعتمد على موارد القرآن المرفقة داخل الحزمة.

صيغة الخرج

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

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

ملاحظات:

• الفهارس هي مواقع كلمات وليست إزاحات حروف.
• إذا كان التطابق يغطي أكثر من آية متتالية فستجد aya_end > aya_start و verses تحتوي أكثر من مقطع.

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

كائن Settings يتحكم في سلوك المطابقة:

• find_errors: bool = True
  تفعيل تصحيح أخطاء الإملاء (مسافة Levenshtein تساوي 1 بين كلمة الإدخال وأحد أبناء العقدة في الـ trie).
• find_missing: bool = True
  تفعيل اكتشاف الكلمات الناقصة عبر السماح بـ “تخطّي” كلمة داخل مسار الـ trie (مكلف حسابيًا؛ انظر الورقة).
• allowed_error_pct: float = 0.25
  أقصى نسبة للأخطاء المسموحة مقارنة بطول التطابق (عدد الكلمات). السجلات التي تتجاوز هذا الحد يتم استبعادها.
• min_match: int = 3
  الحد الأدنى لعدد الكلمات لتكوين مقطع صالح (الافتراضي في الورقة هو 3).
• delimiters: str = GLOBAL_DELIMITERS
  تعبير Regex لفصل/إزالة علامات الترقيم من الكلمات قبل المطابقة.

خيارات CLI تُطابق هذه الحقول 1:1:

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

كيف يعمل الوسم (Annotation)

الدالة annotate() تُرجع نصًا يتم فيه استبدال المقاطع المطابقة بالنص الأصلي للقرآن (كما هو مخزّن في الموارد المرفقة) مع إضافة وسم مرجعي:

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

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

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

على مستوى عالٍ، هذه طريقة مطابقة أنماط متعددة مستوحاة من Aho–Corasick، لكنها في الورقة مُنفّذة عبر “linked hash tables”، وفي هذا المشروع تُنفّذ ببنية trie مخصصة لاكتشاف مقاطع الآيات بكفاءة.

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

للتفاصيل النظرية والخوارزمية، راجع الورقة البحثية من خلال الرابط في الأعلى.

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

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

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

يتم تحميل الموارد عبر 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 دقيقة لكل مجموعة على جهاز محمول.