gac 3.10.3__py3-none-any.whl

gac/providers/base.py

@@ -0,0 +1,329 @@
+"""Base configured provider class to eliminate code duplication."""
+
+import logging
+import os
+from abc import ABC, abstractmethod
+from dataclasses import dataclass
+from typing import Any
+
+import httpx
+
+from gac.constants import ProviderDefaults
+from gac.errors import AIError
+from gac.providers.protocol import ProviderProtocol
+from gac.utils import get_ssl_verify
+
+logger = logging.getLogger(__name__)
+
+
+@dataclass
+class ProviderConfig:
+    """Configuration for AI providers."""
+
+    name: str
+    api_key_env: str
+    base_url: str
+    timeout: int = ProviderDefaults.HTTP_TIMEOUT
+    headers: dict[str, str] | None = None
+
+    def __post_init__(self) -> None:
+        """Initialize default headers if not provided."""
+        if self.headers is None:
+            self.headers = {"Content-Type": "application/json"}
+
+
+class BaseConfiguredProvider(ABC, ProviderProtocol):
+    """Base class for configured AI providers.
+
+    This class eliminates code duplication by providing:
+    - Standardized HTTP handling with httpx
+    - Common error handling patterns
+    - Flexible configuration via ProviderConfig
+    - Template methods for customization
+
+    Implements ProviderProtocol for type safety.
+    """
+
+    def __init__(self, config: ProviderConfig):
+        self.config = config
+        self._api_key: str | None = None  # Lazy load
+
+    @property
+    def api_key(self) -> str:
+        """Lazy-load API key when needed."""
+        if self.config.api_key_env:
+            # Always check environment for fresh value to support test isolation
+            return self._get_api_key()
+        return ""
+
+    @property
+    def name(self) -> str:
+        """Get the provider name."""
+        return self.config.name
+
+    @property
+    def api_key_env(self) -> str:
+        """Get the environment variable name for the API key."""
+        return self.config.api_key_env
+
+    @property
+    def base_url(self) -> str:
+        """Get the base URL for the API."""
+        return self.config.base_url
+
+    @property
+    def timeout(self) -> int:
+        """Get the timeout in seconds."""
+        return self.config.timeout
+
+    def _get_api_key(self) -> str:
+        """Get API key from environment variables."""
+        api_key = os.getenv(self.config.api_key_env)
+        if not api_key:
+            raise AIError.authentication_error(f"{self.config.api_key_env} not found in environment variables")
+        return api_key
+
+    @abstractmethod
+    def _build_request_body(
+        self, messages: list[dict[str, Any]], temperature: float, max_tokens: int, model: str, **kwargs: Any
+    ) -> dict[str, Any]:
+        """Build the request body for the API call.
+
+        Args:
+            messages: List of message dictionaries
+            temperature: Temperature parameter
+            max_tokens: Maximum tokens in response
+            **kwargs: Additional provider-specific parameters
+
+        Returns:
+            Request body dictionary
+        """
+        pass
+
+    @abstractmethod
+    def _parse_response(self, response: dict[str, Any]) -> str:
+        """Parse the API response and extract content.
+
+        Args:
+            response: Response dictionary from API
+
+        Returns:
+            Generated text content
+        """
+        pass
+
+    def _build_headers(self) -> dict[str, str]:
+        """Build headers for the API request.
+
+        Can be overridden by subclasses to add provider-specific headers.
+        """
+        headers = self.config.headers.copy() if self.config.headers else {}
+        return headers
+
+    def _get_api_url(self, model: str | None = None) -> str:
+        """Get the API URL for the request.
+
+        Can be overridden by subclasses for dynamic URLs.
+
+        Args:
+            model: Model name (for providers that need model-specific URLs)
+
+        Returns:
+            API URL string
+        """
+        return self.config.base_url
+
+    def _make_http_request(self, url: str, body: dict[str, Any], headers: dict[str, str]) -> dict[str, Any]:
+        """Make the HTTP request.
+
+        Error handling is delegated to the @handle_provider_errors decorator
+        which wraps the provider's API function. This avoids duplicate exception
+        handling and ensures consistent error classification across all providers.
+
+        Args:
+            url: API URL
+            body: Request body
+            headers: Request headers
+
+        Returns:
+            Response JSON dictionary
+
+        Raises:
+            httpx.HTTPStatusError: For HTTP errors (handled by decorator)
+            httpx.TimeoutException: For timeout errors (handled by decorator)
+            httpx.RequestError: For network errors (handled by decorator)
+        """
+        response = httpx.post(url, json=body, headers=headers, timeout=self.config.timeout, verify=get_ssl_verify())
+        response.raise_for_status()
+        return response.json()
+
+    def generate(
+        self,
+        model: str,
+        messages: list[dict[str, Any]],
+        temperature: float = 0.7,
+        max_tokens: int = 1024,
+        **kwargs: Any,
+    ) -> str:
+        """Generate text using the AI provider.
+
+        Error handling is delegated to the @handle_provider_errors decorator
+        which wraps the provider's API function. This ensures consistent error
+        classification across all providers.
+
+        Args:
+            model: Model name to use
+            messages: List of message dictionaries
+            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 API-related errors (via decorator)
+        """
+        logger.debug(f"Generating with {self.config.name} provider (model={model})")
+
+        # Build request components
+        url = self._get_api_url(model)
+        headers = self._build_headers()
+        body = self._build_request_body(messages, temperature, max_tokens, model, **kwargs)
+
+        # Add model to body if not already present
+        if "model" not in body:
+            body["model"] = model
+
+        # Make HTTP request
+        response_data = self._make_http_request(url, body, headers)
+
+        # Parse response
+        return self._parse_response(response_data)
+
+
+class OpenAICompatibleProvider(BaseConfiguredProvider):
+    """Base class for OpenAI-compatible providers.
+
+    Handles standard OpenAI API format with minimal customization needed.
+    """
+
+    def _build_request_body(
+        self, messages: list[dict[str, Any]], temperature: float, max_tokens: int, model: str, **kwargs: Any
+    ) -> dict[str, Any]:
+        """Build OpenAI-style request body.
+
+        Note: Subclasses should override this if they need max_completion_tokens
+        instead of max_tokens (like OpenAI provider does).
+        """
+        return {"messages": messages, "temperature": temperature, "max_tokens": max_tokens, **kwargs}
+
+    def _build_headers(self) -> dict[str, str]:
+        """Build headers with OpenAI-style authorization."""
+        headers = super()._build_headers()
+        if self.api_key:
+            headers["Authorization"] = f"Bearer {self.api_key}"
+        return headers
+
+    def _parse_response(self, response: dict[str, Any]) -> str:
+        """Parse OpenAI-style response."""
+        choices = response.get("choices")
+        if not choices or not isinstance(choices, list):
+            raise AIError.model_error("Invalid response: missing choices")
+        content = choices[0].get("message", {}).get("content")
+        if content is None:
+            raise AIError.model_error("Invalid response: null content")
+        if content == "":
+            raise AIError.model_error("Invalid response: empty content")
+        return content
+
+
+class AnthropicCompatibleProvider(BaseConfiguredProvider):
+    """Base class for Anthropic-compatible providers."""
+
+    def _build_headers(self) -> dict[str, str]:
+        """Build headers with Anthropic-style authorization."""
+        headers = super()._build_headers()
+        api_key = self._get_api_key()
+        headers["x-api-key"] = api_key
+        headers["anthropic-version"] = "2023-06-01"
+        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 body."""
+        # Convert messages to Anthropic format
+        anthropic_messages = []
+        system_message = ""
+
+        for msg in messages:
+            if msg["role"] == "system":
+                system_message = msg["content"]
+            else:
+                anthropic_messages.append({"role": msg["role"], "content": msg["content"]})
+
+        body = {"messages": anthropic_messages, "temperature": temperature, "max_tokens": max_tokens, **kwargs}
+
+        if system_message:
+            body["system"] = system_message
+
+        return body
+
+    def _parse_response(self, response: dict[str, Any]) -> str:
+        """Parse Anthropic-style response."""
+        content = response.get("content")
+        if not content or not isinstance(content, list):
+            raise AIError.model_error("Invalid response: missing content")
+
+        text_content = content[0].get("text")
+        if text_content is None:
+            raise AIError.model_error("Invalid response: null content")
+        if text_content == "":
+            raise AIError.model_error("Invalid response: empty content")
+        return text_content
+
+
+class GenericHTTPProvider(BaseConfiguredProvider):
+    """Base class for completely custom providers."""
+
+    def _build_request_body(
+        self, messages: list[dict[str, Any]], temperature: float, max_tokens: int, model: str, **kwargs: Any
+    ) -> dict[str, Any]:
+        """Default implementation - override this in subclasses."""
+        return {"messages": messages, "temperature": temperature, "max_tokens": max_tokens, **kwargs}
+
+    def _parse_response(self, response: dict[str, Any]) -> str:
+        """Default implementation - override this in subclasses."""
+        # Try OpenAI-style first
+        choices = response.get("choices")
+        if choices and isinstance(choices, list):
+            content = choices[0].get("message", {}).get("content")
+            if content:
+                return content
+
+        # Try Anthropic-style
+        content = response.get("content")
+        if content and isinstance(content, list):
+            return content[0].get("text", "")
+
+        # Try Ollama-style
+        message = response.get("message", {})
+        if "content" in message:
+            return message["content"]
+
+        # Fallback - try to find any string content
+        for value in response.values():
+            if isinstance(value, str) and len(value) > 10:  # Assume longer strings are content
+                return value
+
+        raise AIError.model_error("Could not extract content from response")
+
+
+__all__ = [
+    "AnthropicCompatibleProvider",
+    "BaseConfiguredProvider",
+    "GenericHTTPProvider",
+    "OpenAICompatibleProvider",
+    "ProviderConfig",
+]

gac/providers/cerebras.py

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

gac/providers/chutes.py

@@ -0,0 +1,25 @@
+"""Chutes.ai API provider for gac."""
+
+import os
+
+from gac.providers.base import OpenAICompatibleProvider, ProviderConfig
+
+
+class ChutesProvider(OpenAICompatibleProvider):
+    """Chutes.ai OpenAI-compatible provider with custom base URL."""
+
+    config = ProviderConfig(
+        name="Chutes",
+        api_key_env="CHUTES_API_KEY",
+        base_url="",  # Will be set in __init__
+    )
+
+    def __init__(self, config: ProviderConfig):
+        """Initialize with base URL from environment or default."""
+        base_url = os.getenv("CHUTES_BASE_URL", "https://llm.chutes.ai")
+        config.base_url = f"{base_url.rstrip('/')}/v1"
+        super().__init__(config)
+
+    def _get_api_url(self, model: str | None = None) -> str:
+        """Get Chutes API URL with /chat/completions endpoint."""
+        return f"{self.config.base_url}/chat/completions"

gac/providers/claude_code.py

@@ -0,0 +1,79 @@
+"""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.
+"""
+
+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
+
+
+class ClaudeCodeProvider(AnthropicCompatibleProvider):
+    """Claude Code OAuth provider with special system message requirements."""
+
+    config = ProviderConfig(
+        name="Claude Code",
+        api_key_env="CLAUDE_CODE_ACCESS_TOKEN",
+        base_url="https://api.anthropic.com/v1/messages",
+    )
+
+    def _get_api_key(self) -> str:
+        """Get OAuth token from token store."""
+        token = load_stored_token()
+        if token:
+            return token
+
+        raise AIError.authentication_error(
+            "Claude Code authentication not found. Run 'gac auth claude-code login' to authenticate."
+        )
+
+    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

@@ -0,0 +1,103 @@
+"""Custom Anthropic-compatible API provider for gac.
+
+This provider allows users to specify a custom Anthropic-compatible endpoint
+while using the same model capabilities as the standard Anthropic provider.
+"""
+
+import json
+import logging
+import os
+from typing import Any
+
+from gac.errors import AIError
+from gac.providers.base import AnthropicCompatibleProvider, ProviderConfig
+
+logger = logging.getLogger(__name__)
+
+
+class CustomAnthropicProvider(AnthropicCompatibleProvider):
+    """Custom Anthropic-compatible provider with configurable endpoint and version."""
+
+    config = ProviderConfig(
+        name="Custom Anthropic",
+        api_key_env="CUSTOM_ANTHROPIC_API_KEY",
+        base_url="",  # Will be set in __init__ from environment
+    )
+
+    def __init__(self, config: ProviderConfig):
+        """Initialize the provider with custom configuration from environment variables.
+
+        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 = base_url.rstrip("/")
+        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"
+
+        # Update config with the custom base URL
+        config.base_url = base_url
+
+        # Store the custom version for use in headers
+        self.custom_version = os.getenv("CUSTOM_ANTHROPIC_VERSION", "2023-06-01")
+
+        super().__init__(config)
+
+    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
+
+    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.get("content", [])
+            if not content_list:
+                raise AIError.model_error("Custom Anthropic API returned empty content array")
+
+            # Try standard Anthropic format first: content[0].text
+            if "text" in content_list[0]:
+                content = content_list[0]["text"]
+            else:
+                # Extended format (e.g., MiniMax with thinking): find first item with type="text"
+                text_item = next((item for item in content_list if item.get("type") == "text"), None)
+                if text_item and "text" in text_item:
+                    content = text_item["text"]
+                else:
+                    logger.error(
+                        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)}")
+            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

