3.2 KiB
3.2 KiB
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. 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:
- Functional Purpose: Summary of the component's job.
- Parameters & Inputs: Specific types.
- Immediate-Mode DAG / Thread Context:
- Called by: Parent caller nodes.
- Calls: Child modules or SDK methods.
- SSDL computational shape: Embedded SSDL trace string under a dedicated
SSDL:header. - 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_resultsendrun_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
- Syntax Integrity: Run
py_check_syntaxon src/ai_client.py after every edit to confirm correct AST construction. - Regression Check: Run
pytest tests/after each phase. The addition of documentation must not alter execution paths, types, or throw warnings. - Indentation Enforcement: Verify all docstrings strictly preserve the 1-space indentation rule in src/ai_client.py.