تنسيق السرب

نظام السرب الكامل: المحرّك، وأنماط الإرسال الستة، واستراتيجيات التجميع، وطبقة الموثوقية (قواطع الدائرة، وإعادة المحاولة، والمهل، والمُدقّقات، والتزامن)، وسجلّ العمّال، ونقاط حفظ خط المعالجة، والمقاييس — جميعها موثّقة بمراجع المصدر.

---

1. SwarmEngine

SwarmEngine (kazma-core/kazma_core/swarm/engine.py:103) هو المنسّق اللّامتزامن المركزي. تغلّفه واجهة توافقية مع الإصدارات السابقة SwarmManager (manager.py:17، تشارك self._workers = self.engine._workers).

1.1 المُنشئ

def __init__(
    self,
    config: SwarmConfig | None = None,
    *,
    result_aggregator: ResultAggregator | None = None,
    task_store: TaskStore | None = None,
    metrics_collector: MetricsCollector | None = None,
    tracing_emitter: TracingEmitter | None = None,
) -> None: ...

1.2 السمات الأساسية

السمة	النوع	الغرض
_workers	dict[str, SwarmWorker]	العمّال المُسجَّلون.
_active_tasks	dict[str, SwarmTask]	المهام قيد التنفيذ.
_task_handles	dict[str, asyncio.Task]	مقابض الإلغاء.
_task_history	dict[str, SwarmTask]	محدودة بحجم LRU (_max_history=500).
_routing_engine	UnifiedRouter	التوجيه التلقائي لحالة workers=["auto"].
_reliability	ReliabilityRegistry	قواطع الدائرة/إعادة المحاولة/المهل/المُدقّقات/التزامن.
_checkpoint_handler	HITLCheckpointHandler	حالة خط المعالجة المُ暂停 (المتوقّف مؤقتاً).
_checkpoint_mgr	CheckpointManager	استمرارية نقاط الحفظ + المهل.
_task_store	TaskStore	الاستمرارية عبر SQLite.
_metrics_collector	MetricsCollector	مقاييس في الذاكرة + SQLite.
_tracing_emitter	TracingEmitter	باعث span داخلي.
_phonebook	WorkerPhonebook	البحث عن العمّال عبر الطوبولوجيا/DAG.
_sse	SseBridge	جسر أحداث SSE.

توقيع المُنشئ لم يتغيّر بعد إعادة الهيكلة P2-1 التي قسّمت الصنف الإلهي الأصلي المؤلَّف من 1878 سطراً إلى وحدات مركّزة. تعمل تجهيزات الاختبار دون أي تعديل.

---

2. أنماط الإرسال الستة

تعداد TaskType (swarm/task.py:65-73): DISPATCH، BROADCAST، PIPELINE، FAN_OUT، CONSULT، CONDITIONAL. يقع منطق التوجيه في dispatch_inner.py (يُستدعى من engine.dispatch ← engine._dispatch_inner).

النمط	نقطة الدخول في المحرّك	الدالة المنفِّذة	الوصف
dispatch	engine.dispatch (312) ← dispatch_inner (35)	عامل واحد مضمّن + سلسلة احتياطية اختيارية	يعالج عامل واحد المهمة.
broadcast	engine.broadcast (367)	broadcast.broadcast_task (broadcast.py:31)	يستقبل جميع العمّال نفس المُحفّز.
pipeline	dispatch_inner.py:72-107	patterns.execute_pipeline (patterns.py:234)	مراحل مرتّبة تتشارك سبورة مشتركة؛ تدعم نقاط حفظ الموافقة البشرية في الحلقة (HITL).
fan_out	dispatch_inner.py:109-157	patterns.execute_fan_out (patterns.py:639)	تنفيذ متوازٍ مع تزامن محدود + تجميع.
consult	dispatch_inner.py:159-201	consultation.execute_consult (consultation.py:124)	آراء متوازية + تركيب عبر LLM.
conditional	dispatch_inner.py:203-229	patterns.execute_conditional (patterns.py:504)	يقرّر المُوجّه عنصر خريطة المسار الذي سيُرسل إليه.

