مشروع تعليمي لبناء مساعد ذكاء اصطناعي محلي قابل للتوسع. النموذج الافتراضي الحالي gemma4:e2b ويعمل عبر Ollama محليًا. يمكن اختيار نموذج آخر بواسطة متغير البيئة LOCAL_MODEL.

مكونات النسخة الأولى

FastAPI كواجهة HTTP محلية.
وكيل تجريبي بأداة حساب آمنة ومحدودة.
واجهة المحادثة تدعم نسخ الإجابة ومشاركتها وتعديل آخر سؤال أو إعادة توليد الإجابة.
تختار الواجهة نموذج Ollama المثبت محليًا من قائمة النماذج.
وضع الوكيل التجريبي يبحث في ملفات المشروع النصية ويقرأ مقتطفات منها فقط؛ لا يكتب ملفات ولا يشغّل أوامر.
خطة المراحل التالية للوكيل والبيانات والنماذج موجودة في ROADMAP.md.
واجهة /docs لاستكشاف الـ API من المتصفح.
يمكن توصيلها بخادم نموذج محلي يوفّر واجهة OpenAI مثل Ollama.
دون إعداد عنوان خادم نموذج، تعمل الواجهة في وضع العرض التجريبي.

التشغيل على Windows

ثبّت Python 3.11 أو أحدث.
افتح PowerShell داخل المجلد. إذا كانت .venv موجودة، تخطَّ خطوة إنشائها وثبّت الاعتماديات فقط عند الحاجة.
أنشئ بيئة افتراضية وثبت الاعتماديات:

py -m venv .venv
.\.venv\Scripts\Activate.ps1
python -m pip install -r requirements.txt

(اختياري على جهاز جديد فقط) شغّل Ollama واسحب Gemma 4 E2B:

ollama pull gemma4:e2b

الخادم مضبوط افتراضيًا على Ollama المحلي وGemma 4 E2B. لتغيير عنوان Ollama أو اختيار نموذج آخر، عرّف المتغيرات في نافذة PowerShell نفسها:

$env:LOCAL_LLM_BASE_URL = "http://127.0.0.1:11434/v1"
$env:LOCAL_MODEL = "gemma4:e2b"

يمكن تثبيت اختيار Gemma صراحةً في الجلسة قبل تشغيل start-api.ps1 (وهو النموذج الافتراضي للسكربت):

$env:LOCAL_MODEL = "gemma4:e2b"
.\start-api.ps1

يمكن أيضًا اختيار النموذج لكل طلب من POST /v1/chat/completions بإرسال model، أو من POST /v1/agent/run بإرسال model مع task. على جهاز الاختبار، Gemma 4 E2B اشتغلت محليًا على CPU؛ وقد تختلف السرعة واستهلاك الذاكرة حسب الجهاز.

راجع رخصة النموذج المختار وشروطه الحالية قبل الاستخدام التجاري. تنزيل النموذج يحتاج اتصال إنترنت ومساحة تخزين.

شغل الـ API على جهازك فقط (أو شغل start-api.ps1):

python -m uvicorn app.main:app --reload --host 127.0.0.1 --port 8000

افتح http://127.0.0.1:8000/docs.

نقاط التجربة

GET /health للتأكد من أن الخدمة تعمل.
POST /v1/chat/completions لإرسال رسالة.
POST /v1/agent/run لتجربة الوكيل والأداة الحسابية.
POST /v1/chat/completions يمرر الطلب إلى الخادم المحلي عند ضبط المتغيرين أعلاه.
يمكن التبديل في Swagger بين النموذجين بإضافة model إلى جسم الطلب، مثل gemma4:e2b.

تحليل الملفات وتقييم الإجابة

POST /v1/agent/files/analyze يستقبل multipart/form-data: حقل files (ملف إلى 3 ملفات من النص/الكود)، وحقل question اختياري. الحد 256KB لكل ملف و512KB للمجموع. المحتوى يُقرأ في الذاكرة ولا يُحفظ أو يُنفذ.
PUT /v1/conversations/{conversation_id}/messages/{message_index}/feedback يحفظ تقييم إجابة محفوظة. الجسم مثل {"version_index":0,"rating":1} للإعجاب أو rating:-1 لعدم الإعجاب. من الأفضل استخدام زري 👍/👎 في التطبيق لأنهما يحددان المحادثة والنسخة الصحيحين تلقائيًا.
هذه التقييمات بيانات قياس وتفضيل أولية؛ لا تغيّر أوزان Gemma ولا تعيد تدريبها تلقائيًا.

