plans and docs

src/multi_agent_conductor.py

@@ -1,3 +1,60 @@
+"""
+Multi-Agent Conductor - 4-tier MMA orchestration engine.
+
+This module implements the ConductorEngine and WorkerPool for executing
+implementation tracks via the 4-tier Multi-Model Agent (MMA) hierarchy.
+
+Key Components:
+ - WorkerPool: Bounded concurrent worker pool with semaphore gating
+ - ConductorEngine: Main orchestration loop with DAG execution
+ - run_worker_lifecycle: Tier 3 worker execution function
+
+Architecture Integration:
+ - Uses TrackDAG and ExecutionEngine from dag_engine.py
+ - Communicates with GUI via SyncEventQueue
+ - Manages tier-specific token usage via update_usage()
+
+Thread Safety:
+ - WorkerPool uses threading.Lock for all state mutations
+ - ConductorEngine uses _tier_usage_lock for tier usage tracking
+ - Abort events use threading.Event for worker cancellation
+
+Configuration:
+ - max_workers: Loaded from config.toml [mma].max_workers (default: 4)
+
+See Also:
+ - docs/guide_mma.md for full MMA documentation
+ - src/dag_engine.py for TrackDAG and ExecutionEngine
+ - src/models.py for Ticket, Track, WorkerContext
+"""
+"""
+Multi-Agent Conductor - MMA 4-Tier orchestration engine.
+
+This module provides the ConductorEngine and WorkerPool for orchestrating
+ the execution of implementation tickets within a Track using the DAG engine
+and the bounded concurrent worker pool with abort event propagation.
+
+Key Components:
+ - ConductorEngine: Tier 2 orchestrator that owns the execution loop
+ - WorkerPool: Bounded concurrent worker pool with semaphore gating
+ - run_worker_lifecycle: Stateless Tier 3 worker execution with context amnesia
+
+Thread Safety:
+ - All state mutations use locks (_workers_lock, _tier_usage_lock)
+ - Worker threads are daemon threads that clean up on exit
+ - Abort events enable per-ticket cancellation
+
+Integration:
+ - Uses SyncEventQueue for state updates to the GUI
+ - Uses ai_client.send() for LLM communication
+ - Uses mcp_client for tool dispatch
+
+See Also:
+ - docs/guide_mma.md for MMA orchestration documentation
+ - src/dag_engine.py for TrackDAG and ExecutionEngine
+ - src/ai_client.py for multi-provider LLM abstraction
+ - src/models.py for Ticket, Track, WorkerContext data structures
+"""
 from src import ai_client
 import json
 import threading