gac 3.10.3__py3-none-any.whl

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",
+]

gac/providers/fireworks.py

@@ -0,0 +1,15 @@
+"""Fireworks AI API provider for gac."""
+
+from gac.providers.base import OpenAICompatibleProvider, ProviderConfig
+
+
+class FireworksProvider(OpenAICompatibleProvider):
+    config = ProviderConfig(
+        name="Fireworks",
+        api_key_env="FIREWORKS_API_KEY",
+        base_url="https://api.fireworks.ai/inference/v1",
+    )
+
+    def _get_api_url(self, model: str | None = None) -> str:
+        """Get Fireworks API URL with /chat/completions endpoint."""
+        return f"{self.config.base_url}/chat/completions"

gac/providers/gemini.py

@@ -0,0 +1,90 @@
+"""Gemini AI provider implementation."""
+
+from typing import Any
+
+from gac.errors import AIError
+from gac.providers.base import GenericHTTPProvider, ProviderConfig
+
+
+class GeminiProvider(GenericHTTPProvider):
+    """Google Gemini provider with custom format and role conversion."""
+
+    config = ProviderConfig(
+        name="Gemini",
+        api_key_env="GEMINI_API_KEY",
+        base_url="https://generativelanguage.googleapis.com/v1beta",
+    )
+
+    def _get_api_url(self, model: str | None = None) -> str:
+        """Build Gemini URL with model in path."""
+        if model is None:
+            return super()._get_api_url(model)
+        return f"{self.config.base_url}/models/{model}:generateContent"
+
+    def _build_headers(self) -> dict[str, str]:
+        """Build headers with Google API key."""
+        headers = super()._build_headers()
+        # Remove any Authorization header
+        if "Authorization" in headers:
+            del headers["Authorization"]
+        headers["x-goog-api-key"] = self.api_key
+        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 Gemini-format request with role conversion and system instruction extraction."""
+        contents: list[dict[str, Any]] = []
+        system_instruction_parts: list[dict[str, str]] = []
+
+        for msg in messages:
+            role = msg.get("role")
+            content_value = msg.get("content")
+            content = "" if content_value is None else str(content_value)
+
+            if role == "system":
+                if content.strip():
+                    system_instruction_parts.append({"text": content})
+                continue
+
+            if role == "assistant":
+                gemini_role = "model"
+            elif role == "user":
+                gemini_role = "user"
+            else:
+                raise AIError.model_error(f"Unsupported message role for Gemini API: {role}")
+
+            contents.append({"role": gemini_role, "parts": [{"text": content}]})
+
+        body: dict[str, Any] = {
+            "contents": contents,
+            "generationConfig": {"temperature": temperature, "maxOutputTokens": max_tokens},
+        }
+
+        if system_instruction_parts:
+            body["systemInstruction"] = {"role": "system", "parts": system_instruction_parts}
+
+        return body
+
+    def _parse_response(self, response: dict[str, Any]) -> str:
+        """Parse Gemini response format: candidates[0].content.parts[0].text."""
+        candidates = response.get("candidates")
+        if not candidates:
+            raise AIError.model_error("Gemini API response missing candidates")
+
+        candidate = candidates[0]
+        if "content" not in candidate or "parts" not in candidate["content"] or not candidate["content"]["parts"]:
+            raise AIError.model_error("Gemini API response has invalid content structure")
+
+        parts = candidate["content"]["parts"]
+        content_text: str | None = None
+        for part in parts:
+            if isinstance(part, dict):
+                part_text = part.get("text")
+                if isinstance(part_text, str) and part_text:
+                    content_text = part_text
+                    break
+        if content_text is None:
+            raise AIError.model_error("Gemini API response missing text content")
+
+        return content_text

gac/providers/groq.py

@@ -0,0 +1,15 @@
+"""Groq API provider for gac."""
+
+from gac.providers.base import OpenAICompatibleProvider, ProviderConfig
+
+
+class GroqProvider(OpenAICompatibleProvider):
+    config = ProviderConfig(
+        name="Groq",
+        api_key_env="GROQ_API_KEY",
+        base_url="https://api.groq.com/openai/v1",
+    )
+
+    def _get_api_url(self, model: str | None = None) -> str:
+        """Get Groq API URL with /chat/completions endpoint."""
+        return f"{self.config.base_url}/chat/completions"

gac/providers/kimi_coding.py

@@ -0,0 +1,27 @@
+"""Kimi Coding AI provider implementation."""
+
+from typing import Any
+
+from gac.providers.base import OpenAICompatibleProvider, ProviderConfig
+
+
+class KimiCodingProvider(OpenAICompatibleProvider):
+    """Kimi Coding API provider using OpenAI-compatible format."""
+
+    config = ProviderConfig(
+        name="Kimi Coding",
+        api_key_env="KIMI_CODING_API_KEY",
+        base_url="https://api.kimi.com/coding/v1",
+    )
+
+    def _get_api_url(self, model: str | None = None) -> str:
+        """Get Kimi Coding API URL with /chat/completions endpoint."""
+        return f"{self.config.base_url}/chat/completions"
+
+    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/lmstudio.py

@@ -0,0 +1,80 @@
+"""LM Studio API provider for gac."""
+
+import os
+from typing import Any
+
+from gac.providers.base import OpenAICompatibleProvider, ProviderConfig
+
+
+class LMStudioProvider(OpenAICompatibleProvider):
+    """LM Studio provider for local OpenAI-compatible models."""
+
+    config = ProviderConfig(
+        name="LM Studio",
+        api_key_env="LMSTUDIO_API_KEY",
+        base_url="http://localhost:1234/v1",
+    )
+
+    def __init__(self, config: ProviderConfig):
+        """Initialize with configurable URL from environment."""
+        super().__init__(config)
+        # Allow URL override via environment variable
+        api_url = os.getenv("LMSTUDIO_API_URL", "http://localhost:1234")
+        api_url = api_url.rstrip("/")
+        self.config.base_url = f"{api_url}/v1"
+
+    def _get_api_key(self) -> str:
+        """Get optional API key for LM Studio."""
+        api_key = os.getenv(self.config.api_key_env)
+        if not api_key:
+            return ""  # Optional API key
+        return api_key
+
+    def _build_headers(self) -> dict[str, str]:
+        """Build headers with optional API key."""
+        headers = super()._build_headers()
+        # Remove Bearer token from parent if it was added
+        if "Authorization" in headers:
+            del headers["Authorization"]
+        # Add optional Authorization
+        api_key = os.getenv("LMSTUDIO_API_KEY")
+        if api_key:
+            headers["Authorization"] = f"Bearer {api_key}"
+        return headers
+
+    def _get_api_url(self, model: str | None = None) -> str:
+        """Get LM Studio API URL with /chat/completions endpoint."""
+        return f"{self.config.base_url}/chat/completions"
+
+    def _build_request_body(
+        self, messages: list[dict[str, Any]], temperature: float, max_tokens: int, model: str, **kwargs: Any
+    ) -> dict[str, Any]:
+        """Build OpenAI-compatible request body with stream disabled."""
+        body = super()._build_request_body(messages, temperature, max_tokens, model, **kwargs)
+        body["stream"] = False
+        return body
+
+    def _parse_response(self, response: dict[str, Any]) -> str:
+        """Parse OpenAI-compatible response with text field fallback."""
+        from gac.errors import AIError
+
+        choices = response.get("choices")
+        if not choices or not isinstance(choices, list):
+            raise AIError.model_error("Invalid response: missing choices")
+
+        # First try message.content (standard OpenAI format)
+        choice = choices[0]
+        content = choice.get("message", {}).get("content")
+        if content is not None:
+            if content == "":
+                raise AIError.model_error("Invalid response: empty content")
+            return content
+
+        # Fallback to text field (some OpenAI-compatible servers use this)
+        content = choice.get("text")
+        if content is not None:
+            if content == "":
+                raise AIError.model_error("Invalid response: empty content")
+            return content
+
+        raise AIError.model_error("Invalid response: missing content")

gac/providers/minimax.py

@@ -0,0 +1,15 @@
+"""MiniMax API provider for gac."""
+
+from gac.providers.base import OpenAICompatibleProvider, ProviderConfig
+
+
+class MinimaxProvider(OpenAICompatibleProvider):
+    config = ProviderConfig(
+        name="MiniMax",
+        api_key_env="MINIMAX_API_KEY",
+        base_url="https://api.minimaxi.com/v1",
+    )
+
+    def _get_api_url(self, model: str | None = None) -> str:
+        """Get MiniMax API URL with /chat/completions endpoint."""
+        return f"{self.config.base_url}/chat/completions"

gac/providers/mistral.py

@@ -0,0 +1,15 @@
+"""Mistral API provider for gac."""
+
+from gac.providers.base import OpenAICompatibleProvider, ProviderConfig
+
+
+class MistralProvider(OpenAICompatibleProvider):
+    config = ProviderConfig(
+        name="Mistral",
+        api_key_env="MISTRAL_API_KEY",
+        base_url="https://api.mistral.ai/v1",
+    )
+
+    def _get_api_url(self, model: str | None = None) -> str:
+        """Get Mistral API URL with /chat/completions endpoint."""
+        return f"{self.config.base_url}/chat/completions"

gac/providers/moonshot.py

@@ -0,0 +1,15 @@
+"""Moonshot AI provider for gac."""
+
+from gac.providers.base import OpenAICompatibleProvider, ProviderConfig
+
+
+class MoonshotProvider(OpenAICompatibleProvider):
+    config = ProviderConfig(
+        name="Moonshot",
+        api_key_env="MOONSHOT_API_KEY",
+        base_url="https://api.moonshot.cn/v1",
+    )
+
+    def _get_api_url(self, model: str | None = None) -> str:
+        """Get Moonshot API URL with /chat/completions endpoint."""
+        return f"{self.config.base_url}/chat/completions"

gac/providers/ollama.py

@@ -0,0 +1,73 @@
+"""Ollama API provider for gac."""
+
+import os
+from typing import Any
+
+from gac.providers.base import OpenAICompatibleProvider, ProviderConfig
+
+
+class OllamaProvider(OpenAICompatibleProvider):
+    """Ollama provider for local LLM models with optional authentication."""
+
+    config = ProviderConfig(
+        name="Ollama",
+        api_key_env="OLLAMA_API_KEY",
+        base_url="http://localhost:11434",
+    )
+
+    def __init__(self, config: ProviderConfig):
+        """Initialize with configurable URL from environment."""
+        super().__init__(config)
+        # Allow URL override via environment variable
+        api_url = os.getenv("OLLAMA_API_URL", "http://localhost:11434")
+        self.config.base_url = api_url.rstrip("/")
+
+    def _build_headers(self) -> dict[str, str]:
+        """Build headers with optional API key."""
+        headers = super()._build_headers()
+        api_key = os.getenv("OLLAMA_API_KEY")
+        if api_key:
+            headers["Authorization"] = f"Bearer {api_key}"
+        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 Ollama request body with stream disabled."""
+        return {
+            "messages": messages,
+            "temperature": temperature,
+            "stream": False,
+            **kwargs,
+        }
+
+    def _get_api_url(self, model: str | None = None) -> str:
+        """Get API URL with /api/chat endpoint."""
+        return f"{self.config.base_url}/api/chat"
+
+    def _get_api_key(self) -> str:
+        """Get optional API key for Ollama."""
+        api_key = os.getenv(self.config.api_key_env)
+        if not api_key:
+            return ""  # Optional API key
+        return api_key
+
+    def _parse_response(self, response: dict[str, Any]) -> str:
+        """Parse Ollama response with flexible format support."""
+        from gac.errors import AIError
+
+        # Handle different response formats from Ollama
+        if "message" in response and "content" in response["message"]:
+            content = response["message"]["content"]
+        elif "response" in response:
+            content = response["response"]
+        else:
+            # Fallback: try to serialize response
+            content = str(response) if response else ""
+
+        if content is None:
+            raise AIError.model_error("Ollama API returned null content")
+        if content == "":
+            raise AIError.model_error("Ollama API returned empty content")
+
+        return content