قراءة رابط ويب محدد

يوفر الـAPI المسار POST /v1/web/read لقراءة صفحة عامة يرسل المستخدم رابطها، واستخراج نصها، ثم سؤال Gemma المحلية عنها. افتح /docs، اختر المسار، وأرسل مثلًا:

{
  "url": "https://example.com",
  "question": "لخّص الصفحة بجملة واحدة."
}

يرجع الرد عنوان الصفحة ورابط المصدر وإجابة النموذج. هذا المسار لقراءة رابط محدد؛ الصفحات التي تتطلب JavaScript أو تسجيل دخول قد لا تُقرأ.

البحث العميق على الإنترنت

يوفر POST /v1/web/search بحثًا أوليًا متعدد المصادر بلا مفتاح API باستخدام نتائج DuckDuckGo العامة. يجلب حتى 8 نتائج من نطاقات مختلفة، يحاول قراءة صفحاتها العامة، ثم يطلب من النموذج المحلي تلخيص المعلومات مع إحالات مرقمة وروابط المصادر. من واجهة Mithqal AI فعّل زر البحث/الكرة الأرضية في الشريط العلوي ثم اكتب موضوع البحث. بعض المواقع تمنع القراءة الآلية أو تعتمد على JavaScript؛ عندها يظهر المصدر بوصفه مقتطف بحث فقط. المسار يرفض العناوين المحلية ويحد أحجام الصفحات ومصادرها.

{
  "query": "كيف تعمل FastAPI dependency injection؟",
  "max_results": 5
}

هذا إصدار تجريبي يعتمد على صفحة نتائج عامة وقد يتأثر بالحجب أو تغييرات HTML ومعدلات الطلب؛ بنية مزوّد البحث قابلة للاستبدال لاحقًا بواجهة رسمية عند اختيار مزود ومفتاح مناسبين.

خادم التطبيق مربوط بـ 127.0.0.1: يمكنه إجراء اتصالات صادرة إلى خدمات الإنترنت مثل Groq وقراءة المواقع العامة، لكنه غير منشور ليستقبل طلبات من أجهزة خارج هذا الكمبيوتر.

الخدمة مربوطة بـ 127.0.0.1 عمدًا، فلا تعرضها لاستقبال طلبات من الشبكة أو الإنترنت الآن. الوكيل يدعم الحساب وقراءة مقتطفات ملفات المشروع المحددة وقراءة رابط ويب عام يرسله المستخدم. لا يكتب ملفات ولا ينفذ أوامر النظام.

واجهة Flutter

يوجد تطبيق Flutter متعدد المنصات في flutter_app، والاسم المعروض المقترح حاليًا Mithqal AI (مثقال AI) بانتظار التحقق النهائي من العلامة التجارية. يضم أصل أيقونة واحدًا وإعدادًا لتوليد أيقونات Android وiOS وmacOS وWindows والويب؛ ويوجد ملف أيقونة وملف Desktop أوليان لتغليف Linux. عنوان الاتصال الافتراضي http://127.0.0.1:8000؛ التطبيق يسمح بتغييره من الإعدادات ويعرض اسم النموذج النشط من الـ API.

تعرض الواجهة إشعارًا داخل الصفحة عند اكتمال كل طلب أو فشله. على تطبيقات الهاتف يفعّل المستخدم إشعارات النظام من زر الجرس، فلا يطلب التطبيق الإذن عند الإقلاع. إعداد النظام على سطح المكتب مفعل افتراضيًا. نسخة الويب الحالية تعرض إشعار الصفحة؛ إذ إن الحزمة المثبتة لإشعارات النظام لا تدعم Web على نسخة Flutter الحالية.

تطبيق Windows

