causaliq-knowledge 0.1.0__py3-none-any.whl → 0.2.0__py3-none-any.whl

causaliq_knowledge/llm/base_client.py

@@ -0,0 +1,220 @@
+"""Abstract base class for LLM clients.
+
+This module defines the common interface that all LLM vendor clients
+must implement. This provides a consistent API regardless of the
+underlying LLM provider.
+"""
+
+import json
+import logging
+from abc import ABC, abstractmethod
+from dataclasses import dataclass, field
+from typing import Any, Dict, List, Optional
+
+logger = logging.getLogger(__name__)
+
+
+@dataclass
+class LLMConfig:
+    """Base configuration for all LLM clients.
+
+    This dataclass defines common configuration options shared by all
+    LLM provider clients. Vendor-specific clients may extend this with
+    additional options.
+
+    Attributes:
+        model: Model identifier (provider-specific format).
+        temperature: Sampling temperature (0.0=deterministic, 1.0=creative).
+        max_tokens: Maximum tokens in the response.
+        timeout: Request timeout in seconds.
+        api_key: API key for authentication (optional, can use env var).
+    """
+
+    model: str
+    temperature: float = 0.1
+    max_tokens: int = 500
+    timeout: float = 30.0
+    api_key: Optional[str] = None
+
+
+@dataclass
+class LLMResponse:
+    """Standard response from any LLM client.
+
+    This dataclass provides a unified response format across all LLM providers,
+    abstracting away provider-specific response structures.
+
+    Attributes:
+        content: The text content of the response.
+        model: The model that generated the response.
+        input_tokens: Number of input/prompt tokens used.
+        output_tokens: Number of output/completion tokens generated.
+        cost: Estimated cost of the request (if available).
+        raw_response: The original provider-specific response (for debugging).
+    """
+
+    content: str
+    model: str
+    input_tokens: int = 0
+    output_tokens: int = 0
+    cost: float = 0.0
+    raw_response: Optional[Dict[str, Any]] = field(default=None, repr=False)
+
+    def parse_json(self) -> Optional[Dict[str, Any]]:
+        """Parse content as JSON, handling common formatting issues.
+
+        LLMs sometimes wrap JSON in markdown code blocks. This method
+        handles those cases and attempts to extract valid JSON.
+
+        Returns:
+            Parsed JSON as dict, or None if parsing fails.
+        """
+        try:
+            # Clean up potential markdown code blocks
+            text = self.content.strip()
+            if text.startswith("```json"):
+                text = text[7:]
+            elif text.startswith("```"):
+                text = text[3:]
+            if text.endswith("```"):
+                text = text[:-3]
+
+            return json.loads(text.strip())  # type: ignore[no-any-return]
+        except json.JSONDecodeError as e:
+            logger.warning(f"Failed to parse JSON response: {e}")
+            return None
+
+
+class BaseLLMClient(ABC):
+    """Abstract base class for LLM clients.
+
+    All LLM vendor clients (OpenAI, Anthropic, Groq, Gemini, Llama, etc.)
+    must implement this interface to ensure consistent behavior across
+    the codebase.
+
+    This abstraction allows:
+    - Easy addition of new LLM providers
+    - Consistent API for all providers
+    - Provider-agnostic code in higher-level modules
+    - Simplified testing with mock implementations
+
+    Example:
+        >>> class MyClient(BaseLLMClient):
+        ...     def completion(self, messages, **kwargs):
+        ...         # Implementation here
+        ...         pass
+        ...
+        >>> client = MyClient(config)
+        >>> msgs = [{"role": "user", "content": "Hello"}]
+        >>> response = client.completion(msgs)
+        >>> print(response.content)
+    """
+
+    @abstractmethod
+    def __init__(self, config: LLMConfig) -> None:
+        """Initialize the client with configuration.
+
+        Args:
+            config: Configuration for the LLM client.
+        """
+        pass
+
+    @property
+    @abstractmethod
+    def provider_name(self) -> str:
+        """Return the name of the LLM provider.
+
+        Returns:
+            Provider name (e.g., "openai", "anthropic", "groq").
+        """
+        pass
+
+    @abstractmethod
+    def completion(
+        self, messages: List[Dict[str, str]], **kwargs: Any
+    ) -> LLMResponse:
+        """Make a chat completion request.
+
+        This is the core method that sends a request to the LLM provider
+        and returns a standardized response.
+
+        Args:
+            messages: List of message dicts with "role" and "content" keys.
+                Roles can be: "system", "user", "assistant".
+            **kwargs: Provider-specific options (temperature, max_tokens, etc.)
+                that override the config defaults.
+
+        Returns:
+            LLMResponse with the generated content and metadata.
+
+        Raises:
+            ValueError: If the API request fails or returns an error.
+        """
+        pass
+
+    def complete_json(
+        self, messages: List[Dict[str, str]], **kwargs: Any
+    ) -> tuple[Optional[Dict[str, Any]], LLMResponse]:
+        """Make a completion request and parse response as JSON.
+
+        Convenience method that calls completion() and attempts to parse
+        the response content as JSON.
+
+        Args:
+            messages: List of message dicts with "role" and "content" keys.
+            **kwargs: Provider-specific options passed to completion().
+
+        Returns:
+            Tuple of (parsed JSON dict or None, raw LLMResponse).
+        """
+        response = self.completion(messages, **kwargs)
+        parsed = response.parse_json()
+        return parsed, response
+
+    @property
+    @abstractmethod
+    def call_count(self) -> int:
+        """Return the number of API calls made by this client.
+
+        Returns:
+            Total number of completion calls made.
+        """
+        pass
+
+    @abstractmethod
+    def is_available(self) -> bool:
+        """Check if the LLM provider is available and configured.
+
+        This method checks whether the client can make API calls:
+        - For cloud providers: checks if API key is set
+        - For local providers: checks if server is running
+
+        Returns:
+            True if the provider is available and ready for requests.
+        """
+        pass
+
+    @abstractmethod
+    def list_models(self) -> List[str]:
+        """List available models from the provider.
+
+        Queries the provider's API to get the list of models accessible
+        with the current API key or configuration. Results are filtered
+        by the user's subscription/access level.
+
+        Returns:
+            List of model identifiers available for use.
+
+        Raises:
+            ValueError: If the API request fails.
+        """
+        pass
+
+    @property
+    def model_name(self) -> str:
+        """Return the model name being used.
+
+        Returns:
+            Model identifier string.
+        """
+        return getattr(self, "config", LLMConfig(model="unknown")).model

