fix: surface retrieved evidence when model abstains

SovereignAI-Starter/ROADMAP.md

@@ -8,6 +8,10 @@
 
 - 2026-10-04 — إصلاح بطء فهرسة PDF الممسوح الذي كان يوقف حلقة FastAPI: نقل تحليل الصفحات والرسم وOCR إلى worker threads؛ صار فهرس Flutter يرسل ملفًا واحدًا في كل مرة بمهلة 5 دقائق ويعرض اسم الملف ورقمه. أثناء OCR حي استغرق 155.21 ثانية، وظل `/health` يستجيب خلال 0.02 ثانية، واكتمل OCR للصفحة وفهرستها دلاليًا. اجتاز اختبار PDF المختلط 1/1؛ واجتازت Flutter 22/22 و`flutter analyze --no-pub` بلا ملاحظات، واختبارات مهلة الوكيل 4/4. لم يكتمل بناء Windows Debug بهذه التغييرات في هذه الجولة: نسخة التطوير المؤقتة تعطلت بسبب مسار تضمين `flutter_secure_storage_windows` في MSBuild/الرابط الرمزي؛ لم يتغير كاش الحزمة أو مصدرها.
 
+- 2026-10-04 — إكمال التقييم الموسع للاسترجاع وإصلاح امتناع Gemma مع وجود الدليل: شغّلت 14 حالة على API التطبيق، بينها نصوص عربية/إنجليزية ودليل طويل وPDF رقمي وممسوح. فُهرست المستندات دلاليًا 14/14 بـ`granite-embedding:278m`، وأعاد البحث Hit@1/Hit@3/MRR/evidence rate جميعها 1.0؛ جُمعت إجابات الوكيل في `evals/results/retrieval_extended_agent_2026-10-04.json`. كشف الفحص أن Gemma امتنعت في 3 إجابات رغم وجود الدليل؛ وُسّع كشف صيغ الامتناع واختُبرت الحالات الثلاث ثانيةً على API معزول: عرض fallback اقتباس `Groq` و`selected_version` حرفيًا، وأجاب مباشرة عن استثناء `.git`، مع ثبات مقاييس الاسترجاع 1.0. اجتازت اختبارات مهارات الوكيل 21/21. تبقى مراجعة بشرية مستقلة؛ مجموعة fixtures صغيرة ولا تثبت جودة عامة.
+
+- تنبيه نشر محلي (2026-10-04): اختبار fallback الجديد تم على API معزول بمنفذ 8102، ثم أُوقف. خدمة التطبيق على 8000 ظلت تعمل بعملية أقدم ولم أعد تشغيلها حتى لا أفقد إعداد قاعدة البيانات المرتبط بها؛ يلزم إعادة تشغيلها من بيئة التشغيل المعتادة لتفعيل هذا التعديل في الواجهة.
+
 - 2026-10-04 — تدقيق حالة «العمل على مشروع»: تأكد وجود إنشاء مجلد جديد أو تسجيل مجلد قائم من Flutter، وربطه بحساب المستخدم في SQLite، وفتح الملفات والبحث فيها واقتراح إنشاء/تعديل ملف عبر diff وموافقة صريحة. التطبيق وFastAPI/Gemma 4/SQLite يعملون محليًا الآن. الوكيل لا يشغّل بعد أوامر البناء أو الاختبارات؛ prototype AppContainer غير مدمج، وحد التخزين الصلب لم يثبت، لذا التنفيذ الآلي للمشروع ليس مدعومًا. في اختبار الحالتين على API التطبيق وجد الاسترجاع الدليل 2/2 لكن Gemma امتنعت مرة بصياغة عربية جديدة؛ أضيفت الصياغة لاختبار fallback، واختبارات مهارات الوكيل 21/21. أُعيد تشغيل API التطبيق على 8000 من الشفرة الحالية مع قاعدة SQLite نفسها؛ `/health` أكد Gemma 4 وSQLite وبقاء ملف قاعدة المحادثات. تحقق الاختبار الحي من السؤالين: الأول عرض مقتطف `migration.md` مع مصدره، والثاني ذكر الحقول الثلاثة؛ ثم أزال فهرس الاختبار وتسجيل المشروع والجلسة (`evals/results/retrieval_live_api_fix_2026-10-04.json`). التفاصيل في `evals/MODEL_REVIEW_2026-10.md`.
 
 - 2026-10-04 — تسجيل المشاريع في الواجهة والـAPI: عند اختيار مجلد من Flutter يُسجّل API المحلي المسار في SQLite تحت هوية الحساب (`user_workspace_roots`) ثم يسرد الملفات المدعومة؛ عند إزالة المشروع يُلغى التسجيل ولا تُحذف الملفات. أضيف POST/DELETE لـ`/v1/agent/projects` ويُسمح بهما عبر loopback فقط. اختبارات API تثبت التسجيل والقراءة لصاحب المشروع، رفض الحساب الآخر، منع تسجيل مجلد متداخل بين حسابين أو مع جذر خصصه مسؤول لحساب آخر (409)، وإلغاء الوصول بعد الحذف أو بعد حذف المجلد الأصلي. اختبار حي على مجلد خارج جذر المنتج قرأ `README.md`، وسأل Gemma عبر الوكيل فأجاب من المحتوى باسم `Cedar`، ثم تحقق رفض الوصول بعد الإلغاء. اختبارات Python ذات الصلة 10/10 وFlutter 17/17، و`flutter analyze` بلا ملاحظات و`compileall` ناجح. أُعيد تشغيل API وفحص `/health` (`ok`, Gemma 4)، وتأكد وجود مساري POST/DELETE في OpenAPI، وبُني وشُغّل Windows Debug الحالي (PID 1328). تشغيل أوامر البناء/الاختبار من الوكيل لم يُدمج بعد؛ عزل نظام التشغيل لهذا التشغيل ما زال مفتوحًا.
