# خارطة تطوير SovereignAI

هذه خارطة تنفيذ تدريجية للمشروع الحالي. التطبيق اليوم Flutter، وواجهة الخدمة FastAPI، والتخزين SQLite، وتوليد النص عبر خادم Ollama محلي. لا نبدأ بتدريب نموذج من الصفر؛ نبني منتجًا قابلًا لتبديل النموذج ونقيس كل مرحلة قبل توسيع الصلاحيات.

## الحالة الحالية — 2026-10-01

- الأساس المحلي يعمل: Flutter Windows Debug ↔ FastAPI ↔ Ollama/Gemma، مع سجل SQLite للمحادثات ونسخ الإجابات.
- اكتملت وظائف المحادثة الأساسية وطبقة مزوّد Ollama؛ المرحلة 1 ما زال ينقصها تحسين Markdown/الروابط/نسخ كتل الكود.
- الوكيل الآن نموذج أولي للقراءة فقط: بحث نصي في مساحة العمل المحددة، وتحليل ملفات كود/نص يختارها المستخدم (حتى 3 ملفات، 256KB للملف و512KB للمجموع، دون تخزين أو تنفيذ).
- أضيف زر البحث العميق متعدد المصادر وزرا اختيار الملفات إلى الواجهة؛ أضيف تقييم الإجابة بإعجاب/عدم إعجاب محفوظ لكل نسخة في SQLite. التقييم يجمع بيانات تقييم، ولا يدرّب أوزان Gemma تلقائيًا.
- تحقق تشغيل Flutter Web على المنفذ 5302 واتصاله بـFastAPI/Gemma؛ نجح سؤال عربي، واختبار زر الإعجاب، ورفع ملف Python تجريبي عبر API. لا توجد بعد مصادقة متعددة المستخدمين أو نشر شبكي آمن؛ الصوت يعتمد على Groq خارجي، ومعالجة الصور وPDF لم تُنفذ بعد.
- التدريب والضبط الدقيق وتوزيع Windows مراحل لاحقة، وليست مما يفعّله التطبيق حاليًا.

## المرحلة 1 — تجربة المحادثة

- [x] نسخ إجابة المساعد.
- [x] مشاركة نص الإجابة عبر نظام التشغيل.
- [x] تعديل آخر سؤال وإعادة إرساله؛ تُستبدل الإجابة وما بعدها في سياق المحادثة.
- [x] إعادة توليد آخر إجابة.
- [x] إشعار داخل التطبيق عند اكتمال الإجابة أو انتهاء الطلب بخطأ.
- [x] تجهيز تنبيهات نظام Windows/macOS/Linux/Android/iOS مع طلب إذن الهاتف عند ضغط المستخدم؛ الويب يعرض تنبيهًا داخل الصفحة في إصدار Flutter الحالي.
- [x] إنشاء أصل أيقونة موحّد وإعداد توليد أيقونات Android/iOS/macOS/Windows/Web، وإضافة أصل تغليف Linux.
- [x] اختيار نموذج Ollama مثبت من واجهة التطبيق، وتمريره صراحةً للطلب.
- [x] وضع وكيل تجريبي للبحث وقراءة مقتطفات ملفات المشروع فقط، مع إرجاع مراجع الملفات.
- [x] حفظ محاولات الإجابة كنسخ منفصلة بدل استبدالها، مع واجهة للتنقل بينها. (2026-10-01: اجتازت اختبارات Flutter التنقل والحفظ، واختبارات SQLite/API الترحيل والحفظ والاسترجاع.)
- [x] إظهار حالة النموذج والوقت وسبب الخطأ، وتوفير إيقاف التوليد. (2026-10-01: اختبار زر الإيقاف في الواجهة، حفظ النص الجزئي، وحماية الإجابة القديمة أثناء إلغاء إعادة التوليد؛ `flutter analyze` بلا ملاحظات، وWindows Debug أُعيد تشغيله.)
- [x] إضافة تقييم 👍/👎 لكل نسخة إجابة وحفظه في SQLite؛ اختبار واجهة حي نجح بعد إصلاح خطأ فهرسة الرسائل في قاعدة البيانات. يستخدم لاحقًا لبناء مجموعة تقييم/تفضيلات بمراجعة بشرية، ولا يغير أوزان النموذج بمفرده.
- [ ] دعم إخراج Markdown كامل، وروابط قابلة للفتح، ونسخ الكتل البرمجية منفردة.

## المرحلة 2 — أساس موثوق للواجهة والـ API

