docs(ai_client): rename send_result to send in 3 current docs

Doc consistency: guide_ai_client.md, guide_app_controller.md, and
the error_handling styleguide now reference the new symbol name.

Also fixes two consistency issues in error_handling.md introduced by
the mechanical rename:
1. The 'Deprecation: send -> send_result' section (lines 623-642) was
   rewritten as a 'Historical deprecation (added 2026-06-15, reverted
   2026-06-16)' note that points to the relevant track specs.
2. Line 204 (the 'Current State Audit' summary for src/ai_client.py)
   had a self-contradictory claim ('send() is the new public API;
   send() is @deprecated') after the rename. Updated to describe
   the canonical public API.

Historical archives (conductor/tracks/*/spec.md, conductor/tracks/*/plan.md,
docs/reports/*) are NOT modified - they document the 2026-06-15
public_api_migration decision and stay as historical record.
This commit is contained in:
ed
2026-06-17 00:50:36 -04:00
parent d17d8743dd
commit 9b5011231c
6 changed files with 136 additions and 21 deletions
+13 -16
View File
@@ -201,7 +201,7 @@ The 3 refactored subsystems demonstrate each pattern in context:
removed.
- **`src/ai_client.py`** — `_send_<vendor>_result()` returns `Result[str]`
(8 vendors: gemini, anthropic, deepseek, minimax, gemini_cli, qwen, llama,
grok); `send_result()` is the new public API; `send()` is `@deprecated`.
grok); `send(...) -> Result[str, ErrorInfo]` is the public API.
- **`src/rag_engine.py:100-180`** — `_init_vector_store_result`,
`_validate_collection_dim_result`, `is_empty_result`, `add_documents_result`
return `Result[None]` or `Result[T]`; broad `except Exception` blocks
@@ -329,7 +329,7 @@ async def _api_get_key(controller, header_key: str) -> str:
# Compliant: broad catch + HTTPException at the FastAPI boundary
async def _api_generate(controller, payload):
try:
result = ai_client.send_result(...)
result = ai_client.send(...)
return result.data
except Exception as e:
raise HTTPException(status_code=500, detail=f"AI call failed: {e}")
@@ -620,22 +620,19 @@ When converting existing code:
---
## Deprecation: `ai_client.send()` → `ai_client.send_result()`
## Historical deprecation (added 2026-06-15, reverted 2026-06-16)
The public `ai_client.send()` is marked `@deprecated` (via
`typing_extensions.deprecated`, the Python 3.11+ backport of
`@warnings.deprecated`). It still works for backward compat but emits a
`DeprecationWarning` at runtime. New code MUST use `ai_client.send_result()`.
The public `ai_client.send()` was briefly marked `@deprecated` in favor of
`ai_client.send_result()` on 2026-06-15 by the
`public_api_migration_and_ui_polish_20260615` track. The decision was
reverted on 2026-06-16 by `send_result_to_send_20260616` after the
Tier 2 autonomous sandbox proved capable of doing the rename safely.
- `send_result(...) -> Result[str, ErrorInfo]` the new public API.
- `send(...) -> str`**deprecated.** Returns `str` for backward compat;
errors are logged to the comms log but not returned.
- Removal timeline: `public_api_migration_20260606` follow-up track.
The deprecation warning is cached per call site (Python's `__warningregistry__`)
to avoid log spam. `tests/conftest.py` adds a `filterwarnings` entry to
silence the warning during the transition; new tests for the new API should
assert the warning is NOT emitted by `send_result()`.
`ai_client.send(...) -> Result[str, ErrorInfo]` is the canonical public API.
No deprecation is in effect. For the historical record of the brief
deprecation cycle, see
`conductor/tracks/public_api_migration_and_ui_polish_20260615/spec.md`
and `conductor/tracks/send_result_to_send_20260616/spec.md`.
---