gac 3.6.0__py3-none-any.whl → 3.10.10__py3-none-any.whl

gac/providers/claude_code.py

@@ -1,102 +1,79 @@
-"""Claude Code provider implementation.
+"""Claude Code API provider for gac.
 
 This provider allows users with Claude Code subscriptions to use their OAuth tokens
 instead of paying for the expensive Anthropic API.
 """
 
-import os
-
-import httpx
+from typing import Any
 
 from gac.errors import AIError
+from gac.oauth.claude_code import load_stored_token
+from gac.providers.base import AnthropicCompatibleProvider, ProviderConfig
 
 
-def call_claude_code_api(model: str, messages: list[dict], temperature: float, max_tokens: int) -> str:
-    """Call Claude Code API using OAuth token.
-
-    This provider uses the Claude Code subscription OAuth token instead of the Anthropic API key.
-    It authenticates using Bearer token authentication with the special anthropic-beta header.
-
-    Environment variables:
-        CLAUDE_CODE_ACCESS_TOKEN: OAuth access token from Claude Code authentication
+class ClaudeCodeProvider(AnthropicCompatibleProvider):
+    """Claude Code OAuth provider with special system message requirements."""
 
-    Args:
-        model: Model name (e.g., 'claude-sonnet-4-5')
-        messages: List of message dictionaries with 'role' and 'content' keys
-        temperature: Sampling temperature (0.0-1.0)
-        max_tokens: Maximum tokens in response
+    config = ProviderConfig(
+        name="Claude Code",
+        api_key_env="CLAUDE_CODE_ACCESS_TOKEN",
+        base_url="https://api.anthropic.com/v1/messages",
+    )
 
-    Returns:
-        Generated text response
+    def _get_api_key(self) -> str:
+        """Get OAuth token from token store."""
+        token = load_stored_token()
+        if token:
+            return token
 
