Skip to content

ROADMAP.md

Latest commit

 

History

History
executable file
·
390 lines (316 loc) · 22.6 KB

ROADMAP.md

File metadata and controls

executable file
·
390 lines (316 loc) · 22.6 KB
Raw

خارطة طريق التطوير — Omni Medical Suite

هذا المستند يحدد المسار التطويري الشامل لمشروع Omni Medical Suite بناءً على مراجعة شاملة للمستودعات البرمجية (14 مستودع، أكثر من 127 عملية إيداع) والنتائج المكتشفة.

سجل الإصدارات (Release History)

الإصدار التاريخ الحالة أبرز الميزات
v1.1.0 2026-07-19 ✅ Stable P0+P1+P2 hardening sprint — lazy OCR, decision log, HF staging, AppImage, CI matrix, LFS coverage. 174 اختبار ناجح (163 وحدوي + 11 AppImage smoke).
v1.1.0-rc1 2026-07-19 ✅ Merged into v1.1.0 أول مرشح إصدار — 161 اختبار ناجح + 11 AppImage smoke مشروطة.
v1.0.0 2026-07-05 ✅ Stable (legacy) الإصدار الأساسي قبل إعادة الهيكلة — هيكل monorepo، CI/CD متكامل، HF Space عملي.

الخطوات القادمة بعد v1.1.0

الأولوية العنصر الإصدار المستهدف
P3-1 توصيل engine_router.py بـ log_decision() (آخر موقع قرار غير مُTool) v1.1.1
P3-2 HF Space live URL smoke (HTTP 200 + فحص endpoint) v1.1.1
P3-3 خط أساس لأداء الانحدار (P95 latency) لـ OCR + field extraction v1.2.0
P3-4 ترحيل ملفات LFS القديمة (git lfs migrate import) v1.2.0 (منسق)
P3-5 ضبط دقيق لـ NER الطبي العربي v1.2.0

الوضع الحالي (Current State)

ملخص المنظومة الحالية

يتكون المشروع من 14 مستودعًا برمجيًا مترابطًا تغطي سلسلة كاملة من أدوات التعرف الضوئي على الحروف الطبية العربية، بدءًا من المعالجة المسبقة للصور وصولًا إلى التحقق السريري وواجهة المستخدم. تم تسجيل أكثر من 127 عملية إيداع (commit) عبر هذه المستودعات، مما يشير إلى نشاط تطويري مكثف.

ما تم إنجازه حتى الآن

  • بنية CI/CD متكاملة: أنابيب GitHub Actions للبناء والاختبار والنشر عبر Docker وKubernetes
  • أداة Scanner Fixer: معالجة مسبقة متقدمة للصور الممسوحة ضوئيًا مع تطبيق Gradio مستقل
  • HF Space عملي: تطبيق Gradio منشور على Hugging Face مع قدرات OCR أساسية
  • تثبيت إصدارات الحزم: جميع المتطلبات (requirements) مثبتة بإصدارات محددة لضمان الاستقرار
  • واجهة Next.js: واجهة ويب حديثة مع Tailwind CSS وshadcn/ui للمكونات
  • نظام تقييم (Benchmark): مقارنة أداء محركات OCR المختلفة على بيانات طبية عربية
  • تصدير FHIR: بدايات تحويل نتائج OCR إلى موارد FHIR للتكامل مع الأنظمة السريرية
  • بنية الخدمات المصغرة: API، WebSocket، Load Balancer كخدمات منفصلة
  • التعلم التفاعلي: نظام HITL (التعلم بالتدخل البشري) مع قاعدة بيانات الأنماط

التحديات المكتشفة

  1. 10 مشكلات مفتوحة في مستودع ai-fuel-engine تحتاج إلى معالجة
  2. 6 مشكلات مفتوحة في مستودع bilingual-extractor تؤثر على جودة الاستخراج
  3. غياب الاختبارات الآلية المنهجية — نسبة التغطية الحالية غير كافية
  4. عدم توحيد هيكل المجلدات بين المستودعات المختلفة
  5. آلية Ensemble تعتمد على أطول نص بدلًا من الثقة والجودة الدلالية

المرحلة 1: تحسين جودة الكود (Q3 2026)

1.1 الاختبارات الآلية

الهدف

بناء شبكة اختبارات صلبة تضمن عدم تدهور الجودة مع كل تعديل برمجي جديد.

خطة التنفيذ

الاختبارات الوحدوية (Unit Tests):

