chore: establish Sovereign AI reference

2026-09-29 22:38:37 +03:00
commit ce1b22f100
147 changed files with 7394 additions and 0 deletions
@@ -0,0 +1,69 @@
+# SovereignAI Starter
+
+مشروع تعليمي لبناء مساعد ذكاء اصطناعي محلي قابل للتوسع. النموذج المحمّل حاليًا: `qwen2.5:1.5b-instruct-q4_K_M` (نحو 986 ميغابايت).
+
+## مكونات النسخة الأولى
+- FastAPI كواجهة HTTP محلية.
+- وكيل تجريبي بأداة حساب آمنة ومحدودة.
+- واجهة `/docs` لاستكشاف الـ API من المتصفح.
+- يمكن توصيلها بخادم نموذج محلي يوفّر واجهة OpenAI مثل Ollama.
+- دون إعداد عنوان خادم نموذج، تعمل الواجهة في وضع العرض التجريبي.
+
+## التشغيل على Windows
+1. ثبّت Python 3.11 أو أحدث.
+2. افتح PowerShell داخل المجلد. إذا كانت `.venv` موجودة، تخطَّ خطوة إنشائها وثبّت الاعتماديات فقط عند الحاجة.
+3. أنشئ بيئة افتراضية وثبت الاعتماديات:
+
+```powershell
+py -m venv .venv
+.\.venv\Scripts\Activate.ps1
+python -m pip install -r requirements.txt
+```
+
+4. (اختياري على جهاز جديد فقط) شغّل Ollama واسحب النموذج:
+
+```powershell
+ollama pull qwen2.5:1.5b-instruct-q4_K_M
+```
+
+الخادم الحالي مضبوط افتراضيًا على Ollama المحلي واسم النموذج أعلاه. لتغييرهما عرّف المتغيرات في نافذة PowerShell نفسها:
+
+```powershell
+$env:LOCAL_LLM_BASE_URL = "http://127.0.0.1:11434/v1"
+$env:LOCAL_MODEL = "qwen2.5:1.5b-instruct-q4_K_M"
+```
+
+راجع رخصة النموذج المختار وشروطه الحالية قبل الاستخدام التجاري. تنزيل النموذج يحتاج اتصال إنترنت ومساحة تخزين.
+
+5. شغل الـ API على جهازك فقط (أو شغل `start-api.ps1`):
+
+```powershell
+python -m uvicorn app.main:app --reload --host 127.0.0.1 --port 8000
+```
+
+6. افتح `http://127.0.0.1:8000/docs`.
+
+## نقاط التجربة
+- `GET /health` للتأكد من أن الخدمة تعمل.
+- `POST /v1/chat/completions` لإرسال رسالة.
+- `POST /v1/agent/run` لتجربة الوكيل والأداة الحسابية.
+- `POST /v1/chat/completions` يمرر الطلب إلى الخادم المحلي عند ضبط المتغيرين أعلاه.
+
+الخدمة مربوطة بـ `127.0.0.1` عمدًا، فلا تعرضها على الشبكة أو الإنترنت الآن. الوكيل الحالي يمرر السؤال النصي للنموذج، وينفذ الحسابات البسيطة بأداة حساب محلية محدودة. لا يقرأ ملفات ولا ينفذ أوامر النظام.
+
+## واجهة Flutter
+
+يوجد تطبيق Flutter متعدد المنصات في `flutter_app`، ويبدأ كواجهة محادثة ويب عربية متصلة بهذا الـ API. راجع `flutter_app/README.md` للتشغيل. عنوان الاتصال الافتراضي `http://127.0.0.1:8000`؛ التطبيق يسمح بتغييره من الإعدادات.
+
+### المحادثات والصوت
+
+- تحفظ 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`.