generic-llm-api-client 0.1.1__py3-none-any.whl

ai_client/__init__.py

@@ -0,0 +1,66 @@
+"""
+Unified AI client package for multiple providers.
+
+This package provides a standardized interface for interacting with various AI models through
+their respective APIs, with separate implementation files for each provider.
+
+Key features:
+- Abstract base client defining the common interface for all AI providers
+- Provider-specific implementations for OpenAI, Google Gemini, Anthropic Claude, Mistral, DeepSeek, and Qwen
+- Support for both text-only and multimodal (text + images) content
+- Consistent LLMResponse format with detailed usage tracking
+- Factory method to create appropriate client based on provider
+- Built-in retry logic and rate limiting
+- Optional async support for parallel processing
+
+Technical implementation details:
+- OpenAI: Uses the chat completions API with multimodal support and structured output
+- Google Gemini: Uses the GenerativeModel class with image support
+- Anthropic Claude: Uses the messages API with tool-based structured output
+- Mistral: Uses the chat completion API with multimodal support
+- DeepSeek: OpenAI-compatible API with custom base URL
+- Qwen: OpenAI-compatible API with custom base URL
+- OpenRouter/sciCORE: Use OpenAI client with custom base URLs
+"""
+
+from .base_client import BaseAIClient, create_ai_client
+from .openai_client import OpenAIClient
+from .gemini_client import GeminiClient
+from .claude_client import ClaudeClient
+from .mistral_client import MistralClient
+from .deepseek_client import DeepSeekClient
+from .qwen_client import QwenClient
+from .response import LLMResponse, Usage
+from .utils import (
+    retry_with_exponential_backoff,
+    is_rate_limit_error,
+    detect_image_mime_type,
+    RateLimitError,
+    APIError,
+)
+
+__version__ = "0.1.1"
+
+__all__ = [
+    # Core classes
+    "BaseAIClient",
+    "create_ai_client",
+    # Provider-specific clients
+    "OpenAIClient",
+    "GeminiClient",
+    "ClaudeClient",
+    "MistralClient",
+    "DeepSeekClient",
+    "QwenClient",
+    # Response and utility classes
+    "LLMResponse",
+    "Usage",
+    # Utility functions and exceptions
+    "retry_with_exponential_backoff",
+    "is_rate_limit_error",
+    "detect_image_mime_type",
+    "RateLimitError",
+    "APIError",
+    # Version
+    "__version__",
+]

ai_client/base_client.py