tests/
├── test_normalization.py          # اختبار توحيد النصوص العربية
├── test_postprocessor.py          # اختبار المعالجة اللاحقة للـ OCR
├── test_spell_checker.py          # اختبار مدققة الإملاء الطبي
├── test_arabic_rtl.py             # اختبار معالجة النص من اليمين لليسار
├── test_engine_router.py          # اختبار توجيه محركات OCR
├── test_result_fusion.py          # اختبار دمج نتائج المحركات المتعددة
├── test_preprocessor.py           # اختبار المعالجة المسبقة للصور
├── test_medical_ner.py            # اختبار استخراج الكيانات الطبية المسماة
└── test_fhir_converter.py         # اختبار تحويل FHIR

اختبارات التكامل:

tests/integration/
├── test_ocr_pipeline.py           # اختبار خط أنابيب OCR الكامل
├── test_scanner_fixer_flow.py     # اختبار تدفق إصلاح الماسح الضوئي
├── test_hf_space_deployment.py    # اختبار نشر HF Space
└── test_api_e2e.py                # اختبار شامل من طرف إلى طرف

الهدف: نسبة تغطية اختبارات 60% كحد أدنى بحلول نهاية Q3 2026.

الأدوات:

  • pytest كإطار عمل رئيسي للاختبارات
  • pytest-cov لقياس نسبة التغطية
  • pytest-mock لمحاكاة التبعيات الخارجية
  • factory-boy لتوليد بيانات الاختبار

1.2 إصلاح المشكلات المفتوحة

ai-fuel-engine — 10 مشكلات مفتوحة

  • أولوية عالية (3 مشكلات): أخطاء في معالجة الصور ذات الدقة المنخفضة، تعطل عند صور فارغة، تسرب ذاكرة في المعالجة الدفعية
  • أولوية متوسطة (4 مشكلات): تحسين سرعة التحميل، دعم صيغ صور إضافية، معالجة أفضل للحدود المائلة، تحسين إدارة السجل
  • أولوية منخفضة (3 مشكلات): توثيق واجهات برمجة التطبيقات، تحسين رسائل الخطأ، إضافة أمثلة للاستخدام

bilingual-extractor — 6 مشكلات مفتوحة

  • أولوية عالية (2 مشكلات): فشل استخراج النصوص المختلطة العربية-الإنجليزية، فقدان السياق الطبي أثناء الاستخراج
  • أولوية متوسطة (3 مشكلات): تحسين التعرف على الجداول، معالجة الرموز الطبية الخاصة، دعم النصوص العمودية
  • أولوية منخفضة (1 مشكلة): تحسين الأداء مع الملفات الكبيرة

استراتيجية الأولوية

  1. بدءًا بالمشكلات ذات الأولوية العالية التي تؤثر على دقة OCR
  2. إنشاء فرع fix/ لكل مشكلة مع اختبارات إعادة الإنتاج
  3. مراجعة الأقران (code review) قبل الدمج في الفرع الرئيسي
  4. إغلاق المشكلة فقط عند تجاوز الاختبارات المرتبطة بها

1.3 توحيد هيكل المجلدات

الهيكل المستهدف

omni-medical-suite/
├── src/
│   ├── ocr/
│   │   ├── engines/               # محركات OCR (EasyOCR, Surya, PaddleOCR)
│   │   ├── preprocessing/         # المعالجة المسبقة للصور
│   │   ├── postprocessing/        # المعالجة اللاحقة للنصوص
│   │   └── ensemble/              # دمج نتائج المحركات
│   ├── nlp/
│   │   ├── normalization/         # توحيد النصوص العربية
│   │   ├── spell_checking/        # التدقيق الإملائي
│   │   ├── ner/                   # استخراج الكيانات المسماة
│   │   └── translation/           # الترجمة والتصحيح
│   ├── medical/
│   │   ├── terminology/           # المصطلحات الطبية
│   │   ├── fhir/                  # تحويل FHIR
│   │   └── validation/            # التحقق السريري
│   ├── api/                       # واجهة برمجة التطبيقات
│   ├── ui/                        # واجهة المستخدم (Gradio + Next.js)
│   └── shared/                    # أدوات مشتركة
├── tests/
├── docs/
├── configs/
└── docker/

قواعد التسمية الموحدة

  • أسماء الملفات: snake_case باللغة الإنجليزية
  • أسماء الدوال: verb_noun مثل extract_entities()
  • أسماء المتغيرات: وصفية باللغة الإنجليزية
  • التعليقات: يمكن أن تكون بالعربية مع توثيق التوثيق العام بالإنجليزية