-    Raises:
-        AIError: If authentication fails or API call fails
-    """
-    access_token = os.getenv("CLAUDE_CODE_ACCESS_TOKEN")
-    if not access_token:
         raise AIError.authentication_error(
-            "CLAUDE_CODE_ACCESS_TOKEN not found in environment variables. "
-            "Please authenticate with Claude Code and set this token."
+            "Claude Code authentication not found. Run 'gac auth claude-code login' to authenticate."
         )
 
-    url = "https://api.anthropic.com/v1/messages"
-    headers = {
-        "Authorization": f"Bearer {access_token}",
-        "anthropic-version": "2023-06-01",
-        "anthropic-beta": "oauth-2025-04-20",
-        "content-type": "application/json",
-    }
-
-    # Convert messages to Anthropic format
-    # IMPORTANT: Claude Code OAuth tokens require the system message to be EXACTLY
-    # "You are Claude Code, Anthropic's official CLI for Claude." with NO additional content.
-    # Any other instructions must be moved to the user message.
-    anthropic_messages = []
-    system_instructions = ""
-
-    for msg in messages:
-        if msg["role"] == "system":
-            system_instructions = msg["content"]
-        else:
-            anthropic_messages.append({"role": msg["role"], "content": msg["content"]})
-
-    # Claude Code requires this exact system message, nothing more
-    system_message = "You are Claude Code, Anthropic's official CLI for Claude."
-
-    # Move any system instructions into the first user message
-    if system_instructions and anthropic_messages:
-        # Prepend system instructions to the first user message
-        first_user_msg = anthropic_messages[0]
-        first_user_msg["content"] = f"{system_instructions}\n\n{first_user_msg['content']}"
-
-    data = {
-        "model": model,
-        "messages": anthropic_messages,
-        "temperature": temperature,
-        "max_tokens": max_tokens,
-        "system": system_message,
-    }
-
-    try:
-        response = httpx.post(url, headers=headers, json=data, timeout=120)
-        response.raise_for_status()
-        response_data = response.json()
-        content = response_data["content"][0]["text"]
-        if content is None:
-            raise AIError.model_error("Claude Code API returned null content")
-        if content == "":
-            raise AIError.model_error("Claude Code API returned empty content")
-        return content
-    except httpx.HTTPStatusError as e:
-        if e.response.status_code == 401:
-            raise AIError.authentication_error(
-                f"Claude Code authentication failed: {e.response.text}. "
-                "Your token may have expired. Please re-authenticate."
-            ) from e
-        if e.response.status_code == 429:
-            raise AIError.rate_limit_error(f"Claude Code API rate limit exceeded: {e.response.text}") from e
-        raise AIError.model_error(f"Claude Code API error: {e.response.status_code} - {e.response.text}") from e
-    except httpx.TimeoutException as e:
-        raise AIError.timeout_error(f"Claude Code API request timed out: {str(e)}") from e
-    except Exception as e:
-        raise AIError.model_error(f"Error calling Claude Code API: {str(e)}") from e
+    def _build_headers(self) -> dict[str, str]:
+        """Build headers with OAuth token and special anthropic-beta."""
+        headers = super()._build_headers()
+        # Replace x-api-key with Bearer token
+        if "x-api-key" in headers:
+            del headers["x-api-key"]
+        headers["Authorization"] = f"Bearer {self.api_key}"
+        # Add special OAuth beta header
+        headers["anthropic-beta"] = "oauth-2025-04-20"
+        return headers
+
+    def _build_request_body(
+        self, messages: list[dict[str, Any]], temperature: float, max_tokens: int, model: str, **kwargs: Any
+    ) -> dict[str, Any]:
+        """Build Anthropic-style request with fixed system message.
+
+        IMPORTANT: Claude Code OAuth tokens require the system message to be EXACTLY
+        "You are Claude Code, Anthropic's official CLI for Claude." with NO additional content.
+        Any other instructions must be moved to the first user message.
+        """
+        # Extract and process messages
+        anthropic_messages = []
+        system_instructions = ""
+
+        for msg in messages:
+            if msg["role"] == "system":
+                system_instructions = msg["content"]
+            else:
+                anthropic_messages.append({"role": msg["role"], "content": msg["content"]})
+
+        # Move any system instructions into the first user message
+        if system_instructions and anthropic_messages:
+            first_user_msg = anthropic_messages[0]
+            first_user_msg["content"] = f"{system_instructions}\n\n{first_user_msg['content']}"
+
+        # Claude Code requires this exact system message
+        system_message = "You are Claude Code, Anthropic's official CLI for Claude."
+
+        body = {
+            "messages": anthropic_messages,
+            "temperature": temperature,
+            "max_tokens": max_tokens,
+            "system": system_message,
+            **kwargs,
+        }
+
+        return body

gac/providers/custom_anthropic.py

@@ -7,79 +7,67 @@ while using the same model capabilities as the standard Anthropic provider.
 import json
 import logging
 import os
-
-import httpx
+from typing import Any
 
 from gac.errors import AIError
+from gac.providers.base import AnthropicCompatibleProvider, ProviderConfig
 
 logger = logging.getLogger(__name__)
 
 
-def call_custom_anthropic_api(model: str, messages: list[dict], temperature: float, max_tokens: int) -> str:
-    """Call a custom Anthropic-compatible API endpoint.
-
-    This provider is useful for:
-    - Anthropic-compatible proxies or gateways
-    - Self-hosted Anthropic-compatible services
-    - Other services implementing the Anthropic Messages API
-
-    Environment variables:
-        CUSTOM_ANTHROPIC_API_KEY: API key for authentication (required)
-        CUSTOM_ANTHROPIC_BASE_URL: Base URL for the API endpoint (required)
-            Example: https://your-proxy.example.com
-        CUSTOM_ANTHROPIC_VERSION: API version header (optional, defaults to '2023-06-01')
+class CustomAnthropicProvider(AnthropicCompatibleProvider):
+    """Custom Anthropic-compatible provider with configurable endpoint and version."""
 
