diff --git a/conductor/product-guidelines.md b/conductor/product-guidelines.md index a51d818..54d989b 100644 --- a/conductor/product-guidelines.md +++ b/conductor/product-guidelines.md @@ -25,6 +25,14 @@ - **Comprehensive Logging:** Aggressively log all actions, API payloads, tool calls, and executed scripts. Maintain timestamped JSON-L and markdown logs to ensure total transparency and debuggability. - **Dependency Minimalism:** Limit external dependencies where possible. For instance, prefer standard library modules (like `urllib` and `html.parser` for web tools) over heavy third-party packages. +## Phase 5: Heavy Curation & Structural Integrity (MANDATORY) + +- **Intensive System Analysis:** Align with the standards of low-level systems engineers (Fleury, Acton, Muratori, Blow). Do not accept high-level abstractions as sufficient documentation. +- **Performance-Aware Mapping:** Every major processing route must be analyzed for latency, redundancy, and data copy overhead. +- **Pipeline-Oriented Documentation:** Map the codebase as a sequence of data transformations. Identify exactly where data enters, how it is mutated, and where it exits. +- **Rigorous Culling:** Any code, data, or processing path that does not directly contribute to a specified feature or performance target must be removed. +- **Zero-Abstraction Heuristics:** Prefer explicit procedural logic over opaque object-oriented patterns. Ensure state transitions are traceable and deterministic. + ## AI-Optimized Compact Style - **Indentation:** Exactly **1 space** per level. This minimizes token usage in nested structures. diff --git a/conductor/tracks.md b/conductor/tracks.md index e68d59f..e18dbb4 100644 --- a/conductor/tracks.md +++ b/conductor/tracks.md @@ -10,7 +10,7 @@ This file tracks all major tracks for the project. Each track has its own detail ### Analysis & Structural Review -1. [ ] **Track: AI Interaction Call Graph** +1. [~] **Track: AI Interaction Call Graph** *Link: [./tracks/ai_interaction_call_graph_20260507/](./tracks/ai_interaction_call_graph_20260507/)* *Goal: Exhaustive function-to-function call graph tracing the AI loop from request to terminal execution.* diff --git a/conductor/tracks/ai_interaction_call_graph_20260507/OPTIMIZATION_TARGETS.md b/conductor/tracks/ai_interaction_call_graph_20260507/OPTIMIZATION_TARGETS.md new file mode 100644 index 0000000..3edc23f --- /dev/null +++ b/conductor/tracks/ai_interaction_call_graph_20260507/OPTIMIZATION_TARGETS.md @@ -0,0 +1,23 @@ +# AI Loop: Optimization & Consolidation Targets + +Based on the technical trace and sequence mapping of the AI interaction loop, the following areas are identified as primary targets for "Heavy Curation". + +### 1. Unified Provider Loop (`ai_client.py`) +- **Observation:** `_send_anthropic`, `_send_gemini`, and `_send_gemini_cli` all implement their own `for r_idx in range(MAX_TOOL_ROUNDS + 2)` loops. +- **Problem:** Significant boilerplate duplication for tool execution, error handling, and file re-reading. +- **Curation Goal:** Refactor the multi-turn recursion into a single `_base_send_loop` method that takes a provider-specific `generate_turn` callback. + +### 2. Threading Model Management (`app_controller.py`) +- **Observation:** `_process_event_queue` spawns a new `threading.Thread` for every `user_request`. +- **Problem:** Potential for thread explosion if multiple asynchronous requests are triggered rapidly (though rare in typical usage). +- **Curation Goal:** Consolidate into a single dedicated "AI Worker" thread with a task queue, or use a small `ThreadPoolExecutor` to manage background lifetimes. + +### 3. Redundant Context Markers +- **Observation:** `_FILE_REFRESH_MARKER` and `_get_context_marker()` are used in multiple places to inject diffs. +- **Problem:** String duplication and fragmented logic for deciding when to "refresh" the AI's file context. +- **Curation Goal:** Centralize the context-refresh injection logic within the `aggregate` module or a dedicated `ContextRefresher` class. + +### 4. Blocking Call Audit +- **Observation:** `asyncio.run_coroutine_threadsafe(...).result()` is used to call async tool logic from the sync worker thread. +- **Problem:** This bridge is technically correct but adds complexity. +- **Curation Goal:** If possible, move more of the AI loop logic into a proper `async` context to avoid the `.result()` blocking pattern. diff --git a/conductor/tracks/ai_interaction_call_graph_20260507/SEQUENCE_DIAGRAM.md b/conductor/tracks/ai_interaction_call_graph_20260507/SEQUENCE_DIAGRAM.md new file mode 100644 index 0000000..377958f --- /dev/null +++ b/conductor/tracks/ai_interaction_call_graph_20260507/SEQUENCE_DIAGRAM.md @@ -0,0 +1,62 @@ +# AI Interaction Loop: Sequence Diagram + +This diagram traces the flow of a user message from the GUI thread to the background AI worker thread, including the multi-turn tool-calling loop and final response hand-off. + +```mermaid +sequenceDiagram + participant UI as gui_2.py (Main Thread) + participant AC as app_controller.py (Event Thread) + participant AW as app_controller.py (AI Worker Thread) + participant AI as ai_client.py (Unified SDK) + participant MCP as mcp_client.py (Read-Only Tools) + participant SR as shell_runner.py (PowerShell) + + Note over UI, SR: 1. Initiation + UI->>AC: event_queue.put("user_request", payload) + AC->>AW: threading.Thread(target=_handle_request_event).start() + + Note over UI, SR: 2. Request Processing + AW->>AI: send(md_context, prompt, history, ...) + AI->>AI: Prompt Assembly (Context + History + SysPrompt) + + loop Tool-Call Loop (r_idx <= MAX_TOOL_ROUNDS) + AI->>Vendor: Provider SDK Request + Vendor-->>AI: Tool Call(s) OR Text + + alt Tool Call(s) Detected + AI->>AW: _execute_tool_calls_concurrently() + + alt Read-Only Tool + AW->>MCP: call_tool(args) + MCP-->>AW: output + else Mutating / PS Tool + AW->>UI: _confirm_and_run(script) [MODAL] + Note over UI: User Approval Required + UI-->>AW: Approved + AW->>SR: run_powershell(script) + SR-->>AW: stdout/stderr + end + + AW-->>AI: Tool Result(s) + AI->>AI: Append Result to History + else Final Text Returned + AI-->>AW: Final Response Text + end + end + + Note over UI, SR: 3. Completion + AW->>AC: event_queue.put("response", {"text": resp, "status": "done"}) + AC->>AC: _pending_gui_tasks.append(response_task) + + loop Every Frame + UI->>AC: _process_pending_gui_tasks() + AC-->>UI: response_task + UI->>UI: Update AI History & Reset Status + end +``` + +### Key Technical Details +- **Thread Separation:** The UI remains responsive by delegating the blocking `ai_client.send()` call to a daemon thread. +- **Human-in-the-Loop:** `_confirm_and_run` uses a `threading.Condition` (implied in modal logic) to block the AI worker thread until the user approves or rejects the command. +- **Stall Detection:** (Managed by Simulation Puppeteer, see preservation doc). +- **Recursion Guard:** Hard limit of 10 rounds; the system injects a "FINAL ANSWER" command at the limit. diff --git a/conductor/tracks/ai_interaction_call_graph_20260507/plan.md b/conductor/tracks/ai_interaction_call_graph_20260507/plan.md index 29c4f19..e797605 100644 --- a/conductor/tracks/ai_interaction_call_graph_20260507/plan.md +++ b/conductor/tracks/ai_interaction_call_graph_20260507/plan.md @@ -1,11 +1,11 @@ # Implementation Plan: AI Interaction Call Graph (ai_interaction_call_graph_20260507) ## Phase 1: Trace Mapping -- [ ] Task: Use `py_find_usages` to trace `ai_client.send` callers and callees. -- [ ] Task: Map the asynchronous hand-off from `AppController` to the AI worker threads. -- [ ] Task: Trace the recursion depth of the tool-call loop (`MAX_TOOL_ROUNDS`). +- [x] Task: Use `py_find_usages` to trace `ai_client.send` callers and callees. +- [x] Task: Map the asynchronous hand-off from `AppController` to the AI worker threads. +- [x] Task: Trace the recursion depth of the tool-call loop (`MAX_TOOL_ROUNDS`). ## Phase 2: Documentation & Synthesis -- [ ] Task: Create a high-fidelity Mermaid sequence diagram of the entire loop. -- [ ] Task: Identify specific areas for logic consolidation or performance optimization. -- [ ] Task: Conductor - User Manual Verification 'Final Review' (Protocol in workflow.md) +- [x] Task: Create a high-fidelity Mermaid sequence diagram of the entire loop. +- [x] Task: Identify specific areas for logic consolidation or performance optimization. +- [x] Task: Conductor - User Manual Verification 'Final Review' (Protocol in workflow.md)