causaliq_knowledge/llm/deepseek_client.py

@@ -0,0 +1,108 @@
+"""Direct DeepSeek API client - OpenAI-compatible API."""
+
+import logging
+import os
+from dataclasses import dataclass
+from typing import Dict, List, Optional
+
+from causaliq_knowledge.llm.openai_compat_client import (
+    OpenAICompatClient,
+    OpenAICompatConfig,
+)
+
+logger = logging.getLogger(__name__)
+
+
+@dataclass
+class DeepSeekConfig(OpenAICompatConfig):
+    """Configuration for DeepSeek API client.
+
+    Extends OpenAICompatConfig with DeepSeek-specific defaults.
+
+    Attributes:
+        model: DeepSeek model identifier (default: deepseek-chat).
+        temperature: Sampling temperature (default: 0.1).
+        max_tokens: Maximum response tokens (default: 500).
+        timeout: Request timeout in seconds (default: 30.0).
+        api_key: DeepSeek API key (falls back to DEEPSEEK_API_KEY env var).
+    """
+
+    model: str = "deepseek-chat"
+    temperature: float = 0.1
+    max_tokens: int = 500
+    timeout: float = 30.0
+    api_key: Optional[str] = None
+
+    def __post_init__(self) -> None:
+        """Set API key from environment if not provided."""
+        if self.api_key is None:
+            self.api_key = os.getenv("DEEPSEEK_API_KEY")
+        if not self.api_key:
+            raise ValueError(
+                "DEEPSEEK_API_KEY environment variable is required"
+            )
+
+
+class DeepSeekClient(OpenAICompatClient):
+    """Direct DeepSeek API client.
+
+    DeepSeek uses an OpenAI-compatible API, making integration straightforward.
+    Known for excellent reasoning capabilities (R1) at low cost.
+
+    Available models:
+        - deepseek-chat: General purpose (DeepSeek-V3)
+        - deepseek-reasoner: Advanced reasoning (DeepSeek-R1)
+
+    Example:
+        >>> config = DeepSeekConfig(model="deepseek-chat")
+        >>> client = DeepSeekClient(config)
+        >>> msgs = [{"role": "user", "content": "Hello"}]
+        >>> response = client.completion(msgs)
+        >>> print(response.content)
+    """
+
+    BASE_URL = "https://api.deepseek.com"
+    PROVIDER_NAME = "deepseek"
+    ENV_VAR = "DEEPSEEK_API_KEY"
+
+    def __init__(self, config: Optional[DeepSeekConfig] = None) -> None:
+        """Initialize DeepSeek client.
+
+        Args:
+            config: DeepSeek configuration. If None, uses defaults with
+                   API key from DEEPSEEK_API_KEY environment variable.
+        """
+        super().__init__(config)
+
+    def _default_config(self) -> DeepSeekConfig:
+        """Return default DeepSeek configuration."""
+        return DeepSeekConfig()
+
+    def _get_pricing(self) -> Dict[str, Dict[str, float]]:
+        """Return DeepSeek pricing per 1M tokens.
+
+        Returns:
+            Dict mapping model prefixes to input/output costs.
+        """
+        # DeepSeek pricing as of Jan 2025
+        # Note: Cache hits are much cheaper but we use regular pricing
+        return {
+            "deepseek-reasoner": {"input": 0.55, "output": 2.19},
+            "deepseek-chat": {"input": 0.14, "output": 0.28},
+        }
+
+    def _filter_models(self, models: List[str]) -> List[str]:
+        """Filter to DeepSeek chat models only.
+
+        Args:
+            models: List of all model IDs from API.
+
+        Returns:
+            Filtered list of DeepSeek models.
+        """
+        filtered = []
+        for model_id in models:
+            # Include deepseek chat and reasoner models
+            if model_id.startswith("deepseek-"):
+                filtered.append(model_id)
+        return filtered

