docs(ai_client): add detailed SQLite-granularity docstrings to secondary senders and context helpers

2026-06-13 18:27:46 -04:00
parent 20b5544d3e
commit 1ccef1685f
1 changed files with 209 additions and 0 deletions
@@ -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: