sentienceapi 0.95.0__py3-none-any.whl

sentience/llm_provider_utils.py

@@ -0,0 +1,120 @@
+"""
+LLM Provider utility functions for common initialization and error handling.
+
+This module provides helper functions to reduce duplication across LLM provider implementations.
+"""
+
+import os
+from collections.abc import Callable
+from typing import Any, Optional, TypeVar
+
+T = TypeVar("T")
+
+
+def require_package(
+    package_name: str,
+    module_name: str,
+    class_name: str | None = None,
+    install_command: str | None = None,
+) -> Any:
+    """
+    Import a package with consistent error handling.
+
+    Args:
+        package_name: Name of the package (for error messages)
+        module_name: Module name to import (e.g., "openai", "google.generativeai")
+        class_name: Optional class name to import from module (e.g., "OpenAI")
+        install_command: Installation command (defaults to "pip install {package_name}")
+
+    Returns:
+        Imported module or class
+
+    Raises:
+        ImportError: If package is not installed, with helpful message
+
+    Example:
+        >>> OpenAI = require_package("openai", "openai", "OpenAI", "pip install openai")
+        >>> genai = require_package("google-generativeai", "google.generativeai", install_command="pip install google-generativeai")
+    """
+    if install_command is None:
+        install_command = f"pip install {package_name}"
+
+    try:
+        if class_name:
+            # Import specific class: from module import class
+            module = __import__(module_name, fromlist=[class_name])
+            return getattr(module, class_name)
+        else:
+            # Import entire module
+            return __import__(module_name)
+    except ImportError:
+        raise ImportError(f"{package_name} package not installed. Install with: {install_command}")
+
+
+def get_api_key_from_env(
+    env_vars: list[str],
+    api_key: str | None = None,
+) -> str | None:
+    """
+    Get API key from parameter or environment variables.
+
+    Args:
+        env_vars: List of environment variable names to check (in order)
+        api_key: Optional API key parameter (takes precedence)
+
+    Returns:
+        API key string or None if not found
+
+    Example:
+        >>> key = get_api_key_from_env(["OPENAI_API_KEY"], api_key="sk-...")
+        >>> # Returns "sk-..." if provided, otherwise checks OPENAI_API_KEY env var
+    """
+    if api_key:
+        return api_key
+
+    for env_var in env_vars:
+        value = os.getenv(env_var)
+        if value:
+            return value
+
+    return None
+
+
+def handle_provider_error(
+    error: Exception,
+    provider_name: str,
+    operation: str = "operation",
+) -> None:
+    """
+    Standardize error handling for LLM provider operations.
+
+    Args:
+        error: Exception that occurred
+        provider_name: Name of the provider (e.g., "OpenAI", "Anthropic")
+        operation: Description of the operation that failed
+
+    Raises:
+        RuntimeError: With standardized error message
+
+    Example:
+        >>> try:
+        ...     response = client.chat.completions.create(...)
+        ... except Exception as e:
+        ...     handle_provider_error(e, "OpenAI", "generate response")
+    """
+    error_msg = str(error)
+    if "api key" in error_msg.lower() or "authentication" in error_msg.lower():
+        raise RuntimeError(
+            f"{provider_name} API key is invalid or missing. "
+            f"Please check your API key configuration."
+        ) from error
+    elif "rate limit" in error_msg.lower() or "429" in error_msg:
+        raise RuntimeError(
+            f"{provider_name} rate limit exceeded. Please try again later."
+        ) from error
+    elif "model" in error_msg.lower() and "not found" in error_msg.lower():
+        raise RuntimeError(
+            f"{provider_name} model not found. Please check the model name."
+        ) from error
+    else:
+        raise RuntimeError(f"{provider_name} {operation} failed: {error_msg}") from error

sentience/llm_response_builder.py