-    Args:
-        model: The model to use (e.g., 'claude-sonnet-4-5', 'claude-haiku-4-5')
-        messages: List of message dictionaries with 'role' and 'content' keys
-        temperature: Controls randomness (0.0-1.0)
-        max_tokens: Maximum tokens in the response
+    config = ProviderConfig(
+        name="Custom Anthropic",
+        api_key_env="CUSTOM_ANTHROPIC_API_KEY",
+        base_url="",  # Will be set in __init__ from environment
+    )
 
-    Returns:
-        The generated commit message
+    def __init__(self, config: ProviderConfig):
+        """Initialize the provider with custom configuration from environment variables.
 
-    Raises:
-        AIError: If authentication fails, API errors occur, or response is invalid
-    """
-    api_key = os.getenv("CUSTOM_ANTHROPIC_API_KEY")
-    if not api_key:
-        raise AIError.authentication_error("CUSTOM_ANTHROPIC_API_KEY environment variable not set")
+        Environment variables:
+            CUSTOM_ANTHROPIC_API_KEY: API key for authentication (required)
+            CUSTOM_ANTHROPIC_BASE_URL: Base URL for the API endpoint (required)
+            CUSTOM_ANTHROPIC_VERSION: API version header (optional, defaults to '2023-06-01')
+        """
+        # Get base_url from environment and normalize it
+        base_url = os.getenv("CUSTOM_ANTHROPIC_BASE_URL")
+        if not base_url:
+            raise AIError.model_error("CUSTOM_ANTHROPIC_BASE_URL environment variable not set")
 
-    base_url = os.getenv("CUSTOM_ANTHROPIC_BASE_URL")
-    if not base_url:
-        raise AIError.model_error("CUSTOM_ANTHROPIC_BASE_URL environment variable not set")
-
-    api_version = os.getenv("CUSTOM_ANTHROPIC_VERSION", "2023-06-01")
-
-    if "/v1/messages" not in base_url:
         base_url = base_url.rstrip("/")
-        url = f"{base_url}/v1/messages"
-    else:
-        url = base_url
-
-    headers = {"x-api-key": api_key, "anthropic-version": api_version, "content-type": "application/json"}
+        if base_url.endswith("/messages"):
+            pass  # Already a complete endpoint URL
+        elif base_url.endswith("/v1"):
+            base_url = f"{base_url}/messages"
+        else:
+            base_url = f"{base_url}/v1/messages"
 
-    anthropic_messages = []
-    system_message = ""
+        # Update config with the custom base URL
+        config.base_url = base_url
 
-    for msg in messages:
-        if msg["role"] == "system":
-            system_message = msg["content"]
-        else:
-            anthropic_messages.append({"role": msg["role"], "content": msg["content"]})
+        # Store the custom version for use in headers
+        self.custom_version = os.getenv("CUSTOM_ANTHROPIC_VERSION", "2023-06-01")
 
-    data = {"model": model, "messages": anthropic_messages, "temperature": temperature, "max_tokens": max_tokens}
+        super().__init__(config)
 
-    if system_message:
-        data["system"] = system_message
+    def _build_headers(self) -> dict[str, str]:
+        """Build headers with custom Anthropic version."""
+        headers = super()._build_headers()
+        headers["anthropic-version"] = self.custom_version
+        return headers
 
-    try:
-        response = httpx.post(url, headers=headers, json=data, timeout=120)
-        response.raise_for_status()
-        response_data = response.json()
+    def _parse_response(self, response: dict[str, Any]) -> str:
+        """Parse response with support for extended format (e.g., MiniMax with thinking).
 
