شبكة Providentia هي واجهة خلفية مبنية على Django تُنسّق الاستدلال متعدد الفروع باستخدام نماذج Gemini من Google، ومعالج مساعد أصلي بلغة C++، ورسومات بيانية اختيارية لشبكة الأفكار. يلخص هذا المستند البنية الحالية ويوفر الأوامر اللازمة لبناء وتشغيل النظام محليًا.

https://www.promptingguide.ai/techniques/tot

Yao et al. (2023) و Long (2023)

اقترحا مؤخرًا إطار "شجرة الأفكار" (ToT)، وهو إطار يعمم أسلوب التوجيه المتسلسل للأفكار ويشجع على استكشاف الأفكار التي تعمل كخطوات وسيطة لحل المشكلات العامة باستخدام نماذج اللغة.

يحافظ ToT على شجرة من الأفكار، حيث تمثل الأفكار تسلسلات لغوية متماسكة تعمل كخطوات وسيطة نحو حل مشكلة. يمكّن هذا النهج نموذج اللغة من التقييم الذاتي للتقدم المحرز من خلال الأفكار الوسيطة نحو حل مشكلة عبر عملية استدلال مدروسة. ثم يتم دمج قدرة نموذج اللغة على توليد وتقييم الأفكار مع خوارزميات البحث (مثل البحث بالعرض الأول والبحث بالعمق الأول) لتمكين الاستكشاف المنهجي للأفكار مع التخطيط المسبق والتراجع.

بنية النظام

تدفق البيانات عالي المستوى