- [x] فصل عقد التطبيق عن تفاصيل Ollama عبر طبقة مزوّد موحدة (Model Provider)، مع بقاء Ollama أول تنفيذ للمزوّد. (2026-10-01: المحادثة والبث والوكيل وقراءة مساحة العمل والويب تستخدم العقد الموحدة؛ `MODEL_PROVIDER=ollama` هو التنفيذ المتاح حاليًا. بعد إعادة تشغيل FastAPI أكد `/health` المزوّد، وأعاد `/v1/models` ثلاثة نماذج، ونجح طلب محادثة حي عبر Gemma.)
- [x] جلب قائمة النماذج المحلية والتحقق من اختيار النموذج قبل الإرسال؛ [ ] إضافة بيانات قدرات كل نموذج.
- [x] مسار تحليل ملفات مرفقة نصية/برمجية عبر FastAPI، مع تحقق النوع والحجم وحد أقصى 3 ملفات؛ اختبار ملف Python تجريبي أعاد تحليلًا عربيًا من Gemma 4 E2B. لا حفظ على القرص ولا تشغيل للكود.
- توحيد أخطاء API ومعرّفات الطلبات والمهل الزمنية، وإضافة اختبارات تكامل لعقد API.
- إبقاء الخدمة محلية افتراضيًا؛ لا تُعرض على الشبكة قبل مصادقة المستخدم ومراجعة إعدادات الأمان.
- نقل إعدادات المستخدم من حقول مؤقتة إلى إعدادات محفوظة، وإظهار حالة الخادم والنموذج بوضوح.

## المرحلة 3 — الهوية والبيانات

- استبدال `X-User-ID` التطويري بجلسة موثقة قبل دعم عدة مستخدمين فعليين.
- تصميم بيانات المستخدمين والمحادثات والمرفقات ونسخ الإجابات مع ملكية واضحة وفهارس وترحيلات قاعدة بيانات.
- SQLite مناسب لنسخة محلية أحادية الجهاز. عند تشغيل خدمة لعدة مستخدمين/أجهزة، ننتقل إلى PostgreSQL، مع نسخ احتياطية وسياسة حذف وتصدير.
- تخزين الملفات الكبيرة في مساحة ملفات منظّمة، وحفظ بياناتها الوصفية ومراجعها في قاعدة البيانات، لا في سجل الرسائل ككتل ضخمة.

## المرحلة 4 — نواة الوكيل

### دورة التنفيذ

1. يستقبل الوكيل هدفًا وسياقًا ومجموعة الأدوات المسموح بها.
2. يقرر النموذج هل يجيب مباشرة أو يطلب استدعاء أداة ببنية محددة.
3. يتحقق الخادم من صحة الوسائط والصلاحية والحدود قبل تنفيذ الأداة.
4. يعيد الخادم نتيجة الأداة إلى النموذج ليستكمل أو يطلب خطوة أخرى.
5. يعرض التطبيق الخطة والخطوات والنتيجة، ويسجل الاستدعاءات والأخطاء.

### سلم الأدوات والصلاحيات

1. [x] قراءة فقط أولية: الحاسبة والبحث النصي واسترجاع مقتطفات من ملفات مساحة العمل المضبوطة عند تشغيل الخادم. لا يوجد حتى الآن اختيار للمجلد من التطبيق.
2. [x] قراءة ملف كود محدد: عند ذكر مساره النسبي مثل `app/model_provider.py` في وضع الملفات، يقرأ الوكيل مقتطفًا أكبر (حتى 12,000 حرف) ويعيد اسم الملف. (2026-10-01: تجربة API حية أعادت جوابًا عن الملف المحدد وأعادت مساره وحده كمصدر.)
3. [ ] اختيار مساحة العمل/الملف من نافذة التطبيق واستعراض قائمة الملفات قبل سؤال الوكيل.
4. كتابة: إنشاء وتعديل ملفات داخل مساحة العمل فقط، مع معاينة diff وتأكيد المستخدم قبل التطبيق.
5. أوامر تطوير: تشغيل أوامر محددة في بيئة معزولة وبمهلة وحدود موارد، ومع موافقة لكل أمر في البداية.
6. لا وصول عام إلى القرص، ولا أوامر مدمرة أو نشر خارجي دون موافقة صريحة. كل أداة لها مخطط مدخلات ومخرجات واختبارات وسجل تدقيق.

### كودكس للبرمجة

- مساحة مشروع يختارها المستخدم، مع فهرسة نصية أولًا ثم استرجاع المقاطع الملائمة للسؤال.
- أدوات مقترحة: قراءة ملف، بحث نصي، قائمة ملفات، إنشاء/تعديل ملف عبر patch، عرض diff، تشغيل اختبارات وأوامر allowlist.
- التنفيذ يتم في مجلد المشروع المحدد، مع حفظ التغييرات في Git وإظهارها للمستخدم قبل اعتمادها.
- نبدأ بوكيل خطوة بخطوة (دورة واحدة واستدعاء أداة واحد)، ثم نرفع عدد الخطوات تدريجيًا بعد قياس الدقة والأمان.
- [ ] تعريف مخطط موحّد للأداة ومدخلاتها ونتيجتها وحالاتها، مع سجل تدقيق لا يحفظ نصوص المحادثات أو محتوى الملفات افتراضيًا.