@@ -0,0 +1,353 @@
+"""
+Abstract base AI client defining the interface for all AI provider implementations.
+
+This module provides an abstract base class that defines the common interface
+for all AI provider client implementations. It handles shared functionality
+like timing and basic client lifecycle, while leaving provider-specific
+implementations to subclasses.
+"""
+
+import abc
+import time
+import asyncio
+from typing import List, Tuple, Any, Optional
+from .response import LLMResponse, Usage
+from .utils import retry_with_exponential_backoff, is_rate_limit_error
+
+
+class BaseAIClient(abc.ABC):
+    """
+    Abstract base AI client defining the interface for all provider implementations.
+
+    This abstract class defines the common methods and properties that all AI
+    provider client implementations must support. It handles basic functionality
+    like timing, retry logic, async support, and client lifecycle.
+
+    Key features:
+    - Images are passed per-request, avoiding stateful management bugs
+    - Returns structured LLMResponse objects with detailed usage info
+    - Optional async support for parallel processing
+    - Built-in retry logic for rate limiting
+
+    Attributes:
+        PROVIDER_ID (str): The unique identifier for this AI provider
+        SUPPORTS_MULTIMODAL (bool): Whether this provider supports multimodal content
+        api_key (str): The API key used for authentication
+        system_prompt (str): Default system prompt for requests
+        settings (dict): Provider-specific settings like temperature, max_tokens, etc.
+        base_url (str, optional): Custom base URL for API (e.g., for OpenRouter, sciCORE)
+    """
+
+    PROVIDER_ID = "base"
+    SUPPORTS_MULTIMODAL = False
+
+    def __init__(
+        self,
+        api_key: str,
+        system_prompt: Optional[str] = None,
+        base_url: Optional[str] = None,
+        **settings,
+    ):
+        """
+        Initialize the AI client base.
+
+        Args:
+            api_key: API key for authentication with the provider
+            system_prompt: System prompt/role description for the AI
+            base_url: Custom base URL for API endpoints (provider-specific)
+            **settings: Additional provider-specific settings like temperature, max_tokens, etc.
+        """
+        self.init_time = time.time()
+        self.end_time = None
+        self.api_key = api_key
+        self.system_prompt = (
+            system_prompt or "A helpful assistant that provides accurate information."
+        )
+        self.base_url = base_url
+        self.settings = settings
+        self.api_client = None
+
+        # Initialize the client implementation
+        self._init_client()
+
+    @abc.abstractmethod
+    def _init_client(self):
+        """
+        Initialize the provider-specific client.
+
+        This method must be implemented by each provider to handle
+        their specific client initialization requirements.
+        """
+        pass
+
+    @property
+    def elapsed_time(self) -> float:
+        """
+        Get the elapsed time since client initialization.
+
+        Returns:
+            Elapsed time in seconds
+        """
+        if self.end_time is None:
+            return time.time() - self.init_time
+        return self.end_time - self.init_time
+
+    def end_client(self):
+        """
+        End the client session and record the end time.
+
+        This method cleans up the client object and records when the session ended.
+        """
+        self.api_client = None
+        self.end_time = time.time()
+
+    @staticmethod
+    def is_url(resource: str) -> bool:
+        """
+        Check if a resource is a URL or a local file path.
+
+        Args:
+            resource: The resource string to check
+
+        Returns:
+            True if the resource is a URL, False if it's a file path
+        """
+        return resource.startswith(("http://", "https://"))
+
+    def prompt(
+        self,
+        model: str,
+        prompt: str,
+        images: Optional[List[str]] = None,
+        system_prompt: Optional[str] = None,
+        response_format: Optional[Any] = None,
+        **kwargs,
+    ) -> Tuple[LLMResponse, float]:
+        """
+        Send a prompt to the AI model and get the response.
+
+        Args:
+            model: The model identifier to use
+            prompt: The text prompt to send to the model
+            images: Optional list of image paths/URLs to include (if provider supports multimodal)
+            system_prompt: Optional system prompt to override the default
+            response_format: Optional Pydantic model for structured output
+            **kwargs: Additional provider-specific parameters
+
+        Returns:
+            Tuple of (LLMResponse object, elapsed_time_in_seconds)
+
+        Note:
+            Images are NOT stored statefully. Pass them with each request.
+        """
+        start_time = time.time()
+
+        # Use provided system prompt or fall back to default
+        sys_prompt = system_prompt or self.system_prompt
+
+        # Handle multimodal content
+        image_list = images or []
+        if image_list and not self.SUPPORTS_MULTIMODAL:
+            # Silently ignore images if provider doesn't support them
+            image_list = []
+
+        # Call provider-specific implementation with retry logic
+        try:
+            response = self._do_prompt_with_retry(
+                model=model,
+                prompt=prompt,
+                images=image_list,
+                system_prompt=sys_prompt,
+                response_format=response_format,
+                **kwargs,
+            )
+        except Exception as e:
+            # Create error response
+            response = self._create_error_response(model, str(e))
+
+        elapsed_time = time.time() - start_time
+        response.duration = elapsed_time
+
+        return response, elapsed_time
+
+    def _do_prompt_with_retry(self, **kwargs) -> LLMResponse:
+        """
+        Execute prompt with retry logic for rate limiting.
+
+        This wraps the provider-specific _do_prompt method with retry logic.
+        """
+        # Configure retry for common rate limit errors
+        retry_func = retry_with_exponential_backoff(
+            self._do_prompt,
+            max_retries=3,
+            initial_delay=1.0,
+            max_delay=60.0,
+            retryable_exceptions=(Exception,),  # Provider-specific exceptions will be caught
+        )
+
+        return retry_func(**kwargs)
+
+    @abc.abstractmethod
+    def _do_prompt(
+        self,
+        model: str,
+        prompt: str,
+        images: List[str],
+        system_prompt: str,
+        response_format: Optional[Any],
+        **kwargs,
+    ) -> LLMResponse:
+        """
+        Provider-specific prompt implementation.
+
+        Args:
+            model: Model identifier
+            prompt: Text prompt
+            images: List of image paths/URLs
+            system_prompt: System prompt to use
+            response_format: Optional Pydantic model for structured output
+            **kwargs: Provider-specific parameters
+
+        Returns:
+            LLMResponse object with the provider's response
+        """
+        pass
+
+    async def prompt_async(
+        self,
+        model: str,
+        prompt: str,
+        images: Optional[List[str]] = None,
+        system_prompt: Optional[str] = None,
+        response_format: Optional[Any] = None,
+        **kwargs,
+    ) -> Tuple[LLMResponse, float]:
+        """
+        Async version of prompt() for parallel processing.
+
+        Args:
+            model: The model identifier to use
+            prompt: The text prompt to send
+            images: Optional list of image paths/URLs
+            system_prompt: Optional system prompt override
+            response_format: Optional Pydantic model for structured output
+            **kwargs: Additional provider-specific parameters
+
+        Returns:
+            Tuple of (LLMResponse object, elapsed_time_in_seconds)
+        """
+        # Default implementation runs sync version in executor
+        loop = asyncio.get_event_loop()
+        return await loop.run_in_executor(
+            None,
+            lambda: self.prompt(model, prompt, images, system_prompt, response_format, **kwargs),
+        )
+
+    def _create_error_response(self, model: str, error_message: str) -> LLMResponse:
+        """
+        Create an error response when the request fails.
+
+        Args:
+            model: Model identifier
+            error_message: Error message
+
+        Returns:
+            LLMResponse with error information
+        """
+        return LLMResponse(
+            text="",
+            model=model,
+            provider=self.PROVIDER_ID,
+            finish_reason="error",
+            usage=Usage(),
+            raw_response={"error": error_message},
+            duration=0.0,
+        )
+
+    @abc.abstractmethod
+    def get_model_list(self) -> List[Tuple[str, Optional[str]]]:
+        """
+        Get a list of available models from the current provider.
+
+        Returns:
+            List of tuples containing (model_id, created_date)
+            The created_date may be None for some providers.
+        """
+        pass
+
+    def has_multimodal_support(self) -> bool:
+        """
+        Check if the provider supports multimodal content.
+
+        Returns:
+            True if the provider supports multimodal content, False otherwise
+        """
+        return self.SUPPORTS_MULTIMODAL
+
+    def __str__(self):
+        """String representation of the AI client."""
+        return self.PROVIDER_ID
+
+
+def create_ai_client(
+    provider: str,
+    api_key: str,
+    system_prompt: Optional[str] = None,
+    base_url: Optional[str] = None,
+    **settings,
+) -> BaseAIClient:
+    """
+    Factory function to create an appropriate AI client for the given provider.
+
+    Args:
+        provider: The AI provider ID ('openai', 'genai', 'anthropic', 'mistral', etc.)
+        api_key: API key for the provider
+        system_prompt: System prompt/role description
+        base_url: Custom base URL for API (for OpenRouter, sciCORE, etc.)
+        **settings: Additional provider-specific settings
+
+    Returns:
+        BaseAIClient: An instance of the appropriate AI client implementation
+
+    Raises:
+        ValueError: If an unsupported provider is specified
+
+    Examples:
+        >>> # Standard usage
+        >>> client = create_ai_client('openai', api_key='sk-...')
+        >>> response, duration = client.prompt('gpt-4', 'Hello!')
+
+        >>> # With custom base URL (OpenRouter)
+        >>> client = create_ai_client('openrouter', api_key='sk-...',
+        ...                          base_url='https://openrouter.ai/api/v1')
+
+        >>> # With multimodal content
+        >>> response, duration = client.prompt('gpt-4o', 'Describe this image',
+        ...                                    images=['path/to/image.jpg'])
+    """
+    from .openai_client import OpenAIClient
+    from .gemini_client import GeminiClient
+    from .claude_client import ClaudeClient
+    from .mistral_client import MistralClient
+    from .deepseek_client import DeepSeekClient
+    from .qwen_client import QwenClient
+
+    provider_map = {
+        "openai": OpenAIClient,
+        "genai": GeminiClient,
+        "anthropic": ClaudeClient,
+        "mistral": MistralClient,
+        "deepseek": DeepSeekClient,
+        "qwen": QwenClient,
+        "openrouter": OpenAIClient,  # Uses OpenAI-compatible API
+        "scicore": OpenAIClient,  # Uses OpenAI-compatible API
+    }
+
+    if provider not in provider_map:
+        raise ValueError(
+            f"Unsupported AI provider: {provider}. "
+            f"Supported providers: {', '.join(provider_map.keys())}"
+        )
+
+    client_class = provider_map[provider]
+    return client_class(api_key, system_prompt, base_url, **settings)