+        Handles both:
+        - Standard Anthropic format: content[0].text
+        - Extended format: first item with type="text"
+        """
         try:
-            content_list = response_data.get("content", [])
+            content_list = response.get("content", [])
             if not content_list:
                 raise AIError.model_error("Custom Anthropic API returned empty content array")
 
@@ -93,41 +81,23 @@ def call_custom_anthropic_api(model: str, messages: list[dict], temperature: flo
                     content = text_item["text"]
                 else:
                     logger.error(
-                        f"Unexpected response format from Custom Anthropic API. Response: {json.dumps(response_data)}"
+                        f"Unexpected response format from Custom Anthropic API. Response: {json.dumps(response)}"
                     )
                     raise AIError.model_error(
                         "Custom Anthropic API returned unexpected format. Expected 'text' field in content array."
                     )
+
+            if content is None:
+                raise AIError.model_error("Custom Anthropic API returned null content")
+            if content == "":
+                raise AIError.model_error("Custom Anthropic API returned empty content")
+            return content
         except AIError:
             raise
         except (KeyError, IndexError, TypeError, StopIteration) as e:
-            logger.error(f"Unexpected response format from Custom Anthropic API. Response: {json.dumps(response_data)}")
+            logger.error(f"Unexpected response format from Custom Anthropic API. Response: {json.dumps(response)}")
             raise AIError.model_error(
                 f"Custom Anthropic API returned unexpected format. Expected Anthropic-compatible response with "
                 f"'content[0].text' or items with type='text', but got: {type(e).__name__}. "
                 f"Check logs for full response structure."
             ) from e
-
-        if content is None:
-            raise AIError.model_error("Custom Anthropic API returned null content")
-        if content == "":
-            raise AIError.model_error("Custom Anthropic API returned empty content")
-        return content
-    except httpx.ConnectError as e:
-        raise AIError.connection_error(f"Custom Anthropic API connection failed: {str(e)}") from e
-    except httpx.HTTPStatusError as e:
-        status_code = e.response.status_code
-        error_text = e.response.text
-
-        if status_code == 401:
-            raise AIError.authentication_error(f"Custom Anthropic API authentication failed: {error_text}") from e
-        elif status_code == 429:
-            raise AIError.rate_limit_error(f"Custom Anthropic API rate limit exceeded: {error_text}") from e
-        else:
-            raise AIError.model_error(f"Custom Anthropic API error: {status_code} - {error_text}") from e
-    except httpx.TimeoutException as e:
-        raise AIError.timeout_error(f"Custom Anthropic API request timed out: {str(e)}") from e
-    except AIError:
-        raise
-    except Exception as e:
-        raise AIError.model_error(f"Error calling Custom Anthropic API: {str(e)}") from e

gac/providers/custom_openai.py

@@ -4,95 +4,41 @@ This provider allows users to specify a custom OpenAI-compatible endpoint
 while using the same model capabilities as the standard OpenAI provider.
 """
 
-import json
-import logging
 import os
-
-import httpx
+from typing import Any
 
 from gac.errors import AIError
+from gac.providers.base import OpenAICompatibleProvider, ProviderConfig
 
-logger = logging.getLogger(__name__)
-
-
-def call_custom_openai_api(model: str, messages: list[dict], temperature: float, max_tokens: int) -> str:
-    """Call a custom OpenAI-compatible API endpoint.
-
-    This provider is useful for:
-    - OpenAI-compatible proxies or gateways
-    - Self-hosted OpenAI-compatible services
-    - Other services implementing the OpenAI Chat Completions API
-
-    Environment variables:
-        CUSTOM_OPENAI_API_KEY: API key for authentication (required)
-        CUSTOM_OPENAI_BASE_URL: Base URL for the API endpoint (required)
-            Example: https://your-proxy.example.com/v1
-            Example: https://your-custom-endpoint.com
-
-    Args:
-        model: The model to use (e.g., 'gpt-4', 'gpt-3.5-turbo')
-        messages: List of message dictionaries with 'role' and 'content' keys
-        temperature: Controls randomness (0.0-1.0)
-        max_tokens: Maximum tokens in the response
-
-    Returns:
-        The generated commit message
-
-    Raises:
-        AIError: If authentication fails, API errors occur, or response is invalid
-    """
-    api_key = os.getenv("CUSTOM_OPENAI_API_KEY")
-    if not api_key:
-        raise AIError.authentication_error("CUSTOM_OPENAI_API_KEY environment variable not set")
-
-    base_url = os.getenv("CUSTOM_OPENAI_BASE_URL")
-    if not base_url:
-        raise AIError.model_error("CUSTOM_OPENAI_BASE_URL environment variable not set")
-
-    if "/chat/completions" not in base_url:
-        base_url = base_url.rstrip("/")
-        url = f"{base_url}/chat/completions"
-    else:
-        url = base_url
-
-    headers = {"Authorization": f"Bearer {api_key}", "Content-Type": "application/json"}
-
-    data = {"model": model, "messages": messages, "temperature": temperature, "max_completion_tokens": max_tokens}
 
