Record retrieval and Gemma evaluation results

SovereignAI-Starter/ROADMAP.md

@@ -6,6 +6,8 @@
 
 - تحقق تشغيل حديث: أُعيد تشغيل FastAPI على `127.0.0.1:8000` من نسخة المشروع الحالية مع Ollama وGemma 4؛ `/health` أعاد `ok`، والجلسة المحلية أكدت وضع الوكيل متعدد الخطوات وحده 3، وتجربة API حية اختارت `calculator` وأعادت `391.0` لـ17×23. في 2026-10-03 اختُبر أيضًا طلب بحث+حساب حي: `search_workspace` أعاد `MAX_AGENT_TOOL_CALLS = 3` من `app/main.py`، ثم الحاسبة أعادت `21` لـ3×7 في خطوتين. بقي تطبيق Windows Debug شغّالًا، وظل ملف SQLite المحلي موجودًا في مساره. اختبارات Python الكاملة 83/83؛ اختبارات Flutter 15/15 و`flutter analyze` بلا ملاحظات من الجولة السابقة، ولم تتغير واجهة Flutter في هذه الخطوة.
 
+- 2026-10-03: أعيد تقييم البحث الهجين على 9 أسئلة بملفات المشروع الفعلية. فُهرست 4 ملفات بنموذج `granite-embedding:278m`، وأعاد البحث الملف المقصود ضمن أول 3 نتائج في 9/9، وفي المركز الأول في 6/9، ووجد النص الداعم المتوقع في 8/9؛ `MRR=0.833`. صُحح توقع اختبار PDF من قيمة افتراضية قديمة إلى الثابت الحقيقي `MAX_PDF_PAGES = 30`. بقي سؤال صلاحيات الأداة دون المقطع الدقيق في `main.py`. التقرير `evals/results/retrieval_2026-10-03_145357.json`. التقييم صغير ويقيس الاسترجاع لا جودة إجابة Gemma؛ لم تحصل مراجعة بشرية بعد. أداة التقييم صارت تستخدم جلسة loopback مؤقتة وتلغيها، وتسجل نمط البحث والتضمين، مع مهلة أطول للفهرسة على CPU.
+
 - الأساس المحلي يعمل: Flutter Windows Debug ↔ FastAPI ↔ Ollama، مع سجل SQLite للمحادثات ونسخ الإجابات. Gemma 4 E2B هو الافتراضي للنصوص، وطلبات الصور وPDFات الممسوحة تتحول تلقائيًا إلى Ministral 3:3b المحلي عند توفره. أضيف عقد أدوات الوكيل وسجل تدقيق للبيانات الوصفية فقط؛ ينفذ الوكيل حتى ثلاث خطوات أدوات مسموحة بالتتابع ثم يعيد النتائج إلى Gemma لصياغة الرد. عند طلب المستخدم البحث صراحةً في المشروع، يجلب الخادم مقتطفات المساحة المخصصة أولًا ويمررها كبيانات غير موثوقة. توجد ثلاث مهارات محلية قابلة للاختيار مع قائمة أدوات مسموحة يتحقق منها الخادم في كل خطوة. فهرس SQLite يدعم FTS5 وتضمينات Granite محلية اختيارية لملفات النص والكود وPDF الرقمي والممسوح والمختلط؛ PDF الممسوح يفهرس أول 3 صفحات عبر OCR الاختياري. الوكيل يسترجع المقاطع نصيًا ودلاليًا ويهمل النتائج القديمة عند تغير الملف. تجربة تضمين API حقيقية أعادت الملف المقصود أولًا في 3/3 أسئلة عربية؛ بقي توسيع التقييم على ملفات واقعية ومعايرة OCR وترتيب الأعمدة.
 - اكتملت وظائف المحادثة الأساسية وطبقة مزوّد Ollama، بما فيها جداول Markdown القابلة للتمرير والقوائم المتداخلة ومربعات مهام GFM؛ اجتاز التطبيق تحليل Flutter و10 اختبارات واجهة وحالة.
 - الوكيل يقرأ ملفات يختارها المستخدم، ويمكنه اقتراح إنشاء/تحديث ملف داخل مساحة العمل فقط. يعرض التطبيق diff ويطلب الموافقة قبل الكتابة؛ لا يخزّن الخادم الملفات ولا يشغل كودها. يبث الخادم مراحل التحقق واختيار الأداة والتنفيذ وصياغة الرد إلى واجهة Flutter.