gac/providers/custom_openai.py

@@ -0,0 +1,44 @@
+"""Custom OpenAI-compatible API provider for gac.
+
+This provider allows users to specify a custom OpenAI-compatible endpoint
+while using the same model capabilities as the standard OpenAI provider.
+"""
+
+import os
+from typing import Any
+
+from gac.errors import AIError
+from gac.providers.base import OpenAICompatibleProvider, ProviderConfig
+
+
+class CustomOpenAIProvider(OpenAICompatibleProvider):
+    """Custom OpenAI-compatible provider with configurable base URL."""
+
+    config = ProviderConfig(
+        name="Custom OpenAI",
+        api_key_env="CUSTOM_OPENAI_API_KEY",
+        base_url="",  # Will be set in __init__
+    )
+
+    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 "/chat/completions" not in base_url:
+            base_url = base_url.rstrip("/")
+            url = f"{base_url}/chat/completions"
+        else:
+            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

@@ -0,0 +1,15 @@
+"""DeepSeek API provider for gac."""
+
+from gac.providers.base import OpenAICompatibleProvider, ProviderConfig
+
+
+class DeepSeekProvider(OpenAICompatibleProvider):
+    config = ProviderConfig(
+        name="DeepSeek",
+        api_key_env="DEEPSEEK_API_KEY",
+        base_url="https://api.deepseek.com/v1",
+    )
+
+    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"