العميل -> /speech/simple_response (عرض Django REST)
      -> مدير التفكير Python (speech/context_manager/ThinkingManager.py)
      -> مفكر C++ "كييفان روس" (speech/context_manager/Kievan Rus/*.cpp)
      -> واجهة Gemini API (JSON عبر HTTPS)
      -> حمولة ثنائية (حالة + سياق + ملخص)
      -> مفكك تسلسل Python وتوسيع الفروع
      -> رسم بياني PNG اختياري (speech/context_manager/graphs/)
      -> نص استجابة Django

المكونات الأساسية

نقطة نهاية Django REST (speech/views.py)
تستقبل مطالبة المستخدم، وتُنشئ ThinkingManager، وترسل نص التعليمات النهائي الذي يعيده الوكيل.
مدير التفكير Python (speech/context_manager/ThinkingManager.py)
يحافظ على شجرة الأفكار ويفرض القواعد المعمارية:
- يستدعي المساعد الأصلي C++ كعملية فرعية مع الرسالة الحالية، وتسمية الفرع، وبيانات التكرار.
- يحلل الاستجابة الثنائية (1 بايت للحالة، 4 بايت للأطوال، حمولات UTF-8) ويتحقق من صحة JSON مقابل ContextStruct (Pydantic).
- يسجل لكل فرع probability_of_success، وpotential_score التزايدي، وpossible_setbacks، وتسميات الفروع.
- يضمن استكشاف فرعين على الأقل لكل مستوى ويجمع درجة الاحتمال التراكمية.
- يصدر شجرة نصية ويقدم اختياريًا رسمًا بيانيًا PNG (انظر أدناه).
مفكر C++ "كييفان روس" (speech/context_manager/Kievan Rus/)
مقسم إلى ملفات رأس ومصادر لتحليل الوسائط، وتحميل البيئة، واستدعاءات Gemini HTTP (libcurl)، وبناء المطالبات، والتسلسل الثنائي.
- يقرأ مفتاح Gemini API من بيئة العملية أو ملف .env.
- يصدر طلبين لـ Gemini: واحد للتحليل المنظم، وآخر للملخص السردي.
- يشفّر السياق المنظم والملخص في تنسيق ثنائي محمول يستهلكه Python.
- الهدف build-thinker في Makefile يعيد ترجمة الوحدة (g++17، -lcurl) ويتم ربطه تلقائيًا عند تشغيل الخادم.
عرض الرسوم البيانية (plotting/graphing.py)
يستخدم Matplotlib (واجهة Agg) لتصور شجرة الأفكار النهائية. تتضمن كل عقدة تسمية الفرع، ونص الخطة المغلف، والاحتمالات، ودلتا الاحتمال لكل خطوة، والاحتمال التراكمي، وإبراز الحالات "النهائية" أو "المأسوف عليها". تُحفظ الصور في speech/context_manager/graphs/.
وكيل Gemini (speech/gemini/agent.py)
غلاف خفيف حول عميل genai من Google. تعكس وحدة C++ هذه الوظيفة للاستدلال الحساس لزمن الاستجابة.

دلالات التفرع والتسجيل

يحافظ ThinkingManager على عمق الشجرة محدودًا (max_iterations = 8) مع ضمان أن كل عقدة تُنتج فرعين مُسمّين على الأقل (مثل Primary-A، Primary-B) ما لم يتم تحديد حد التكرار.
يحمل كل فرع:
- probability_of_success — رقم عشري مقيد بـ [0.0, 1.0].
- potential_score — دلتا موقعة تُضاف إلى cumulative_potential.
- possible_setbacks — تقييم نصي للمخاطر مضمن في السجلات، ومخرجات وحدة التحكم، والرسومات البيانية.
تُصدر السجلات لكل إنشاء فرع، وتقييم عددي، وخطوة عرض رسومي لتسهيل التصحيح.

الإعداد والاستخدام

المتطلبات الأساسية

Python 3 (يُوصى باستخدام virtualenv أو بيئة Conda).
g++ مع دعم C++17 وملفات الرأس التطويرية لـ libcurl.
الوصول إلى مفتاح Gemini API (GEMINI_API_KEY) موضوع في .env أو بيئة العملية.
(اختياري) Matplotlib لتوليد رسومات PNG؛ بدونه يسجل النظام تحذيرًا ويتخطى الرسم.

إنشاء البيئة

make update              # يستخدم environment.yml عبر conda/micromamba

تجاوز الإعدادات الافتراضية:

make update CONDA_ENV=my-env-name
make update ENV_FILE=envs/dev.yml
make update CONDA=~/.local/bin/micromamba

البناء والتشغيل

make run                 # يعيد ترجمة مفكر C++ ثم يشغل `python manage.py runserver`

التجميع المستقل (إذا لزم الأمر):

make build-thinker       # cd speech/context_manager/Kievan\ Rus && g++ ... -lcurl

يتوقع الخادم ملف .env في جذر المشروع ما لم يتم تعيين KIEVAN_RUS_ENV_PATH.

أهداف Make الشائعة

الهدف	الوصف
`make run`	بناء المساعد C++ وتشغيل خادم Django التطويري
`make migrate`	تشغيل الترحيلات (`makemigrations` + `migrate`)
`make prepare`	إنشاء بيئة Conda من `environment.yml`
`make update`	تحديث/إنشاء بيئة Conda مع التقليم
`make build-thinker`	إعادة ترجمة وحدة الاستدلال C++
`make help`	عرض الأهداف المتاحة (إذا كانت محددة في Makefile)

استخدم PY=... للإشارة إلى مترجم معين، أو تجاوز DJANGO_SETTINGS_MODULE حسب الحاجة.

ملاحظات التكوين

.env

GEMINI_API_KEY=your-key
# إعدادات Django اختيارية...

KIEVAN_RUS_ENV_PATH (متغير بيئة) يمكنه تجاوز موقع .env لعملية C++.
تُكتب الرسومات إلى speech/context_manager/graphs/thought_graph_<root-id>.png. احذف الدليل لتنظيف القطع الأثرية.

نصائح الاختبار والتصحيح

البروتوكول الثنائي صارم؛ الاستجابات غير الصحيحة من Gemini (مثل حقول text المفقودة) تثير استثناءات واضحة يسجلها كل من طبقات Python و C++.
إنشاء الفروع، وحسابات الاحتمالات، وعرض الرسومات كلها تسجل تقدمًا مفصلاً عبر بادئات [ThinkingManager]. راقب وحدة تحكم Django أثناء التطوير لتتبع تدفق الاستدلال.
إذا كان Matplotlib مفقودًا، يستمر النظام بدون إخراج PNG ولكنه يسجل فشل الاستيراد.

هيكل المستودع (مختار)

speech/
├── context_manager/
│   ├── ThinkingManager.py     # منسق Python
│   └── Kievan Rus/            # مفكر أصلي C++ (مصادر معيارية)
├── gemini/
│   └── agent.py               # غلاف عميل Python لـ Gemini
plotting/
├── graphing.py                # عارض Matplotlib لأشجار الأفكار
README.md
Makefile

تم تصميم الواجهة الخلفية لشبكة Providentia للتجريب التكراري: قم بتحديث المطالبات، أو ضبط معايير التسجيل، أو توسيع التنسيق الثنائي حسب الحاجة. make run يحافظ على تزامن المساعد C++ حتى تتمكن من التركيز على منطق الاستدلال. برمجة سعيدة!

Providence