2.1 التوجيه التلقائي

تُحلَّل workers=["auto"] في dispatch_inner.py:44-70 عبر engine._routing_engine.route(...) (UnifiedRouter)، مع احتياطي تغيير حجم تلقائي (الأسطر 53-61) عبر engine.get_autoscaler().maybe_scale(...).

2.2 تفاصيل خط المعالجة

• السبورة المشتركة — ترى كل مرحلة مخرجات المراحل السابقة.
• نقاط حفظ الموافقة البشرية في الحلقة (HITL) — task.metadata["hitl_checkpoints"] هي مجموعة من فهارس الخطوات ذات الأساس 1 (patterns.py:252). عند نقطة الحفظ، يتوقّف التنفيذ بحالة status="paused” مع بيانات وصفية لنقطة الحفظ (الأسطر 328-354، 458-484).
• الاستئناف — patterns.resume_pipeline (patterns.py:365).
• المعالجة اللاحقة (_finalize_pipeline، patterns.py:139-202) تشغّل أربع خطافات: تركيب “Refiner” عبر LLM، والتحسين الذاتي، ومُسجّل خط المعالجة، ثم تُعيد PatternExecution.

2.3 تخطيط حالة التوزيع المتشعّب (fan-out)

الشرط	الحالة
ينجح جميع العمّال	success
ينجح بعضهم	partial
لا ينجح أيٌّ منهم	failed

---

3. استراتيجيات التجميع

ResultAggregator.aggregate (aggregator.py:44-121)، مفتاح التوجيه task.aggregation (الافتراضي "collect"):

الاستراتيجية	السلوك
collect	بيانات وصفية فقط؛ دون مُخرَج مجمَّع.
first_valid	أول نتيجة ناجحة.
merge_all	ضمّ كتل [worker] output.
vote	تعدّد الأغلبية؛ تُكسَر التعادل بترتيب الظهور الأول (الأسطر 98-104).
synthesize	تركيب عبر LLM باستخدام _SYNTHESIS_SYSTEM_PROMPT (الأسطر 20-26)؛ احتياطي حتمي _fallback_synthesis (السطر 194).
(غير معروفة)	تُطلق ValueError.

---

4. التسليمات واكتشاف الدورات

حين يُسلِّم عامل مهمةً إلى عامل آخر في منتصف المهمة، تستدعي _handle_handoff() (engine.py:625-743) نفسها بشكل تعاودي. تُمنَع الحلقات اللانهائية (A→B→A) بواسطة حارسين في swarm/handoff_guards.py:

الثابت	القيمة	المعنى
MAX_HANDOFF_DEPTH	5	أقصى عمق للتعاود.
MAX_VISITS	2	أقصى عدد مرات إعادة زيارة عامل واحد (يسمح بتسليمات الإرجاع المشروعة A→B→A).

الآلية:

1. _visited هي dict[str, int] لأعداد زيارات كل عامل (وليست مجموعة منطقية).
2. يزيد _register_handoff_visit عدد العامل المصدر.
3. يُطلِق _handoff_guard_error عند عمق > 5 أو زيادات لكل عامل > 2.
4. يُزاد _depth داخل worker_dispatch.dispatch_worker عندما يستدعي engine._handle_handoff(..., _depth=_depth + 1) (worker_dispatch.py:148-160).
5. عند النجاح/الفشل، يُستدعى record_success/record_failure الخاص بقاطع الدائرة (الأسطر 729، 740).

ملاحظة حول تسمية الرموز: تشير نصوص docstring في engine.py:646 حرفياً إلى _MAX_VISITS، لكن الرمز المُصدَّر هو MAX_VISITS (handoff_guards.py:17). نفس القيمة (2).

