دليل الباحث

لمن هذا الدليل

لباحثي الذكاء الاصطناعي والمطوّرين الذين يرغبون في استكشاف التجارب في Agent-Lab وإعادة إنتاجها وتوسيعها. إذا كنت تكتب بلغة Python، وتستخدم Jupyter، وتفكّر بمنطق التجارب والوكلاء ومسارات المعالجة، فستشعر بالألفة هنا. الإلمام بأساسيات LLM وRAG والحاويات مفيد لكنه ليس شرطاً.

يوفّر Agent-Lab مكونات قابلة لإعادة الاستخدام (أنواع الوكلاء، والأدوات، والتكاملات) إضافة إلى مجموعة من دفاتر Jupyter مع أمثلة خطوة بخطوة، لتصبح منتجاً بسرعة.

البدء السريع — تشغيل الأمثلة

المتطلبات: Python 3.12+، وبيئة Jupyter عاملة (JupyterLab أو Notebook)، واختيارياً Docker محلي للتكاملات من طرف إلى طرف. عند العمل في نسخة مستنسخة من المستودع:

uv sync --group notebooks   # runtime + notebook dependencies in one virtualenv
jupyter lab                 # from the repository root

افتح notebooks/ وابدأ بـ 01_…، ثم تقدّم عبر الدفاتر التي تهمّك.

ملاحظات:

• الدفاتر مستقلة بذاتها في الغالب؛ ويذكر رأس كل دفتر متغيرات البيئة المطلوبة والخدمات الخارجية (مفاتيح API، ونقاط النهاية).
• توجد المفاتيح المطلوبة في .env — انسخ .env.example واملأه (راجع مرجع الإعدادات).
• لإجراء التجارب على Agent-Lab من مشروعك الخاص بدلاً من المستودع، نفّذ pip install btech-agent-lab وجمّع التطبيق باستخدام create_app() — راجع توسيع الإطار في دليل المطوّر.

بنية المشروع — جولة سريعة

• notebooks/ — أمثلة تفاعلية لأنواع الوكلاء والتقييم والتكاملات. ابدأ من هنا.
• agent_lab/ — حزمة الإطار:
  • app_factory.py — جذر التركيب: create_app().
  • core/ — مصادر الإعدادات، وحاوية DI، وحل extra_deps.
  • domain/ — النماذج، وواجهات المستودعات، والاستثناءات (نموذج نطاق الكيانات).
  • services/ — منطق الأعمال وتنفيذات agent_types/.
  • interface/ — api/ (موجّهات HTTP) وmcp/ (خادم MCP).
  • infrastructure/ — محوّلات قاعدة البيانات، والمصادقة، والمقاييس/التتبّع.
• tests/ — حزم unit/ وintegration/ وtemplate/ وsimulation/ (راجع الاختبارات والمحاكاة).
• doc/ — التوثيق الذي تقرؤه الآن.

يوضّح لك فهم هذه الطبقات أين يقع كل سلوك: الأمثلة في notebooks، والعقود الأساسية في core/ وdomain/، والمحوّلات في infrastructure/.

الدفاتر — مسار التعلّم الأساسي

التسلسل المعتاد:

يحتوي كل دفتر على: وصف موجز لهدف التجربة، و متغيرات البيئة والأسرار المطلوبة، ودوال مساعدة، ومخرجات مطبوعة/مرئية لفحص قرارات الوكيل ومقاييسه.

نصيحة احترافية: شغّل الدفاتر بالترتيب لمنحنى تعلّم تدريجي. واستخدم مجموعات بيانات وأحجام عيّنات أصغر أثناء التكرار للحفاظ على سرعة التشغيل.

المفاهيم الأساسية

