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. Ensure zero functional regression.

File Structure

File	Action	Purpose
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	Modify	Track implementation state.
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.

4.7 KiB Raw Blame History