-    try:
-        response = httpx.post(url, headers=headers, json=data, timeout=120)
-        response.raise_for_status()
-        response_data = response.json()
+class CustomOpenAIProvider(OpenAICompatibleProvider):
+    """Custom OpenAI-compatible provider with configurable base URL."""
 
-        try:
-            content = response_data["choices"][0]["message"]["content"]
-        except (KeyError, IndexError, TypeError) as e:
-            logger.error(f"Unexpected response format from Custom OpenAI API. Response: {json.dumps(response_data)}")
-            raise AIError.model_error(
-                f"Custom OpenAI API returned unexpected format. Expected OpenAI-compatible response with "
-                f"'choices[0].message.content', but got: {type(e).__name__}. Check logs for full response structure."
-            ) from e
+    config = ProviderConfig(
+        name="Custom OpenAI",
+        api_key_env="CUSTOM_OPENAI_API_KEY",
+        base_url="",  # Will be set in __init__
+    )
 
-        if content is None:
-            raise AIError.model_error("Custom OpenAI API returned null content")
-        if content == "":
-            raise AIError.model_error("Custom OpenAI API returned empty content")
-        return content
-    except httpx.ConnectError as e:
-        raise AIError.connection_error(f"Custom OpenAI API connection failed: {str(e)}") from e
-    except httpx.HTTPStatusError as e:
-        status_code = e.response.status_code
-        error_text = e.response.text
+    def __init__(self, config: ProviderConfig):
+        """Initialize with base URL from environment."""
+        base_url = os.getenv("CUSTOM_OPENAI_BASE_URL")
+        if not base_url:
+            raise AIError.model_error("CUSTOM_OPENAI_BASE_URL environment variable not set")
 
-        if status_code == 401:
-            raise AIError.authentication_error(f"Custom OpenAI API authentication failed: {error_text}") from e
-        elif status_code == 429:
-            raise AIError.rate_limit_error(f"Custom OpenAI API rate limit exceeded: {error_text}") from e
+        if "/chat/completions" not in base_url:
+            base_url = base_url.rstrip("/")
+            url = f"{base_url}/chat/completions"
         else:
-            raise AIError.model_error(f"Custom OpenAI API error: {status_code} - {error_text}") from e
-    except httpx.TimeoutException as e:
-        raise AIError.timeout_error(f"Custom OpenAI API request timed out: {str(e)}") from e
-    except AIError:
-        raise
-    except Exception as e:
-        raise AIError.model_error(f"Error calling Custom OpenAI API: {str(e)}") from e
+            url = base_url
+
+        config.base_url = url
+        super().__init__(config)
+
+    def _build_request_body(
+        self, messages: list[dict[str, Any]], temperature: float, max_tokens: int, model: str, **kwargs: Any
+    ) -> dict[str, Any]:
+        """Build request body with max_completion_tokens instead of max_tokens."""
+        data = super()._build_request_body(messages, temperature, max_tokens, model, **kwargs)
+        data["max_completion_tokens"] = data.pop("max_tokens")
+        return data

gac/providers/deepseek.py

@@ -1,38 +1,15 @@
 """DeepSeek API provider for gac."""
 
-import os
+from gac.providers.base import OpenAICompatibleProvider, ProviderConfig
 
-import httpx
 
