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

ai_client/deepseek_client.py

@@ -0,0 +1,28 @@
+"""
+DeepSeek-specific client using OpenAI-compatible API.
+
+DeepSeek uses an OpenAI-compatible API, so we can reuse the OpenAIClient
+with a custom base URL.
+"""
+
+from .openai_client import OpenAIClient
+
+
+class DeepSeekClient(OpenAIClient):
+    """
+    DeepSeek client using OpenAI-compatible API.
+
+    This client simply extends OpenAIClient with a custom base URL.
+    """
+
+    PROVIDER_ID = "deepseek"
+    SUPPORTS_MULTIMODAL = True
+
+    def _init_client(self):
+        """Initialize the client with DeepSeek's base URL."""
+        # Override base_url if not provided
+        if not self.base_url:
+            self.base_url = "https://api.deepseek.com/v1"
+
+        # Call parent initialization
+        super()._init_client()

ai_client/gemini_client.py

@@ -0,0 +1,269 @@
+"""
+Google Gemini-specific implementation of the BaseAIClient.
+
+This module provides the GeminiClient class, which implements the BaseAIClient
+interface specifically for Google's Gemini API, supporting both text-only and
+multimodal (text + images) content.
+"""
+
+import base64
+import json
+import logging
+from typing import List, Tuple, Any, Optional
+
+import google.genai as genai
+from google.genai.types import GenerateContentConfig, Part
+import requests
+
+from .base_client import BaseAIClient
+from .response import LLMResponse, Usage
+
+logger = logging.getLogger(__name__)
+
+
+class GeminiClient(BaseAIClient):
+    """
+    Google Gemini-specific implementation of the BaseAIClient.
+
+    This class implements the BaseAIClient interface for Google's Gemini API,
+    handling both text-only and multimodal (text + images) requests.
+
+    Key features:
+    - Full support for multimodal content via Gemini Pro Vision models
+    - Support for Gemini-specific parameters like top_k, top_p
+    - Structured output via response schema
+    """
+
+    PROVIDER_ID = "genai"
+    SUPPORTS_MULTIMODAL = True
+
+    def _init_client(self):
+        """Initialize Gemini API client with the provided API key."""
+        self.api_client = genai.Client(api_key=self.api_key)
+
+    def _prepare_content_with_images(self, prompt: str, images: List[str]) -> List[Any]:
+        """
+        Prepare Gemini content with text and images.
+
+        Args:
+            prompt: The text prompt
+            images: List of image paths/URLs
+
+        Returns:
+            List of content parts for Gemini API
+        """
+        contents = [prompt]
+
+        # Add images if any
+        for resource in images:
+            try:
+                if self.is_url(resource):
+                    # For URLs, fetch the image
+                    response = requests.get(resource)
+                    if response.status_code == 200:
+                        image_data = response.content
+                    else:
+                        logger.error(
+                            f"Failed to fetch image from URL {resource}: {response.status_code}"
+                        )
+                        continue
+                else:
+                    # For local files, read the image
+                    with open(resource, "rb") as f:
+                        image_data = f.read()
+
+                # Detect MIME type from file extension
+                from .utils import detect_image_mime_type
+
+                mime_type = detect_image_mime_type(resource)
+
+                # Create image part
+                image_part = Part(
+                    inline_data={
+                        "mime_type": mime_type,
+                        "data": base64.b64encode(image_data).decode("utf-8"),
+                    }
+                )
+                contents.append(image_part)
+            except Exception as e:
+                logger.error(f"Error processing image {resource}: {e}")
+
+        return contents
+
+    @staticmethod
+    def _remove_defaults_from_schema(schema):
+        """Recursively remove default values from JSON schema (for GenAI compatibility)."""
+        if isinstance(schema, dict):
+            if "default" in schema:
+                del schema["default"]
+            for key, value in schema.items():
+                if isinstance(value, (dict, list)):
+                    GeminiClient._remove_defaults_from_schema(value)
+        elif isinstance(schema, list):
+            for item in schema:
+                if isinstance(item, (dict, list)):
+                    GeminiClient._remove_defaults_from_schema(item)
+
+    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 Gemini model and get the response.
+
+        Args:
+            model: The Gemini model identifier (e.g., "gemini-pro", "gemini-pro-vision")
+            prompt: The text prompt to send
+            images: List of image paths/URLs
+            system_prompt: System prompt (prepended to prompt for Gemini)
+            response_format: Optional Pydantic model for structured output
+            **kwargs: Additional Gemini-specific parameters
+
+        Returns:
+            LLMResponse object with the provider's response
+        """
+        # Prepend system prompt to user prompt for Gemini
+        full_prompt = f"{system_prompt}\n\n{prompt}" if system_prompt else prompt
+
+        # Prepare content with images
+        contents = self._prepare_content_with_images(full_prompt, images)
+
+        # Build generation config
+        generation_config = {}
+
+        # Extract Gemini-specific parameters
+        optional_params = [
+            "temperature",
+            "top_p",
+            "top_k",
+            "max_output_tokens",
+            "candidate_count",
+            "stop_sequences",
+        ]
+        for param in optional_params:
+            value = kwargs.get(param, self.settings.get(param))
+            if value is not None:
+                generation_config[param] = value
+
+        # Handle structured output
+        if response_format and hasattr(response_format, "model_json_schema"):
+            schema = response_format.model_json_schema()
+            # GenAI doesn't support default values in schema
+            self._remove_defaults_from_schema(schema)
+
+            generation_config["response_mime_type"] = "application/json"
+            generation_config["response_schema"] = schema
+
+        # Generate content
+        # Try different approaches based on what parameters are available
+        try:
+            if generation_config:
+                # Try passing config as a GenerateContentConfig object
+                config = GenerateContentConfig(**generation_config)
+                raw_response = self.api_client.models.generate_content(
+                    model=model, contents=contents, config=config
+                )
+            else:
+                raw_response = self.api_client.models.generate_content(
+                    model=model, contents=contents
+                )
+        except TypeError as e:
+            # If config parameter doesn't work, try passing generation_config directly
+            if "config" in str(e):
+                logger.warning(f"Config parameter not accepted, trying alternative API: {e}")
+                if generation_config:
+                    raw_response = self.api_client.models.generate_content(
+                        model=model, contents=contents, generation_config=generation_config
+                    )
+                else:
+                    raw_response = self.api_client.models.generate_content(
+                        model=model, contents=contents
+                    )
+            else:
+                raise
+
+        return self._create_response_from_raw(raw_response, model, response_format)
+
+    def _create_response_from_raw(
+        self, raw_response: Any, model: str, response_format: Optional[Any]
+    ) -> LLMResponse:
+        """
+        Create LLMResponse from Gemini raw response.
+
+        Args:
+            raw_response: Raw Gemini response object
+            model: Model identifier
+            response_format: Pydantic model if structured output was requested
+
+        Returns:
+            LLMResponse object
+        """
+        text = raw_response.text if hasattr(raw_response, "text") else ""
+
+        # If response_format was provided, try to validate
+        if response_format and hasattr(response_format, "model_json_schema") and text:
+            try:
+                json_data = json.loads(text)
+                validated = response_format(**json_data)
+                text = validated.model_dump_json()
+            except Exception as e:
+                logger.warning(f"Failed to validate Gemini structured response: {e}")
+                # Keep original text
+
+        usage = Usage()
+        if hasattr(raw_response, "usage_metadata"):
+            usage = Usage(
+                input_tokens=raw_response.usage_metadata.prompt_token_count,
+                output_tokens=raw_response.usage_metadata.candidates_token_count,
+                total_tokens=raw_response.usage_metadata.total_token_count,
+            )
+
+        # Determine finish reason
+        finish_reason = "unknown"
+        if hasattr(raw_response, "candidates") and raw_response.candidates:
+            candidate = raw_response.candidates[0]
+            if hasattr(candidate, "finish_reason"):
+                # Extract the value from the enum (e.g., FinishReason.STOP -> 'STOP')
+                fr = candidate.finish_reason
+                if hasattr(fr, "value"):
+                    finish_reason = fr.value
+                elif hasattr(fr, "name"):
+                    finish_reason = fr.name
+                else:
+                    finish_reason = str(fr)
+
+        return LLMResponse(
+            text=text,
+            model=model,
+            provider=self.PROVIDER_ID,
+            finish_reason=finish_reason,
+            usage=usage,
+            raw_response=raw_response,
+        )
+
+    def get_model_list(self) -> List[Tuple[str, Optional[str]]]:
+        """
+        Get a list of available models from Gemini.
+
+        Returns:
+            List of tuples (model_id, created_date)
+        """
+        model_list = []
+
+        try:
+            raw_list = self.api_client.models.list()
+            for model in raw_list:
+                model_name = model.name if hasattr(model, "name") else str(model)
+                # Remove 'models/' prefix if present
+                if model_name.startswith("models/"):
+                    model_name = model_name[7:]
+                model_list.append((model_name, None))
+        except Exception as e:
+            logger.error(f"Error listing Gemini models: {e}")
+
+        return model_list

ai_client/mistral_client.py

@@ -0,0 +1,191 @@
+"""
+Mistral-specific implementation of the BaseAIClient.
+
+This module provides the MistralClient class, which implements the BaseAIClient
+interface specifically for Mistral's API, supporting both text-only and multimodal
+interactions.
+"""
+
+import base64
+import json
+import logging
+from typing import List, Tuple, Any, Optional
+
+from mistralai import Mistral
+
+from .base_client import BaseAIClient
+from .response import LLMResponse, Usage
+
+logger = logging.getLogger(__name__)
+
+
+class MistralClient(BaseAIClient):
+    """
+    Mistral-specific implementation of the BaseAIClient.
+
+    This class implements the BaseAIClient interface for Mistral's API,
+    supporting text-only and multimodal requests via the chat completion API.
+
+    Key features:
+    - Integration with Mistral's chat completion API
+    - Support for multimodal content (text + images)
+    - Support for Mistral-specific parameters
+    - Structured output via JSON mode
+    """
+
+    PROVIDER_ID = "mistral"
+    SUPPORTS_MULTIMODAL = True  # Mistral supports images
+
+    def _init_client(self):
+        """Initialize the Mistral client with the provided API key."""
+        self.api_client = Mistral(api_key=self.api_key)
+
+    def _prepare_content_with_images(self, prompt: str, images: List[str]) -> List[dict]:
+        """
+        Prepare Mistral content with text and images.
+
+        Args:
+            prompt: The text prompt
+            images: List of image paths/URLs
+
+        Returns:
+            List of content blocks for Mistral API
+        """
+        content = [{"type": "text", "text": prompt}]
+
+        # Add images if any
+        for resource in images:
+            try:
+                if self.is_url(resource):
+                    # For URLs, use directly
+                    data_uri = resource
+                else:
+                    # For local files, encode as base64
+                    with open(resource, "rb") as image_file:
+                        base64_image = base64.b64encode(image_file.read()).decode("utf-8")
+
+                        # Detect MIME type from file extension
+                        from .utils import detect_image_mime_type
+
+                        mime_type = detect_image_mime_type(resource)
+
+                        data_uri = f"data:{mime_type};base64,{base64_image}"
+
+                content.append({"type": "image_url", "image_url": {"url": data_uri}})
+            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 Mistral model and get the response.
+
+        Args:
+            model: The Mistral model identifier
+            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 Mistral-specific parameters
+
+        Returns:
+            LLMResponse object with the provider's response
+        """
+        # Prepare content with images
+        content = self._prepare_content_with_images(prompt, images)
+
+        # Build messages
+        messages = [{"role": "user", "content": content}]
+
+        # Add system message if provided
+        if system_prompt:
+            messages.insert(0, {"role": "system", "content": system_prompt})
+
+        params = {"messages": messages, "model": model}
+
+        # Handle structured output
+        if response_format and hasattr(response_format, "model_json_schema"):
+            schema = response_format.model_json_schema()
+            schema_prompt = (
+                f"\n\nReturn a JSON response matching this exact schema: {json.dumps(schema)}"
+            )
+            messages[-1]["content"] = prompt + schema_prompt
+            params["response_format"] = {"type": "json_object"}
+
+        # Send the request
+        raw_response = self.api_client.chat.complete(**params)
+
+        return self._create_response_from_raw(raw_response, model, response_format)
+
+    def _create_response_from_raw(
+        self, raw_response: Any, model: str, response_format: Optional[Any]
+    ) -> LLMResponse:
+        """
+        Create LLMResponse from Mistral raw response.
+
+        Args:
+            raw_response: Raw Mistral response object
+            model: Model identifier
+            response_format: Pydantic model if structured output was requested
+
+        Returns:
+            LLMResponse object
+        """
+        choice = raw_response.choices[0]
+        text = choice.message.content if hasattr(choice.message, "content") else ""
+
+        # If response_format was provided, try to validate
+        if response_format and hasattr(response_format, "model_json_schema") and text:
+            try:
+                json_data = json.loads(text)
+                validated = response_format(**json_data)
+                text = validated.model_dump_json()
+            except Exception as e:
+                logger.warning(f"Failed to validate Mistral structured response: {e}")
+                # Keep original text
+
+        usage = Usage()
+        if hasattr(raw_response, "usage") and raw_response.usage:
+            usage = Usage(
+                input_tokens=raw_response.usage.prompt_tokens,
+                output_tokens=raw_response.usage.completion_tokens,
+                total_tokens=raw_response.usage.total_tokens,
+            )
+
+        finish_reason = choice.finish_reason if hasattr(choice, "finish_reason") else "unknown"
+
+        return LLMResponse(
+            text=text,
+            model=model,
+            provider=self.PROVIDER_ID,
+            finish_reason=finish_reason,
+            usage=usage,
+            raw_response=raw_response,
+        )
+
+    def get_model_list(self) -> List[Tuple[str, Optional[str]]]:
+        """
+        Get a list of available models from Mistral.
+
+        Returns:
+            List of tuples (model_id, created_date)
+        """
+        if self.api_client is None:
+            raise ValueError("Mistral client is not initialized.")
+
+        model_list = []
+        raw_list = self.api_client.models.list()
+
+        for model in raw_list:
+            model_list.append((model.id, None))
+
+        return model_list