sentienceapi 0.90.12__py3-none-any.whl → 0.92.2__py3-none-any.whl

sentience/llm_provider.py

@@ -1,3 +1,5 @@
+from typing import Optional
+
 """
 LLM Provider abstraction layer for Sentience SDK
 Enables "Bring Your Own Brain" (BYOB) pattern - plug in any LLM provider
@@ -6,6 +8,9 @@ Enables "Bring Your Own Brain" (BYOB) pattern - plug in any LLM provider
 from abc import ABC, abstractmethod
 from dataclasses import dataclass
 
+from .llm_provider_utils import get_api_key_from_env, handle_provider_error, require_package
+from .llm_response_builder import LLMResponseBuilder
+
 
 @dataclass
 class LLMResponse:
@@ -31,6 +36,15 @@ class LLMProvider(ABC):
     - Any other completion API
     """
 
+    def __init__(self, model: str):
+        """
+        Initialize LLM provider with model name.
+
+        Args:
+            model: Model identifier (e.g., "gpt-4o", "claude-3-sonnet")
+        """
+        self._model_name = model
+
     @abstractmethod
     def generate(self, system_prompt: str, user_prompt: str, **kwargs) -> LLMResponse:
         """
@@ -95,13 +109,16 @@ class OpenAIProvider(LLMProvider):
             base_url: Custom API base URL (for compatible APIs)
             organization: OpenAI organization ID
         """
-        try:
-            from openai import OpenAI
-        except ImportError:
-            raise ImportError("OpenAI package not installed. Install with: pip install openai")
+        super().__init__(model)  # Initialize base class with model name
+
+        OpenAI = require_package(
+            "openai",
+            "openai",
+            "OpenAI",
+            "pip install openai",
+        )
 
         self.client = OpenAI(api_key=api_key, base_url=base_url, organization=organization)