-from gac.errors import AIError
+class DeepSeekProvider(OpenAICompatibleProvider):
+    config = ProviderConfig(
+        name="DeepSeek",
+        api_key_env="DEEPSEEK_API_KEY",
+        base_url="https://api.deepseek.com/v1",
+    )
 
-
-def call_deepseek_api(model: str, messages: list[dict], temperature: float, max_tokens: int) -> str:
-    """Call DeepSeek API directly."""
-    api_key = os.getenv("DEEPSEEK_API_KEY")
-    if not api_key:
-        raise AIError.authentication_error("DEEPSEEK_API_KEY not found in environment variables")
-
-    url = "https://api.deepseek.com/v1/chat/completions"
-    headers = {"Authorization": f"Bearer {api_key}", "Content-Type": "application/json"}
-
-    data = {"model": model, "messages": messages, "temperature": temperature, "max_tokens": max_tokens}
-
-    try:
-        response = httpx.post(url, headers=headers, json=data, timeout=120)
-        response.raise_for_status()
-        response_data = response.json()
-        content = response_data["choices"][0]["message"]["content"]
-        if content is None:
-            raise AIError.model_error("DeepSeek API returned null content")
-        if content == "":
-            raise AIError.model_error("DeepSeek API returned empty content")
-        return content
-    except httpx.HTTPStatusError as e:
-        if e.response.status_code == 429:
-            raise AIError.rate_limit_error(f"DeepSeek API rate limit exceeded: {e.response.text}") from e
-        raise AIError.model_error(f"DeepSeek API error: {e.response.status_code} - {e.response.text}") from e
-    except httpx.TimeoutException as e:
-        raise AIError.timeout_error(f"DeepSeek API request timed out: {str(e)}") from e
-    except Exception as e:
-        raise AIError.model_error(f"Error calling DeepSeek API: {str(e)}") from e
+    def _get_api_url(self, model: str | None = None) -> str:
+        """Get DeepSeek API URL with /chat/completions endpoint."""
+        return f"{self.config.base_url}/chat/completions"

gac/providers/error_handler.py