المرحلة 2: تحسين محرك OCR (Q3–Q4 2026)

2.1 دمج محركات جديدة

Surya لتحليل التخطيط

  • الموقع الحالي: packages/vision/surya_ocr.py — تكامل أولي
  • التحسينات المطلوبة:
    • استغلال قدرات Surya في اكتشاف ترتيب القراءة (Reading Order)
    • تحليل التخطيط متعدد الأعمدة في الوصفات الطبية
    • فصل الرؤوس من المحتوى تلقائيًا
  • الجدول الزمني: Q3 2026 — الأسابيع 1–4

تحسين PaddleOCR للخط العربي اليدوي

  • الموقع الحالي: محرك PaddleOCR مدمج عبر packages/omni-ocr/
  • التحسينات المطلوبة:
    • ضبط دقيق (fine-tuning) لنموذج PaddleOCR على بيانات خط عربي طبي يدوي
    • استخدام مستودع PaddleOCR_Handwritten_Arabic كنقطة انطلاق
    • إضافة نموذج مخصص للوصفات الطبية المكتوبة يدويًا
  • الجدول الزمني: Q3 2026 — الأسابيع 5–8

Ollama للمعالجة اللاحقة بالذكاء الاصطناعي

  • الموقع الحالي: packages/ai/gateway/providers/ollama/ — مزود Ollama موجود
  • التحسينات المطلوبة:
    • تكامل مستودع OCR-Images لاستخدام نماذج LLM محلية في تصحيح نتائج OCR
    • نموذج مُحسَّن لمهام التصحيح الإملائي الطبي العربي
    • تشغيل محلي بالكامل بدون اتصال بالإنترنت
  • الجدول الزمني: Q4 2026 — الأسابيع 1–4

2.2 Meta-Learner للـ Ensemble

المشكلة الحالية

نظام الدمج الحالي يعتمد على heuristic بسيط يختار النص الأطول بين المحركات المختلفة، وهو نهج غير دقيق لأن المحرك قد ينتج نصًا أطول لكنه يحتوي على أخطاء أكثر.

الحل المقترح: Meta-Learner

  • نموذج تصنيف خفيف يتلقى مميزات من كل محرك ويتخذ قرارًا ذكيًا:
    • درجة الثقة (confidence score) من كل محرك
    • خصائص الصورة (الدقة، التباين، مستوى الضوضاء)
    • نوع المستند (وصفة طبية، تقرير مختبر، تقرير إشعاعي)
    • لغة النص (عربي فصحى، عامية، مختلط)
  • آلية الترجيح: ترجيح بناءً على الثقة بدلًا من الطول: 
    weighted_score = Σ(engine_confidence_i × domain_weight_i × quality_factor_i)
  • الجدول الزمني: Q4 2026 — الأسابيع 5–8

2.3 التقييم الدلالي الطبي

مقياس CER الدلالي الطبي (Medical Semantic CER)

  • الفكرة: أخطاء OCR في المصطلحات الطبية أخطر من الأخطاء في الكلمات العادية
  • الآلية:
    • تعريف قاموس للمصطلحات الطبية العربية (حاليًا: medical_terms.json)
    • عند حساب CER، يُطبَّق معامل جزاء 3x على الأخطاء في المصطلحات الطبية
    • مثال: خطأ في كلمة "أموكسيسيلين" يُحسب كثلاثة أخطاء عادية
  • التكامل مع KITAB-Bench:
    • تشغيل التقييم على معيار KITAB-Bench للمقارنة الموضوعية مع أنظمة OCR الأخرى
    • نشر النتائج بشكل دوري كمرجع لمجتمع OCR العربي
  • الجدول الزمني: Q4 2026 — الأسابيع 9–12

المرحلة 3: معالجة اللغة الطبية العربية (Q4 2026)

3.1 NER طبي عربي خفيف

المرحلة الأولى: NER قائم على الأنماط (Regex-based)

  • الكيانات المستهدفة:
    • أسماء الأدوية: أموكسيسيلين 500 ملغ، باراسيتامول شراب
    • الجرعات: 500 ملغ، مرتين يوميًا، بعد الأكل
    • التشخيصات: ارتفاع ضغط الدم، التهاب الجيوب الأنفية
    • الأعمار والأوزان: مريض عمره 45 سنة
    • التواريخ: تواريخ الوصفات والفحوصات
  • الأدوات: regex + قواميس طبية مخصصة + SinaTools للمعالجة الأساسية
  • الموقع المقترح: src/nlp/ner/medical_regex_ner.py
  • الجدول الزمني: Q4 2026 — الأسابيع 1–3