@@ -157,7 +161,7 @@
 - [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` (بعده). العينة صغيرة واختبارها معجمي؛ الدقة الدلالية وجودة الإجابة لم تُقاسا.
 - [x] جولة تحسين استرجاع المقاطع العميقة على 11 سؤالًا من المجموعة المحلية (2026-10-03): توسيع محدود لمرادفات صلاحيات المهارات بالعربية والإنجليزية، ورفع سقف النتائج من 5 إلى 8 مع إبقاء حد 4 مقاطع لكل ملف لحماية تنوع المصادر. على API محلي تجريبي بقاعدة معزولة: `Hit@1=1.0`, `Hit@3=1.0`, `MRR=1.0`, وظهور الدليل `11/11`؛ تقرير `evals/results/retrieval_2026-10-03_160000.json`. اجتازت اختبارات قاعدة المعرفة `12/12`.
 - [x] توسيع الحزمة وإضافة جواب الوكيل من الأدلة المفهرسة (2026-10-03): أضيف دليل تقني بطول 15.7 كيلوبايت فيه المعلومة المستهدفة في المقطع 17 وPDF نصي؛ حفظ المشغّل اختياريًا إجابات الوكيل ومصادرها للمراجعة دون منح درجة آلية. الجولة الأولى على 13 حالة أعادت `Hit@1=1.0`, `Hit@3=1.0`, `MRR=1.0`, وظهور الدليل `13/13` (`evals/results/retrieval_extended_2026-10-03.json`). بعد إصلاح وزن OCR المحلي المعطوب وإعادة تشغيله دون تنزيل، أضيف PDF ممسوح فعلي إلى المجموعة؛ على API التطبيق الحالي بقاعدة SQLite الحية المؤقتة ثم حذف عناصرها بعد القياس: `Hit@1=1.0`, `Hit@3=1.0`, `MRR=1.0`, وظهور الدليل `14/14` (`evals/results/retrieval_extended_14_2026-10-03.json`). جواب الوكيل على PDF الممسوح استخرج الموعد `17 October 2026` وذكر مصدره (`evals/results/retrieval_scanned_pdf_agent_2026-10-03.json`). تجربة EasyOCR المباشرة والـAPI استخدمتا أوزانًا محلية فقط؛ النسخة التالفة محفوظة احتياطيًا بجانب الوزن المُصلح.
-- [ ] متابعة التقييم على ملفات طويلة وPDFات متنوعة وأسئلة جديدة، وجمع مراجعة مستقلة لجودة إجابات النموذج فوق السياق المسترجع. النتائج الحالية fixtures صغيرة ومصطنعة؛ الدرجات تصف هذه الحالات ولا تثبت جودة عامة. في 2026-10-04 جُمعت 14 إجابة محفوظة من المجموعة ذات 11 حالة ومجموعتي PDF الطويل/الممسوح في ورقة مراجعة `evals/HUMAN_REVIEW_2026-10.md` مع سلم موحد وخانات فارغة. أضيفت مقتطفات المرجع بجانب كل إجابة؛ نص PDF الممسوح استُخرج محليًا بـEasyOCR (ثقة 0.591). مراجعة Codex الآلية في `evals/MODEL_REVIEW_2026-10.md` أعطت خط أساس 48/56 وكشفت امتناعين رغم وجود الدليل. بعد إصلاح الامتناع أُعيد تشغيل الحالتين على API 8000؛ ظهرت الأدلة المطلوبة 2/2، وأضيفت الإجابات الجديدة إلى ورقة المراجعة بجانب baseline القديم لئلا يختلط تقييم النسختين. لا يُعد هذا إعادة تقييم للمجموعة كاملة؛ المراجعة البشرية المستقلة ودرجات الحالات الأربع عشرة ما زالت مطلوبة. خلال محاولة إعادة التقييم الموسعة 2026-10-04 تجاوز طلب الفهرسة المجمع مهلة 180 ثانية بسبب تضمينات 14 ملفًا ومعالجة PDF؛ نظّف المشغّل الفهرس وتسجيل المشروع. أضيف `--workspace-dir` لمجلد اختبار فارغ ظاهر مع حذف الملفات ببصمة المحتوى، وصار يفهرس كل ملف بطلب منفصل لتقليل زمن الطلب الواحد. تجربة حالة نصية مفردة نجحت 1/1 (`evals/results/retrieval_workspace_smoke_2026-10-04.json`). إعادة الجولة الموسعة بعد التغيير ومراجعة بشرية مستقلة ما زالتا مطلوبتين.
+- [ ] متابعة التقييم على ملفات طويلة وPDFات متنوعة وأسئلة جديدة، وجمع مراجعة مستقلة لجودة إجابات النموذج فوق السياق المسترجع. النتائج fixtures صغيرة ومصطنعة؛ الدرجات لا تثبت جودة عامة. في 2026-10-04 جُمعت 14 إجابة baseline في `evals/HUMAN_REVIEW_2026-10.md` بسلم موحد ومقتطفات مرجعية؛ استُخرج PDF الممسوح محليًا بـEasyOCR (ثقة 0.591). مراجعة Codex الآلية السابقة في `evals/MODEL_REVIEW_2026-10.md` أعطت 48/56 وكشفت امتناعين رغم وجود الدليل؛ أعيدت الحالتان بعد إصلاح أول، ثم اكتملت الجولة الموسعة الحالية (14/14 semantic indexing وHit@1/Hit@3/MRR/evidence rate = 1.0) في `evals/results/retrieval_extended_agent_2026-10-04.json`. ظهرت 3 امتناعات جديدة رغم الأدلة؛ أضيف كشفها واختُبرت الحالات الثلاث بعد الإصلاح على API منفصل، والنتيجة في `evals/results/retrieval_fallback_fix_2026-10-04.json`. ما زالت المراجعة البشرية المستقلة وقياس إجابات المجموعة كلها على بيانات واقعية مطلوبين.
 - [x] مهارات محلية أولية قابلة للاختيار من واجهة وضع الوكيل: شرح الكود، مراجعة الكود، وخطة اختبارات. تعرض `/v1/agent/skills` وصف كل مهارة وأدواتها؛ تُحقن التعليمات الموثوقة في سياق الوكيل وتُفلتر قائمة الأدوات، ويرفض الخادم استدعاء أداة خارج صلاحيات المهارة. لمهارة مراجعة الكود معاينة فقط ولا تطبيق مباشر. اجتازت اختبارات الصلاحيات والواجهة؛ يبقى تقييم دقة كل مهارة على أمثلة أكثر قبل اعتمادها افتراضيًا.
 - [x] قراءة رابط عام محدد عبر `POST /v1/web/read`: استخراج نص HTML الثابت وتمريره إلى Gemma المحلية للإجابة مع إرجاع الرابط والعنوان.
 - [x] بحث ويب متعدد المصادر تجريبي عبر DuckDuckGo بلا مفتاح API: اختيار نطاقات مختلفة، محاولة جلب الصفحات العامة، تلخيص بالنموذج المحلي مع روابط المصادر، ووسم المقتطفات عند تعذر فتح الصفحة. (2026-10-01: استجابة حية أعادت ملخصًا ومصدرين مختلفين عبر FastAPI/Gemma.) أضيف زمن جلب إجمالي وزمن لكل مصدر إلى الاستجابة لمساعدة تشخيص المصادر البطيئة؛ اختبارات الحجب ومزوّد رسمي اختياري ما زالت لاحقًا.