-        self._model_name = model
 
     def generate(
         self,
@@ -148,12 +165,15 @@ class OpenAIProvider(LLMProvider):
         api_params.update(kwargs)
 
         # Call OpenAI API
-        response = self.client.chat.completions.create(**api_params)
+        try:
+            response = self.client.chat.completions.create(**api_params)
+        except Exception as e:
+            handle_provider_error(e, "OpenAI", "generate response")
 
         choice = response.choices[0]
         usage = response.usage
 
-        return LLMResponse(
+        return LLMResponseBuilder.from_openai_format(
             content=choice.message.content,
             prompt_tokens=usage.prompt_tokens if usage else None,
             completion_tokens=usage.completion_tokens if usage else None,
@@ -191,15 +211,16 @@ class AnthropicProvider(LLMProvider):
             api_key: Anthropic API key (or set ANTHROPIC_API_KEY env var)
             model: Model name (claude-3-opus, claude-3-sonnet, claude-3-haiku, etc.)
         """
-        try:
-            from anthropic import Anthropic
-        except ImportError:
-            raise ImportError(
-                "Anthropic package not installed. Install with: pip install anthropic"
-            )
+        super().__init__(model)  # Initialize base class with model name
+
+        Anthropic = require_package(
+            "anthropic",
+            "anthropic",
+            "Anthropic",
+            "pip install anthropic",
+        )
 
         self.client = Anthropic(api_key=api_key)
-        self._model_name = model
 
     def generate(
         self,
@@ -237,21 +258,19 @@ class AnthropicProvider(LLMProvider):
         api_params.update(kwargs)
 
         # Call Anthropic API
-        response = self.client.messages.create(**api_params)
+        try:
+            response = self.client.messages.create(**api_params)
+        except Exception as e:
+            handle_provider_error(e, "Anthropic", "generate response")
 
         content = response.content[0].text if response.content else ""
 
-        return LLMResponse(
+        return LLMResponseBuilder.from_anthropic_format(
             content=content,
-            prompt_tokens=response.usage.input_tokens if hasattr(response, "usage") else None,
-            completion_tokens=response.usage.output_tokens if hasattr(response, "usage") else None,
-            total_tokens=(
-                (response.usage.input_tokens + response.usage.output_tokens)
-                if hasattr(response, "usage")
-                else None
-            ),
+            input_tokens=response.usage.input_tokens if hasattr(response, "usage") else None,
+            output_tokens=response.usage.output_tokens if hasattr(response, "usage") else None,
             model_name=response.model,
-            finish_reason=response.stop_reason,
+            stop_reason=response.stop_reason,
         )
 
     def supports_json_mode(self) -> bool:
@@ -263,6 +282,215 @@ class AnthropicProvider(LLMProvider):
         return self._model_name
 
 
+class GLMProvider(LLMProvider):
+    """
+    Zhipu AI GLM provider implementation (GLM-4, GLM-4-Plus, etc.)
+
+    Requirements:
+        pip install zhipuai
+
+    Example:
+        >>> from sentience.llm_provider import GLMProvider
+        >>> llm = GLMProvider(api_key="your-api-key", model="glm-4-plus")
+        >>> response = llm.generate("You are a helpful assistant", "Hello!")
+        >>> print(response.content)
+    """
+
+    def __init__(self, api_key: str | None = None, model: str = "glm-4-plus"):
+        """
+        Initialize GLM provider
+
+        Args:
+            api_key: Zhipu AI API key (or set GLM_API_KEY env var)
+            model: Model name (glm-4-plus, glm-4, glm-4-air, glm-4-flash, etc.)
+        """
+        super().__init__(model)  # Initialize base class with model name
+
+        ZhipuAI = require_package(
+            "zhipuai",
+            "zhipuai",
+            "ZhipuAI",
+            "pip install zhipuai",
+        )
+
+        self.client = ZhipuAI(api_key=api_key)
+
+    def generate(
+        self,
+        system_prompt: str,
+        user_prompt: str,
+        temperature: float = 0.0,
+        max_tokens: int | None = None,
+        **kwargs,
+    ) -> LLMResponse:
+        """
+        Generate response using GLM API
+
+        Args:
+            system_prompt: System instruction
+            user_prompt: User query
+            temperature: Sampling temperature (0.0 = deterministic, 1.0 = creative)
+            max_tokens: Maximum tokens to generate
+            **kwargs: Additional GLM API parameters
+
+        Returns:
+            LLMResponse object
+        """
+        messages = []
+        if system_prompt:
+            messages.append({"role": "system", "content": system_prompt})
+        messages.append({"role": "user", "content": user_prompt})
+
+        # Build API parameters
+        api_params = {
+            "model": self._model_name,
+            "messages": messages,
+            "temperature": temperature,
+        }
+
+        if max_tokens:
+            api_params["max_tokens"] = max_tokens
+
+        # Merge additional parameters
+        api_params.update(kwargs)
+
+        # Call GLM API
+        try:
+            response = self.client.chat.completions.create(**api_params)
+        except Exception as e:
+            handle_provider_error(e, "GLM", "generate response")
+
+        choice = response.choices[0]
+        usage = response.usage
+
+        return LLMResponseBuilder.from_openai_format(
+            content=choice.message.content,
+            prompt_tokens=usage.prompt_tokens if usage else None,
+            completion_tokens=usage.completion_tokens if usage else None,
+            total_tokens=usage.total_tokens if usage else None,
+            model_name=response.model,
+            finish_reason=choice.finish_reason,
+        )
+
+    def supports_json_mode(self) -> bool:
+        """GLM-4 models support JSON mode"""
+        return "glm-4" in self._model_name.lower()
+
+    @property
+    def model_name(self) -> str:
+        return self._model_name
+
+
+class GeminiProvider(LLMProvider):
+    """
+    Google Gemini provider implementation (Gemini 2.0, Gemini 1.5 Pro, etc.)
+
+    Requirements:
+        pip install google-generativeai
+
+    Example:
+        >>> from sentience.llm_provider import GeminiProvider
+        >>> llm = GeminiProvider(api_key="your-api-key", model="gemini-2.0-flash-exp")
+        >>> response = llm.generate("You are a helpful assistant", "Hello!")
+        >>> print(response.content)
+    """
+
+    def __init__(self, api_key: str | None = None, model: str = "gemini-2.0-flash-exp"):
+        """
+        Initialize Gemini provider
+
+        Args:
+            api_key: Google API key (or set GEMINI_API_KEY or GOOGLE_API_KEY env var)
+            model: Model name (gemini-2.0-flash-exp, gemini-1.5-pro, gemini-1.5-flash, etc.)
+        """
+        super().__init__(model)  # Initialize base class with model name
+
+        genai = require_package(
+            "google-generativeai",
+            "google.generativeai",
+            install_command="pip install google-generativeai",
+        )
+
+        # Configure API key (check parameter first, then environment variables)
+        api_key = get_api_key_from_env(["GEMINI_API_KEY", "GOOGLE_API_KEY"], api_key)
+        if api_key:
+            genai.configure(api_key=api_key)
+
+        self.genai = genai
+        self.model = genai.GenerativeModel(model)
+
+    def generate(
+        self,
+        system_prompt: str,
+        user_prompt: str,
+        temperature: float = 0.0,
+        max_tokens: int | None = None,
+        **kwargs,
+    ) -> LLMResponse:
+        """
+        Generate response using Gemini API
+
+        Args:
+            system_prompt: System instruction
+            user_prompt: User query
+            temperature: Sampling temperature (0.0 = deterministic, 2.0 = very creative)
+            max_tokens: Maximum tokens to generate
+            **kwargs: Additional Gemini API parameters
+
+        Returns:
+            LLMResponse object
+        """
+        # Combine system and user prompts (Gemini doesn't have separate system role in all versions)
+        full_prompt = f"{system_prompt}\n\n{user_prompt}" if system_prompt else user_prompt
+
+        # Build generation config
+        generation_config = {
+            "temperature": temperature,
+        }
+
+        if max_tokens:
+            generation_config["max_output_tokens"] = max_tokens
+
+        # Merge additional parameters
+        generation_config.update(kwargs)
+
+        # Call Gemini API
+        try:
+            response = self.model.generate_content(full_prompt, generation_config=generation_config)
+        except Exception as e:
+            handle_provider_error(e, "Gemini", "generate response")
+
+        # Extract content
+        content = response.text if response.text else ""
+
+        # Token usage (if available)
+        prompt_tokens = None
+        completion_tokens = None
+        total_tokens = None
+
+        if hasattr(response, "usage_metadata") and response.usage_metadata:
+            prompt_tokens = response.usage_metadata.prompt_token_count
+            completion_tokens = response.usage_metadata.candidates_token_count
+            total_tokens = response.usage_metadata.total_token_count
+
+        return LLMResponseBuilder.from_gemini_format(
+            content=content,
+            prompt_tokens=prompt_tokens,
+            completion_tokens=completion_tokens,
+            total_tokens=total_tokens,
+            model_name=self._model_name,
+        )
+
+    def supports_json_mode(self) -> bool:
+        """Gemini 1.5+ models support JSON mode via response_mime_type"""
+        model_lower = self._model_name.lower()
+        return any(x in model_lower for x in ["gemini-1.5", "gemini-2.0"])
+
+    @property
+    def model_name(self) -> str:
+        return self._model_name
+
+
 class LocalLLMProvider(LLMProvider):
     """
     Local LLM provider using HuggingFace Transformers
@@ -297,6 +525,9 @@ class LocalLLMProvider(LLMProvider):
             load_in_8bit: Use 8-bit quantization (saves 50% memory)
             torch_dtype: Data type ("auto", "float16", "bfloat16", "float32")
         """
+        super().__init__(model_name)  # Initialize base class with model name
+
+        # Import required packages with consistent error handling
         try:
             import torch
             from transformers import AutoModelForCausalLM, AutoTokenizer, BitsAndBytesConfig
@@ -306,8 +537,6 @@ class LocalLLMProvider(LLMProvider):
                 "Install with: pip install transformers torch"
             )
 
-        self._model_name = model_name
-
         # Load tokenizer
         self.tokenizer = AutoTokenizer.from_pretrained(model_name, trust_remote_code=True)
 
@@ -414,11 +643,10 @@ class LocalLLMProvider(LLMProvider):
         generated_tokens = outputs[0][input_length:]
         response_text = self.tokenizer.decode(generated_tokens, skip_special_tokens=True).strip()
 
-        return LLMResponse(
+        return LLMResponseBuilder.from_local_format(
             content=response_text,
             prompt_tokens=input_length,
             completion_tokens=len(generated_tokens),
-            total_tokens=input_length + len(generated_tokens),
             model_name=self._model_name,
         )
 

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,
+        )