From 1ccef1685fce635b1c587feff0df3d67794732bd Mon Sep 17 00:00:00 2001 From: Ed_ Date: Sat, 13 Jun 2026 18:27:46 -0400 Subject: [PATCH] docs(ai_client): add detailed SQLite-granularity docstrings to secondary senders and context helpers --- src/ai_client.py | 209 +++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 209 insertions(+) diff --git a/src/ai_client.py b/src/ai_client.py index a581f1aa..d4230b30 100644 --- a/src/ai_client.py +++ b/src/ai_client.py @@ -961,6 +961,30 @@ def _truncate_tool_output(output: str) -> str: #region: File Context Building def _reread_file_items(file_items: list[dict[str, Any]]) -> tuple[list[dict[str, Any]], list[dict[str, Any]]]: + """ + Re-reads file items from the filesystem if their modification times have changed. + + Functional Purpose: + Iterates through context files, compares current filesystem mtime against cached mtime, + and reads file contents if changes are detected, returning both the full refreshed set + and the subset of changed items. + + Parameters & Inputs: + file_items (list[dict[str, Any]]): List of file dictionaries containing keys "path" and optionally "mtime", "content". + + Returns: + tuple[list[dict[str, Any]], list[dict[str, Any]]]: A tuple containing (refreshed_items, changed_items). + + Immediate-Mode DAG / Thread Context: + Called by: _send_gemini + Calls: pathlib.Path.stat, pathlib.Path.read_text + + SSDL: + `o-> [I:get_mtime] -> [B:changed?] -> [I:read_file] -> [T:diff_text]` + + Thread Boundaries: + Runs synchronously in the caller thread. Does synchronous blocking file system I/O. + """ refreshed: list[dict[str, Any]] = [] changed: list[dict[str, Any]] = [] for item in file_items: @@ -999,6 +1023,29 @@ def _build_file_context_text(file_items: list[dict[str, Any]]) -> str: _DIFF_LINE_THRESHOLD: int = 200 def _build_file_diff_text(changed_items: list[dict[str, Any]]) -> str: + """ + Generates unified diffs or full file dumps for changed files in the context. + + Functional Purpose: + Formats file modifications for the LLM prompt. If a file change is small or lacks prior content, + the full file is dumped; otherwise, a unified diff is constructed. + + Parameters & Inputs: + changed_items (list[dict[str, Any]]): List of file dictionaries that have changed. + + Returns: + str: Combined markdown string representing the changes or full files. + + Immediate-Mode DAG / Thread Context: + Called by: _send_gemini + Calls: difflib.unified_diff + + SSDL: + `o-> [I:get_mtime] -> [B:changed?] -> [I:read_file] -> [T:diff_text]` + + Thread Boundaries: + Runs synchronously in the caller thread. + """ if not changed_items: return "" parts: list[str] = [] @@ -2286,6 +2333,38 @@ def _send_grok(md_content: str, user_message: str, base_dir: str, 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]: + """ + Dispatches queries to Grok (x.ai) model endpoint using OpenAI compatible client. + + Functional Purpose: + Initializes/ensures Grok client, sets up tool schema, appends new messages to Grok history, + constructs the Grok request structure, and executes it via the run_with_tool_loop. + + Parameters & Inputs: + md_content (str): Markdown formatted context content. + user_message (str): User prompt text. + base_dir (str): Workspace root directory. + file_items (Optional[list[dict[str, Any]]]): Media or file items for multimodal queries. + discussion_history (str): Contextual discussion text. + stream (bool): Whether to stream output. + pre_tool_callback (Optional[Callable]): Hook for HITL tool confirmation. + qa_callback (Optional[Callable]): Verification callback for QA checks. + stream_callback (Optional[Callable]): Callback function for streaming chunks. + patch_callback (Optional[Callable]): Validation callback for code edits. + + Returns: + Result[str]: Wrap of string response and potential errors. + + Immediate-Mode DAG / Thread Context: + Called by: send_result + Calls: _ensure_grok_client, _get_deepseek_tools, get_capabilities, run_with_tool_loop + + SSDL: + `[I:_ensure_grok_client] -> [I:run_with_tool_loop] -> [T:Result]` + + Thread Boundaries: + Runs synchronously in the caller thread; synchronizes Grok history using _grok_history_lock. + """ from src.openai_compatible import OpenAICompatibleRequest, _classify_openai_compatible_error try: client = _ensure_grok_client() @@ -2338,6 +2417,39 @@ def _send_minimax(md_content: str, user_message: str, base_dir: str, 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]: + """ + Dispatches queries to the MiniMax provider using OpenAI compatible client. + + Functional Purpose: + Ensures client setup, performs MiniMax-specific history repairs, appends new messages, + constructs the MiniMax request structure, extracts reasoning content, and executes it via the tool loop. + + Parameters & Inputs: + md_content (str): Markdown formatted context content. + user_message (str): User prompt text. + base_dir (str): Workspace root directory. + file_items (Optional[list[dict[str, Any]]]): Media or file items for multimodal queries. + discussion_history (str): Contextual discussion text. + stream (bool): Whether to stream output. + pre_tool_callback (Optional[Callable]): Hook for HITL tool confirmation. + qa_callback (Optional[Callable]): Verification callback for QA checks. + stream_callback (Optional[Callable]): Callback function for streaming chunks. + patch_callback (Optional[Callable]): Validation callback for code edits. + + Returns: + Result[str]: Wrap of string response and potential errors. + + Immediate-Mode DAG / Thread Context: + Called by: send_result + Calls: _ensure_minimax_client, _repair_minimax_history, _get_deepseek_tools, + get_capabilities, run_with_tool_loop + + SSDL: + `[I:_ensure_minimax_client] -> [I:_repair_minimax_history] -> [I:run_with_tool_loop] -> [T:Result]` + + Thread Boundaries: + Runs synchronously in the caller thread; synchronizes MiniMax history using _minimax_history_lock. + """ from src.openai_compatible import OpenAICompatibleRequest try: _ensure_minimax_client() @@ -2459,6 +2571,38 @@ def _send_qwen(md_content: str, user_message: str, base_dir: str, 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]: + """ + Dispatches queries to Alibaba's Qwen model via DashScope SDK. + + Functional Purpose: + Initializes/ensures DashScope setup, builds the conversation history, + and delegates the invocation to _dashscope_call which triggers dashscope.Generation.call. + + Parameters & Inputs: + md_content (str): Markdown formatted context content. + user_message (str): User prompt text. + base_dir (str): Workspace root directory. + file_items (Optional[list[dict[str, Any]]]): Media or file items for multimodal queries. + discussion_history (str): Contextual discussion text. + stream (bool): Whether to stream output. + pre_tool_callback (Optional[Callable]): Hook for HITL tool confirmation. + qa_callback (Optional[Callable]): Verification callback for QA checks. + stream_callback (Optional[Callable]): Callback function for streaming chunks. + patch_callback (Optional[Callable]): Validation callback for code edits. + + Returns: + Result[str]: Wrap of string response and potential errors. + + Immediate-Mode DAG / Thread Context: + Called by: send_result + Calls: _ensure_qwen_client, _dashscope_call + + SSDL: + `[I:_ensure_qwen_client] -> [I:dashscope.Generation.call] -> [T:Result]` + + Thread Boundaries: + Runs synchronously in the caller thread; synchronizes history using _qwen_history_lock. + """ from src.qwen_adapter import classify_dashscope_error try: _ensure_qwen_client() @@ -2510,6 +2654,39 @@ def _send_llama(md_content: str, user_message: str, base_dir: str, 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]: + """ + Dispatches queries to Llama-based models using OpenAI compatible client or native Ollama backend. + + Functional Purpose: + Routes execution either to _send_llama_native (if using a local/Ollama base URL) or + to the OpenAI compatible client setup with history management and tool loop execution. + + Parameters & Inputs: + md_content (str): Markdown formatted context content. + user_message (str): User prompt text. + base_dir (str): Workspace root directory. + file_items (Optional[list[dict[str, Any]]]): Media or file items for multimodal queries. + discussion_history (str): Contextual discussion text. + stream (bool): Whether to stream output. + pre_tool_callback (Optional[Callable]): Hook for HITL tool confirmation. + qa_callback (Optional[Callable]): Verification callback for QA checks. + stream_callback (Optional[Callable]): Callback function for streaming chunks. + patch_callback (Optional[Callable]): Validation callback for code edits. + + Returns: + Result[str]: Wrap of string response and potential errors. + + Immediate-Mode DAG / Thread Context: + Called by: send_result + Calls: _send_llama_native, _ensure_llama_client, _get_deepseek_tools, + get_capabilities, run_with_tool_loop + + SSDL: + `[I:_ensure_llama_client] -> [I:run_with_tool_loop] -> [T:Result]` + + Thread Boundaries: + Runs synchronously in the caller thread; synchronizes history using _llama_history_lock. + """ from src.openai_compatible import OpenAICompatibleRequest, _classify_openai_compatible_error try: if "localhost" in _llama_base_url or "127.0.0.1" in _llama_base_url: @@ -2575,6 +2752,38 @@ def _send_llama_native(md_content: str, user_message: str, base_dir: str, 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]: + """ + Dispatches queries natively to local Ollama endpoints using direct HTTP requests. + + Functional Purpose: + Bypasses the OpenAI compatible wrapper to interact directly with the Ollama REST API. + Supports image attachments and extracts deep thinking logs (if present) to format the response. + + Parameters & Inputs: + md_content (str): Markdown formatted context content. + user_message (str): User prompt text. + base_dir (str): Workspace root directory. + file_items (Optional[list[dict[str, Any]]]): Media or file items for multimodal queries. + discussion_history (str): Contextual discussion text. + stream (bool): Whether to stream output. + pre_tool_callback (Optional[Callable]): Hook for HITL tool confirmation. + qa_callback (Optional[Callable]): Verification callback for QA checks. + stream_callback (Optional[Callable]): Callback function for streaming chunks. + patch_callback (Optional[Callable]): Validation callback for code edits. + + Returns: + Result[str]: Wrap of string response (possibly including thinking blocks) and potential errors. + + Immediate-Mode DAG / Thread Context: + Called by: _send_llama + Calls: ollama_chat + + SSDL: + `[I:_ensure_llama_client] -> [I:run_with_tool_loop] -> [T:Result]` + + Thread Boundaries: + Runs synchronously in the caller thread; synchronizes history using _llama_history_lock. + """ try: base_url = _llama_base_url.replace("/v1", "") with _llama_history_lock: