quran-detector-api

خدمة FastAPI جاهزة للإنتاج تقوم بتوفير واجهات HTTP لاستخدام مكتبة quran-detector.

الرابط العام: https://quran-detector-api.ieasybooks.com/

التوثيق (OpenAPI)

• OpenAPI: /openapi.json
• Swagger UI: /docs
• ReDoc: /redoc

مميزات الخدمة

• نقطة نهاية لاكتشاف الآيات/المقاطع: POST /v1/detect.
• نقطة نهاية لوسم النص وإرجاعه: POST /v1/annotate.
• نقاط فحص جاهزية وصحة: /v1/healthz و /v1/readyz.
• تحميل محرك الكشف عند الإقلاع (warm startup) لضمان استجابة أسرع.
• حدود واضحة لحجم النص والطلب.
• دعم CORS (اختياري) لاستخدام الخدمة مباشرة من المتصفح.

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

• Python بإصدار 3.12 أو أحدث.
• يُفضّل استخدام uv لإدارة الاعتماديات.
• إذا كنت تريد التشغيل محليًا بنفس بيئة المشروع: mise (اختياري).

التشغيل السريع

المتطلبات: mise (Python 3.12) و uv.

cd quran-detector-api
mise trust
mise install
uv sync
uv run quran-detector-api

العنوان الافتراضي: http://127.0.0.1:8000

الواجهات (API)

المسار الأساسي: /v1

Health

• GET /v1/healthz → {"status":"ok"} (الخدمة تعمل)
• GET /v1/readyz → {"status":"ok"} (المحرك تم تهيئته)

Detect

POST /v1/detect

نموذج الطلب:

{
  "text": "string (1..5000 chars)",
  "settings": {
    "find_errors": true,
    "find_missing": true,
    "allowed_error_pct": 0.25,
    "min_match": 3,
    "delimiters": "optional override"
  }
}

نموذج الاستجابة:

{
  "matches": [
    {
      "surah_name": "الإخلاص",
      "verses": ["قل هو الله احد"],
      "errors": [[]],
      "start_in_text": 0,
      "end_in_text": 4,
      "aya_start": 1,
      "aya_end": 1
    }
  ]
}

Annotate

POST /v1/annotate

نموذج الطلب:

{
  "text": "string (1..5000 chars)",
  "settings": {
    "find_errors": true,
    "find_missing": true,
    "allowed_error_pct": 0.25,
    "min_match": 3,
    "delimiters": "optional override"
  }
}

نموذج الاستجابة:

{ "annotated_text": "..." }

الحدود (Limits)

• أقصى طول نص: 5000 حرف (مطبق على مستوى API).
• أقصى حجم للطلب: QD_API_MAX_BODY_BYTES (الافتراضي 65536).

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

متغيرات البيئة (اختيارية):

• QD_API_HOST (default: 127.0.0.1)
• QD_API_PORT (default: 8000)
• QD_API_WORKERS (default: 1)
• QD_API_LOG_LEVEL (default: info)
• QD_API_CORS_ORIGINS (default: empty; comma-separated list, or *)
• QD_API_ROOT_PATH (default: empty; set behind a proxy path prefix)
• QD_API_DOCS_ENABLED (default: true)
• QD_API_MAX_TEXT_LENGTH (default/max: 5000)
• QD_API_MAX_BODY_BYTES (default: 65536)

التطوير

إعادة تشغيل تلقائي (Auto-reload)

uv run uvicorn quran_detector_api.main:app --reload

التشغيل في الإنتاج (Deployment)

تشغيل Uvicorn بعدة workers

uv run uvicorn quran_detector_api.main:app --host 0.0.0.0 --port 8000 --workers 2

التشغيل باستخدام Docker

بناء الصورة:

docker build -t quran-detector-api .

تشغيل الحاوية:

docker run --rm -p 8000:8000 quran-detector-api