واجهة البرمجة (API) ونقاط التوسعة

واجهة HTTP/SSE لواجهة كاظمة على الويب، وعقد أحداث الأحداث المُرسلة من الخادم (SSE)، والأماكن المحدّدة لتوسعة الإطار (الأدوات، المُزوّدون، المُحوّلات، المهارات، MCP).

---

1. واجهة واجهة البرمجة (API)

تُحمَّل جميع نقاط النهاية بواسطة KazmaAppBuilder في kazma-ui/kazma_ui/app.py:615-709. المُوجّهات:

المُوجّه	البادئة/النطاق	المصدر
health_router	/health/*	health.py
chat_router	مسارات الصفحات (/chat, …)	chat.py
settings_router	/settings	settings.py
skills_router	المهارات	مسارات skills
mcp_router	MCP	مسارات mcp
agents_router	الوكلاء	مسارات agents
providers_router	/api/providers	مسارات providers
sse_router	/api/chat/*	sse_chat.py
telemetry_router	القياس عن بُعد	مسارات telemetry
dashboard_router	/api/dashboard/*	dashboard.py
models_router	النماذج	مسارات models
workspace_router	مساحة العمل	مسارات workspace
swarm_router	/api/swarm/*	swarm_panel/
monitor_router	المراقبة	مسارات monitor
metrics_router	المقاييس	مسارات metrics

بالإضافة إلى مسارات مباشرة في routes_direct.py وخطّاف ويب (webhook) مشروط لـ Telegram عند /api/webhooks/telegram (app.py:365).

---

2. نقاط النهاية الرئيسية (مُتحقَّق منها)

2.1 الدردشة (SSE)

الطريقة	المسار	الغرض
POST	/api/chat/stream	قناة الدردشة الأساسية. المتن {message, session_id, model}. يُرجِع text/event-stream. (sse_chat.py:353)
GET	/api/chat/sessions	سرد الجلسات. (السطر 547)
DELETE	/api/chat/sessions/{session_id}	حذف الجلسة. (السطر 555)
GET	/api/chat/sessions/{session_id}/messages	سجلّ الجلسة. (السطر 561)

القديم: يُرجِع GET /ws/chat الخطأ 410 Gone (chat.py:4). لا تستخدمه.

2.2 المُزوّدون

الطريقة	المسار	الغرض
GET	/api/provider/active	المُزوّد/النموذج النشط. (السطر 583)
GET	/api/providers	سرد المُزوّدين. (السطر 601)
POST	/api/provider/switch	تبديل المُزوّد/النموذج النشط. (السطر 607)

2.3 موافقة الموافقة البشرية في الحلقة (HITL)

الطريقة	المسار	الغرض
GET	/api/pending-approvals	موافقات HITL المعلّقة. (hitl_approval.py:146)
POST	/api/approve/{thread_id}	الموافقة على/رفض أداة متوقّفة مؤقتًا. المتن `{action: “approve"

2.4 لوحة المعلومات

الطريقة	المسار	الغرض
GET	/api/dashboard/status	نظرة عامة على لوحة المعلومات. (dashboard.py:177)
GET	/api/sessions	قائمة الجلسات. (السطر 221)
POST	/api/sessions/clear-all	مسح الجلسات. (السطر 330)

2.5 السرب

الطريقة	المسار	الغرض
GET	/api/swarm/status	حالة السرب.
GET/POST/DELETE	/api/swarm/workers[/{name}]	عمليات CRUD للعاملين.
POST	/api/swarm/dispatch	إرسال مهمة (جميع الأنماط عبر type).
GET	/api/swarm/tasks[/{id}]	قائمة/تفاصيل المهام.
POST	/api/swarm/tasks/{id}/approve	الموافقة على نقطة تفتيش pipeline. (routes_tasks.py:612)
POST	/api/swarm/tasks/{id}/reject	رفض نقطة تفتيش pipeline. (السطر 657)
GET	/api/swarm/workers/{name}/metrics	مقاييس العامل.
GET	/api/swarm/circuit-breakers	حالات قواطع الدائرة.

2.6 الصحّة

الطريقة	المسار	الغرض
GET	/health/live	التحقق من الحياة. (health.py:94)
GET	/health/ready	التحقق من الجاهزية. (السطر 104)
GET	/health/details	صحة تفصيلية. (السطر 148)
GET	/api/gateway/status	حالة المُحوّل/البوابة.

---

3. عقد أحداث SSE

يُرجِع POST /api/chat/stream تدفّقًا من الأحداث المُرسلة من الخادم (SSE). لكل حدث سطر event: مُحدَّد النوع وحمولة data: بصيغة JSON (sse_chat.py:8-13).

event:	المعنى	حقول الحمولة الرئيسية
token	جزء بثّ من النموذج اللغوي الكبير (LLM).	content
tool_call	أداة تبدأ التنفيذ.	tool, args
tool_result	أداة انتهى تنفيذها.	tool, result, is_error
approval_required	توقيف HITL ظهر — يجب على الواجهة الأمامية استدعاء POST /api/approve/{thread_id}. (السطر 199-207)	thread_id, tool, args
done	اكتمال الدور.	tokens, cost_usd, duration_ms
error	خطأ قاتل.	message

3.1 مثال من جهة العميل (JavaScript)

// chat.js uses KS.sse('/api/chat/stream', {...}); the raw shape is:
const resp = await fetch('/api/chat/stream', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ message: 'Hello', session_id: sess, model: 'gpt-4o-mini' }),
});

const reader = resp.body.getReader();
const decoder = new TextDecoder();
let buffer = '';

while (true) {
  const { value, done } = await reader.read();
  if (done) break;
  buffer += decoder.decode(value, { stream: true });

  // SSE events are separated by blank lines
  let idx;
  while ((idx = buffer.indexOf('\n\n')) !== -1) {
    const block = buffer.slice(0, idx);
    buffer = buffer.slice(idx + 2);
    const eventType = (block.match(/^event: (.+)$/m) || [])[1];
    const data = JSON.parse(((block.match(/^data: (.+)$/m) || [])[1]) || '{}');
    handleEvent(eventType, data);
  }
}

function handleEvent(type, data) {
  switch (type) {
    case 'token':            appendToken(data.content); break;
    case 'tool_call':        showToolCall(data.tool, data.args); break;
    case 'tool_result':      showToolResult(data.tool, data.result); break;
    case 'approval_required': promptApproval(data.thread_id, data.tool); break;
    case 'done':             finishTurn(data.tokens, data.cost_usd); break;
    case 'error':            showError(data.message); break;
  }
}

3.2 إعطاء الموافقة عبر واجهة البرمجة (API) (Python)

import httpx

resp = httpx.post(
    "http://127.0.0.1:8000/api/approve/<thread_id>",
    headers={"X-Kazma-Secret": KAZMA_SECRET},   # required if KAZMA_SECRET is set
    json={"action": "approve", "reason": "looks safe"},
)
print(resp.status_code, resp.json())

---

4. نقاط التوسعة

4.1 إضافة أداة

سجّل دالة لدى ToolRegistry:

from kazma_core.agent.tool_registry import register_tool

@register_tool(
    name="weather_lookup",
    description="Look up current weather for a city.",
    danger=False,            # True → triggers HITL
)
async def weather_lookup(city: str) -> str:
    ...
    return f"Weather in {city}: sunny, 25C"

سجّلها أثناء بدء التشغيل (أو عبر نقطة دخول مهارة). يعرضها المشرف على النموذج اللغوي تلقائيًا.

4.2 إضافة مُزوّد

المُزوّدون هم إدخالات ConfigStore تحت providers.list. الإعدادات المسبقة العشر المُدمجة موجودة في kazma_core/providers.py:13-84. لإضافة نقطة نهاية مخصّصة متوافقة مع OpenAI:

from kazma_core.config_store import get_config_store
from kazma_core.model_registry import get_model_registry

store = get_config_store()
reg = get_model_registry()

# Option A: use the 'custom' preset shape
reg.upsert_provider(
    name="my-endpoint",
    display_name="My Inference Server",
    base_url="https://infer.example.com/v1",
    api_key="sk-...",
    enabled=True,
)

# Option B: switch active provider/model
reg.set_active_provider("my-endpoint")
reg.set_active_model("my-model-id")

أي نقطة نهاية متوافقة مع OpenAI تعمل (vLLM، Together، Groq، Fireworks، …). بالنسبة لأنظمة المصادقة غير التابعة لـ OpenAI، انتبه إلى أن LLMProvider.chat() يُرسِل دائمًا Authorization: Bearer — وجّه الطلب عبر وكيل (proxy) متوافق مع OpenAI إذا كان المصدر المنبع يتطلّب ترويسة مختلفة.

4.3 إضافة مُحوّل منصّة

أنشئ فئة فرعية من BaseAdapter (kazma-gateway/kazma_gateway/gateway.py:239)، نفّذ receive/send، أنتج IncomingMessage، وسجّله. بالنسبة لـ HITL للسرب على المنصّة الجديدة، أنشئ أيضًا فئة فرعية من BusAdapter (kazma_core/swarm/bus.py:66) وأوصِلها في كتلة المفرد (singleton) للناقل (bus) في app.py.

4.4 إضافة مهارة

انظر المهارات وMCP والأدوات ← إضافة مهارة مخصّصة. وقّعها باستخدام kazma hub sign.

4.5 إضافة خادم MCP

انظر المهارات وMCP والأدوات ← ضبط خادم MCP. تُكتشَف الأدوات وقت التشغيل وتُصنَّف عبر classify_mcp_tool.

4.6 إضافة عامل سرب

kazma swarm worker add researcher --model deepseek-chat --provider deepseek --type in_process --role researcher

أو عبر واجهة البرمجة (API):

import httpx
httpx.post("http://127.0.0.1:8000/api/swarm/workers", json={
    "name": "researcher",
    "model": "deepseek-chat",
    "provider": "deepseek",
    "worker_type": "in_process",
    "roles": ["researcher"],
})

4.7 استغلال مُحوّل الذاكرة رباعي الطبقات (متقدّم)

يُستخدَم UnifiedMemoryAdapter (swarm/memory/adapter.py) فقط بواسطة self_improvement.py وphonebook.py. لاستخدامه في مكان آخر:

from kazma_core.swarm.memory.adapter import get_adapter

adapter = get_adapter()
results = await adapter.query("your query", top_k=5)   # RRF-blended across 4 layers

ملاحظة: هذا ليس موصولًا بوكيل الدردشة افتراضيًا — انظر الذاكرة وRAG.

---

5. نقاط نهاية القياس عن بُعد والمراقبة

• /api/telemetry/* (telemetry_router) — القياس عن بُعد أثناء التشغيل.
• /api/dashboard/status — نظرة عامة للوحة المعلومات.
• مقاييس السرب عند /api/swarm/workers/{name}/metrics.

نقطة نهاية Prometheus /metrics غير موجودة. حزم OTel مُعلَنة لكن تتبّع كاظمة هو مُصدِر سبان (span) داخلي المنشأ. انظر البنية ← المراقبة.

---

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

• نقطة نهاية دردشة WebSocket ميتة (410 Gone). يجب على جميع مستهلكي واجهة البرمجة (API) استخدام SSE.
• حدث approval_required الخاص بـ SSE هو الطريقة المعيارية لواجهات الواجهة الأمامية لإظهار توقفات HITL؛ اقرنها بـ POST /api/approve/{thread_id}.
• إعمال ملكية /api/approve (403 بين المستخدمين المختلفين) يعني أن رموز الموافقة تكون لكل مستخدم — لا يمكن للمسؤول الموافقة على مهمة مستخدم آخر دون تطابق حقول الهوية.
• مُحوّل الذاكرة رباعي الطبقات هو نقطة توسعة وليس افتراضيًا — استدعاء get_adapter() من كود مخصّص مدعوم، لكن لا تفترض أن وكيل الدردشة يستخدمه بالفعل.