@@ -131,7 +133,7 @@
 - [x] حذف مستندات محددة من فهرس SQLite عبر API وزر الواجهة. قبل إعادة أي مقطع يتحقق البحث من بصمة الملف؛ إذا تغيّر أو اختفى يحذف فهرسه القديم، ثم يعاد فهرسته باختيار المستخدم؛ تغطي اختبارات Python كشف التغيير.
 - [x] فحص استرجاع أولي من 11 سؤالًا عربيًا وإنجليزيًا على API حي. ظهرت مشكلة مرادفات عربية في سؤال الصوت وترتيب ضعيف لسؤال تحويل الصور؛ أضفنا توسيعًا محدودًا لمرادفات التفريغ الصوتي وأعدنا التقييم: Hit@1=1.0 وHit@3=1.0 وMRR=1.0 ومعدل ظهور الدليل=1.0. قبل التحسين كان Hit@1=0.818. حُذفت ملفات التقييم المؤقتة من الفهرس بعد القياس. النتائج: `retrieval_2026-10-02_140339.json` و`retrieval_2026-10-02_140538.json`. تبقى العينة مصطنعة وصغيرة، فلا تثبت جودة عامة.
 - [x] قياس إضافي على 9 أسئلة عن ملفات الكود الفعلية (`workspace.py`, `knowledge.py`, `pdf_documents.py`, `main.py`). كشف التقييم أن تكرار مقاطع الملف الواحد يزاحم مصادر أخرى؛ حدّثنا البحث لجلب مجموعة أوسع ثم توزيع حتى مقطعين لكل ملف. بعد التعديل: Hit@1=0.667، Hit@3=1.0، MRR=0.833، وظهور الدليل=1.0. النتائج في `retrieval_2026-10-02_141132.json` (قبل التعديل) و`retrieval_2026-10-02_141337.json` (بعده). العينة صغيرة واختبارها معجمي؛ الدقة الدلالية وجودة الإجابة لم تُقاسا.
-- توسيع التقييم إلى مستندات واقعية أطول وPDFات ومسائل بصياغات بعيدة عن مفردات المصدر، ثم مراجعة بشرية لجودة إجابات النموذج فوق السياق المسترجع.
+- [ ] توسيع تقييم الاسترجاع إلى مستندات أطول وPDFات وأسئلة بعيدة عن ألفاظ المصدر، وتحسين استرجاع المقاطع العميقة (في القياس الحالي لم يظهر مقطع فحص صلاحيات الأداة)، ثم مراجعة بشرية لجودة إجابات النموذج فوق السياق المسترجع. قياس 2026-10-03: 9 حالات على 4 ملفات كود، `Hit@1=0.667`, `Hit@3=1.0`, `MRR=0.833`, وظهور الدليل `8/9` باستخدام البحث الهجين المحلي. لا تمثل هذه العينة الصغيرة اكتمال البند.
 - [x] مهارات محلية أولية قابلة للاختيار من واجهة وضع الوكيل: شرح الكود، مراجعة الكود، وخطة اختبارات. تعرض `/v1/agent/skills` وصف كل مهارة وأدواتها؛ تُحقن التعليمات الموثوقة في سياق الوكيل وتُفلتر قائمة الأدوات، ويرفض الخادم استدعاء أداة خارج صلاحيات المهارة. لمهارة مراجعة الكود معاينة فقط ولا تطبيق مباشر. اجتازت اختبارات الصلاحيات والواجهة؛ يبقى تقييم دقة كل مهارة على أمثلة أكثر قبل اعتمادها افتراضيًا.
 - [x] قراءة رابط عام محدد عبر `POST /v1/web/read`: استخراج نص HTML الثابت وتمريره إلى Gemma المحلية للإجابة مع إرجاع الرابط والعنوان.
 - [x] بحث ويب متعدد المصادر تجريبي عبر DuckDuckGo بلا مفتاح API: اختيار نطاقات مختلفة، محاولة جلب الصفحات العامة، تلخيص بالنموذج المحلي مع روابط المصادر، ووسم المقتطفات عند تعذر فتح الصفحة. (2026-10-01: استجابة حية أعادت ملخصًا ومصدرين مختلفين عبر FastAPI/Gemma.) أضيف زمن جلب إجمالي وزمن لكل مصدر إلى الاستجابة لمساعدة تشخيص المصادر البطيئة؛ اختبارات الحجب ومزوّد رسمي اختياري ما زالت لاحقًا.
