manual_slop/conductor/tech-stack.md

Technology Stack: Manual Slop

Core Language

• Python 3.11+

GUI Frameworks

• Dear PyGui: For immediate/retained mode GUI rendering and node mapping.
• ImGui Bundle (imgui-bundle): To provide advanced multi-viewport and dockable panel capabilities on top of Dear ImGui.

Web & Service Frameworks

• FastAPI: High-performance REST API framework for providing the headless backend service.
• Uvicorn: ASGI server for serving the FastAPI application.

AI Integration SDKs

• google-genai: For Google Gemini API interaction and explicit context caching.
• anthropic: For Anthropic Claude API interaction, supporting ephemeral prompt caching.
• DeepSeek (Dedicated SDK): Integrated for high-performance codegen and reasoning (Phase 2).
• Gemini CLI: Integrated as a headless backend provider, utilizing a custom subprocess adapter and bridge script for tool execution control. Achieves full functional parity with direct SDK usage, including real-time token counting and detailed subprocess observability.
• Gemini 3.1 Pro Preview: Tier 1 Orchestrator model for complex reasoning.
• Gemini 2.5 Flash: High-performance, low-latency model for Tier 2 Tech Lead, Tier 3 Workers, and Tier 4 QA.
• DeepSeek-V3: Tier 3 Worker model optimized for code implementation.
• DeepSeek-R1: Specialized reasoning model for complex logical chains and "thinking" traces.

Configuration & Tooling

• ai_style_formatter.py: Custom Python formatter specifically designed to enforce 1-space indentation and ultra-compact whitespace to minimize token consumption.

• src/paths.py: Centralized module for path resolution, allowing directory paths (logs, conductor, scripts) to be configured via config.toml or environment variables, eliminating hardcoded filesystem dependencies.

• tree-sitter / AST Parsing: For deterministic AST parsing and automated generation of curated "Skeleton Views" and "Targeted Views" (extracting specific functions and their dependencies). Features an integrated AST cache with mtime-based invalidation to minimize re-parsing overhead.

• pydantic / dataclasses: For defining strict state schemas (Tracks, Tickets) used in linear orchestration.

• tomli-w: For writing TOML configuration files.

• tomllib: For native TOML parsing (Python 3.11+).

• LogRegistry & LogPruner: Custom components for session metadata persistence and automated filesystem cleanup within the logs/sessions/ taxonomy.

• psutil: For system and process monitoring (CPU/Memory telemetry).

• uv: An extremely fast Python package and project manager.

• pytest: For unit and integration testing, leveraging custom fixtures for live GUI verification.

• Taxonomy & Artifacts: Enforces a clean root by organizing core implementation into a src/ directory, and redirecting session logs and artifacts to configurable directories (defaulting to logs/sessions/ and scripts/generated/). Temporary test data and test logs are siloed in tests/artifacts/ and tests/logs/.

• ApiHookClient: A dedicated IPC client for automated GUI interaction and state inspection.

• mma-exec / mma.ps1: Python-based execution engine and PowerShell wrapper for managing the 4-Tier MMA hierarchy and automated documentation mapping.

• dag_engine.py: A native Python utility implementing TrackDAG and ExecutionEngine for dependency resolution, cycle detection, transitive blocking propagation, and programmable task execution loops. Refined to decouple status management from dependency resolution to support external pool control.

• multi_agent_conductor.py: Orchestrates the concurrent execution of implementation tracks using a non-blocking ConductorEngine and a thread-safe WorkerPool. Employs configurable concurrency limits and thread-local context isolation to manage multi-agent state.

• Thread-Local Context Isolation: Utilizes threading.local() for managing per-thread AI client context (e.g., source tier tagging), ensuring thread safety during concurrent multi-agent execution.

• Asynchronous Tool Execution Engine: Refactored MCP tool dispatch and AI client loops to use asyncio.gather and asyncio.to_thread, enabling parallel execution of independent tool calls within a single AI turn to reduce latency.

Architectural Patterns

• Event-Driven Metrics: Uses a custom EventEmitter to decouple API lifecycle events from UI rendering, improving performance and responsiveness.
• Synchronous Event Queue: Employs a SyncEventQueue based on queue.Queue to manage communication between the UI and backend agents, maintaining responsiveness through a threaded execution model.
• Synchronous IPC Approval Flow: A specialized bridge mechanism that allows headless AI providers (like Gemini CLI) to synchronously request and receive human approval for tool calls via the GUI's REST API hooks.
• Interface-Driven Development (IDD): Enforces a "Stub-and-Resolve" pattern where cross-module dependencies are resolved by generating signatures/contracts before implementation.