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

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

FastAPI كواجهة HTTP محلية.
وكيل محلي ينسّق حتى 3 أدوات مسموحة بالتتابع (مثل البحث في الملفات ثم الحساب)، ويعيد نتيجة نهائية مع خطوات التنفيذ.
واجهة المحادثة تدعم نسخ الإجابة ومشاركتها وتعديل آخر سؤال أو إعادة توليد الإجابة.
تختار الواجهة نموذج Ollama المثبت محليًا من قائمة النماذج.
وضع الوكيل يقرأ مقتطفات الملفات المحددة أو المفهرسة فقط؛ اقتراح تعديل الملف ينشئ معاينة diff تتطلب موافقة صريحة، ولا يشغّل أوامر.
خطة المراحل التالية للوكيل والبيانات والنماذج موجودة في 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.

HTTPS محلي اختياري على Windows

لإنشاء جذر تطوير موثوق لحساب Windows الحالي وشهادة خادم لـlocalhost:

.\scripts\setup_local_tls.ps1       # مرة واحدة لكل مستخدم Windows
.\start-api-https.ps1                # HTTPS على https://localhost:8443

يثق Windows بجذر محلي في CurrentUser\Root فقط. مفتاح الجذر يُنشأ مؤقتًا ثم يُحذف بعد توقيع شهادة الخادم؛ مفتاح الخادم يبقى في %LOCALAPPDATA%\SovereignAI\certs مع ACL للمستخدم الحالي وSYSTEM. بعد تشغيل الخدمة، غيّر عنوان API في Flutter إلى https://localhost:8443. لإزالة الشهادة والملفات المعروفة لهذا الإعداد استخدم scripts/remove_local_tls.ps1.

جرى التحقق من /health عبر Windows PowerShell وDart HttpClient، وفتح Edge headless الصفحة وأظهر JSON بالحالة 200؛ رفض عميل HTTPX ذي مخزن CA الافتراضي الشهادة الخاصة. المتصفح الداخلي في Codex حجب عنوان localhost بسياسة العميل. الإعداد تطوير محلي فقط: الخادم يظل مربوطًا بـ127.0.0.1 وحاجز loopback فعالًا، ولا يجهز شهادة عامة أو وصولًا من أجهزة أخرى. اترك TLS غير مضبوط لاستخدام HTTP المحلي الافتراضي على 8000.

نقاط التجربة

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

تثبيت OCR المحلي الاختياري للصور وPDFات الممسوحة:

python -m pip install -r requirements-ocr.txt

تُحمّل EasyOCR أوزان العربية والإنجليزية لأول مرة إلى %LOCALAPPDATA%\SovereignAI\models\easyocr (نحو 300MB في تجربة Windows). الصور والوثائق نفسها تبقى داخل FastAPI ولا تُرفع. يمكن تحديد مجلد الأوزان عبر LOCAL_OCR_MODEL_DIR، أو ضبط LOCAL_OCR_ALLOW_DOWNLOAD=false بعد وضع الأوزان محليًا. في تجربة صورة اللقاء قرأ OCR العنوان العربي والإنجليزي والمكان والتاريخ والوقت؛ ترتيب الصفوف جمع «لقاء القراءة المجتمعي». متوسط الثقة 0.625، وقراءة الصورة نحو 71 ثانية على CPU بعد تهيئة أولى استغرقت ~45 ثانية. راجع النص قبل استخدامه، وتحقق من تراخيص الحزمة والأوزان قبل التوزيع التجاري.

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

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

تقييم النماذج المحلية

توجد مجموعة عربية/برمجية أولية في evals/baseline_arabic_programming.jsonl. تشغّل الطلبات على API المحلي وتسجل الرد والمدة والأداة والفحوص الآلية في JSON لمراجعة بشرية؛ لا تعتبر فحوص التنسيق والقيم تقييمًا كاملًا للجودة.

python scripts/run_model_eval.py --model gemma4:e2b --warmup
python scripts/run_model_eval.py --model qwen2.5:1.5b-instruct-q4_K_M --warmup