---

5. طبقة الموثوقية

ReliabilityRegistry (swarm/reliability_registry.py:31) هي حامل إعدادات. تعيش آلات الحالة الفعلية في swarm/reliability.py. ستة مكوّنات:

5.1 CircuitBreaker (reliability.py:238-389)

الجانب	التفصيل
الحالات	CLOSED، OPEN، HALF_OPEN (CircuitState StrEnum، الأسطر 219-224).
failure_threshold	الافتراضي 5.
cooldown_seconds	الافتراضي 60.0.
OPEN ← HALF_OPEN	انتقال تلقائي عند time.monotonic() - _opened_at >= cooldown (خاصية الحالة، الأسطر 260-272).
probe مفرد نصف المفتوح	يسمح allow_probe() (الأسطر 278-294) بتمرير إرسال واحد فقط؛ محمي بـ _probe_in_flight (السطر 254). كلٌّ من record_success() وrecord_failure() يُصفّرانه. لا تزل هذه العلامة أبداً — الاستدعاءات المتزامنة ستتجاوز دلالات الـ probe.
record_success	يُصفّر consecutive_failures، يمحو _probe_in_flight، HALF_OPEN ← CLOSED.
record_failure	يمحو _probe_in_flight؛ HALF_OPEN ← إعادة OPEN بمؤقّت جديد؛ CLOSED ← زيادة، وانطلاق عند الحدّ.
الاستمرارية	to_dict() / from_dict() (الأسطر 364-389)؛ السجلّ save_breaker_state/load_breaker_state.

5.2 RetryPolicy (reliability.py:66-211)

الحقل	الافتراضي
max_retries	3
base_delay	1.0 ث
max_delay	60.0 ث
jitter	True

تراجع زمني أُسّي: base_delay * 2**(attempt-1) (السطر 92). الأنماط غير القابلة لإعادة المحاولة (الأسطر 45-50): 401/403، auth/unauthorized/forbidden، api key، not found، rate limit، quota، billing. تُعاد المحاولة عند الاستثناءات وعند status in ("error","timeout") في القواميس.

5.3 TimeoutGuard (reliability.py:397-480)

الحقل	الافتراضي
default_timeout	300.0 ث
on_timeout	fail | retry | skip

يستخدم asyncio.wait_for. عند انتهاء المهلة يُعيد {"status": "timeout", ...} مع retry=True أو skipped=True اختيارياً.

5.4 OutputValidator (reliability.py:488-689)

يدعم ثلاثة أنواع من المخططات:

• Pydantic BaseModel
• JSON Schema (عبر jsonschema إن كان مثبّتاً، وإلا احتياطي مدمج)
• قاموس نوع بسيط ({"name": "str"})

يُحلِّل تلقائياً المُخرَج النصّي بوصفه JSON حين يتوقّع المخطط كائناً/مصفوفة.

5.5 FallbackChain (reliability.py:734-864)

احتياطيات متتالية بعد فشل الأساسي. يحصل كل احتياطي على HandoffRecord. يُنهي النجاح الأول السلسلة؛ يُعيد النفاد خطأً مُلخَّصاً.

5.6 BoundedConcurrency (reliability.py:872-909)

غلاف لـ asyncio.Semaphore، الافتراضي max_concurrent=5؛ مدير سياق لامتزامن يُطلِق دائماً عند الخروج.

5.7 الإعداد لكل عامل (عبر مفوّضي المحرّك)

الدالة	ما تُهيّئه
set_circuit_breaker_config(worker, failure_threshold, cooldown_seconds)	حدود قاطع الدائرة.
set_retry_policy(worker, policy)	سياسة إعادة المحاولة.
set_timeout_guard(worker, guard)	المهلة.
set_output_validator(worker, validator)	مخطط المُخرَج.
get_bounded_concurrency(task_max_concurrent)	التزامن (تجاوز المهمة > افتراضي المحرّك).

