Skip to content

Commit 33c7f61

Browse files
DrAbdulmalekDrAbdulmalek
committed
Initial commit — من محادثة DeepSeek 1m3ih8eveq98lv7aqc (مدقَّق ومصحَّح)
0 parents  commit 33c7f61

15 files changed

Lines changed: 791 additions & 0 deletions

File tree

‎.github/workflows/ci.yml‎

Lines changed: 24 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,24 @@
1+
name: ci
2+
on:
3+
push:
4+
branches: [main]
5+
pull_request:
6+
jobs:
7+
test:
8+
runs-on: ubuntu-latest
9+
strategy:
10+
matrix:
11+
python-version: ["3.10", "3.11", "3.12"]
12+
steps:
13+
- uses: actions/checkout@v4
14+
- uses: actions/setup-python@v5
15+
with:
16+
python-version: ${{ matrix.python-version }}
17+
- name: Install (dev only — scaffold is dependency-free)
18+
run: |
19+
python -m pip install --upgrade pip
20+
pip install -e ".[dev]"
21+
- name: Lint (ruff)
22+
run: ruff check src tests || true
23+
- name: Test
24+
run: pytest -q

‎.gitignore‎

Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,16 @@
1+
__pycache__/
2+
*.py[cod]
3+
*.egg-info/
4+
build/
5+
dist/
6+
.venv/
7+
venv/
8+
.pytest_cache/
9+
.ruff_cache/
10+
.mypy_cache/
11+
# بيانات ونماذج ضخمة — لا تُرفع
12+
data/
13+
models/
14+
*.qdrant/
15+
qdrant_storage/
16+
.env

‎LICENSE‎

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
MIT License
2+
3+
Copyright (c) 2026 Dr Abdulmalek Al-Husseini
4+
5+
Permission is hereby granted, free of charge, to any person obtaining a copy
6+
of this software and associated documentation files (the "Software"), to deal
7+
in the Software without restriction, including without limitation the rights
8+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9+
copies of the Software, and to permit persons to whom the Software is
10+
furnished to do so, subject to the following conditions:
11+
12+
The above copyright notice and this permission notice shall be included in all
13+
copies or substantial portions of the Software.
14+
15+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21+
SOFTWARE.

‎README.md‎