@@ -147,7 +149,7 @@
 ## المرحلة 7 — تقييم النماذج والتدريب
 
 - [x] إنشاء مجموعة أولية من خمسة أسئلة عربية/برمجية مع معايير مراجعة بشرية وفحوص شكل/قيمة محدودة، ومشغّل يسجل الأجوبة ووقت كل طلب واسم أداة الوكيل في JSON. تجربة واحدة على Gemma 4 E2B وQwen 2.5 1.5B وحُفظت النتائج في `evals/results/` (2026-10-02).
-- تكرار التقييم مع إجابات مرجعية ومراجعين/درجات بشرية، وقياس استهلاك الذاكرة وتوحيد حالة الإحماء قبل اعتماد مقارنة بين النماذج. أضيف الإحماء وجرى تشغيل مرة إضافية لكل نموذج على خمسة أسئلة؛ هذه العينة اتجاهية ولم تُكرر عدة مرات ولم تُراجع من المستخدم. الجولة السابقة كانت Gemma 8/10 بمتوسط 16.32 ثانية؛ Qwen 5/10 بمتوسط 8.93 ثانية. أظهرت الجولة الدافئة تفاوتًا في اتباع التعليمات، كما أظهرت أن الحساب المباشر قد يتجاوز الأداة وأن Qwen قد يرسل صيغة رياضية غير معيارية؛ عولج المساران واختُبر كل نموذج على طلب الحاسبة، لكن يلزم إعادة تقييم المجموعة كاملة بعد الإصلاح مع مراجعة بشرية وقياس الذاكرة.
+- تكرار التقييم مع إجابات مرجعية ومراجعين/درجات بشرية، وقياس استهلاك الذاكرة واعتماد مقارنة قابلة للتكرار. (2026-10-03: أُعيد تشغيل المجموعة بعد إصلاحات الوكيل على Gemma 4 E2B مع warmup 24.5 ثانية؛ 5/5 طلبات بلا أخطاء، الفحوص التلقائية 4/4، ومتوسط زمن الرد 14.61 ثانية، الوسيط 12.91، والمدى 0.03–25.93 ثانية. تقرير `evals/results/gemma4_e2b_2026-10-03_175827.json`. الإجابات محفوظة للمراجعة، لكن التقييم البشري فارغ. قراءة عملية Ollama وحدها أعطت 120.7MB private/87MB working set بعد التشغيل؛ هذا لا يشمل بالضرورة عامل النموذج أو ذاكرة الأوزان، فلا يُعد قياسًا صالحًا لاستهلاك النموذج. تبقى درجات بشرية، قياس RAM/VRAM peak موثوق، وإعادة متعددة لتوحيد المقارنة.) الجولة الدافئة السابقة كانت Gemma 8/10 بمتوسط 16.32 ثانية وQwen 5/10 بمتوسط 8.93 ثانية. أظهرت آنذاك مشكلة الحساب المباشر مقابل الأداة وصيغة Qwen الرياضية؛ أُصلح المساران، وأداة التقييم الآن تستخدم جلسة loopback مؤقتة.
 - اختيار النماذج حسب الرخصة، الجودة، اللغة، دعم الأدوات، كمية VRAM، وإمكانية التشغيل التجاري. لا نعتمد وصف «مفتوح» وحده كإثبات سماح تجاري؛ نراجع الرخصة الرسمية لكل إصدار.
 - تحسين أولي عبر prompts وRAG والأدوات؛ هذه غالبًا تعالج نقص المعرفة أو القدرة على الفعل دون تغيير أوزان النموذج.
 - عند توفر GPU مناسب: تجربة LoRA/QLoRA على بيانات مرخصة ومنقحة، ومقارنة النتائج بالمجموعة المرجعية قبل اعتماد adapter.