الـAPI يجب أن يكون شغالًا على 127.0.0.1:8000 والنماذج مختارة/مثبتة محليًا. يطلب المشغّل جلسة loopback محلية مؤقتة ويلغيها بعد التقييم. --warmup يرسل سؤال إحماء واحدًا قبل قياس الحالات، والتقرير يسجل زمن الإحماء وملخص متوسط/وسيط/أقل/أعلى زمن. كل نتيجة تحفظ في evals/results/. أُضيفت فحوص شكلية لعدد النقاط، الجملة الواحدة، ومثال Python؛ لكنها لا تكشف كل الأخطاء الدلالية. قياس 2026-10-03 أعطى Gemma 9/9 وQwen 8/9 فحوصًا على خمسة أسئلة، لكن إجابة Qwen عن SQLite كانت غير دقيقة رغم اجتياز عدّ النقاط؛ لذلك يلزم تقييم بشري. التقارير الأخيرة evals/results/gemma4_e2b_2026-10-03_183058.json وevals/results/qwen2.5_1.5b-instruct-q4_K_M_2026-10-03_183140.json. المراجعة تستخدم مقياسًا من 0 إلى 2 لكل سؤال: 0 إخفاق، 1 جزئي، 2 مستوفٍ للمعيار؛ مرّة واحدة من خمسة أسئلة لا تكفي لقرار نهائي.

لقطة الذاكرة الحالية على Windows تُلتقط بـpowershell -ExecutionPolicy Bypass -File scripts/capture_ollama_runtime.ps1. تحفظ الأداة حالة Ollama المحمّلة من /api/ps وأحجام عمليات llama-server؛ إنها لقطة لحظية وليست قياس ذروة، ولا تربط PID بعينه بالنموذج.

اختبار استرجاع RAG يستخدم مجموعة صغيرة من ملفات عربية مؤقتة عبر API، ويقيس Hit@1/3 وMRR ووجود الدليل ثم يزيل الملفات من الفهرس:

python scripts/eval_knowledge_retrieval.py
python scripts/eval_knowledge_retrieval.py --dataset evals/knowledge_retrieval_project.jsonl

الاختبار الأول يستخدم 11 سؤالًا وملفات اصطناعية صغيرة؛ نتيجته بعد إضافة مرادفات محدودة للصوت 100% في Hit@1/3 وMRR ووجود الدليل، لكنه لا يقيس جودة الإجابة. الاختبار الثاني يفهرس نسخًا مؤقتة من ملفات المشروع الحقيقية ويقيس 9 أسئلة عن سلوك الكود. آخر تشغيل (2026-10-03) استخدم البحث الهجين مع granite-embedding:278m: Hit@1=66.7%، Hit@3=100%، MRR=83.3%، ووجود الدليل=8/9. يُصحح الاختبار توقع حد PDF ليطابق الثابت الفعلي. كشف التشغيل سؤالًا عن صلاحيات الأداة لم يسترجع المقطع الدقيق؛ العينة صغيرة ولا تقيس جودة الإجابات. المشغّل يحصل على جلسة محلية مؤقتة، يحذف الوثائق المفهرسة ويلغي الجلسة، وتبلغ المهلة الافتراضية للفهرسة 180 ثانية (--request-timeout). التقارير في evals/results/retrieval_2026-10-02_140339.json, ...140538.json, ...141132.json, ...141337.json، وretrieval_2026-10-03_145357.json.

يدعم الفهرس بحثًا هجينًا: FTS5 للمطابقة النصية مع متجهات تشابه محلية. للحصول على البحث الدلالي ثبّت نموذج التضمين العربي متعدد اللغات مرة واحدة عبر ollama pull granite-embedding:278m (نحو 563MB، ترخيص Apache 2.0)، ثم أعد فهرسة ملفات مساحة العمل حتى تُنشأ متجهاتها. الافتراضي KNOWLEDGE_EMBEDDING_MODEL=granite-embedding:278m ويمكن تغييره. يبيّن POST /v1/agent/knowledge/index الحقل semantic_indexed، ويعيد البحث search_mode بقيمة hybrid أو keyword. إذا لم يتوفر النموذج أو تعذر التضمين، يستمر الفهرس النصي ويعمل البحث دونه؛ لا تُرسل المستندات إلى خدمة خارجية. تجربة محلية بـ3 أسئلة عربية معادَة الصياغة استرجعت الملف الصحيح أولًا في الحالات الثلاث، بتشابه 0.648–0.827. هذه عينة أولية صغيرة وليست قياسًا عامًا للجودة.

