diff --git a/docs/guide_ai_client.md b/docs/guide_ai_client.md index f113114a..76242f85 100644 --- a/docs/guide_ai_client.md +++ b/docs/guide_ai_client.md @@ -465,16 +465,10 @@ meaning — do not overload `UNKNOWN` when a new failure mode surfaces ### Public API -- **`ai_client.send_result(...)`** — the new public API. Returns - `Result[str, ErrorInfo]`. Mirrors the `send()` signature (13+ - parameters including 8 callbacks). Internally calls - `_send__result()` for the active provider. -- **`ai_client.send(...)`** — **deprecated.** Emits `DeprecationWarning` - at runtime (via `typing_extensions.deprecated`; cached per call site to - avoid log spam). Returns `str` (the response text) for backward compat. - Errors are logged to the comms log via the deprecated path's comms entry - but not returned. Will be removed in the `public_api_migration_20260606` - follow-up track. +- **`ai_client.send_result(...)`** — the public API. Returns + `Result[str, ErrorInfo]`. Accepts 13+ parameters including 8 callbacks. + Internally calls `_send_()` for the active provider (the + vendor functions return `Result[str]` directly). ### Example @@ -493,17 +487,11 @@ print(r.data) ### Migration Notes for Existing Callers -- The `app_controller._api_generate` path and the MMA worker dispatch - (`multi_agent_conductor.py:591`) call `ai_client.send()`. They will - continue to work during the deprecation window; migration to - `send_result()` is the work of the `public_api_migration_20260606` - follow-up track. -- Tests that mock `ai_client._send_` should be updated to mock - `_send__result()` (or `send_result()` at the public API level). -- `tests/conftest.py` adds a `filterwarnings` entry to silence the - `DeprecationWarning` from `send()` during the transition; new tests - for the new API should assert the warning is **not** emitted by - `send_result()`. +- All production call sites and tests now use `send_result()`. The + legacy `send()` function was removed in the + `public_api_migration_and_ui_polish_20260615` track. +- Tests that mock `ai_client._send_` should use the + `Result(data=...)` return value pattern. ### See Also (in-doc) @@ -526,7 +514,7 @@ print(r.data) - **[docs/reports/qwen_llama_grok_followup_audit_20260611.md](qwen_llama_grok_followup_audit_20260611.md)** — Audit of the parent track's gaps; follow-up track `qwen_llama_grok_followup_20260611` covers them - **Gemini / Gemini CLI thinking-format compatibility (deferred from `ai_loop_regressions_20260614`)** — the user's complaint included Gemini; the likely cause is a format mismatch between the Gemini SDK output and `parse_thinking_trace`. Empirically investigate by running a Gemini request that produces reasoning and inspecting the raw `resp.text`. **Resolved 2026-06-15 by `doeh_test_thinking_cleanup_20260615`**: the `google-genai` SDK filters `thought=True` parts out of `resp.text`. The new helper `_extract_gemini_thoughts` in `src/ai_client.py` scans `resp.candidates[0].content.parts` for `thought=True` and prepends the concatenated text as `...` so `parse_thinking_trace` extracts it. 5 regression tests in `tests/test_gemini_thinking_format.py` cover the helper and the wrap path. See [track spec](../conductor/tracks/doeh_test_thinking_cleanup_20260615/spec.md) §3.2 G15. - **`` (half-width) marker support in thinking_parser (deferred from `ai_loop_regressions_20260614`)** — user screenshot showed `...` format; current `parse_thinking_trace` requires ``. The change is small (~3 lines in `src/thinking_parser.py:9`). **Resolved 2026-06-15 by `doeh_test_thinking_cleanup_20260615`**: the `tag_pattern` regex in `src/thinking_parser.py:20` now also matches `...` (the backreference `\1` matches the closing tag). New test `test_parse_half_width_think_tag` in `tests/test_thinking_trace.py`. All 8 thinking_trace tests pass. -- **Public API Result Migration (planned, separate track `public_api_migration_20260606`)** — the 5 production + 63 test call sites not migrated in this track; the follow-up removes the deprecated `ai_client.send()`. See [parent track spec](../conductor/tracks/data_oriented_error_handling_20260606/spec.md) §12.1. **Partial progress 2026-06-15 by `doeh_test_thinking_cleanup_20260615`**: 11 of the 63 test mock bugs were fixed (the 11 mechanical ones in `test_grok_provider.py`, `test_llama_provider.py`, `test_llama_ollama_native.py`, `test_ai_client_tool_loop_builder.py`, `test_headless_service.py`). The remaining 50+ test call sites + 5 production call sites remain for `public_api_migration`. +- **Public API Result Migration (planned, separate track `public_api_migration_20260606`)** — the 5 production + 63 test call sites not migrated in this track; the follow-up removes the deprecated `ai_client.send()`. See [parent track spec](../conductor/tracks/data_oriented_error_handling_20260606/spec.md) §12.1. **Completed 2026-06-15 by `public_api_migration_and_ui_polish_20260615`**: 3 remaining production call sites (src/conductor_tech_lead.py:68, src/orchestrator_pm.py:86, src/multi_agent_conductor.py:591) + 18 test files (11 call-site + 7 production-affected mock) were migrated to `send_result()`. The deprecated `send()` function was removed from `src/ai_client.py`. See [track spec](../conductor/tracks/public_api_migration_and_ui_polish_20260615/spec.md). - **`doeh_test_thinking_cleanup_20260615` (shipped 2026-06-15)** — cleanup follow-up to `data_oriented_error_handling_20260606` and `ai_loop_regressions_20260614`. Fixed: 1 CRITICAL production regression (`_api_generate` `NameError` from commit `2b7b571a`), 11 test mock bugs, 2 deferred bugs (Gemini thinking format, `` half-width marker), and 2 housekeeping items (state.toml duplicate keys, tracks.md row 24). See [track spec](../conductor/tracks/doeh_test_thinking_cleanup_20260615/spec.md) + [plan](../conductor/tracks/doeh_test_thinking_cleanup_20260615/plan.md). ---