---

6. TaskStore

swarm/task_store.py:82، قاعدة البيانات الافتراضية kazma-data/swarm_tasks.db.

6.1 التزامن

تُطبَّق PRAGMAs مركزياً عبر apply_sqlite_pragmas() من config_store:

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

اتصال مشترك واحد + threading.Lock.

6.2 المخطط

swarm_tasks (الأسطر 33-52): id, type, prompt, status, workers (JSON), result, context, dependencies, fallback_chain, validation_schema, aggregation, timeout, created_at, started_at, completed_at, cost, tokens, metadata. فهارس على status، type، completed_at، created_at.

swarm_worker_metrics (الأسطر 59-68): worker, date, tasks_completed, tasks_failed, avg_latency, total_tokens, total_cost، المفتاح الأساسي (worker, date).

6.3 التهجير التلقائي

بعد executescript(_SCHEMA)، يقرأ PRAGMA table_info(swarm_tasks) وينفّذ ALTER TABLE … ADD COLUMN لأيٍّ من context, dependencies, fallback_chain, validation_schema, aggregation, timeout المفقودة (الأسطر 111-124، مغلّفة بـ try/except).

6.4 فلتر العامل (تطابق تام)

يُرشِّح list_tasks() (الأسطر 205-279) حسب العامل باستخدام json_each() — وليس LIKE:

WHERE EXISTS (SELECT 1 FROM json_each(workers) WHERE value = ?)

هذا يتجنّب الإيجابيات الزائفة للسلاسل الفرعية (مثلاً مطابقة العامل "a" لـ "ab").

---

7. سجلّ العمّال ودليل العمّال

• WorkerRegistry (swarm/registry.py) — سجلّ مدعوم بـ JSON، يُحمَّل من swarm_registry.json (الجذر) عند إنشاء المُفرد. يمتلك كل WorkerEntry: name, expertise, roles, model, provider, worker_type, system_prompt, enabled, tools, metadata.
• WorkerPhonebook (swarm/phonebook.py:23) — يتجاوز طبقة الموثوقية للاستدعاء والإرسال المباشر من منفِّذي الطوبولوجيا/DAG. يُعيد summon(name) عنصر InProcessWorker (أُزيل مسار العملية الفرعية القديم لـ TelegramWorker). يُحقن dispatch_by_name سياق الذاكرة الحلَقية من المحوّل رباعي الطبقات قبل الإرسال.
• worker_factory._IN_PROCESS_TYPES = {"in_process", "telegram_bot"} — كلاهما يحلّ إلى InProcessWorker.

لا يوجد كتالوج أدوار/إعدادات مسبقة محدّد. الأدوار نصوص حرّة. يحتوي swarm_registry.json على نحو 57 إدخالاً (معظمها تجهيزات اختبار مثل a/b/c لاختبارات دورات التسليم، بالإضافة إلى primary/fallback-alpha/fallback-beta لاختبارات سلسلة الاحتياطي). جميعها ذات system_prompt فارغ، لذا يعاملها is_generalist (registry.py:67-74) كعوامل عامّين رغم وسوم الخبرة.

---

8. نقاط حفظ خط المعالجة (الموافقة البشرية في الحلقة HITL)

يمكن لخط المعالجة أن يتوقّف عند خطوات مُعدَّة للموافقة البشرية.

المكوّن	الدور
HITLCheckpoint / HITLCheckpointHandler	swarm/checkpoint.py:24,50 — dataclass + تنسيق التوقّف/الموافقة/الرفض عبر asyncio.Events.
CheckpointManager	swarm/checkpoint_manager.py:28 — يمتلك حالة خط المعالجة المتوقّف، ومهلة الرفض التلقائي، والاستمرارية عبر SQLite.

8.1 التدفّق

