From bcca433f271b16938df1656ac8892236a33e872e Mon Sep 17 00:00:00 2001 From: Ed_ Date: Wed, 13 May 2026 18:17:59 -0400 Subject: [PATCH] docs: Add ai_client.py style curation design spec --- ...6-05-13-ai-client-style-curation-design.md | 101 ++++++++++++++++++ 1 file changed, 101 insertions(+) create mode 100644 docs/superpowers/specs/2026-05-13-ai-client-style-curation-design.md diff --git a/docs/superpowers/specs/2026-05-13-ai-client-style-curation-design.md b/docs/superpowers/specs/2026-05-13-ai-client-style-curation-design.md new file mode 100644 index 0000000..19240e1 --- /dev/null +++ b/docs/superpowers/specs/2026-05-13-ai-client-style-curation-design.md @@ -0,0 +1,101 @@ +# ai_client.py Style Convention Curation + +## Overview + +Refactor `src/ai_client.py` (2522 lines) to align with `conductor/code_styleguides/python.md` conventions, following the pattern established in the recent `gui_2.py` refactor. + +## Current State Audit (as of UNCOMMITTED) + +### Already Implemented +- 1-space indentation throughout +- Type annotations on all functions +- Thread-local helpers (`get_current_tier`, `set_current_tier`) as module-level functions +- SDM tags on docstrings + +### Gaps to Fill +- `ProviderError` defined inside module (should be at module level per convention) +- No `#region` blocks despite 2522-line size (violates python.md Section 14) +- No logical section organization for 80+ functions +- Error classifier functions (`_classify_*_error`) could use vertical alignment + +## Goals + +1. Move `ProviderError` to module level (proper exception class, justified) +2. Add `#region` blocks to organize functions into logical sections +3. Apply vertical compaction alignment to dense conditionals +4. Preserve all call sites and SDM tags + +## Changes + +### 1. Module-Level `ProviderError` + +Move from inline class definition to module level, before top-level functions: + +```python +class ProviderError(Exception): + def __init__(self, provider: str, message: str, code: str | None = None): + self.provider = provider + self.message = message + self.code = code + + def ui_message(self) -> str: + return f"[{self.provider.upper()}] {self.message}" +``` + +Location: After imports, before first function (~line 300). + +### 2. Region Block Organization + +Add `#region: Section Name` / `#endregion: Section Name` blocks: + +| Region | Functions | +|--------|-----------| +| `#region: Provider Configuration` | `set_provider`, `get_provider`, `set_model_params`, `list_models`, `_list_gemini_cli_models`, `_list_gemini_models`, `_list_anthropic_models`, `_list_deepseek_models`, `_list_minimax_models` | +| `#region: Credentials & Setup` | `_get_proxy`, `get_credentials_path`, `_load_credentials`, `cleanup` | +| `#region: System Prompt Management` | `set_custom_system_prompt`, `set_base_system_prompt`, `set_use_default_base_prompt`, `set_project_context_marker`, `_get_context_marker`, `_get_combined_system_prompt`, `get_combined_system_prompt` | +| `#region: Comms Log` | `get_comms_log_callback`, `set_comms_log_callback`, `_append_comms`, `get_comms_log`, `clear_comms_log` | +| `#region: Error Classification` | `_classify_anthropic_error`, `_classify_gemini_error`, `_classify_deepseek_error`, `_classify_minimax_error` | +| `#region: Tool Configuration` | `set_agent_tools`, `set_tool_preset`, `set_bias_profile`, `get_bias_profile`, `_build_anthropic_tools`, `_get_anthropic_tools`, `_gemini_tool_declaration`, `_build_deepseek_tools`, `_get_deepseek_tools`, `_content_block_to_dict` | +| `#region: Tool Execution` | `_execute_tool_calls_concurrently`, `_execute_single_tool_call_async`, `_run_script`, `_truncate_tool_output` | +| `#region: File Context Building` | `_reread_file_items`, `_build_file_context_text`, `_build_file_diff_text` | +| `#region: Token Estimation` | `_estimate_message_tokens`, `_invalidate_token_estimate`, `_estimate_prompt_tokens`, `_strip_stale_file_refreshes` | +| `#region: History Management` | `_trim_anthropic_history`, `_repair_anthropic_history`, `_repair_deepseek_history`, `_add_history_cache_breakpoint`, `_strip_cache_controls` | +| `#region: Gemini Provider` | `_ensure_gemini_client`, `_get_gemini_history_list`, `_send_gemini`, `_send_gemini_cli`, `get_gemini_cache_stats` | +| `#region: Anthropic Provider` | `_ensure_anthropic_client`, `_chunk_text`, `_build_chunked_context_blocks`, `_send_anthropic` | +| `#region: DeepSeek Provider` | `_ensure_deepseek_client`, `_send_deepseek` | +| `#region: MiniMax Provider` | `_ensure_minimax_client`, `_send_minimax` | +| `#region: Tier 4 Analysis` | `run_tier4_analysis`, `run_tier4_patch_callback`, `run_tier4_patch_generation` | +| `#region: Session & Public API` | `reset_session`, `get_token_stats`, `send`, `_add_bleed_derived`, `run_subagent_summarization` | + +### 3. Vertical Compaction + +Apply alignment to error classifier functions: + +```python +# Before +if status == 'running': col = (0.0, 1.0, 0.0, 1.0) +elif status == 'starting': col = (1.0, 1.0, 0.0, 1.0) +elif status == 'error': col = (1.0, 0.0, 0.0, 1.0) + +# Apply to _classify_*_error functions with similar patterns +``` + +## Non-Functional Requirements + +- No logic changes — purely organizational +- All existing `[C: ...]` SDM tags preserved +- All call sites continue to work (50+ references) +- 1-space indentation maintained + +## Out of Scope + +- Extraction of class methods to module-level functions +- Indentation changes +- Logic modifications +- Test changes (unless regression detected) + +## Architecture Reference + +- `conductor/code_styleguides/python.md` — Style conventions +- `src/gui_2.py` — Reference for region block pattern (5000+ line refactor) +- `docs/guide_architecture.md` — AI client threading model context \ No newline at end of file