causaliq_knowledge/llm/gemini_client.py

@@ -1,6 +1,5 @@
 """Direct Google Gemini API client - clean and reliable."""
 
-import json
 import logging
 import os
 from dataclasses import dataclass
@@ -8,12 +7,28 @@ from typing import Any, Dict, List, Optional
 
 import httpx
 
+from causaliq_knowledge.llm.base_client import (
+    BaseLLMClient,
+    LLMConfig,
+    LLMResponse,
+)
+
 logger = logging.getLogger(__name__)
 
 
 @dataclass
-class GeminiConfig:
-    """Configuration for Gemini API client."""
+class GeminiConfig(LLMConfig):
+    """Configuration for Gemini API client.
+
+    Extends LLMConfig with Gemini-specific defaults.
+
+    Attributes:
+        model: Gemini model identifier (default: gemini-2.5-flash).
+        temperature: Sampling temperature (default: 0.1).
+        max_tokens: Maximum response tokens (default: 500).
+        timeout: Request timeout in seconds (default: 30.0).
+        api_key: Gemini API key (falls back to GEMINI_API_KEY env var).
+    """
 
     model: str = "gemini-2.5-flash"
     temperature: float = 0.1
@@ -29,48 +44,52 @@ class GeminiConfig:
             raise ValueError("GEMINI_API_KEY environment variable is required")
 
 
-@dataclass
-class GeminiResponse:
-    """Response from Gemini API."""
-
-    content: str
-    model: str
-    input_tokens: int = 0
-    output_tokens: int = 0
-    cost: float = 0.0  # Gemini free tier
-    raw_response: Optional[Dict] = None
-
-    def parse_json(self) -> Optional[Dict[str, Any]]:
-        """Parse content as JSON, handling common formatting issues."""
-        try:
-            # Clean up potential markdown code blocks
-            text = self.content.strip()
-            if text.startswith("```json"):
-                text = text[7:]
-            elif text.startswith("```"):
-                text = text[3:]
-            if text.endswith("```"):
-                text = text[:-3]
-
-            return json.loads(text.strip())  # type: ignore[no-any-return]
-        except json.JSONDecodeError:
-            return None
+class GeminiClient(BaseLLMClient):
+    """Direct Gemini API client.
 
+    Implements the BaseLLMClient interface for Google's Gemini API.
+    Uses httpx for HTTP requests.
 
-class GeminiClient:
-    """Direct Gemini API client."""
+    Example:
+        >>> config = GeminiConfig(model="gemini-2.5-flash")
+        >>> client = GeminiClient(config)
+        >>> msgs = [{"role": "user", "content": "Hello"}]
+        >>> response = client.completion(msgs)
+        >>> print(response.content)
+    """
 
     BASE_URL = "https://generativelanguage.googleapis.com/v1beta/models"
 
