# 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).