gac/providers/openai.py

@@ -0,0 +1,32 @@
+"""OpenAI API provider for gac."""
+
+from typing import Any
+
+from gac.providers.base import OpenAICompatibleProvider, ProviderConfig
+
+
+class OpenAIProvider(OpenAICompatibleProvider):
+    """OpenAI API provider with model-specific adjustments."""
+
+    config = ProviderConfig(name="OpenAI", api_key_env="OPENAI_API_KEY", base_url="https://api.openai.com/v1")
+
+    def _get_api_url(self, model: str | None = None) -> str:
+        """Get OpenAI API URL with /chat/completions endpoint."""
+        return f"{self.config.base_url}/chat/completions"
+
+    def _build_request_body(
+        self, messages: list[dict[str, Any]], temperature: float, max_tokens: int, model: str, **kwargs: Any
+    ) -> dict[str, Any]:
+        """Build OpenAI-specific request body."""
+        data = super()._build_request_body(messages, temperature, max_tokens, model, **kwargs)
+
+        # OpenAI uses max_completion_tokens instead of max_tokens
+        data["max_completion_tokens"] = data.pop("max_tokens")
+
+        # Handle optional parameters
+        if "response_format" in kwargs:
+            data["response_format"] = kwargs["response_format"]
+        if "stop" in kwargs:
+            data["stop"] = kwargs["stop"]
+
+        return data

