البنية المعمارية

تفكيك عميق ومرجعي للمصدر لمحرك كاظمة: عقل المُشرف، مسار البيانات من نيّة المستخدم إلى تنفيذ الأدوات، والأنظمة الفرعية التي تجعلها دائمة وآمنة ومتعددة اللغات.

---

1. الفلسفة: عقل واحد، أفواه كثيرة

تُنظَّم كاظمة حول فصل صارم بين الاستدلال (رسم LangGraph للمُشرف) والنقل (مُكيّفات المنصات). نسخة رسم واحدة — تُبنى مرة بـ build_supervisor_graph() — تخدم كل قناة. الرسم لا يرى معرّفات خاصة بالمنصة؛ المُكيّفات تملكها وتعيد ربطها عند الإرسال فقط.

ينتج عن ذلك ثلاث خصائص يعتمد عليها النظام:

1. حرية المزوّد — العقل يتحدث إلى أي نقطة OpenAI-متوافقة عبر httpx. بلا SDK بائع.
2. تكافؤ القنوات — وقفة HITL واستدعاء أداة ورمز متدفّق متطابقة سواء من Telegram أو واجهة الويب.
3. حالة دائمة — لأن معرّفات المنصة خارج الرسم، حالة الرسم محادثية خالصة ويمكن حفظها وإعادة تشغيلها عبر إعادة التشغيل.

---

2. طوبولوجيا الحزم

كاظمة monorepo من سبع حزم قابلة للتثبيت (في pyproject.toml):

الحزمة	المسار	المسؤولية
kazma-core	kazma-core/kazma_core/	مشغّل الوكيل، مزوّد LLM، سجل النماذج، محرك السرب، ConfigStore، الأمان، الذاكرة، المهارات، MCP، hub، الضغط، المجلس
kazma-gateway	kazma-gateway/kazma_gateway/	مُكيّفات Telegram/Discord/Slack، جسر الرسم، أوامر slash، مخزن الجلسات
kazma-ui	kazma-ui/kazma_ui/	مصنع FastAPI، دردشة SSE، لوحة السرب، الإعدادات، لوحة التحكم، i18n
kazma-tui	kazma-tui/kazma_tui/	لوحة Textual (مستهلك قراءة غالبًا)
kazma-memory	kazma-memory/kazma_memory/	مُرمِّز عربي + خلفية بحث SQLite/FTS5
kazma-skills	kazma-skills/kazma_skills/	بيانات manifests المهارات
kazma-cli	kazma-cli/kazma_cli/	سطح أمر kazma

سكربتات الكونسول:

kazma     = "kazma_cli.main:main"
kazma-tui = "kazma_tui.app:main"
kazma-web = "kazma_ui.app:main"

---

3. عقل المُشرف (LangGraph)

الرسم الأساسي حلقة ReAct في agent/graph_builder.py.

3.1 طوبولوجيا العقد

flowchart LR
    START([user message]) --> SUP[Supervisor Node]
    SUP -- "LLM calls tools" --> TW[Tool Worker Node]
    TW -- "tool results" --> AUTH{ContextAuthority<br/>check & enforce}
    AUTH -- "compact if ≥80%" --> SUP
    AUTH -- "under threshold" --> SUP
    SUP -- "no tool calls" --> RESP[Respond Node]
    RESP --> END([reply / SSE stream])
    TW -- "danger tool + HITL on" --> INT[LangGraph interrupt]
    INT -- "approval" --> TW
    INT -- "denial / timeout" --> RESP

• عقدة المُشرف — تستدعي LLM النشط بالأدوات والتاريخ.
• عقدة عامل الأدوات — تنفّذ الاستدعاءات؛ بوابة HITL هنا: أدوات الخطر → interrupt().
• ContextAuthority — قبل استدعاء LLM؛ ضغط عند ≥80% من النافذة.
• عقدة الرد — تُنهي رد المساعد للبث.

3.2 الحلقة في الكود

build_supervisor_graph() يمرّر hitl_config لتفعيل البوابة. موقع البناء الحقيقي في agent_runner.get_streaming_graph():

def get_streaming_graph(self):
    hitl_config = {
        "enabled": self._config.get("safety.hitl.enabled", True),
        "require_approval_for": self._config.get(
            "safety.hitl.require_approval_for",
            DEFAULT_DANGER_TOOLS,
        ),
        "approval_timeout_seconds": self._config.get(
            "safety.hitl.approval_timeout_seconds", 60
        ),
    }
    graph = build_supervisor_graph(
        model=self.model,
        tools=self.tools,
        hitl_config=hitl_config,
        checkpointer=self._checkpointer,
    )
    return graph

3.3 التنفيذ الدائم