رفع .pdf مدعوم ضمن مسار تحليل الملفات: يستخرج نص الصفحات الرقمية محليًا مع أرقامها، ويرسم الصفحات المصورة وحدها ثم يمررها إلى OCR المحلي ونموذج الرؤية. في الملفات المختلطة يُحافظ على ترتيب الصفحات؛ حد الطلب 3 صفحات مصورة، 30 صفحة إجمالًا و24,000 محرف للنص المستخرج. فهرس المعرفة يجمع النص الرقمي وOCR لأول 3 صفحات ممسوحة. حد الصور 2 مليون بكسل و4MB لكل صفحة و8MB إجماليًا، وحد PDF 8MB للملف و16MB للمجموع. الملف والصور المؤقتة تبقى في الذاكرة ولا تُرسل لخدمة سحابية. الملفات المشفرة أو غير الصالحة تُرفض.

مسار الصفحات الممسوحة يعتمد على قراءة نموذج الرؤية؛ الاختبار الحي الحالي التقط المكان والتاريخ والوقت، لكنه لم ينسخ العنوان العربي بدقة ثابتة. راجع النص المنسوخ قبل استخدامه؛ OCR متخصص مع درجة ثقة ما زال خطوة لاحقة.

يستخدم تحويل الصفحات pypdfium2 وPillow. قبل توزيع نسخة تجارية يجب إرفاق إشعارات وتراخيص PDFium واعتمادياته كما يوضح دليل الترخيص الرسمي.

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

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

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

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

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