## المرحلة 5 — المعرفة والمهارات

- بناء RAG للمستندات المحلية: استخراج النص، تقطيع، فهرسة محلية، استرجاع مع مصادر وإشارات للمقاطع.
- تعريف المهارات كتعليمات وإجراءات موثقة ومحددة النطاق، مع صلاحية اختيار الأدوات المطلوبة فقط.
- [x] قراءة رابط عام محدد عبر `POST /v1/web/read`: استخراج نص HTML الثابت وتمريره إلى Gemma المحلية للإجابة مع إرجاع الرابط والعنوان.
- [x] بحث ويب متعدد المصادر تجريبي عبر DuckDuckGo بلا مفتاح API: اختيار نطاقات مختلفة، محاولة جلب الصفحات العامة، تلخيص بالنموذج المحلي مع روابط المصادر، ووسم المقتطفات عند تعذر فتح الصفحة. (2026-10-01: استجابة حية أعادت ملخصًا ومصدرين مختلفين عبر FastAPI/Gemma.) بقي تسجيل وقت الجلب واختبار الحجب ومزوّد رسمي اختياري لاحقًا.
- اختبار كل مهارة على أمثلة ناجحة وفاشلة قبل إتاحتها افتراضيًا.

## المرحلة 6 — الوسائط

- الصوت: حاليًا Groq خارجي للتفريغ. Gemma 4 E2B تدعم الصوت بحسب [بطاقة النموذج](https://ai.google.dev/gemma/docs/core/model_card_4)، لكن مسار إرسال الصوت إليها/نسخ محلي لم يُنفّذ؛ Whisper محلي لاحقًا.
- الصور: Gemma 4 E2B تدعم إدخال الصور وقراءة المستندات وOCR بحسب [بطاقة النموذج](https://ai.google.dev/gemma/docs/core/model_card_4)، لكن التطبيق لا يمرر الصور حاليًا؛ المطلوب إضافة اختيار/رفع صورة وتحجيم آمن ثم تمريرها عبر Ollama.
- دعم ملفات PDF والمستندات: قدرات النموذج تشمل فهم صفحات المستندات، لكننا نحتاج تنفيذ خط رفع واستخراج النص أو تحويل صفحات PDF إلى صور مع أرقام الصفحات والمصادر.
- تصميم الواجهة لتوضيح ما إذا عولج الملف محليًا أم أرسل إلى مزوّد خارجي.

## المرحلة 7 — تقييم النماذج والتدريب

- إنشاء مجموعة أسئلة عربية/برمجية ممثلة لاستخدامنا، وقياس صحة الإجابة، اتباع التعليمات، استدعاء الأدوات، السرعة واستهلاك الذاكرة.
- اختيار النماذج حسب الرخصة، الجودة، اللغة، دعم الأدوات، كمية VRAM، وإمكانية التشغيل التجاري. لا نعتمد وصف «مفتوح» وحده كإثبات سماح تجاري؛ نراجع الرخصة الرسمية لكل إصدار.
- تحسين أولي عبر prompts وRAG والأدوات؛ هذه غالبًا تعالج نقص المعرفة أو القدرة على الفعل دون تغيير أوزان النموذج.
- عند توفر GPU مناسب: تجربة LoRA/QLoRA على بيانات مرخصة ومنقحة، ومقارنة النتائج بالمجموعة المرجعية قبل اعتماد adapter.
- تدريب نموذج أساسي من الصفر خارج نطاق العتاد الشخصي المعتاد؛ يحتاج بيانات وحوسبة وبنية تدريب كبيرة، ولا يكون خطتنا الأولى.

## المرحلة 8 — تطبيق Windows ثم التوزيع

- أثناء التطوير نشغّل Debug/hot reload. بعد ثبات الوظائف ننتج نسخة Windows قابلة للتثبيت.
- حسم طريقة توزيع خدمة Python وOllama/النماذج وإدارتها، دون تضمين أوزان ضخمة داخل التطبيق نفسه.
- توقيع التطبيق، تحديثات واضحة، سجلات تشخيص لا تكشف الأسرار، وإعدادات حذف البيانات والنسخ الاحتياطي.
- قبل الاستخدام التجاري: مراجعة تراخيص النماذج والاعتماديات، الخصوصية، المصادقة، حدود الاستخدام، النسخ الاحتياطي، والتحديثات الأمنية.

## إضافات قبل توسيع الوكيل

- [x] إلغاء التوليد وإظهار المدة وحالة الاتصال ورسالة الخطأ (2026-10-01: اختبارات Cubit وواجهة ناجحة).
- [x] حفظ نسخ إعادة التوليد والتنقل بينها (2026-10-01: اختبار واجهة وAPI وقاعدة البيانات ناجح)؛ تجربة أفضل للأخطاء وإعادة المحاولة ما زالت لاحقة.
- [x] إكمال طبقة مزوّد النموذج الأساسية قبل توسيع أدوات الوكيل؛ مزوّد Ollama فقط متاح الآن، وإضافات المزوّدين وبيانات قدرات النماذج لاحقة.
- حفظ إعدادات التنبيه والمظهر وعنوان API بطريقة محلية آمنة.
- إضافة دعم Markdown موثوقًا، وروابط المصادر، ونسخ كتل الكود بصورة مستقلة.
- وضع تقييم صغير بالعربية والبرمجة لقياس التغييرات على السرعة والجودة وعدم فقد الميزات.
- بعدها نكمل وكيل الملفات: اختيار مجلد مساحة العمل، معاينة التغييرات، ثم موافقة صريحة قبل أي كتابة أو أمر.

## ترتيب التنفيذ القادم

1. [x] التحقق من إجراءات المحادثة الجديدة على Windows Debug (2026-10-01): تشغيل API وGemma وGroq، اختبار صوت من الميكروفون حتى التفريغ والرد والحفظ في SQLite، نجاح اختبار الواجهة على نافذة 800px ونجاح `flutter analyze`.
2. [x] حفظ نسخ الإجابات وترحيل SQLite (2026-10-01): ترحيل قاعدة قديمة مع الحفاظ على الرسائل، وحفظ النسخ واسترجاع النسخة المختارة عبر PUT/GET؛ اجتاز اختبارا Python واختبار API حي على قاعدة التطبيق ثم حذف سجل الاختبار. اختبارا Flutter نجحا، و`flutter analyze` بلا ملاحظات. شُغّلت نسخة Windows Debug باسم Mithqal AI واتصلت الخدمة بـGemma؛ اختبار API للمحادثة أعاد ردًا عربيًا.
3. [x] حالة النموذج والمدة والخطأ وإيقاف التوليد (2026-10-01): اختبار إلغاء الرد الجزئي وإلغاء إعادة التوليد قبل أول رمز مع الحفاظ على الإجابة السابقة، واختبار زر الإيقاف بالواجهة؛ `flutter analyze` و5 اختبارات Flutter ناجحة، وWindows Debug يعمل بعد hot restart.
4. [x] إضافة طبقة مزود النموذج واكتشاف النماذج (2026-10-01): عقد موحد للطلب الكامل والبث والقائمة، واستخدامه في المحادثة والوكيل وقراءة مساحة العمل والويب؛ Ollama هو المزوّد المنفذ حاليًا. تحقق حي من `/health` و`/v1/models` وطلب محادثة باستخدام Gemma.
5. عقد الأدوات وسجل التدقيق، واختيار ملف/مجلد العمل من الواجهة واستعراضه، ثم إظهار مراجع الملفات المقروءة بصورة أوضح.
6. تعديل الملفات داخل مساحة العمل عبر diff وموافقة صريحة؛ ثم أوامر محددة ومعزولة فقط بعد بناء الحدود اللازمة.
7. مصادقة وهوية متعددة المستخدمين قبل أي نشر شبكي، ثم PostgreSQL عند الحاجة إلى خدمة متعددة الأجهزة.
8. توسيع بحث الويب التجريبي بمصادر/وقت جلب وموفّر رسمي اختياري، ثم RAG للمستندات والصور/PDF وبدائل Whisper محليًا حسب الموارد.
9. مجموعة تقييم للنماذج، ثم دراسة LoRA/QLoRA عند توفر بيانات وGPU ملائمين.
10. تجهيز توزيع Windows وإدارة الخدمة والنموذج، ثم مراجعة الأمان والتراخيص قبل أي استخدام تجاري.

## شروط الانتقال بين المراحل

- كل قدرة جديدة لها عرض واضح للمستخدم، حدود صلاحيات، وسجل مفهوم.
- لا تُفعل أداة كتابة أو تنفيذ قبل وجود تحقق خادمي من المسارات والمدخلات.
- لا نعتبر نجاح HTTP كافيًا: نتحقق من النتيجة في الواجهة ومن استمرار حفظ البيانات بعد إعادة فتح التطبيق.
- قبل الإنتاج، نستبدل هوية التطوير ونراجع المصادقة والترخيص والأسرار والنسخ الاحتياطية.