• Checkpointer: AsyncSqliteSaver على kazma-data/checkpoints.db.
• هوية الخيط: thread_id (مثل gw-telegram-12345 أو UUID).
• استرداد الأعطال: وقفات HITL في الـ checkpointer؛ restore_paused_tasks() يعيد مهام السرب.
• السفر عبر الزمن: /replay وإعداد time_travel (max_snapshots: 50).

---

4. تدفق البيانات من طرف لطرف

sequenceDiagram
    participant U as User (Telegram/Web/...)
    participant A as Platform Adapter
    participant S as SessionStore
    participant H as AgentHandler (graph bridge)
    participant G as Supervisor Graph
    participant L as LLM Provider (httpx)
    participant T as ToolRegistry
    participant M as Bus (HITL)

    U->>A: text message
    A->>S: put(thread_id, {chat_id, user_id, ...})
    A->>H: IncomingMessage (no platform IDs in body)
    H->>G: graph.ainvoke({messages:[...]}, config={thread_id})
    loop ReAct
        G->>L: POST /chat/completions (tools=...)
        L-->>G: tool_calls or final text
        alt danger tool
            G->>M: interrupt(approval_input)
            Note over G,M: graph SUSPENDED
            M-->>U: approval request (inline button / SSE event)
            U->>M: approve
            M->>G: Command(resume={"approved":true})
        end
        G->>T: execute(tool, args)
        T-->>G: ToolResult
    end
    G-->>H: final state
    H->>S: get(thread_id)
    H->>A: OutboundMessage(target_id, text)
    A-->>U: reply

الثابت	يُفرض بواسطة	الموقع
معرّفات المنصة لا تدخل حالة الرسم	_PLATFORM_KEYS + _build_initial_state	agent_handler/store.py
الرد يعود للدردشة الصحيحة	_build_target_id	store.py
نموذج مزوّد خاطئ لا يضرب نقطة خاطئة	get_client() auto-correction	model_registry.py
أدوات الخطر تتوقف ولا تُنفَّذ بصمت	interrupt() + _hitl_approved	graph_builder.py

---

5. طبقة مزوّد LLM

llm_provider.py عميل httpx بلا SDK بصيغة OpenAI Chat Completions. معظم المزوّدين يعملون عبر LLMProvider العام.

أربعة مزوّدين بفئات أصلية:

المزوّد	الصنف	السبب
Google Gemini	GeminiProvider	Vertex/ADC
Anthropic	AnthropicProvider	/messages + x-api-key
Azure OpenAI	AzureProvider	api-key + api-version
AWS Bedrock	BedrockProvider	SigV4 + Converse

انظر LLM Providers.

5.1 حل المزوّد

ModelRegistry.get_client() يصحّح تلقائيًا إن طلب نموذجًا يملكه مزوّد آخر غير النشط.

5.2 حل NVIDIA NIM عند رفض الأدوات

بعض المزوّدين يرفضون تعريفات الأدوات بـ 404 Function not found؛ العميل يعيد المحاولة بلا أدوات مرة واحدة.

5.3 البث

stream_chat() في streaming.py — مولّد async منفصل، أحداث StreamEvent (token, tool_call, done, error).

5.4 التكلفة وإعادة المحاولة

الاهتمام	الآلية
تكلفة النداء	tokens × تكلفة/1M
سقف التكلفة	CostCircuitBreaker (افتراضي $0.50)
إعادة المحاولة	tenacity — شبكة/مهلة فقط، لا 4xx
معالجة 429	غير منفَّذة

---

6. تنسيق السرب (نظرة عامة)

SwarmEngine يدعم ستة أنماط: DISPATCH، BROADCAST، PIPELINE، FAN_OUT، CONSULT، CONDITIONAL.

flowchart TB
    subgraph SwarmEngine
        DI[dispatch_inner]
        DI -->|single| DSP[dispatch]
        DI -->|all| BCAST[broadcast]
        DI -->|ordered| PIPE[pipeline + blackboard]
        DI -->|parallel| FAN[fan-out + aggregate]
        DI -->|opinions| CONS[consult + synthesize]
        DI -->|router| COND[conditional routes]
    end
    DSP & BCAST & PIPE & FAN & CONS & COND --> W[Worker]
    W --> REL[ReliabilityRegistry]

حراسة التسليم: MAX_HANDOFF_DEPTH = 5 وMAX_VISITS = 2. التفاصيل: تنسيق السرب.

---

7. أنظمة الذاكرة (نظرة عامة)

ذاكرة الدردشة في كاظمة هي محرك V2 المعرفي (رسم معتقدات ثنائي الزمن، استدعاء PPR). أُزيل مكدّس RRF بأربع طبقات (V1) في التحوّل من V1 إلى V2؛ V2 هي المكدّس الوحيد. أجزاء مساندة:

