From 20b5544d3e16ba75422ca7d4639fb93721c5ddc7 Mon Sep 17 00:00:00 2001 From: Ed_ Date: Sat, 13 Jun 2026 18:08:04 -0400 Subject: [PATCH] doc: add detailed SSDL docstrings to primary provider functions in ai_client.py --- src/ai_client.py | 36 +++++++++++++++++++++++++++++++++--- 1 file changed, 33 insertions(+), 3 deletions(-) diff --git a/src/ai_client.py b/src/ai_client.py index 9e8e983f..a581f1aa 100644 --- a/src/ai_client.py +++ b/src/ai_client.py @@ -1282,6 +1282,19 @@ def _repair_anthropic_history(history: list[dict[str, Any]]) -> None: def _send_anthropic(md_content: str, user_message: str, base_dir: str, file_items: list[dict[str, Any]] | None = None, discussion_history: str = "", pre_tool_callback: Optional[Callable[[str, str, Optional[Callable[[str], str]]], Optional[str]]] = None, qa_callback: Optional[Callable[[str], str]] = None, stream_callback: Optional[Callable[[str], None]] = None, patch_callback: Optional[Callable[[str, str], Optional[str]]] = None) -> Result[str]: """ [C: src/ai_server.py:_handle_send] + + Functional Purpose: + Sends requests to Anthropic models, managing conversation history, prompt caching, token limits, and executing tool loops. + Parameters & Inputs: + - md_content, user_message, base_dir, file_items, discussion_history: Context and input parameters. + - pre_tool_callback, qa_callback, stream_callback, patch_callback: Execution control callbacks. + Immediate-Mode DAG / Thread Context: + - Called by: send + - Calls: _ensure_anthropic_client, _trim_anthropic_history, client.messages.create, run_with_tool_loop + SSDL: + [I:_ensure_anthropic_client] -> [I:_trim_anthropic_history] -> [I:client.messages.create] -> [T:Result] + Thread Boundaries: + Runs on whichever thread calls send (typically an async worker thread). """ anthropic = _require_warmed("anthropic") genai = _require_warmed("google.genai") @@ -1532,6 +1545,12 @@ def _send_gemini(md_content: str, user_message: str, base_dir: str, patch_callback: Optional[Callable[[str, str], Optional[str]]] = None) -> Result[str]: """ [C: src/ai_server.py:_handle_send, tests/test_tier4_interceptor.py:test_gemini_provider_passes_qa_callback_to_run_script] + Functional Purpose: Sends requests to Gemini via google-genai SDK, handling context caching, chat history, and tools. + Parameters & Inputs: md_content, user_message, base_dir, file_items, discussion_history, callbacks, enable_tools. + Immediate-Mode DAG / Thread Context: Called by: send; Calls: _ensure_gemini_client, client.caches.create, client.chats.create, run_with_tool_loop + SSDL: + [I:_ensure_gemini_client] -> [B:Cache Changed?] -> [I:client.caches.create] -> [I:client.chats.create] -> [T:Result] + Thread Boundaries: Runs on caller thread (typically an async worker thread). """ global _gemini_chat, _gemini_cache, _gemini_cache_md_hash, _gemini_cache_created_at, _gemini_cached_file_paths genai = _require_warmed("google.genai") @@ -1767,8 +1786,13 @@ def _send_gemini_cli(md_content: str, user_message: str, base_dir: str, patch_callback: Optional[Callable[[str, str], Optional[str]]] = None) -> Result[str]: from src.openai_compatible import OpenAICompatibleRequest, NormalizedResponse """ - [C: src/ai_server.py:_handle_send] - [C: src/ai_server.py:_handle_send] + [C: src/ai_server.py:_handle_send] + Functional Purpose: Sends requests to Gemini via the headless Gemini CLI subprocess adapter. + Parameters & Inputs: md_content, user_message, base_dir, file_items, discussion_history, callbacks. + Immediate-Mode DAG / Thread Context: Called by: send; Calls: run_with_tool_loop, GeminiCliAdapter.send + SSDL: + [I:run_with_tool_loop] -> [I:GeminiCliAdapter.send] -> [T:Result] + Thread Boundaries: Runs on caller thread (typically an async worker thread). """ global _gemini_cli_adapter try: @@ -1912,7 +1936,13 @@ def _send_deepseek(md_content: str, user_message: str, base_dir: str, stream_callback: Optional[Callable[[str], None]] = None, patch_callback: Optional[Callable[[str, str], Optional[str]]] = None) -> Result[str]: """ - [C: src/ai_server.py:_handle_send] + [C: src/ai_server.py:_handle_send] + Functional Purpose: Sends requests to DeepSeek via requests.post API call, managing history repairs and tools. + Parameters & Inputs: md_content, user_message, base_dir, file_items, discussion_history, stream, callbacks. + Immediate-Mode DAG / Thread Context: Called by: send; Calls: _ensure_deepseek_client, _repair_deepseek_history, requests.post + SSDL: + [I:_ensure_deepseek_client] -> [I:_repair_deepseek_history] -> [I:requests.post] -> [T:Result] + Thread Boundaries: Runs on caller thread (typically an async worker thread). """ requests = _require_warmed("requests") monitor = performance_monitor.get_monitor()