Initialize track: SQLite-Granularity Inline Docs for ai_client.py

Creates spec, plan, and state configurations to document the dispatch loops, providers, and helper functions in src/ai_client.py.
2026-06-13 17:55:48 -04:00
parent 501f112591
commit 23a8554051
4 changed files with 172 additions and 0 deletions
@@ -0,0 +1,70 @@
+# SQLite-Granularity Inline Docs for ai_client.py — Implementation Plan
+
+> **For agentic workers:** Use task-by-task execution. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** Implement SQLite-style docstrings with SSDL traces, parameters, functional scopes, and thread boundaries for the primary entry points, providers, and helper functions in [src/ai_client.py](file:///C:/projects/manual_slop/src/ai_client.py). Ensure zero functional regression.
+
+---
+
+## File Structure
+
+| File | Action | Purpose |
+|---|---|---|
+| [src/ai_client.py](file:///C:/projects/manual_slop/src/ai_client.py) | Modify | Add docstrings with SSDL & visual topologies to core loops, providers, and helper functions. |
+| [conductor/tracks/ai_client_docs_20260613/state.toml](file:///C:/projects/manual_slop/conductor/tracks/ai_client_docs_20260613/state.toml) | Modify | Track implementation state. |
+| [conductor/tracks.md](file:///C:/projects/manual_slop/conductor/tracks.md) | Modify | Register the new track. |
+
+---
+
+# Phase 1: Core Dispatch Loop & Public APIs
+
+## Task 1.1: Document Public Entry Points & Dispatch Loops
+- [ ] **Step 1: Document `send_result` (ai_client.py:2645-2730)**
+  Add docstring detailing functional purpose, parameters, return type, thread-local storage setup, and error handling. SSDL trace: `[Q:active_provider] -> [I:SetupTierTag] -> [I:DispatchProvider] -> [T:Result]`.
+- [ ] **Step 2: Document `send` (ai_client.py:2617-2643)**
+  Mark as deprecated, explain callback mapping and Result extraction. SSDL trace: `[I:send_result] -> [T:text]`.
+- [ ] **Step 3: Document `run_with_tool_loop` (ai_client.py:714-784)**
+  Document the core execution loop and tool dispatch mechanics. SSDL trace: `o-> [I:dispatch_send] -> [B:tool_calls?] => [I:_execute_tool_calls_concurrently] -> [T:response_text]`.
+- [ ] **Step 4: Document `_execute_tool_calls_concurrently` (ai_client.py:664-712)**
+  Document the asynchronous gather and execution flow. SSDL trace: `[I:gather] => o-> [I:_execute_single_tool_call_async] -> [M] -> [T:tool_results]`.
+- [ ] **Step 5: Document `_execute_single_tool_call_async` (ai_client.py:786-846)**
+  Document execution sandboxing, clutch authorization, and callback handling. SSDL trace: `[I:CheckClutch] -> [B:Approved?] -> [I:run_powershell] -> [T:output]`.
+- [ ] **Step 6: Verify syntax and run tests**
+  Run: `pytest tests/test_ai_client_tool_loop.py tests/test_ai_client_result.py`
+  Expected: Success.
+
+---
+
+# Phase 2: Primary Provider Senders
+
+## Task 2.1: Document Primary Provider Senders
+- [ ] **Step 1: Document `_send_anthropic` (ai_client.py:1188-1364)**
+  Add docstring detailing cache control breakpoints, history pruning, and token tracking. SSDL trace: `[I:_ensure_anthropic_client] -> [I:_trim_anthropic_history] -> [I:client.messages.create] -> [T:Result]`.
+- [ ] **Step 2: Document `_send_gemini` (ai_client.py:1431-1665)**
+  Document caching states, explicit server-side cache invalidation, and chat session creation. SSDL trace: `[I:_ensure_gemini_client] -> [B:Cache Changed?] -> [I:client.caches.create] -> [I:client.chats.create] -> [T:Result]`.
+- [ ] **Step 3: Document `_send_gemini_cli` (ai_client.py:1667-1776)**
+  Document the headless adapter, subprocess execution, and callback wrapper. SSDL trace: `[I:run_with_tool_loop] -> [I:GeminiCliAdapter.send] -> [T:Result]`.
+- [ ] **Step 4: Document `_send_deepseek` (ai_client.py:1812-2067)**
+  Document token limits, custom REST client calls, and history repair loops. SSDL trace: `[I:_ensure_deepseek_client] -> [I:_repair_deepseek_history] -> [I:requests.post] -> [T:Result]`.
+- [ ] **Step 5: Verify syntax and run tests**
+  Run: `pytest tests/test_deepseek_provider.py tests/test_gemini_cli_integration.py`
+  Expected: Success.
+
+---
+
+# Phase 3: Secondary Provider Senders & Helpers
+
+## Task 3.1: Document Secondary Senders & Context Helpers
+- [ ] **Step 1: Document `_send_minimax` (ai_client.py:2209-2251)**
+  SSDL trace: `[I:_ensure_minimax_client] -> [I:_repair_minimax_history] -> [I:run_with_tool_loop] -> [T:Result]`.
+- [ ] **Step 2: Document `_send_grok` (ai_client.py:2157-2203)**
+  SSDL trace: `[I:_ensure_grok_client] -> [I:run_with_tool_loop] -> [T:Result]`.
+- [ ] **Step 3: Document `_send_qwen` (ai_client.py:2330-2363)**
+  SSDL trace: `[I:_ensure_qwen_client] -> [I:dashscope.Generation.call] -> [T:Result]`.
+- [ ] **Step 4: Document `_send_llama` & `_send_llama_native` (ai_client.py:2381-2478)**
+  SSDL trace: `[I:_ensure_llama_client] -> [I:run_with_tool_loop] -> [T:Result]`.
+- [ ] **Step 5: Document `_reread_file_items` & `_build_file_diff_text` (ai_client.py:869-927)**
+  SSDL trace: `o-> [I:get_mtime] -> [B:changed?] -> [I:read_file] -> [T:diff_text]`.
+- [ ] **Step 6: Verify syntax and run all tests**
+  Run: `pytest tests/` (full batch run check)
+  Expected: All green.