@@ -0,0 +1,139 @@
+"""Centralized error handling decorator for AI providers.
+
+This module provides the single authoritative location for converting exceptions
+to AIError types. All provider API functions should be decorated with
+@handle_provider_errors to ensure consistent error handling.
+
+Error Classification:
+    - httpx.ConnectError -> AIError.connection_error
+    - httpx.TimeoutException -> AIError.timeout_error
+    - httpx.HTTPStatusError:
+        - 401 -> AIError.authentication_error
+        - 429 -> AIError.rate_limit_error
+        - 404 -> AIError.model_error
+        - 5xx -> AIError.connection_error (server issues)
+        - other -> AIError.model_error
+    - Other exceptions: String-based classification as fallback
+"""
+
+import re
+from collections.abc import Callable
+from functools import wraps
+from typing import Any
+
+import httpx
+
+from gac.errors import AIError
+
+MAX_ERROR_RESPONSE_LENGTH = 200
+
+SENSITIVE_PATTERNS = [
+    re.compile(r"sk-[A-Za-z0-9_-]{20,}"),  # OpenAI keys
+    re.compile(r"sk-ant-[A-Za-z0-9_-]{20,}"),  # Anthropic keys
+    re.compile(r"(?:ghp|gho|ghu|ghs|ghr)_[A-Za-z0-9]{20,}"),  # GitHub tokens
+    re.compile(r"AIza[0-9A-Za-z_-]{20,}"),  # Google API keys
+    re.compile(r"(?:sk|pk|rk)_(?:live|test)_[A-Za-z0-9]{20,}"),  # Stripe keys
+    re.compile(r"xox[baprs]-[A-Za-z0-9-]{20,}"),  # Slack tokens
+    re.compile(r"eyJ[A-Za-z0-9_-]+\.eyJ[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+"),  # JWT tokens
+    re.compile(r"Bearer\s+[A-Za-z0-9_-]{20,}"),  # Bearer tokens
+    re.compile(r"[A-Za-z0-9]{32,}"),  # Generic long alphanumeric tokens
+]
+
+
+def sanitize_error_response(text: str) -> str:
+    """Sanitize API error response text for safe logging/display.
+
+    This function:
+    1. Redacts potential API keys and tokens
+    2. Truncates to MAX_ERROR_RESPONSE_LENGTH characters
+
+    Args:
+        text: Raw error response text from an API
+
+    Returns:
+        Sanitized text safe for logging/display
+    """
+    if not text:
+        return ""
+
+    sanitized = text
+    for pattern in SENSITIVE_PATTERNS:
+        sanitized = pattern.sub("[REDACTED]", sanitized)
+
+    if len(sanitized) > MAX_ERROR_RESPONSE_LENGTH:
+        sanitized = sanitized[:MAX_ERROR_RESPONSE_LENGTH] + "..."
+
+    return sanitized
+
+
+def handle_provider_errors(provider_name: str) -> Callable[[Callable[..., Any]], Callable[..., Any]]:
+    """Decorator to standardize error handling across all AI providers.
+
+    This is the single authoritative location for error handling. Provider
+    implementations should not catch httpx exceptions - they will be caught
+    and converted to appropriate AIError types by this decorator.
+
+    Args:
+        provider_name: Name of the AI provider for error messages
+
+    Returns:
+        Decorator function that wraps provider functions with standardized error handling
+    """
+
+    def decorator(func: Callable[..., Any]) -> Callable[..., Any]:
+        @wraps(func)
+        def wrapper(*args: Any, **kwargs: Any) -> Any:
+            try:
+                return func(*args, **kwargs)
+            except AIError:
+                # Re-raise AIError exceptions as-is without wrapping
+                raise
+            except httpx.ConnectError as e:
+                raise AIError.connection_error(f"{provider_name}: {e}") from e
+            except httpx.TimeoutException as e:
+                raise AIError.timeout_error(f"{provider_name}: {e}") from e
+            except httpx.HTTPStatusError as e:
+                sanitized_response = sanitize_error_response(e.response.text)
+                if e.response.status_code == 401:
+                    raise AIError.authentication_error(
+                        f"{provider_name}: Invalid API key or authentication failed"
+                    ) from e
+                elif e.response.status_code == 429:
+                    raise AIError.rate_limit_error(
+                        f"{provider_name}: Rate limit exceeded. Please try again later."
+                    ) from e
+                elif e.response.status_code == 404:
+                    raise AIError.model_error(f"{provider_name}: Model not found or endpoint not available") from e
+                elif e.response.status_code >= 500:
+                    raise AIError.connection_error(
+                        f"{provider_name}: Server error (HTTP {e.response.status_code})"
+                    ) from e
+                else:
+                    raise AIError.model_error(
+                        f"{provider_name}: HTTP {e.response.status_code}: {sanitized_response}"
+                    ) from e
+            except Exception as e:
+                # Handle any other unexpected exceptions with string-based classification
+                error_str = str(e).lower()
+                if "authentication" in error_str or "unauthorized" in error_str:
+                    raise AIError.authentication_error(f"Error calling {provider_name} API: {e}") from e
+                elif "rate limit" in error_str or "quota" in error_str:
+                    raise AIError.rate_limit_error(f"Error calling {provider_name} API: {e}") from e
+                elif "timeout" in error_str:
+                    raise AIError.timeout_error(f"Error calling {provider_name} API: {e}") from e
+                elif "connection" in error_str:
+                    raise AIError.connection_error(f"Error calling {provider_name} API: {e}") from e
+                else:
+                    raise AIError.model_error(f"Error calling {provider_name} API: {e}") from e
+
+        return wrapper
+
+    return decorator
+
+
+__all__ = [
+    "MAX_ERROR_RESPONSE_LENGTH",
+    "SENSITIVE_PATTERNS",
+    "handle_provider_errors",
+    "sanitize_error_response",
+]