• الوكيل (Agent) — تنفيذ مسجّل ضمن agent_lab/services/agent_types/ (@discoverable_agent). يحلّه السجل بشكل كسول (lazily) عبر حاوية DI، مع حقن extra_deps المُعلَنة.
• الأدوات (Tools) — قدرات منفصلة يمكن للوكيل استدعاؤها (البحث، والتصفّح، وTTS/ASR)، مُنفَّذة بوصفها محوّلات في agent_lab/infrastructure/ أو agent_lab/interface/.
• الحاوية (Container) — كائن تركيب DI (agent_lab/core/container.py)؛ أنشئ فئة فرعية منه لإضافة مزوّدات لتجاربك.
• المستودعات (Repositories) — واجهات الوصول إلى البيانات في agent_lab/domain/repositories/.
• ConfigSource — مصدر الإعدادات؛ استخدم مصادر YAML في التجارب، وVault في بيئة الإنتاج.

عندما تريد تعديل السلوك، حدّد ما إذا كان التغيير: تجريبياً (في الدفتر فقط)، أو معمارياً (core/domain/services)، أو على مستوى التكامل (محوّل في infrastructure). فضّل التغييرات الصغيرة القابلة للاختبار — وأضف دفتراً أو حدّث دفتراً قائماً لعرض السلوك الجديد.

تشغيل التجارب وتسجيل النتائج

تطبع الدفاتر الخطوات الوسيطة؛ وللحصول على تجارب أكثر متانة:

• استخدم بذوراً (seeds) حتمية حيثما تكون العشوائية مؤثرة.

• سجّل المقاييس ذات الصلة بسؤالك — زمن الاستجابة، واستهلاك الرموز، وعدد استدعاءات الأدوات، ودرجات المُحكِّم. تصدّر طبقة قابلية المراقبة كل شيء عبر OpenTelemetry (راجع قابلية المراقبة)؛ وتسجّل بيئة المحاكاة درجات المُحكِّم في Langfuse/LangWatch (راجع الاختبارات والمحاكاة).

• للحصول على تشغيلات قابلة للتكرار، صدّر خلايا الدفاتر إلى سكربتات وشغّلها في CI أو على عُقد الحوسبة:

  jupyter nbconvert --to script notebooks/02_test_agent_type-adaptive_rag.ipynb

• يبني docker/app/Dockerfile صورة تشغيل مثبّتة الإصدارات لتنفيذ قابل لإعادة الإنتاج.

بناء نماذج أولية لسلوكيات جديدة

1. أضف نوع وكيل جديداً: أنشئ الفئة ضمن agent_lab/services/agent_types/، وزخرفها بـ @discoverable_agent("your_type")، وأضف دفتراً يركّبها عبر حاوية DI ويختبرها بسيناريو صغير. يتوفر الشرح الكامل في بناء سير العمل الوكيلي.
2. استبدل مزوّد التضمينات: نفّذ محوّلاً متوافقاً ضمن agent_lab/infrastructure/ وتحقّق منه باستخدام الدفتر 01.
3. أضف مخزن استرجاع أو قاعدة بيانات متّجهية: نفّذ دوال المستودع في agent_lab/domain/repositories/ ومحوّلاً في agent_lab/infrastructure/database/؛ واملأه بالبيانات عبر دفتر تحميل صغير واعرض الاسترجاع في دفتر استعلام.

نصيحة تصميمية: اجعل واجهات المحوّلات ضيقة النطاق واختبرها بمعزل عن غيرها باستخدام اختبارات وحدة صغيرة.

الاختبار والتقييم

make test_unit           # unit tests — no infrastructure needed
make test                # unit + integration with coverage
make test_simulations    # LLM-as-judge agent simulations (live LLMs)

عندما تغيّر السلوك الأساسي، أضف اختبار وحدة ودفتراً قصيراً يوضّح التغيير — فهذا الاقتران هو ما يجعل البحث قابلاً لإعادة الإنتاج هنا. تتناول صفحة الاختبارات والمحاكاة بيئة الاختبار الكاملة، وإعداد المُحكِّم، ومنصات التقييم.

قائمة التحقق من قابلية إعادة الإنتاج

• ثبّت إصدارات بيئتك (uv + pyproject.toml / uv.lock).
• سجّل البذور وملفات الإعدادات (config-dev.yml، وconfig-test.yml).
• احفظ نقطة حفظ الدفتر وأي مخرجات (CSV/JSON) إلى جانب تجربتك.
• دوّن نقاط نهاية التتبّع التي صدّرت إليها — فالتتبّعات هي سجل تجربتك.