diff --git a/conductor/tracks.md b/conductor/tracks.md index 8aa2da8b..7b834e59 100644 --- a/conductor/tracks.md +++ b/conductor/tracks.md @@ -24,6 +24,7 @@ Tracks that are unblocked and ready to start. Ordered by **dependency** (blocked | 7 | — | [UI Polish (Five Issues)](#track-ui-polish-five-issues) | spec ✓, plan ✓, ready to start | (none — independent) | | 7a | B | [SQLite-Granularity Inline Docs for gui_2.py](#track-sqlite-granularity-inline-docs-for-gui_2py) | spec ✓, plan ✓, complete | (none — independent) | | 7b | B | [Continued SQLite-Granularity Inline Docs for gui_2.py](#track-continued-sqlite-granularity-inline-docs-for-gui_2py) | spec ✓, plan ✓, complete | (none — independent) | +| 7c | B | [SQLite-Granularity Inline Docs for ai_client.py](#track-sqlite-granularity-inline-docs-for-ai_clientpy) | spec ✓, plan ✓, ready to start | (none — independent) | | 8 | — | [Bootstrap gencpp Python Bindings](#track-bootstrap-gencpp-python-bindings) | spec TBD | (none — independent) | | 9 | — | [Tree-Sitter Lua MCP Tools](#track-tree-sitter-lua-mcp-tools) | spec TBD | (none — independent) | | 10 | — | [GDScript Language Support Tools](#track-gdscript-language-support-tools) | spec TBD | (none — independent) | @@ -510,6 +511,13 @@ Lightweight chronology; full spec/plan/state per track is in the linked folder. *Goal: Document preset managers/editors, persona selectors/editors, provider panel, and command palette in `src/gui_2.py` and `src/command_palette.py` with embedded SSDL and ASCII layouts.* +#### Track: SQLite-Granularity Inline Docs for ai_client.py `[IN PROGRESS: ai_client_docs_20260613]` +*Link: [./tracks/ai_client_docs_20260613/](./tracks/ai_client_docs_20260613/), Spec: [./tracks/ai_client_docs_20260613/spec.md](./tracks/ai_client_docs_20260613/spec.md), Plan: [./tracks/ai_client_docs_20260613/plan.md](./tracks/ai_client_docs_20260613/plan.md)* + +*Status: 2026-06-13 — READY TO START. Spec and plan initialized.* + +*Goal: Add SQLite-granularity docstrings with SSDL traces, parameters, functional scopes, and thread boundaries for the primary entry points, providers, and helper functions in `src/ai_client.py`.* + #### Track: Intent-Based Scripting Languages Survey `[COMPLETE: 213e4994]` *Link: [./tracks/intent_dsl_survey_20260612/](./tracks/intent_dsl_survey_20260612/), Spec: [./tracks/intent_dsl_survey_20260612/spec.md](./tracks/intent_dsl_survey_20260612/spec.md), Plan: [./tracks/intent_dsl_survey_20260612/plan.md](./tracks/intent_dsl_survey_20260612/plan.md), Report: [./tracks/intent_dsl_survey_20260612/report_v1.2.md](./tracks/intent_dsl_survey_20260612/report_v1.2.md), v1.1: [./tracks/intent_dsl_survey_20260612/report_v1.1.md](./tracks/intent_dsl_survey_20260612/report_v1.1.md), v1.0: [./tracks/intent_dsl_survey_20260612/report.md](./tracks/intent_dsl_survey_20260612/report.md), Review: [./tracks/intent_dsl_survey_20260612/reportreview.md](./tracks/intent_dsl_survey_20260612/reportreview.md)* diff --git a/conductor/tracks/ai_client_docs_20260613/plan.md b/conductor/tracks/ai_client_docs_20260613/plan.md new file mode 100644 index 00000000..fca10b09 --- /dev/null +++ b/conductor/tracks/ai_client_docs_20260613/plan.md @@ -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. diff --git a/conductor/tracks/ai_client_docs_20260613/spec.md b/conductor/tracks/ai_client_docs_20260613/spec.md new file mode 100644 index 00000000..7ea6cb17 --- /dev/null +++ b/conductor/tracks/ai_client_docs_20260613/spec.md @@ -0,0 +1,68 @@ +# Track: SQLite-Granularity Inline Docs for ai_client.py + +**Status:** Spec approved 2026-06-13 +**Initialized:** 2026-06-13 +**Owner:** Tier 1 Orchestrator +**Priority:** Medium (Documentation / Core Maintenance) + +--- + +## 1. Overview +This track adds SQLite-style inline documentation to the core LLM orchestration engine in [src/ai_client.py](file:///C:/projects/manual_slop/src/ai_client.py). By enriching its dispatch loops, providers, and helper functions with clear docstrings, SSDL traces, and visual topology diagrams where relevant, we make the central AI interface highly auditable and understandable for future development and paired programming sessions. + +--- + +## 2. Goals (Priority Order) + +| Priority | Goal | Rationale | +|---|---|---| +| **A** | Document Public APIs & Core Loops (`send_result`, `send`, `run_with_tool_loop`, `_execute_tool_calls_concurrently`, `_execute_single_tool_call_async`). | These constitute the central execution loop and entry points for all AI reasoning. | +| **A** | Document Primary Provider Senders (`_send_anthropic`, `_send_gemini`, `_send_gemini_cli`, `_send_deepseek`). | These handle context caching, token estimation, tool translation, and response normalization for the primary platforms. | +| **B** | Document Secondary Provider Senders (`_send_minimax`, `_send_grok`, `_send_qwen`, `_send_llama`, `_send_llama_native`). | Document the integrations for regional, compatible, and local models. | +| **B** | Document Context & Context-Refresh Helpers (`_reread_file_items`, `_build_file_diff_text`, `set_current_tier`, `get_current_tier`). | Traces file-system synchronization and thread-local tier auditing. | + +--- + +## 3. The Documentation Convention +Every target function gets a Python docstring (`"""`) structured as follows: + +1. **Functional Purpose:** Summary of the component's job. +2. **Parameters & Inputs:** Specific types. +3. **Immediate-Mode DAG / Thread Context:** + - **Called by:** Parent caller nodes. + - **Calls:** Child modules or SDK methods. +4. **SSDL computational shape:** Embedded SSDL trace string under a dedicated `SSDL:` header. +5. **Thread Boundaries:** Confirming threading model (e.g. main thread vs async worker thread pool). + +--- + +## 4. Phased Breakdown + +### Phase 1: Core Dispatch Loop & Public APIs +- `send_result` +- `send` +- `run_with_tool_loop` +- `_execute_tool_calls_concurrently` +- `_execute_single_tool_call_async` + +### Phase 2: Primary Provider Senders +- `_send_anthropic` +- `_send_gemini` +- `_send_gemini_cli` +- `_send_deepseek` + +### Phase 3: Secondary Provider Senders & Helpers +- `_send_minimax` +- `_send_grok` +- `_send_qwen` +- `_send_llama` +- `_send_llama_native` +- `_reread_file_items` +- `_build_file_diff_text` + +--- + +## 5. Verification Criteria +1. **Syntax Integrity:** Run `py_check_syntax` on [src/ai_client.py](file:///C:/projects/manual_slop/src/ai_client.py) after every edit to confirm correct AST construction. +2. **Regression Check:** Run `pytest tests/` after each phase. The addition of documentation must not alter execution paths, types, or throw warnings. +3. **Indentation Enforcement:** Verify all docstrings strictly preserve the 1-space indentation rule in [src/ai_client.py](file:///C:/projects/manual_slop/src/ai_client.py). diff --git a/conductor/tracks/ai_client_docs_20260613/state.toml b/conductor/tracks/ai_client_docs_20260613/state.toml new file mode 100644 index 00000000..b1915aa6 --- /dev/null +++ b/conductor/tracks/ai_client_docs_20260613/state.toml @@ -0,0 +1,26 @@ +# Track state for ai_client_docs_20260613 +# Updated as tasks complete + +[meta] +track_id = "ai_client_docs_20260613" +name = "SQLite-Granularity Inline Docs for ai_client.py" +status = "ready" +current_phase = 1 +last_updated = "2026-06-13" + +[blocked_by] + +[phases] +phase_1 = { status = "ready", checkpoint_sha = "", name = "Core Dispatch Loop & Public APIs" } +phase_2 = { status = "pending", checkpoint_sha = "", name = "Primary Provider Senders" } +phase_3 = { status = "pending", checkpoint_sha = "", name = "Secondary Provider Senders & Helpers" } + +[tasks] +# Phase 1: Core Dispatch Loop & Public APIs +t1_1 = { status = "pending", commit_sha = "", description = "Document Public Entry Points & Dispatch Loops (send_result, send, run_with_tool_loop, _execute_tool_calls_concurrently, _execute_single_tool_call_async)" } + +# Phase 2: Primary Provider Senders +t2_1 = { status = "pending", commit_sha = "", description = "Document Primary Provider Senders (_send_anthropic, _send_gemini, _send_gemini_cli, _send_deepseek)" } + +# Phase 3: Secondary Provider Senders & Helpers +t3_1 = { status = "pending", commit_sha = "", description = "Document Secondary Senders & Context Helpers (_send_minimax, _send_grok, _send_qwen, _send_llama, _send_llama_native, _reread_file_items, _build_file_diff_text)" }