يوفر POST /v1/web/search بحثًا أوليًا متعدد المصادر بلا مفتاح API باستخدام نتائج DuckDuckGo العامة. يجلب حتى 8 نتائج من نطاقات مختلفة، يحاول قراءة صفحاتها العامة، ثم يطلب من النموذج المحلي تلخيص المعلومات مع إحالات مرقمة وروابط المصادر. تتضمن استجابة API زمن جلب المصادر إجمالًا ولكل مصدر. من واجهة 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 قبل تشغيل الخدمة. يمكن لمسؤول الخدمة التصريح بعدة جذور عبر SOVEREIGNAI_ALLOWED_WORKSPACES مفصولة بفاصل المسارات الخاص بالنظام؛ أي مجلد يختاره العميل يجب أن يقع داخل أحدها. لتخصيص مساحات منفصلة للحسابات، عرّف SOVEREIGNAI_USER_WORKSPACES ككائن JSON مفاتيحه عناوين البريد وقيمه مصفوفات مسارات فرعية ضمن الجذور المسموحة، مثل {"user@example.com":["D:\\SovereignAI\\workspaces\\user"]}. يرفض الخادم جذور الحسابات المتداخلة ويمنع الحساب من اختيار مسار حساب آخر. حساب بلا تخصيص يستطيع الدردشة لكنه لا يستطيع قراءة مساحة عمل.
الوكيل يطابق السؤال مع ملفات النص/الكود المدعومة، ويمكنه قراءة PDF رقمي يحدده المستخدم؛ يمرر مقتطفات محدودة للنموذج، وعند ذكر مسار نسبي مثل app/main.py يزيد المقتطف إلى 12,000 حرف كحد أقصى. يعيد أسماء الملفات التي قرأها. الملفات المخفية، مجلدات .git وبيئات البناء، والملفات الكبيرة أو خارج جذر مساحة العمل مستثناة.
في وضع الوكيل اختر المهارة من أيقونة الدماغ بجانب زر مساحة العمل: شرح الكود أو مراجعة الكود أو خطة اختبارات. يستعرض GET /v1/agent/skills المهارات وأدوات كل منها؛ يتحقق الخادم من صلاحيات الأداة ولا يعتمد على طلب النموذج وحده. يمكنه استخدام حتى 3 أدوات مسموحة بالتتابع ضمن الطلب، أداة واحدة في كل خطوة، ثم يعيد النتائج للنموذج لصياغة الإجابة. مراجعة الكود تستطيع طلب معاينة diff فقط، ولا تطبق تغييرًا.
فهرس معرفة محلي: في وضع مساحة العمل حدد ملفات UTF-8 أو PDF رقميًا/ممسوحًا ثم اضغط زر الفهرسة بجانب أيقونة المجلد؛ زر الإزالة يحذف الملفات المحددة من الفهرس. يدعم POST /v1/agent/knowledge/index وDELETE /v1/agent/knowledge/index وPOST /v1/agent/knowledge/search. يقتصر الطلب على 20 ملفًا و2 ميغابايت إجمالًا، و256 كيلوبايت للملف النصي، وPDF حتى 30 صفحة و24 ألف محرف مستخرج. يجمع PDF المختلط نص الصفحات الرقمية وOCR لأول 3 صفحات ممسوحة، ويضيف تضمينات Granite المحلية الاختيارية إلى FTS5 عند توفر النموذج؛ لا يرفع المحتوى إلى خدمة خارجية. تعذر التضمين يبقي البحث النصي فعالًا. إعادة الفهرسة تستبدل النسخة السابقة، والبحث يحذف تلقائيًا أي مستند تغيّر أو لم يعد ضمن المساحة.
زر مشبك الورق يفتح اختيار ملفات الكود/النص وPDF (حتى 3 ملفات؛ النص 256KB للملف، وPDF 8MB للملف، والمجموع 16MB). تُقرأ الملفات في الذاكرة؛ يستخرج API نص الصفحات الرقمية حتى 30 صفحة و24,000 محرف، ويرسم أول 3 صفحات ممسوحة ضمن الطلب. يضيف OCR عربي/إنجليزي اختياريًا قبل نموذج الرؤية المحلي مع تحويل تلقائي إلى ministral-3:3b إن كان مثبتًا. لا يخزن الملفات أو ينفذ الكود.
تظهر 👍/👎 تحت إجابات المساعد. يحفظ التقييم مع رقم نسخة الإجابة في SQLite حتى نتمكن من قياس الجودة وتجهيز أمثلة تقييم أو تفضيلات بمراجعة بشرية؛ الضغط لا يدرّب النموذج ولا يغيّر أوزانه تلقائيًا.
Gemma 4 E2B لديها قدرة نموذجية على إدخال الصور والصوت وفق بطاقة Google الرسمية. الصور وPDFات الصفحات الممسوحة تمر عبر مسار محلي إلى نموذج الرؤية، مع دعم OCR عربي/إنجليزي اختياري يعرض النص والثقة المتوسطة. ترتيب القراءة تقريبي والثقة غير معايرة؛ قراءة ملفات الكود النصية تعمل عبر زر المرفقات أو وضع مساحة العمل.
لإنشاء نسخة Release، نفّذ flutter build windows --release من داخل flutter_app.
التطبيق المكتبي واجهة أمامية؛ يحتاج Ollama وFastAPI شغّالين على الجهاز. النموذج لا يُضمّن داخل ملف التطبيق التنفيذي، ويظل نسخ الصوت للنص عبر Groq Whisper عند استخدام الميكروفون.

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

