sentienceapi 0.90.16__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:
@@ -285,13 +304,16 @@ class GLMProvider(LLMProvider):
             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.)
         """
-        try:
-            from zhipuai import ZhipuAI
-        except ImportError:
-            raise ImportError("ZhipuAI package not installed. Install with: pip install zhipuai")
+        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)
-        self._model_name = model
 
     def generate(
         self,
@@ -333,12 +355,15 @@ class GLMProvider(LLMProvider):
         api_params.update(kwargs)
 
         # Call GLM 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, "GLM", "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,
@@ -378,25 +403,20 @@ class GeminiProvider(LLMProvider):
             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.)
         """
-        try:
-            import google.generativeai as genai
-        except ImportError:
-            raise ImportError(
-                "Google Generative AI package not installed. Install with: pip install google-generativeai"
-            )
+        super().__init__(model)  # Initialize base class with model name
 
-        # Configure API key
+        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)
-        else:
-            import os
-
-            api_key = os.getenv("GEMINI_API_KEY") or os.getenv("GOOGLE_API_KEY")
-            if api_key:
-                genai.configure(api_key=api_key)
 
         self.genai = genai
-        self._model_name = model
         self.model = genai.GenerativeModel(model)
 
     def generate(
@@ -435,7 +455,10 @@ class GeminiProvider(LLMProvider):
         generation_config.update(kwargs)
 
         # Call Gemini API
-        response = self.model.generate_content(full_prompt, generation_config=generation_config)
+        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 ""
@@ -450,13 +473,12 @@ class GeminiProvider(LLMProvider):
             completion_tokens = response.usage_metadata.candidates_token_count
             total_tokens = response.usage_metadata.total_token_count
 
-        return LLMResponse(
+        return LLMResponseBuilder.from_gemini_format(
             content=content,
             prompt_tokens=prompt_tokens,
             completion_tokens=completion_tokens,
             total_tokens=total_tokens,
             model_name=self._model_name,
-            finish_reason=None,  # Gemini uses different finish reason format
         )
 
     def supports_json_mode(self) -> bool:
@@ -503,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
@@ -512,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)
 
@@ -620,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,
+        )

sentience/models.py

@@ -2,7 +2,8 @@
 Pydantic models for Sentience SDK - matches spec/snapshot.schema.json
 """
 
-from typing import Literal, Optional
+from dataclasses import dataclass
+from typing import Any, Literal, Optional
 
 from pydantic import BaseModel, Field
 
@@ -50,6 +51,9 @@ class Element(BaseModel):
     ml_probability: float | None = None  # Confidence score from ONNX model (0.0 - 1.0)
     ml_score: float | None = None  # Raw logit score (optional, for debugging)
 
+    # Diff status for frontend Diff Overlay feature
+    diff_status: Literal["ADDED", "REMOVED", "MODIFIED", "MOVED"] | None = None
+
 
 class Snapshot(BaseModel):
     """Snapshot response from extension"""
@@ -410,3 +414,58 @@ class TextRectSearchResult(BaseModel):
     )
     viewport: Viewport | None = Field(None, description="Current viewport dimensions")
     error: str | None = Field(None, description="Error message if status is 'error'")
+
+
+class ReadResult(BaseModel):
+    """Result of read() or read_async() operation"""
+
+    status: Literal["success", "error"]
+    url: str
+    format: Literal["raw", "text", "markdown"]
+    content: str
+    length: int
+    error: str | None = None
+
+
+class TraceStats(BaseModel):
+    """Execution statistics for trace completion"""
+
+    total_steps: int
+    total_events: int
+    duration_ms: int | None = None
+    final_status: Literal["success", "failure", "partial", "unknown"]
+    started_at: str | None = None
+    ended_at: str | None = None
+
+
+class StepExecutionResult(BaseModel):
+    """Result of executing a single step in ConversationalAgent"""
+
+    success: bool
+    action: str
+    data: dict[str, Any]  # Flexible data field for step-specific results
+    error: str | None = None
+
+
+class ExtractionResult(BaseModel):
+    """Result of extracting information from a page"""
+
+    found: bool
+    data: dict[str, Any]  # Extracted data fields
+    summary: str  # Brief description of what was found
+
+
+@dataclass
+class ScreenshotMetadata:
+    """
+    Metadata for a stored screenshot.
+
+    Used by CloudTraceSink to track screenshots before upload.
+    All fields are required for type safety.
+    """
+
+    sequence: int
+    format: Literal["png", "jpeg"]
+    size_bytes: int
+    step_id: str | None
+    filepath: str