@@ -0,0 +1,153 @@
+"""
+LLM Response building utilities for consistent response construction.
+
+This module provides helper functions for building LLMResponse objects
+from various provider API responses.
+"""
+
+from typing import Any, Optional
+
+# Import LLMResponse here to avoid circular dependency
+# We import it inside functions to break the cycle
+
+
+class LLMResponseBuilder:
+    """
+    Helper for building LLMResponse objects with consistent structure.
+
+    Provides static methods for building responses from different provider formats.
+    """
+
+    @staticmethod
+    def from_openai_format(
+        content: str,
+        prompt_tokens: int | None = None,
+        completion_tokens: int | None = None,
+        total_tokens: int | None = None,
+        model_name: str | None = None,
+        finish_reason: str | None = None,
+    ) -> "LLMResponse":
+        """
+        Build LLMResponse from OpenAI-style API response.
+
+        Args:
+            content: Response text content
+            prompt_tokens: Number of prompt tokens
+            completion_tokens: Number of completion tokens
+            total_tokens: Total tokens (or sum of prompt + completion)
+            model_name: Model identifier
+            finish_reason: Finish reason (stop, length, etc.)
+
+        Returns:
+            LLMResponse object
+        """
+        from .llm_provider import LLMResponse  # Import here to avoid circular dependency
+
+        return LLMResponse(
+            content=content,
+            prompt_tokens=prompt_tokens,
+            completion_tokens=completion_tokens,
+            total_tokens=total_tokens
+            or (
+                (prompt_tokens + completion_tokens) if prompt_tokens and completion_tokens else None
+            ),
+            model_name=model_name,
+            finish_reason=finish_reason,
+        )
+
+    @staticmethod
+    def from_anthropic_format(
+        content: str,
+        input_tokens: int | None = None,
+        output_tokens: int | None = None,
+        model_name: str | None = None,
+        stop_reason: str | None = None,
+    ) -> "LLMResponse":
+        """
+        Build LLMResponse from Anthropic-style API response.
+
+        Args:
+            content: Response text content
+            input_tokens: Number of input tokens
+            output_tokens: Number of output tokens
+            model_name: Model identifier
+            stop_reason: Stop reason (end_turn, max_tokens, etc.)
+
+        Returns:
+            LLMResponse object
+        """
+        from .llm_provider import LLMResponse  # Import here to avoid circular dependency
+
+        return LLMResponse(
+            content=content,
+            prompt_tokens=input_tokens,
+            completion_tokens=output_tokens,
+            total_tokens=(input_tokens + output_tokens) if input_tokens and output_tokens else None,
+            model_name=model_name,
+            finish_reason=stop_reason,
+        )
+
+    @staticmethod
+    def from_gemini_format(
+        content: str,
+        prompt_tokens: int | None = None,
+        completion_tokens: int | None = None,
+        total_tokens: int | None = None,
+        model_name: str | None = None,
+    ) -> "LLMResponse":
+        """
+        Build LLMResponse from Gemini-style API response.
+
+        Args:
+            content: Response text content
+            prompt_tokens: Number of prompt tokens
+            completion_tokens: Number of completion tokens
+            total_tokens: Total tokens
+            model_name: Model identifier
+
+        Returns:
+            LLMResponse object
+        """
+        from .llm_provider import LLMResponse  # Import here to avoid circular dependency
+
+        return LLMResponse(
+            content=content,
+            prompt_tokens=prompt_tokens,
+            completion_tokens=completion_tokens,
+            total_tokens=total_tokens
+            or (
+                (prompt_tokens + completion_tokens) if prompt_tokens and completion_tokens else None
+            ),
+            model_name=model_name,
+            finish_reason=None,  # Gemini uses different finish reason format
+        )
+
+    @staticmethod
+    def from_local_format(
+        content: str,
+        prompt_tokens: int,
+        completion_tokens: int,
+        model_name: str,
+    ) -> "LLMResponse":
+        """
+        Build LLMResponse from local model generation.
+
+        Args:
+            content: Response text content
+            prompt_tokens: Number of prompt tokens
+            completion_tokens: Number of completion tokens
+            model_name: Model identifier
+
+        Returns:
+            LLMResponse object
+        """
+        from .llm_provider import LLMResponse  # Import here to avoid circular dependency
+
+        return LLMResponse(
+            content=content,
+            prompt_tokens=prompt_tokens,
+            completion_tokens=completion_tokens,
+            total_tokens=prompt_tokens + completion_tokens,
+            model_name=model_name,
+            finish_reason=None,
+        )