-    def __init__(self, config: Optional[GeminiConfig] = None):
-        """Initialize Gemini client."""
+    def __init__(self, config: Optional[GeminiConfig] = None) -> None:
+        """Initialize Gemini client.
+
+        Args:
+            config: Gemini configuration. If None, uses defaults with
+                   API key from GEMINI_API_KEY environment variable.
+        """
         self.config = config or GeminiConfig()
         self._total_calls = 0
 
+    @property
+    def provider_name(self) -> str:
+        """Return the provider name."""
+        return "gemini"
+
     def completion(
         self, messages: List[Dict[str, str]], **kwargs: Any
-    ) -> GeminiResponse:
-        """Make a chat completion request to Gemini."""
+    ) -> LLMResponse:
+        """Make a chat completion request to Gemini.
+
+        Args:
+            messages: List of message dicts with "role" and "content" keys.
+            **kwargs: Override config options (temperature, max_tokens).
+
+        Returns:
+            LLMResponse with the generated content and metadata.
+
+        Raises:
+            ValueError: If the API request fails.
+        """
 
         # Convert OpenAI-style messages to Gemini format
         contents = []
@@ -158,7 +177,7 @@ class GeminiClient:
                     f"Gemini response: {input_tokens} in, {output_tokens} out"
                 )
 
-                return GeminiResponse(
+                return LLMResponse(
                     content=content,
                     model=self.config.model,
                     input_tokens=input_tokens,
@@ -191,13 +210,72 @@ class GeminiClient:
 
     def complete_json(
         self, messages: List[Dict[str, str]], **kwargs: Any
-    ) -> tuple[Optional[Dict[str, Any]], GeminiResponse]:
-        """Make a completion request and parse response as JSON."""
+    ) -> tuple[Optional[Dict[str, Any]], LLMResponse]:
+        """Make a completion request and parse response as JSON.
+
+        Args:
+            messages: List of message dicts with "role" and "content" keys.
+            **kwargs: Override config options passed to completion().
+
+        Returns:
+            Tuple of (parsed JSON dict or None, raw LLMResponse).
+        """
         response = self.completion(messages, **kwargs)
         parsed = response.parse_json()
         return parsed, response
 
     @property
     def call_count(self) -> int:
-        """Number of API calls made."""
+        """Return the number of API calls made."""
         return self._total_calls
+
+    def is_available(self) -> bool:
+        """Check if Gemini API is available.
+
+        Returns:
+            True if GEMINI_API_KEY is configured.
+        """
+        return bool(self.config.api_key)
+
+    def list_models(self) -> List[str]:
+        """List available models from Gemini API.
+
+        Queries the Gemini API to get models accessible with the current
+        API key. Filters to only include models that support generateContent.
+
+        Returns:
+            List of model identifiers (e.g., ['gemini-2.5-flash', ...]).
+
+        Raises:
+            ValueError: If the API request fails.
+        """
+        try:
+            with httpx.Client(timeout=self.config.timeout) as client:
+                response = client.get(
+                    f"{self.BASE_URL}?key={self.config.api_key}",
+                )
+                response.raise_for_status()
+                data = response.json()
+
+                # Filter to models that support text generation
+                models = []
+                for model in data.get("models", []):
+                    methods = model.get("supportedGenerationMethods", [])
+                    if "generateContent" not in methods:
+                        continue
+                    # Extract model name (remove 'models/' prefix)
+                    name = model.get("name", "").replace("models/", "")
+                    # Skip embedding and TTS models
+                    if any(x in name.lower() for x in ["embed", "tts", "aqa"]):
+                        continue
+                    models.append(name)
+
+                return sorted(models)
+
+        except httpx.HTTPStatusError as e:
+            raise ValueError(
+                f"Gemini API error: {e.response.status_code} - "
+                f"{e.response.text}"
+            )
+        except Exception as e:
+            raise ValueError(f"Failed to list Gemini models: {e}")