ai_client/claude_client.py

@@ -0,0 +1,283 @@
+"""
+Anthropic Claude-specific implementation of the BaseAIClient.
+
+This module provides the ClaudeClient class, which implements the BaseAIClient
+interface specifically for Anthropic's Claude API, supporting both text and multimodal
+interactions.
+"""
+
+import base64
+import json
+import logging
+from datetime import datetime
+from typing import List, Tuple, Any, Optional
+
+from anthropic import Anthropic
+
+from .base_client import BaseAIClient
+from .response import LLMResponse, Usage
+
+logger = logging.getLogger(__name__)
+
+
+class ClaudeClient(BaseAIClient):
+    """
+    Anthropic Claude-specific implementation of the BaseAIClient.
+
+    This class implements the BaseAIClient interface for Anthropic's Claude API,
+    supporting both text-only and multimodal requests with tool-based structured output.
+
+    Key features:
+    - Integration with Anthropic's Messages API
+    - Support for multimodal content (text + images)
+    - Support for Claude-specific parameters like top_p, top_k
+    - Structured output via tools API
+    """
+
+    PROVIDER_ID = "anthropic"
+    SUPPORTS_MULTIMODAL = True  # Claude supports images
+
+    def _init_client(self):
+        """Initialize the Anthropic client with the provided API key."""
+        self.api_client = Anthropic(api_key=self.api_key, timeout=300.0)  # 5 minutes timeout
+
+    def _prepare_content_with_images(self, prompt: str, images: List[str]) -> List[dict]:
+        """
+        Prepare Anthropic content with text and images.
+
+        Args:
+            prompt: The text prompt
+            images: List of image paths/URLs
+
+        Returns:
+            List of content blocks for Anthropic API
+        """
+        content = [{"type": "text", "text": prompt}]
+
+        # Add images if any
+        for resource in images:
+            try:
+                if self.is_url(resource):
+                    # For URLs, we need to fetch and encode
+                    import requests
+
+                    response = requests.get(resource)
+                    if response.status_code == 200:
+                        base64_image = base64.b64encode(response.content).decode("utf-8")
+                    else:
+                        logger.error(
+                            f"Failed to fetch image from URL {resource}: {response.status_code}"
+                        )
+                        continue
+                else:
+                    # For local files, read and encode
+                    with open(resource, "rb") as image_file:
+                        base64_image = base64.b64encode(image_file.read()).decode("utf-8")
+
+                # Detect media type from file extension
+                from .utils import detect_image_mime_type
+
+                media_type = detect_image_mime_type(resource)
+
+                content.append(
+                    {
+                        "type": "image",
+                        "source": {
+                            "type": "base64",
+                            "media_type": media_type,
+                            "data": base64_image,
+                        },
+                    }
+                )
+            except Exception as e:
+                logger.error(f"Error processing image {resource}: {e}")
+
+        return content
+
+    def _do_prompt(
+        self,
+        model: str,
+        prompt: str,
+        images: List[str],
+        system_prompt: str,
+        response_format: Optional[Any],
+        **kwargs,
+    ) -> LLMResponse:
+        """
+        Send a prompt to the Claude model and get the response.
+
+        Args:
+            model: The Claude model identifier (e.g., "claude-3-opus-20240229")
+            prompt: The text prompt to send
+            images: List of image paths/URLs
+            system_prompt: System prompt to use
+            response_format: Optional Pydantic model for structured output
+            **kwargs: Additional Claude-specific parameters
+
+        Returns:
+            LLMResponse object with the provider's response
+        """
+        # Prepare content with images
+        content = self._prepare_content_with_images(prompt, images)
+
+        # Determine max_tokens based on model
+        if "opus" in model.lower():
+            default_max_tokens = 4096
+        elif "sonnet" in model.lower():
+            default_max_tokens = 8192
+        else:
+            default_max_tokens = 4096
+
+        # Extract Claude-specific parameters
+        params = {
+            "model": model,
+            "messages": [{"role": "user", "content": content}],
+            "system": system_prompt,
+            "max_tokens": kwargs.get(
+                "max_tokens", self.settings.get("max_tokens", default_max_tokens)
+            ),
+            "timeout": 300.0,
+        }
+
+        # Add optional parameters if specified
+        optional_params = ["temperature", "top_p", "top_k"]
+        for param in optional_params:
+            value = kwargs.get(param, self.settings.get(param))
+            if value is not None:
+                params[param] = value
+
+        # Handle structured output using tools
+        if response_format and hasattr(response_format, "model_json_schema"):
+            json_schema = response_format.model_json_schema()
+
+            tools = [
+                {
+                    "name": "extract_structured_data",
+                    "description": "Extract structured data according to the provided schema",
+                    "input_schema": json_schema,
+                }
+            ]
+
+            params["tools"] = tools
+            params["tool_choice"] = {"type": "tool", "name": "extract_structured_data"}
+
+            try:
+                raw_response = self.api_client.messages.create(**params)
+                return self._create_response_from_tool(raw_response, model, response_format)
+            except Exception as e:
+                logger.warning(
+                    f"Structured output via tools failed: {e}. Falling back to text mode."
+                )
+                # Remove tools and try again
+                del params["tools"]
+                del params["tool_choice"]
+
+        # Send the request to Anthropic
+        raw_response = self.api_client.messages.create(**params)
+
+        return self._create_response_from_raw(raw_response, model)
+
+    def _create_response_from_tool(
+        self, raw_response: Any, model: str, response_format: Any
+    ) -> LLMResponse:
+        """
+        Create LLMResponse from Claude tool-based response (structured output).
+
+        Args:
+            raw_response: Raw Anthropic response object
+            model: Model identifier
+            response_format: Pydantic model for validation
+
+        Returns:
+            LLMResponse object
+        """
+        # Extract tool use from response
+        text = ""
+        for block in raw_response.content:
+            if block.type == "tool_use" and block.name == "extract_structured_data":
+                try:
+                    # Validate with Pydantic and convert to JSON
+                    structured = response_format(**block.input)
+                    text = structured.model_dump_json()
+                except Exception as e:
+                    logger.warning(f"Pydantic validation failed: {e}")
+                    # Use raw tool input without validation
+                    text = json.dumps(block.input)
+                break
+            elif block.type == "text":
+                text = block.text
+
+        usage = Usage()
+        if hasattr(raw_response, "usage") and raw_response.usage:
+            usage = Usage(
+                input_tokens=raw_response.usage.input_tokens,
+                output_tokens=raw_response.usage.output_tokens,
+                total_tokens=raw_response.usage.input_tokens + raw_response.usage.output_tokens,
+            )
+
+        return LLMResponse(
+            text=text,
+            model=model,
+            provider=self.PROVIDER_ID,
+            finish_reason=raw_response.stop_reason or "unknown",
+            usage=usage,
+            raw_response=raw_response,
+        )
+
+    def _create_response_from_raw(self, raw_response: Any, model: str) -> LLMResponse:
+        """
+        Create LLMResponse from Claude raw response.
+
+        Args:
+            raw_response: Raw Anthropic response object
+            model: Model identifier
+
+        Returns:
+            LLMResponse object
+        """
+        # Extract text from content blocks
+        text = ""
+        if raw_response.content:
+            for block in raw_response.content:
+                if block.type == "text":
+                    text = block.text
+                    break
+
+        usage = Usage()
+        if hasattr(raw_response, "usage") and raw_response.usage:
+            usage = Usage(
+                input_tokens=raw_response.usage.input_tokens,
+                output_tokens=raw_response.usage.output_tokens,
+                total_tokens=raw_response.usage.input_tokens + raw_response.usage.output_tokens,
+            )
+
+        return LLMResponse(
+            text=text,
+            model=model,
+            provider=self.PROVIDER_ID,
+            finish_reason=raw_response.stop_reason or "unknown",
+            usage=usage,
+            raw_response=raw_response,
+        )
+
+    def get_model_list(self) -> List[Tuple[str, Optional[str]]]:
+        """
+        Get a list of available models from Claude.
+
+        Returns:
+            List of tuples (model_id, created_date)
+        """
+        if self.api_client is None:
+            raise ValueError("Claude client is not initialized.")
+
+        model_list = []
+        raw_list = self.api_client.models.list()
+
+        for model in raw_list:
+            try:
+                readable_date = datetime.fromisoformat(str(model.created_at)).strftime("%Y-%m-%d")
+            except:
+                readable_date = None
+            model_list.append((model.id, readable_date))
+
+        return model_list