1. يُفوِّض SwarmEngine._handle_pipeline_checkpoint (engine.py:889) إلى CheckpointManager.handle_pipeline_checkpoint.
2. يخزّن المدير الحالة، يُسلِّح مهلة رفض تلقائي إن كان task.metadata["checkpoint_timeout"] > 0 (الأسطر 96-104)، يضبط حالة المهمة إلى PAUSED، ويُ persist إلى SQLite.
3. الموافقة: يلغي SwarmEngine.approve_checkpoint (engine.py:920-988) المهلة، يضبط checkpoint.status="approved”، يُخرج الإدخال المتوقّف، ويستأنف من next_step = checkpoint.step + 1 عبر resume_pipeline(...).
4. الرفض: يُفوِّض SwarmEngine.reject_checkpoint (engine.py:990) إلى المعالج.
5. التعافي من الانهيار: يُعيد restore_paused_tasks() (checkpoint_manager.py:182) تحميل المهام المتوقفة من SQLite ويُسلِّح المهل ثانيةً (الأسطر 222-230).

8.2 نقاط النهاية HTTP

• POST /api/swarm/tasks/{task_id}/approve (swarm_panel/routes_tasks.py:612) ← engine.approve_checkpoint(task_id).
• POST /api/swarm/tasks/{task_id}/reject (السطر 657).

---

9. المقاييس

MetricsCollector (swarm/metrics.py:56) — مُجمِّع في الذاكرة آمن مع الخيوط مدعوم بـ TaskStore اختياري. لقطات لكل (worker, date):

المقياس	المعنى
tasks_completed	المهام الناجحة.
tasks_failed	المهام الفاشلة.
avg_latency	متوسط جارٍ مُرجَّح.
total_tokens	مجموع الرموز.
total_cost	مجموع بالدولار الأمريكي.

يُفرِّغ إلى TaskStore.record_worker_metric عند كل تسجيل. يُكشَف عبر REST عند GET /api/swarm/workers/{name}/metrics.

لا يوجد Prometheus. لا يملك السرب اعتمادية على prometheus_client، ولا نقطة نهاية /metrics. المقاييس مخصّصة في الذاكرة + SQLite فقط. راجع البنية ← قابلية الملاحظة.

---

10. التتبّع

TracingEmitter / Span / InMemorySpanExporter (داخلي، وفق swarm/__init__.py:57). ليس OpenTelemetry. تُبعث الـ spans لأحداث الإرسال، والتسليم، ونقاط الحفظ.

---

11. خطوط المعالجة المسبقة (kazma.yaml)

خط المعالجة	المراحل
standard	researcher (العامل core) ← refiner (العامل bridge) ← builder (العامل core) ← validator (العامل bridge).
quick	researcher (العامل core) ← builder (العامل core).

تحمل كل مرحلة system_prompt. راجع الإعداد ← خطوط المعالجة.

---

12. أوامر CLI الخاصة بالسرب

سطح kazma swarm الكامل (dispatch، broadcast، consult، pipeline، fanout، history، metrics، approve، reject، circuit-breaker، …) موثَّق في مرجع CLI ← swarm.

---

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

• reliability_registry.py للإعدادات فقط. منطق _probe_in_flight نصف المفتوح يعيش على dataclass الخاص بـ CircuitBreaker في reliability.py. أي من يُعدِّل دلالات قاطع الدائرة يجب أن يُحرِّر reliability.py، لا السجلّ.
• الرمز _MAX_VISITS مقابل MAX_VISITS: تستخدم docstring للمحرّك الصيغة ذات الشرطة السفلية، لكن الثابت المُصدَّر هو MAX_VISITS. نفس القيمة (2).
• swarm_registry.json معظمه تجهيزات اختبار. لا تفترض أن العمّال المُصدَّرين بمستوى الإنتاج — فلديهم حقول system_prompt فارغة.
• Prometheus غائب. أي من يخطّط لمسح كاظمة باستخدام Prometheus يحتاج إلى إضافة ذلك التكامل؛ فهو غير موجود اليوم.