المرحلة الثانية: NER بالتعلم العميق (Future)

  • ضبط دقيق لنموذج AraBERT Medical MLM من Hugging Face على بيانات طبية عربية مُعلَّمة
  • إنشاء مجموعة بيانات تدريبية مُعلَّمة يدويًا (annotated) من الوصفات الطبية الحقيقية
  • استخدام scripts/generate_ner_data.py الحالي كنقطة انطلاق
  • الجدول الزمني: Q1 2027

3.2 BiMediX كـ LLM محلي للتصحيح

البديل عن Jais

  • BiMediX نموذج طبي ثنائي اللغة (عربي-إنجليزي) من MBZUAI
  • المزايا:
    • متخصص في المجال الطبي
    • يدعم العربية بشكل أفضل من النماذج العامة
    • يمكن تشغيله محليًا عبر Ollama
    • مجاني ومفتوح المصدر بالكامل
  • حالات الاستخدام:
    • تصحيح أخطاء OCR في المصطلحات الطبية
    • التحقق من صحة التشخيصات المستخرجة
    • اقتراح التشخيصات البديلة بناءً على السياق
  • التكامل: عبر packages/ai/gateway/providers/ollama/ الحالي
  • الجدول الزمني: Q4 2026 — الأسابيع 4–6

3.3 نظام RAG للأسئلة الطبية

استرجاع هجين (Hybrid Retrieval)

  • BM25: للبحث الدقيق عن المصطلحات الطبية في النصوص
  • Vector Embeddings: للبحث الدلالي والتشابه المعنوي
    • استخدام Qdrant (موجود في البنية التحتية) كقاعدة بيانات متجهة
    • نماذج التضمين: aubmindlab/bert-base-arabertv02 للنصوص العربية
  • تصنيف التخصصات الطبية:
    • تصنيف المستندات الطبية حسب التخصص (باطنة، جراحة، أطفال، إلخ)
    • تحسين نتائج البحث بتصفية حسب التخصص
  • المصدر: مستودع Advancing-Arabic-Medical-QA كمرجع للأسئلة والأجوبة الطبية
  • الجدول الزمني: Q4 2026 — الأسابيع 7–10

المرحلة 4: التكامل السريري (Q1 2027)

4.1 تصدير FHIR

التحويل إلى موارد FHIR

  • الموقع الحالي: services/api/fhir/converter.py — بدايات التحويل
  • الموارد المستهدفة:
    • MedicationRequest: تحويل أوامر الأدوية من الوصفات
    • DiagnosticReport: تحويل تقارير المختبرات
    • Condition: تحويل التشخيصات
    • Patient: استخراج بيانات المريض الأساسية
  • التوافق مع أنظمة المستشفيات:
    • دعم FHIR R4 كإصدار أساسي
    • اختبار التكامل مع أنظمة HIS الشائعة في المنطقة
    • توفير واجهة REST API لتصدير FHIR
  • الجدول الزمني: Q1 2027 — الأسابيع 1–4

4.2 واجهة مستخدم محسّنة

تبويبات Gradio الشاملة

  • تبويب OCR: رفع الصور، اختيار المحرك، عرض النتائج مع التظليل
  • تبويب Scanner Fixer: تحسين جودة الصور الممسوحة ضوئيًا
  • تبويب إدارة البيانات: رفع وتنظيم مجموعات التدريب
  • تبويب التدريب: ضبط دقيق للنماذج على بيانات مخصصة
  • تبويب FHIR: عرض وتصدير نتائج التحويل السريري

تحسينات الواجهة

  • الوضع الداكن (Dark Mode): دعم كامل للعمل في بيئات إضاءة مختلفة
  • دعم RTL: تخطيط كامل من اليمين لليسار للعربية
  • تصميم متجاوب: يعمل على الشاشات الكبيرة والأجهزة المحمولة
  • إمكانية الوصول: دعم قارئات الشاشة ولوحة المفاتيح
  • الجدول الزمني: Q1 2027 — الأسابيع 5–8

4.3 التوزيع

حزمة PyPI

  • إنشاء حزمة omni-medical-suite قابلة للتثبيت عبر pip
  • توفير واجهة برمجية بسيطة: 
    from omni_medical_suite import OCRPipeline