Lines changed: 77 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,77 @@
1+
# medical-rag-ar — Arabic Medical RAG
2+
3+
> **الحالة: مرحلة التخطيط/السقالة (planning).** هذا المستودع يوثّق التصميم
4+
> والخطة (12 أسبوعًا) ويضع البنية الأساسية. التنفيذ الفعلي (ingestion/
5+
> retrieval/reasoning) لم يبدأ بعد — الخطة في `docs/PLAN-12WEEKS.md`.
6+
>
7+
> المصدر: محادثة DeepSeek `1m3ih8eveq98lv7aqc` (رسائل 158-161).
8+
9+
## الفكرة
10+
11+
نظام **RAG طبي بالعربية** يجاوب على أسئلة طبية من مستندات عربية — يبني على
12+
أصول المالك الفريدة:
13+
14+
- [`ocr-core`](https://github.com/DrAbdulmalek/ocr-core) — استخراج النص (ميثاق 18 قاعدة)
15+
- [`arabic-medical-glossary`](https://github.com/DrAbdulmalek/arabic-medical-glossary) — ‏470K+ مصطلح
16+
- `arabic-medical-ocr-corrections` (HF) — تصحيحات موثقة
17+
- بيانات طبية/كتب ممسوحة
18+
19+
**لماذا هذا المشروع؟** (من `docs/DECISION_ANALYSIS.md): طبيب + أصول عربية
20+
طبية نادرة + ocr-core جاهز = شيء لا تبنيه شركات أمريكية لا تفهم العربية
21+
الطبية. الجمهور فوري (أطباء/طلاب/باحثون عرب). القياس واضح (دقة إجابة + CER).
22+
23+
## المعمارية
24+
25+
```
26+
Ingestion ─→ Retrieval ─→ Reasoning
27+
(PDF/صور (BM25 + (Qwen 2.5 7B
28+
→ ocr-core dense + محلي +
29+
→ chunking RRF fusion guardrails)
30+
→ embed) Qdrant)
31+
└── Evaluation (500 سؤال/جواب طبي عربي) ──┘
32+
```
33+
34+
| الطبقة | الاختيار | السبب |
35+
|---|---|---|
36+
| OCR | `ocr-core` (Tesseract + Paddle) | موجود، يعمل |
37+
| Embeddings | `BAAI/bge-m3` أو `aubmindlab/bert-base-arabertv2` | عربي جيد، مفتوح |
38+
| Vector store | Qdrant (محلي) | سريع، Python-first |
39+
| LLM | Qwen 2.5 7B Instruct (محلي) | الأفضل للعربية حاليًا |
40+
| Fusion | RRF (Reciprocal Rank Fusion) | دمج BM25 + dense |
41+
| الواجهة | Gradio (HF Space) ثم Next.js | سرعة إطلاق |
42+
43+
## البنية
44+
45+
```
46+
src/medical_rag_ar/
47+
├── ingestion/ pdf_processor · chunker · embedder · indexer
48+
├── retrieval/ bm25 · dense · fusion (RRF)
49+
├── reasoning/ llm · guardrails · answer
50+
├── evaluation/ 500 Q/A · metrics (دقة + CER + زمن)
51+
└── demo/ Gradio HF Space
52+
```
53+
54+
## التثبيت (سقالة)
55+
56+
```bash
57+
pip install -e ".[dev]" # أدوات التطوير فقط
58+
pip install -e ".[ingest]" # ocr-core + sentence-transformers + qdrant
59+
pip install -e ".[retrieval]" # rank_bm25 + qdrant-client
60+
pip install -e ".[llm]" # transformers + torch (Qwen 2.5)
61+
pip install -e ".[all]"
62+
```
63+
64+
## الوثائق
65+
66+
- `docs/DECISION_ANALYSIS.md` — لماذا هذا المشروع (4 سيناريوهات مُقارنة)
67+
- `docs/PLAN-12WEEKS.md` — الخطة الأسبوعية التفصيلية (الأسبوع 1-12)
68+
- `docs/ARCHITECTURE.md` — المعمارية والقرارات التقنية
69+
70+
## القاعدة الأولى (من الخطة)
71+
72+
> يُبنى على 4 مستودعات فقط (ocr-core + arabic-medical-glossary +
73+
> arabic-medical-ocr-corrections + هذا). الباقي يُجمَّد 12 أسبوعًا.
74+
75+
## الترخيص
76+
77+
MIT (الكود). النماذج: Qwen 2.5 (Apache-2.0)، bge-m3 (MIT)، AraBERT (Apache-2.0).

‎docs/ARCHITECTURE.md‎

Lines changed: 50 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,50 @@
1+
# المعمارية — medical-rag-ar
2+
3+
> تفصيل الخطة الزمنية في `PLAN-12WEEKS.md` وتحليل القرار في `DECISION_ANALYSIS.md`.
4+
5+
## تدفق البيانات
6+
7+
```
8+
PDF/صور طبية
9+
│ (1) ingestion/pdf_processor.py ← ocr-core (Tesseract+Paddle، ميثاق 18 قاعدة)
10+
▼
11+
نص خام + metadata
12+
│ (2) ingestion/chunker.py ← تقسيم بالفقرة/العنوان (لا بالحرف)
13+
▼
14+
chunks
15+
│ (3) ingestion/embedder.py ← bge-m3 / AraBERT (sentence-transformers)
16+
▼
17+
vectors ──(4) ingestion/indexer.py──▶ Qdrant
18+
19+
سؤال عربي
20+
│ (5) retrieval/bm25.py + retrieval/dense.py (Qdrant)
21+
▼ (6) retrieval/fusion.py — RRF (Reciprocal Rank Fusion)
22+
أفضل K chunks
23+
│ (7) reasoning/llm.py — Qwen 2.5 7B Instruct (محلي)
24+
│ (8) reasoning/guardrails.py — رفض الإجابة بلا دليل + تحذير طبي
25+
▼
26+
إجابة + استشهادات (chunks المصدر)
27+
```
28+
29+
## القرارات التقنية
30+
31+
| القرار | الاختيار | البديل المرفوض | السبب |
32+
|---|---|---|---|
33+
| OCR | ocr-core | إعادة بناء | موجود ومُختبَر (485 اختبارًا) |
34+
| Fusion | RRF | weighted-sum | بلا معاملات لضبطها، قوي |
35+
| LLM | Qwen 2.5 7B محلي | API خارجي | خصوصية + تكلفة + عربية قوية |
36+
| Vector DB | Qdrant محلي | FAISS | Python-first + فلترة metadata |
37+
| Guardrails | رفض بلا دليل | إجابة حرة | طبي — لا هلوسة |
38+
39+
## مجموعة التقييم (evaluation/)
40+
41+
- 500 سؤال/جواب طبي عربي **موثق المصدر** (من كتب المالك + مسارد).
42+
- مقاييس: دقة الإجابة (LLM-as-judge + بشري على عينة)، ‏CER للاستخراج،
43+
زمن الاستجابة، recall@k للاسترجاع.
44+
- مقارنة أساس: GPT-4 على نفس الأسئلة (للإبلاغ فقط — لا اعتماد).
45+
46+
## حدود أمانة
47+
48+
- لا يوجد كود تنفيذي بعد — هذه سقالة + خطة.
49+
- guardrails الطبية **إلزامية** قبل أي عرض على مستخدم نهائي.
50+
- Qwen/bge تُحمّل أوزانًا خارجية — راجع التراخيص قبل النشر التجاري.

‎docs/DECISION_ANALYSIS.md‎

Lines changed: 188 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,188 @@
1+
<!-- المصدر: محادثة DeepSeek 1m3ih8eveq98lv7aqc — رسالة 159 -->
2+
3+
4+
# اختيار المشروع الواحد — تحليل قرار
5+
6+
## معايير الاختيار (5 معايير فقط)
7+
8+
| المعيار | الوزن | لماذا |
9+
|---------|-------|-------|
10+
| **التميز العالمي** | 30% | لا يوجد منافس مباشر |
11+
| **استغلال الأصول الفريدة** | 25% | يستخدم ما لا يملكه غيره |
12+
| **قابلية القياس برقم واحد** | 20% | يمكن إثبات القيمة |
13+
| **الجمهور الواضح** | 15% | من سيستخدمه غدًا |
14+
| **الزمن حتى الإطلاق** | 10% | كم شهر |
15+
16+
## المقارنة — 4 سيناريوهات
17+
18+
### السيناريو A: `ocr-core` كمنتج مستقل
19+
20+
**القصة**: "مكتبة OCR عربية بمعايير إنتاجية + ميثاق دليل بصري"
21+
22+
| المعيار | التقييم |
23+
|---------|---------|
24+
| التميز | ⚠️ متوسط — Tesseract/Paddle موجودان |
25+
| الأصول | ✅ يستخدم الميثاق (فريد) |
26+
| القياس | ✅ CER/WER |
27+
| الجمهور | ⚠️ مطورون (محدود) |
28+
| الزمن | ✅ 6-8 أسابيع |
29+
30+
**النتيجة**: 300-600 نجمة محتملة. **لكن ليس "حديث الجميع".**
31+
32+
### السيناريو B: `arabic-vdr-benchmark`
33+
34+
**القصة**: "أول معيار تقييم عربي بصري متعدد المجالات"
35+
36+
| المعيار | التقييم |
37+
|---------|---------|
38+
| التميز | ✅ فريد تمامًا |
39+
| الأصول | ⚠️ يستخدم جزءًا |
40+
| القياس | ✅ nDCG@5 |
41+
| الجمهور | ❌ باحثون فقط (صغير) |
42+
| الزمن | ✅ 2-3 أشهر |
43+
44+
**النتيجة**: 200-500 نجمة، **اقتباسات أكاديمية أكثر من النجوم.** قيمة غير مباشرة.
45+
46+
### السيناريو C: `Arabic Medical RAG`
47+
48+
**القصة**: "طبيب بنى نظام RAG يجاوب على أسئلة طبية من مستندات عربية — الوحيد من نوعه"
49+
50+
| المعيار | التقييم |
51+
|---------|---------|
52+
| التميز | ✅ **لا يوجد مثيل** |
53+
| الأصول | ✅ **يستخدمها كلها**: ocr-core + مسارد + تصحيحات + بيانات طبية |
54+
| القياس | ✅ دقة الإجابة + CER + زمن الاستجابة |
55+
| الجمهور | ✅ **أطباء عرب + طلاب طب + باحثون** |
56+
| الزمن | ⚠️ 4-5 أشهر |
57+
58+
**النتيجة**: 500-2000 نجمة. **الأعلى إمكانيًا.**
59+
60+
### السيناريو D: تدريب نموذج OCR عربي طبي
61+
62+
**القصة**: "نموذج OCR عربي يتفوق على Tesseract في المجال الطبي"
63+
64+
| المعيار | التقييم |
65+
|---------|---------|
66+
| التميز | ⚠️ موجودة (DeepSeek-OCR، PaddleOCR) |
67+
| الأصول | ✅ يستخدم dataset التصحيحات |
68+
| القياس | ✅ CER/WER |
69+
| الجمهور | ⚠️ مطورون |
70+
| الزمن | ❌ 6-9 أشهر (تحتاج GPU) |
71+
72+
**النتيجة**: قد لا يتفوق فعليًا على النماذج الكبيرة. **مخاطرة عالية.**
73+
74+
## التوصية: `Arabic Medical RAG`
75+
76+
### لماذا؟
77+
78+
**1. هذا الشيء الذي لا يستطيع أحد تقليده بسهولة**
79+
80+
- أنت **طبيب** → تفهم ما يحتاجه الطبيب
81+
- لديك **470K+ مدخل طبي عربي** → لا يوجد مثيل
82+
- لديك **319 تصحيحًا موثقًا** → dataset نادر
83+
- لديك **ocr-core** → جاهز تقنيًا
84+
85+
**منافسك الوحيد**: شركات أمريكية لا تفهم العربية الطبية. لن يبنوا هذا.
86+
87+
**2. له جمهور فوري**
88+
89+
- 50,000+ طبيب عربي على Telegram
90+
- 200,000+ طالب طب عربي
91+
- 10,000+ باحث عربي
92+
93+
**3. القياس واضح**
94+
95+
- "أجاب على 500 سؤال طبي بدقة 85%"
96+
- "استخرج نصًا عربيًا بـ CER 8%"
97+
- "أسرع من ChatGPT الطبي بـ 3× (محلي، بلا API)"
98+
99+
**4. القيمة الحقيقية**
100+
101+
هذا ليس "مشروع GitHub". هذا **منتج**. يساعد مريضًا فعليًا.
102+
103+
### ما ستبنيه (3 أشهر)
104+
105+
**الشهر 1: النواة**
106+
```
107+
medical-rag-ar/
108+
├── ingestion/ ← يستخدم ocr-core + مسارد
109+
├── retrieval/ ← ColPali أو BM25 + embeddings
110+
├── reasoning/ ← LLM محلي (Qwen 2.5 7B أو Llama 3.1)
111+
├── evaluation/ ← مجموعة 500 سؤال/جواب موثقة
112+
└── demo/ ← Hugging Face Space
113+
```
114+
115+
**الشهر 2: التقييم**
116+
- جمع 500 سؤال طبي عربي حقيقي
117+
- تشغيل النظام + قياس الدقة
118+
- مقارنة مع GPT-4 على نفس الأسئلة
119+
- نشر النتائج
120+
121+
**الشهر 3: الإطلاق**
122+
- HF Space يعمل
123+
- README مع GIF
124+
- إعلان في r/medicine_ar + Telegram
125+
- paper قصير (اختياري)
126+
127+
### المؤشرات المتوقعة
128+
129+
| الشهر | النتيجة |
130+
|-------|---------|
131+
| 1 | POC يعمل محليًا |
132+
| 2 | 200 نجمة + demo حي |
133+
| 3 | 500-1000 نجمة + اقتباسات |
134+
| 6 | 1500+ نجمة + مستخدمون فعليون |
135+
| 12 | "المرجع" العربي الطبي |
136+
137+
### المخاطر الحقيقية
138+
139+
| المخاطرة | الحل |
140+
|----------|------|
141+
| LLM عربي ضعيف | استخدم Qwen 2.5 7B (الأفضل للعربية) |
142+
| بطء الاسترجاع | Qdrant + FAISS |
143+
| جودة OCR | ابدأ بمستندات مطبوعة، تجاهل الخط اليدوي للمرحلة 2 |
144+
| بيانات ناقصة | استخدم PubMed Arabic + مواقع طبية عربية |
145+
| تشتت مجددًا | **القاعدة الصارمة**: لا مشروع آخر قبل إطلاق v1 |
146+
147+
## ما يجب أن تتخلى عنه
148+
149+
**كل هذا يُجمَّد أو يُؤرشف**:
150+
- marathon_ted_pipeline (اهتمام جانبي)
151+
- tg-campaign-toolkit (أدوات، لا منتج)
152+
- 35 مستودعًا آخر
153+
- نظام الأوامر (يبقى في ocr-core كأداة داخلية)
154+
- المحرر التفاعلي (ميزة، لا مشروع)
155+
156+
**يبقى فقط**:
157+
- `medical-rag-ar` ← المنتج
158+
- `ocr-core` ← التبعية
159+
- `arabic-medical-glossary` ← البيانات
160+
- `arabic-medical-ocr-corrections` ← البيانات
161+
162+
**الباقي → أرشف أو ادمج.**
163+
164+
## اختبار الحقيقة (اسأل نفسك)
165+
166+
قبل أن تقرر، أجب على 3 أسئلة:
167+
168+
**1. لو كان لديك 3 أشهر فقط، ما الذي تريد أن يراه الناس؟**
169+
- مستودع `ocr-core` أكثر نضجًا؟ ← السيناريو A
170+
- معيار تقييم؟ ← السيناريو B
171+
- **نظام يجيب على أسئلة طبية بالعربية؟** ← السيناريو C
172+
173+
**2. من الجمهور الذي تريد أن يفخر بك؟**
174+
- مطورون (A, B, D) ← جمهور صغير، نقد تقني
175+
- **أطباء عرب (C)** ← جمهور أكبر، تأثير مباشر
176+
177+
**3. لو نجح 100%، ما الذي سيتغير؟**
178+
- A, B, D: مجتمع OCR عربي أفضل
179+
- **C: أطباء عرب يستخدمونه يوميًا**
180+
181+
## السؤال الأخير لك
182+
183+
هل تختار **السيناريو C (Arabic Medical RAG)**؟
184+
185+
- **نعم** ← أعطيك خطة 3 أشهر تفصيلية بأسبوع
186+
- **لا، أفضل A** ← أعطيك خطة ocr-core
187+
- **لا، أفضل B** ← أعطيك خطة benchmark
188+
- **لا، لا أعرف بعد** ← أعطني إجابة صادقة: ما الذي يمنعك من القرار؟

0 commit comments

Comments
 (0)