gac/providers/openrouter.py

@@ -0,0 +1,21 @@
+"""OpenRouter API provider for gac."""
+
+from gac.providers.base import OpenAICompatibleProvider, ProviderConfig
+
+
+class OpenRouterProvider(OpenAICompatibleProvider):
+    config = ProviderConfig(
+        name="OpenRouter",
+        api_key_env="OPENROUTER_API_KEY",
+        base_url="https://openrouter.ai/api/v1",
+    )
+
+    def _get_api_url(self, model: str | None = None) -> str:
+        """Get OpenRouter API URL with /chat/completions endpoint."""
+        return f"{self.config.base_url}/chat/completions"
+
+    def _build_headers(self) -> dict[str, str]:
+        """Build headers with OpenRouter-style authorization and HTTP-Referer."""
+        headers = super()._build_headers()
+        headers["HTTP-Referer"] = "https://github.com/codeindolence/gac"
+        return headers

gac/providers/protocol.py

@@ -0,0 +1,71 @@
+"""Provider protocol for type-safe AI provider implementations."""
+
+from typing import Any, Protocol, runtime_checkable
+
+
+@runtime_checkable
+class ProviderProtocol(Protocol):
+    """Protocol defining the contract for AI providers.
+
+    All providers must implement this protocol to ensure consistent
+    interface and type safety across the codebase.
+
+    This protocol supports both class-based providers (with methods)
+    and function-based providers (used in the registry).
+    """
+
+    def generate(
+        self, model: str, messages: list[dict[str, Any]], temperature: float, max_tokens: int, **kwargs: Any
+    ) -> str:
+        """Generate text using the AI model.
+
+        Args:
+            model: The model name to use
+            messages: List of message dictionaries in chat format
+            temperature: Temperature parameter (0.0-2.0)
+            max_tokens: Maximum tokens in response
+            **kwargs: Additional provider-specific parameters
+
+        Returns:
+            Generated text content
+
+        Raises:
+            AIError: For any generation-related errors
+        """
+        ...
+
+    @property
+    def name(self) -> str:
+        """Get the provider name.
+
+        Returns:
+            Provider name identifier
+        """
+        ...
+
+    @property
+    def api_key_env(self) -> str:
+        """Get the environment variable name for the API key.
+
+        Returns:
+            Environment variable name
+        """
+        ...
+
+    @property
+    def base_url(self) -> str:
+        """Get the base URL for the API.
+
+        Returns:
+            Base API URL
+        """
+        ...
+
+    @property
+    def timeout(self) -> int:
+        """Get the timeout in seconds.
+
+        Returns:
+            Timeout in seconds
+        """
+        ...