pipeline = OCRPipeline(engines=["surya", "easyocr"])
result = pipeline.process("prescription.jpg")
  • الجدول الزمني: Q1 2027 — الأسابيع 5–6

صور Docker على GHCR

  • صور متعددة الأغراض: cpu, gpu, lite
  • نشر تلقائي عبر GitHub Actions عند كل إصدار جديد
  • توثيق كامل لكل صورة في README
  • الجدول الزمني: Q1 2027 — الأسابيع 7–8

HF Space شامل

  • دمج جميع الميزات في تطبيق HF Space واحد
  • تشغيل على GPU مجاني من Hugging Face
  • تحديث تلقائي عند كل إصدار جديد
  • الجدول الزمني: Q1 2027 — الأسابيع 9–10

المرحلة 5: بناء المجتمع (Q1–Q2 2027)

5.1 التوثيق

التوثيق التقني

  • توثيق API: استخدام mkdocs-material مع mkdocstrings لتوليد التوثيق تلقائيًا من الكود
  • الأدلة التعليمية: سلسلة دروس خطوة بخطوة:
    1. البدء مع Omni Medical Suite
    2. معالجة الوصفات الطبية
    3. تدريب نموذج OCR مخصص
    4. التكامل مع أنظمة المستشفيات
  • عروض توضيحية بالفيديو: تسجيل شاشة لكل ميزة رئيسية
  • الجدول الزمني: Q1 2027 — الأسابيع 1–4

مساهمة المجتمع

  • وسم "Good First Issue": تحديد 20+ مهمة مناسبة للمساهمين الجدد
  • دليل المساهمة محدث: CONTRIBUTING.md شامل مع أمثلة عملية
  • قوالب Issues و Pull Requests: تسهيل عملية المساهمة
  • مراجعة الأقران السريعة: الرد على المساهمات خلال 48 ساعة

5.2 الإصدارات

الإصدارات الدلالية (Semantic Versioning)

  • التنسيق: MAJOR.MINOR.PATCH (مثل 1.2.3)
  • MAJOR: تغييرات غير متوافقة مع الإصدارات السابقة
  • MINOR: ميزات جديدة متوافقة
  • PATCH: إصلاحات أخطاء
  • التكرار: إصدار MINOR كل شهر، PATCH حسب الحاجة

أتمتة سجل التغييرات (Changelog)

  • استخدام conventional-commits لتوحيد رسائل الإيداع
  • توليد CHANGELOG.md تلقائيًا باستخدام commitizen
  • إنشاء GitHub Release تلقائيًا مع ملاحظات الإصدار
  • الجدول الزمني: Q2 2027 — الأسابيع 1–2

5.3 الترويج

ورقة بحثية عن OCR الطبي العربي

  • العنوان المقترح: "Omni Medical Suite: نظام مفتوح المصدر للتعرف الضوئي على الوثائق الطبية العربية"
  • المحتويات:
    • وصف المشكلة: ندرة أدوات OCR الطبي العربي
    • المنهجية: بنية Ensemble متعدد المحركات مع Meta-Learner
    • النتائج: تحسين CER بنسبة X% مقارنة بالمحركات الفردية
    • النشر: Hugging Face، PyPI، Docker
  • المجلات المستهدفة: EMNLP, ACL, أو مجلات طبية رقمية
  • الجدول الزمني: Q2 2027 — الأسابيع 3–8

العروض في المؤتمرات

  • مؤتمرات تقنية: PyCon Arabia, AI Arabia
  • مؤتمرات طبية: مؤتمرات التقنية الصحية الإقليمية
  • ورش عمل: ورشة عمل عملية في Hugging Face Community Events
  • الجدول الزمني: Q2 2027 — الأسابيع 9–12

ملخص الجدول الزمني

المرحلة الفترة المخرجات الرئيسية
المرحلة 1 Q3 2026 اختبارات 60%، إصلاح 16 مشكلة، هيكل موحد
المرحلة 2 Q3–Q4 2026 محركات جديدة، Meta-Learner، تقييم دلالي
المرحلة 3 Q4 2026 NER طبي، BiMediX، نظام RAG
المرحلة 4 Q1 2027 FHIR، واجهة محسّنة، حزمة PyPI
المرحلة 5 Q1–Q2 2027 توثيق شامل، إصدارات منتظمة، ورقة بحثية

ملاحظة: هذه الخارطة حية وستُحدَّث بناءً على التقدم الفعلي وتغذية راجعة من المجتمع. آخر تحديث: يوليو 2025