لتشغيل النسخة المكتبية، شغّل start-api.ps1 أولًا، ثم افتح flutter_app/build/windows/x64/runner/Release/flutter_app.exe بعد بنائه.
يعرض شريط المحادثة قائمة النماذج المثبتة من Ollama؛ اختيار النموذج يمرر اسمه مع الطلب.
زر المجلد يفعّل وضع الوكيل للقراءة فقط، وزر الكرة الأرضية يفعّل البحث العميق متعدد المصادر. عند تشغيل start-api.ps1 تكون مساحة العمل الافتراضية مجلد المشروع SovereignAI-Starter؛ لتغييرها عرّف SOVEREIGNAI_WORKSPACE قبل تشغيل الخدمة.
الوكيل يطابق السؤال مع ملفات النص/الكود المدعومة، ويمرر مقتطفات محدودة للنموذج؛ عند ذكر مسار نسبي مثل app/main.py يزيد المقتطف إلى 12,000 حرف كحد أقصى. يعيد أسماء الملفات التي قرأها. الملفات المخفية، مجلدات .git وبيئات البناء، والملفات الكبيرة أو خارج جذر مساحة العمل مستثناة.
زر مشبك الورق يفتح اختيار ملفات الكود/النص (حتى 3 ملفات، 256KB لكل ملف و512KB إجمالًا). يدعم API قائمة أنواع نصية وبرمجية فقط؛ يقرأ المحتوى في الذاكرة، ولا يخزنه أو ينفذه. PDF والصور غير مدعومة في هذا المسار حتى الآن.
تظهر 👍/👎 تحت إجابات المساعد. يحفظ التقييم مع رقم نسخة الإجابة في SQLite حتى نتمكن من قياس الجودة وتجهيز أمثلة تقييم أو تفضيلات بمراجعة بشرية؛ الضغط لا يدرّب النموذج ولا يغيّر أوزانه تلقائيًا.
Gemma 4 E2B لديها قدرة نموذجية على إدخال الصور والصوت وفهم المستندات وفق بطاقة Google الرسمية، لكن هذه الواجهة الحالية لا تمرر مدخلات الصور ولا تقرأ PDF بعد؛ نحتاج بناء مسار منفصل لذلك. قراءة ملفات الكود النصية تعمل عبر زر المرفقات أو وضع مساحة العمل.
لإنشاء نسخة Release، نفّذ flutter build windows --release من داخل flutter_app.
التطبيق المكتبي واجهة أمامية؛ يحتاج Ollama وFastAPI شغّالين على الجهاز. النموذج لا يُضمّن داخل ملف التطبيق التنفيذي، ويظل نسخ الصوت للنص عبر Groq Whisper عند استخدام الميكروفون.

المحادثات والصوت

تحفظ FastAPI المحادثات والرسائل في SQLite محليًا. على Windows يوجد الملف في %LOCALAPPDATA%\SovereignAI\data\sovereign_ai.sqlite3، وخارج مجلد المشروع لتجنب مزامنة قاعدة البيانات مع OneDrive.
لكل سجل محادثة user_id، وتُفلتر عمليات القراءة والتعديل والحذف على أساسه. في النسخة المحلية يوفّر FastAPI ملف مستخدم تطوير ثابتًا، وترسل الواجهة معرّفه في ترويسة X-User-ID؛ هذا ليس تسجيل دخول أو عزلًا أمنيًا صالحًا للاستضافة العامة.
جدول user_identities مهيأ لربط المستخدم مستقبلًا بمعرّف مزود مثل Google أو البريد/الهاتف، لكن تدفق تسجيل الدخول لم يُنفذ بعد. عند إضافة مستخدمين حقيقيين يجب استبدال الترويسة بهوية موثقة من جلسة/JWT.
رسائل الدردشة ترسل إلى Ollama المحلي. التسجيل الصوتي يحوّل إلى نص عبر Groq Whisper؛ لذلك يُرسل الصوت إلى Groq عند الضغط على إيقاف التسجيل.
مفتاح Groq يجب أن يبقى في متغير البيئة GROQ_API_KEY الخاص بخادم FastAPI، ولا يوضع في Flutter أو في ملفات المشروع.
على جهاز التطوير الحالي حُفظ المتغير في بيئة Windows الخاصة بالمستخدم، وليس في ملف .env. يقرأه start-api.ps1 عند تشغيل الخادم، ويظهر /health حالة الإعداد فقط دون إظهار المفتاح. عند استضافة الخادم لاحقًا، أضف المفتاح إلى إعدادات البيئة السرية في خدمة الاستضافة.

عنوان الشبكة

عنوان Wi-Fi الحالي لهذا الجهاز 192.168.100.20 والبوابة 192.168.100.1، والعنوان موزع عبر DHCP. لتثبيته، احجز العنوان الحالي من صفحة الراوتر ضمن DHCP Reservation / Address Reservation للجهاز DESKTOP-13T75A5، مستخدمًا MAC واجهة Wi-Fi الظاهر في ipconfig /all. لا تغيّر إعداد IPv4 يدويًا في Windows بالتزامن مع حجز DHCP. هذا يثبت العنوان داخل الشبكة المنزلية فقط؛ لا يفتح وصولًا من الإنترنت. الخوادم ما زالت مربوطة بـ 127.0.0.1.