docs(ai_client): add detailed SQLite-granularity docstrings to send() and send_result()

src/ai_client.py

@@ -2629,8 +2629,42 @@ def send(
  rag_engine: Optional[Any] = None,
 ) -> str:
  """
-  [DEPRECATED] Use send_result() instead. Returns str (the response text). Errors are logged to the comms log but not returned.
-  The full Result[str, ErrorInfo] is available via send_result() (no deprecation).
+  [DEPRECATED] Sends a request to the configured AI provider and returns the raw response text.
+
+  Functional Purpose:
+   Acts as the legacy wrapper around send_result(). It extracts the string payload ('data')
+   from the returned Result container, logging warnings for any internal execution errors
+   to the communication logs, but suppressing the actual error objects from the caller.
+
+  Parameters & Inputs:
+   md_content (str): Base/system prompt template or markdown content.
+   user_message (str): The primary user instruction.
+   base_dir (str): Base workspace directory path (defaults to ".").
+   file_items (list[dict[str, Any]] | None): Optional list of active context files.
+   discussion_history (str): Contextual discussion history lines.
+   stream (bool): Whether to stream the response chunks.
+   pre_tool_callback (Optional[Callable]): Hook called before a tool call is executed.
+   qa_callback (Optional[Callable]): Hook for Tier 4 quality/validation checks.
+   enable_tools (bool): Controls whether LLM tool usage is enabled.
+   stream_callback (Optional[Callable]): Hook to stream response chunks to.
+   patch_callback (Optional[Callable]): Custom callback for interactive patch validation.
+   rag_engine (Optional[Any]): The RAG engine instance for retrieving vector context.
+
+  Returns:
+   str: The raw text response from the active AI provider.
+
+  Immediate-Mode DAG / Thread Context:
+   Called by: Various legacy scripts, tests, PM/Tech Lead orchestrators, and GUI event loops.
+              See list below.
+   Calls: send_result()
+
+  SSDL:
+   `[I:send_result] -> [T:text]`
+
+  Thread Boundaries:
+   Executes on whichever thread calls it (typically the GUI main thread, API hook handlers,
+   or a background async worker pool thread).
+
   [C: simulation/user_agent.py:UserSimAgent.generate_response, src/api_hooks.py:WebSocketServer._handler, src/api_hooks.py:WebSocketServer.broadcast, src/app_controller.py:AppController._handle_request_event, src/app_controller.py:_api_generate, src/conductor_tech_lead.py:generate_tickets, src/multi_agent_conductor.py:run_worker_lifecycle, src/orchestrator_pm.py:generate_tracks, tests/test_ai_cache_tracking.py:test_gemini_cache_tracking, tests/test_ai_client_cli.py:test_ai_client_send_gemini_cli, tests/test_api_events.py:test_send_emits_events_proper, tests/test_api_events.py:test_send_emits_tool_events, tests/test_deepseek_provider.py:test_deepseek_completion_logic, tests/test_deepseek_provider.py:test_deepseek_payload_verification, tests/test_deepseek_provider.py:test_deepseek_reasoner_payload_verification, tests/test_deepseek_provider.py:test_deepseek_reasoning_logic, tests/test_deepseek_provider.py:test_deepseek_streaming, tests/test_deepseek_provider.py:test_deepseek_tool_calling, tests/test_gemini_cli_adapter.py:TestGeminiCliAdapter.test_full_flow_integration, tests/test_gemini_cli_adapter.py:TestGeminiCliAdapter.test_send_captures_usage_metadata, tests/test_gemini_cli_adapter.py:TestGeminiCliAdapter.test_send_handles_tool_use_events, tests/test_gemini_cli_adapter.py:TestGeminiCliAdapter.test_send_parses_jsonl_output, tests/test_gemini_cli_adapter.py:TestGeminiCliAdapter.test_send_starts_subprocess_with_correct_args, tests/test_gemini_cli_adapter_parity.py:TestGeminiCliAdapterParity.test_send_parses_tool_calls_from_streaming_json, tests/test_gemini_cli_adapter_parity.py:TestGeminiCliAdapterParity.test_send_starts_subprocess_with_model, tests/test_gemini_cli_edge_cases.py:test_gemini_cli_context_bleed_prevention, tests/test_gemini_cli_edge_cases.py:test_gemini_cli_loop_termination, tests/test_gemini_cli_integration.py:test_gemini_cli_full_integration, tests/test_gemini_cli_integration.py:test_gemini_cli_rejection_and_history, tests/test_gemini_cli_parity_regression.py:test_send_invokes_adapter_send, tests/test_gui2_mcp.py:test_mcp_tool_call_is_dispatched, tests/test_tier4_interceptor.py:test_ai_client_passes_qa_callback, tests/test_token_usage.py:test_token_usage_tracking, tests/test_websocket_server.py:test_websocket_subscription_and_broadcast]
  """
  result = send_result(
@@ -2657,8 +2691,45 @@ def send_result(
  rag_engine: Optional[Any] = None,
 ) -> Result[str]:
  """
-  [NEW] The Result-based public API. Returns Result[str, ErrorInfo].
-  data is the response text on success; errors contains ErrorInfo on failure.
+  Sends a prompt to the currently configured AI provider, returning a comprehensive Result object.
+
+  Functional Purpose:
+   This is the primary public entry point for AI communication. It integrates retrieval-augmented
+   generation (RAG) by searching the vector index and injecting relevant context chunks into the user
+   message. It logs the outgoing request to the communications logger, acquires a global thread-safety
+   lock (_send_lock), and routes the request to the appropriate vendor-specific handler based on the
+   active provider configuration. All exceptions are caught and returned gracefully as ErrorInfo objects.
+
+  Parameters & Inputs:
+   md_content (str): System prompt template or markdown prompt structure.
+   user_message (str): The primary user instruction.
+   base_dir (str): Base workspace directory path (defaults to ".").
+   file_items (list[dict[str, Any]] | None): Optional list of active context files.
+   discussion_history (str): Contextual discussion history lines.
+   stream (bool): Whether to stream the response chunks.
+   pre_tool_callback (Optional[Callable]): Hook called before executing tool calls.
+   qa_callback (Optional[Callable]): Hook for Tier 4 quality/validation checks.
+   enable_tools (bool): Controls whether LLM tool usage is enabled.
+   stream_callback (Optional[Callable]): Hook to stream response chunks to.
+   patch_callback (Optional[Callable]): Custom callback for interactive patch validation.
+   rag_engine (Optional[Any]): RAG search engine instance to fetch vector context.
+
+  Returns:
+   Result[str]: Container holding the successful response string or error details.
+
+  Immediate-Mode DAG / Thread Context:
+   Called by: send() and direct public callers verifying error structures.
+   Calls: performance_monitor, rag_engine.search, _append_comms, _send_gemini,
+          _send_gemini_cli, _send_anthropic, _send_deepseek, _send_minimax,
+          _send_qwen, _send_llama, _send_grok, _send_llama_native
+
+  SSDL:
+   `[Q:active_provider] -> [I:SetupTierTag] -> [I:DispatchProvider] -> [T:Result]`
+
+  Thread Boundaries:
+   Acquires the global _send_lock to synchronize provider calls. Safely called from any worker
+   thread executing background tasks, preventing concurrent thread collisions on shared provider SDK states.
+
   [C: tests/test_ai_client_result.py:test_send_result_public_api_returns_result, tests/test_ai_client_result.py:test_send_result_preserves_errors, tests/test_deprecation_warnings.py:test_send_result_does_not_emit_deprecation]
  """
  monitor = performance_monitor.get_monitor()