تحفظ FastAPI المحادثات والرسائل في SQLite محليًا. على Windows يوجد الملف في %LOCALAPPDATA%\SovereignAI\data\sovereign_ai.sqlite3، وخارج مجلد المشروع لتجنب مزامنة قاعدة البيانات مع OneDrive.
لكل سجل محادثة user_id، وتُفلتر القراءة والتعديل والحذف بهوية جلسة Bearer موثقة؛ لم يعد X-User-ID يمنح أي صلاحية. في الوضع المحلي تطلب الواجهة تلقائيًا جلسة للمستخدم المحلي، ولا يصدرها الخادم إلا لاتصال loopback.
يوفّر API الآن POST /v1/auth/register وPOST /v1/auth/login وGET /v1/auth/me وPOST /v1/auth/logout. كلمات المرور تُخزن بتجزئة PBKDF2 مع salt؛ رمز الجلسة العشوائي يُخزن كـSHA-256 وينتهي بعد 7 أيام ويمكن إلغاؤه. أضاف Flutter واجهة تسجيل ودخول وخروج، ويحفظ رمز الحساب عبر flutter_secure_storage في تطبيقات الأنظمة الأصلية. على الويب يبقى الرمز في الذاكرة فقط ولا يُحفظ بعد إعادة تحميل الصفحة أو إغلاق التبويب؛ بذلك يحتاج المستخدم لتسجيل الدخول مجددًا. هذا يتجنب التخزين الدائم في JavaScript-accessible browser storage، لكنه لا يمنع سرقة الجلسة أثناء تشغيل صفحة مخترقة؛ يحتاج النشر العام مراجعة حماية XSS وHTTPS.
استعادة كلمة المرور عبر POST /v1/auth/password-reset/request ثم POST /v1/auth/password-reset/complete. الإرسال معطل حتى تضبط على خادم FastAPI: SOVEREIGNAI_SMTP_HOST, SOVEREIGNAI_SMTP_PORT (587 افتراضيًا أو 465 مع SSL), SOVEREIGNAI_SMTP_SECURITY (starttls افتراضيًا أو ssl), SOVEREIGNAI_SMTP_FROM, وبيانات الدخول الاختيارية SOVEREIGNAI_SMTP_USERNAME/SOVEREIGNAI_SMTP_PASSWORD. لا تحفظ كلمة مرور SMTP في Flutter أو Git. رمز الاستعادة عمره 30 دقيقة، بصمته فقط محفوظة، ويُستخدم مرة واحدة؛ تغيير كلمة المرور يلغي جلسات الحساب السابقة. رد طلب الاستعادة عام، والميزة تعيد 503 إن لم تُهيأ خدمة SMTP.
يوجد كذلك smoke test مؤقت مستقل: .venv/Scripts/python.exe scripts/local_tls_smoke.py ينشئ شهادة مؤقتة وخادم loopback ثم ينظفهما. الإعداد الدائم الاختياري لعميل Windows موثق أعلاه؛ ثقة المتصفح والوصول الشبكي ما زالا غير متحققين.
بناء Windows يتطلب مكوّن C++ ATL ضمن Visual Studio Build Tools بسبب إضافة flutter_secure_storage_windows؛ ATL مثبت الآن ونجح بناء Debug على هذا الجهاز. على Android الحد الأدنى صار API 23.
كل عمليات /v1/* الخاصة تتطلب الآن Bearer session؛ الاستثناءات العامة هي الصحة وقائمة النماذج وتسجيل/دخول الحساب وإنشاء الجلسة المحلية. عميل Flutter يرسل الجلسة للمحادثة والوكيل والملفات والمعرفة والبحث والصوت. ملكية سجل تدقيق الوكيل وفهرس المعرفة ومقترحات تعديل الملفات مرتبطة بمعرّف الحساب.
أضيف حد أولي لمحاولات الدخول وإنشاء الحسابات وطلبات استعادة كلمة المرور في SQLite، لكنه لم يخضع بعد لاختبار ضغط/خلف reverse proxy. يخصص SOVEREIGNAI_USER_WORKSPACES مجلدات منفصلة للحسابات ضمن جذور SOVEREIGNAI_ALLOWED_WORKSPACES، لكن عملية FastAPI ما زالت ترث صلاحيات نظام التشغيل. أبقِ الخدمة على 127.0.0.1 إلى أن يكتمل العزل على مستوى العملية ويُختبر TLS.
يرفض FastAPI الآن أي طلب مصدر اتصاله ليس loopback (127.0.0.1 أو ::1) بحالة 403، حتى لو شُغّل الخادم خطأً على واجهة شبكة أوسع. هذا حاجز تطبيق إضافي، وليس عزلًا لصلاحيات ملفات العملية؛ لا تعرض الخدمة على الشبكة قبل إكمال العزل وتكوين TLS.
رسائل الدردشة ترسل إلى 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.