النظام الفرعي	الخلفية	الحالة
محرك V2 المعرفي	رسم معتقدات ثنائي الزمن + حلقات من 4 طبقات + sqlite-vec (memory_state.db)	✅ افتراضي الدردشة — مسار قراءة/كتابة واحد (recall() من memory/recall.py)
PPR بمخطط الأنانية المحلي	Personalized PageRank على رسم المعتقدات/الحلقات (قفزتان، N≤200)	✅ memory/ppr.py
Consolidator	استخلاص معتقدات/حلقات LLM/استدلالي، بسياج	✅ memory/consolidator.py
طابور توحيد دائم	طابور عمّال بـ SQLite (memory_ops.db)	✅ memory/task_queue.py
المكتبة المعرفية	kazma_kb_* معزول	✅ منفصل عن ذاكرة الدردشة

الإعداد: إشارات memory.* تستخدم ConfigStore ← kazma.yaml؛ V2 مفعّل عند memory.v2.use_new_stack: true. التفاصيل: الذاكرة وRAG.

---

8. الطبقة العربية والثقافية

كاظمة عربية افتراضيًا (agent.language: ar, agent.rtl: true):

1. مُرمِّز عربي — تطبيع + FTS content_arabic
2. i18n + RTL — ترجمات EN/AR، dir/lang
3. بروتوكول المجلس — GREETING → SOCIAL → TRANSACTION → FAREWELL

انظر الميزات العربية والثقافية.

---

9. الرصد (الحالة الحالية)

الإشارة	الحالة
سجلات منظمة	✅
مقاييس السرب	✅
تتبع داخلي (TraceStore)	✅
أدوات البحث على الويب	✅ — البحث على الويب
SSE telemetry	✅
Langfuse	✅ موصول، خامد افتراضيًا
OpenTelemetry	🔴 أُزيل
Prometheus	🔴 غير منفَّذ

---

10. مخازن البيانات المشتركة

كل مخازن SQLite تستخدم:

PRAGMA journal_mode=WAL;
PRAGMA busy_timeout=5000;
PRAGMA synchronous=NORMAL;

المخزن	المسار	الغرض
ConfigStore	kazma-data/settings.db	إعدادات وقت التشغيل
Checkpointer	kazma-data/checkpoints.db	حالة المحادثة / HITL
TaskStore	kazma-data/swarm_tasks.db	مهام السرب
اللقطات	kazma-data/snapshots.db	/replay
Hub	~/.kazma/hub/registry.db	مهارات مثبتة
ذاكرة V2 (الحالة)	kazma-data/memory_state.db	معتقدات/حلقات/كيانات ثنائية الزمن (قراءات ساخنة)
ذاكرة V2 (العمليات)	kazma-data/memory_ops.db	طابور التوحيد + سجل التدقيق (كتابات باردة)

---

السلامة والمرونة (شاملة للقطاعات)

نظامان شاملان للقطاعات يجلسان عبر المشرف والأدوات:

• محرك التشغيل المتواصل والشفاء الذاتي. يغلّف supervised_invoke() تنفيذ الرسم بنبضات العُقد وكشف التوقّف؛ عند التوقّف يعود إلى آخر نقطة حفظ دائمة، يحقن تأمّلاً [KAZMA RECOVERY]، ويستأنف حتى N محاولة. النماذج الأساسية المستنفَدة تتبدّل عبر agent.nonstop.failover.chain مع فترات تبريد لكل نموذج (دون تغيير الملف النشط). سجلّ استدعاءات LLM دائم (kazma-data/llm_calls.db) يسجّل كل استدعاء؛ تُعاد مهام السرب المتروكة إلى الطابور عند الإقلاع؛ ومراقب يرفض تلقائياً موافقات HITL المعلّقة بعد safety.hitl.approval_timeout_seconds.
• طبقة الالتزام (الحل قبل التنفيذ). بوابة سياسات بين نموذج اللغة والتعديلات الدائمة. قبل الجدولة/الإرسال/التنفيذ/تغيير الإعدادات، يحلّ authorize_effect القصد مقابل الذاكرة والسياسات؛ الأفعال الغامضة تُطلق بطاقة مقاطعة توضيح/تأكيد دلالية على كل منصة. يعمل في tool_worker_node قبل انقسام HITL ليُعيد كتابة وسطاء الأداة أولاً. الدليل المخصّص: طبقة الالتزام.

---

ملاحظات تدقيق الوثائق

• الذاكرة (تحوّل 2026-07): V2 (معتقدات ثنائية الزمن + استدعاء PPR) هي مكدّس الذاكرة الوحيد (استدعاء لكل دور، أدوات، auto-store، ضغط). أُزيل محوّل RRF الرباعي الطبقات (V1)؛ الملاحظات القديمة التي تشير إلى UnifiedMemoryAdapter / VectorMemory باطلة.
• agent_handler حزمة وليس ملفًا واحدًا.
• UnifiedModelRegistry مجرد alias لـ ModelRegistry.