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

sentience/browser.py

@@ -11,7 +11,8 @@ from urllib.parse import urlparse
 
 from playwright.sync_api import BrowserContext, Page, Playwright, sync_playwright
 
-from sentience.models import ProxyConfig, StorageState
+from sentience._extension_loader import find_extension_path
+from sentience.models import ProxyConfig, StorageState, Viewport
 
 # Import stealth for bot evasion (optional - graceful fallback if not available)
 try:
@@ -35,6 +36,7 @@ class SentienceBrowser:
         storage_state: str | Path | StorageState | dict | None = None,
         record_video_dir: str | Path | None = None,
         record_video_size: dict[str, int] | None = None,
+        viewport: Viewport | dict[str, int] | None = None,
     ):
         """
         Initialize Sentience browser
@@ -67,6 +69,11 @@ class SentienceBrowser:
                              Examples: {"width": 1280, "height": 800} (default)
                                       {"width": 1920, "height": 1080} (1080p)
                              If None, defaults to 1280x800.
+            viewport: Optional viewport size as Viewport object or dict with 'width' and 'height' keys.
+                     Examples: Viewport(width=1280, height=800) (default)
+                              Viewport(width=1920, height=1080) (Full HD)
+                              {"width": 1280, "height": 800} (dict also supported)
+                     If None, defaults to Viewport(width=1280, height=800).
         """
         self.api_key = api_key
         # Only set api_url if api_key is provided, otherwise None (free tier)
@@ -94,6 +101,14 @@ class SentienceBrowser:
         self.record_video_dir = record_video_dir
         self.record_video_size = record_video_size or {"width": 1280, "height": 800}
 
+        # Viewport configuration - convert dict to Viewport if needed
+        if viewport is None:
+            self.viewport = Viewport(width=1280, height=800)
+        elif isinstance(viewport, dict):
+            self.viewport = Viewport(width=viewport["width"], height=viewport["height"])
+        else:
+            self.viewport = viewport
+
         self.playwright: Playwright | None = None
         self.context: BrowserContext | None = None
         self.page: Page | None = None
@@ -147,28 +162,8 @@ class SentienceBrowser:
 
     def start(self) -> None:
         """Launch browser with extension loaded"""
-        # Get extension source path (relative to project root/package)
-        # Handle both development (src/) and installed package cases
-
-        # 1. Try relative to this file (installed package structure)
-        # sentience/browser.py -> sentience/extension/
-        package_ext_path = Path(__file__).parent / "extension"
-
-        # 2. Try development root (if running from source repo)
-        # sentience/browser.py -> ../sentience-chrome
-        dev_ext_path = Path(__file__).parent.parent.parent / "sentience-chrome"
-
-        if package_ext_path.exists() and (package_ext_path / "manifest.json").exists():
-            extension_source = package_ext_path
-        elif dev_ext_path.exists() and (dev_ext_path / "manifest.json").exists():
-            extension_source = dev_ext_path
-        else:
-            raise FileNotFoundError(
-                f"Extension not found. Checked:\n"
-                f"1. {package_ext_path}\n"
-                f"2. {dev_ext_path}\n"
-                "Make sure the extension is built and 'sentience/extension' directory exists."
-            )
+        # Get extension source path using shared utility
+        extension_source = find_extension_path()
 
         # Create temporary extension bundle
         # We copy it to a temp dir to avoid file locking issues and ensure clean state
@@ -211,7 +206,7 @@ class SentienceBrowser:
             "user_data_dir": user_data_dir,
             "headless": False,  # IMPORTANT: See note above
             "args": args,
-            "viewport": {"width": 1280, "height": 800},
+            "viewport": {"width": self.viewport.width, "height": self.viewport.height},
             # Remove "HeadlessChrome" from User Agent automatically
             "user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/122.0.0.0 Safari/537.36",
         }
@@ -480,6 +475,97 @@ class SentienceBrowser:
 
         return final_path
 
+    @classmethod
+    def from_existing(
+        cls,
+        context: BrowserContext,
+        api_key: str | None = None,
+        api_url: str | None = None,
+    ) -> "SentienceBrowser":
+        """
+        Create SentienceBrowser from an existing Playwright BrowserContext.
+
+        This allows you to use Sentience SDK with a browser context you've already created,
+        giving you more control over browser initialization.
+
+        Args:
+            context: Existing Playwright BrowserContext
+            api_key: Optional API key for server-side processing
+            api_url: Optional API URL (defaults to https://api.sentienceapi.com if api_key provided)
+
+        Returns:
+            SentienceBrowser instance configured to use the existing context
+
+        Example:
+            from playwright.sync_api import sync_playwright
+            from sentience import SentienceBrowser, snapshot
+
+            with sync_playwright() as p:
+                context = p.chromium.launch_persistent_context(...)
+                browser = SentienceBrowser.from_existing(context)
+                browser.page.goto("https://example.com")
+                snap = snapshot(browser)
+        """
+        instance = cls(api_key=api_key, api_url=api_url)
+        instance.context = context
+        instance.page = context.pages[0] if context.pages else context.new_page()
+
+        # Apply stealth if available
+        if STEALTH_AVAILABLE:
+            stealth_sync(instance.page)
+
+        # Wait for extension to be ready (if extension is loaded)
+        time.sleep(0.5)
+
+        return instance
+
+    @classmethod
+    def from_page(
+        cls,
+        page: Page,
+        api_key: str | None = None,
+        api_url: str | None = None,
+    ) -> "SentienceBrowser":
+        """
+        Create SentienceBrowser from an existing Playwright Page.
+
+        This allows you to use Sentience SDK with a page you've already created,
+        giving you more control over browser initialization.
+
+        Args:
+            page: Existing Playwright Page
+            api_key: Optional API key for server-side processing
+            api_url: Optional API URL (defaults to https://api.sentienceapi.com if api_key provided)
+
+        Returns:
+            SentienceBrowser instance configured to use the existing page
+
+        Example:
+            from playwright.sync_api import sync_playwright
+            from sentience import SentienceBrowser, snapshot
+
+            with sync_playwright() as p:
+                browser_instance = p.chromium.launch()
+                context = browser_instance.new_context()
+                page = context.new_page()
+                page.goto("https://example.com")
+
+                browser = SentienceBrowser.from_page(page)
+                snap = snapshot(browser)
+        """
+        instance = cls(api_key=api_key, api_url=api_url)
+        instance.page = page
+        instance.context = page.context
+
+        # Apply stealth if available
+        if STEALTH_AVAILABLE:
+            stealth_sync(instance.page)
+
+        # Wait for extension to be ready (if extension is loaded)
+        time.sleep(0.5)
+
+        return instance
+
     def __enter__(self):
         """Context manager entry"""
         self.start()

sentience/cloud_tracing.py

@@ -325,9 +325,7 @@ class CloudTraceSink(TraceSink):
                     pass  # Ignore cleanup errors
             else:
                 if self.logger:
-                    self.logger.warning(
-                        f"Index upload failed: HTTP {index_response.status_code}"
-                    )
+                    self.logger.warning(f"Index upload failed: HTTP {index_response.status_code}")
                 print(f"⚠️  [Sentience] Index upload failed: HTTP {index_response.status_code}")
 
         except Exception as e:

sentience/conversational_agent.py

@@ -10,7 +10,7 @@ from typing import Any
 from .agent import SentienceAgent
 from .browser import SentienceBrowser
 from .llm_provider import LLMProvider
-from .models import Snapshot
+from .models import Snapshot, SnapshotOptions
 from .snapshot import snapshot
 
 
@@ -274,7 +274,7 @@ Create a step-by-step execution plan."""
             elif action == "EXTRACT_INFO":
                 info_type = params["info_type"]
                 # Get current page snapshot and extract info
-                snap = snapshot(self.browser, limit=50)
+                snap = snapshot(self.browser, SnapshotOptions(limit=50))
 
                 # Use LLM to extract specific information
                 extracted = self._extract_information(snap, info_type)
@@ -361,7 +361,7 @@ Return JSON with extracted information:
             True if condition is met, False otherwise
         """
         try:
-            snap = snapshot(self.browser, limit=30)
+            snap = snapshot(self.browser, SnapshotOptions(limit=30))
 
             # Build context
             elements_text = "\n".join([f"{el.role}: {el.text}" for el in snap.elements[:20]])

sentience/extension/release.json

@@ -67,7 +67,7 @@
       "state": "uploaded",
       "size": 78091,
       "digest": "sha256:e281f8b755b61da4b8015d6172064aa9a337c14133ceceff4ab29199ee53307e",
-      "download_count": 2,
+      "download_count": 5,
       "created_at": "2025-12-29T03:57:09Z",
       "updated_at": "2025-12-29T03:57:09Z",
       "browser_download_url": "https://github.com/SentienceAPI/Sentience-Geometry-Chrome-Extension/releases/download/v2.0.7/extension-files.tar.gz"

sentience/llm_provider.py

@@ -263,6 +263,212 @@ 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.)
+        """
+        try:
+            from zhipuai import ZhipuAI
+        except ImportError:
+            raise ImportError("ZhipuAI package not installed. Install with: pip install zhipuai")
+
+        self.client = ZhipuAI(api_key=api_key)
+        self._model_name = model
+
+    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
+        response = self.client.chat.completions.create(**api_params)
+
+        choice = response.choices[0]
+        usage = response.usage
+
+        return LLMResponse(
+            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.)
+        """
+        try:
+            import google.generativeai as genai
+        except ImportError:
+            raise ImportError(
+                "Google Generative AI package not installed. Install with: pip install google-generativeai"
+            )
+
+        # Configure 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(
+        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
+        response = self.model.generate_content(full_prompt, generation_config=generation_config)
+
+        # 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 LLMResponse(
+            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:
+        """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

sentience/models.py

@@ -2,7 +2,7 @@
 Pydantic models for Sentience SDK - matches spec/snapshot.schema.json
 """
 
-from typing import Literal
+from typing import Literal, Optional
 
 from pydantic import BaseModel, Field
 
@@ -44,6 +44,12 @@ class Element(BaseModel):
     is_occluded: bool = False
     z_index: int = 0
 
+    # ML reranking metadata (optional - can be absent or null)
+    rerank_index: int | None = None  # 0-based, The rank after ML reranking
+    heuristic_index: int | None = None  # 0-based, Where it would have been without ML
+    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)
+
 
 class Snapshot(BaseModel):
     """Snapshot response from extension"""

sentience/snapshot.py

@@ -5,7 +5,7 @@ Snapshot functionality - calls window.sentience.snapshot() or server-side API
 import json
 import os
 import time
-from typing import Any
+from typing import Any, Optional
 
 import requests
 
@@ -41,41 +41,33 @@ def _save_trace_to_file(raw_elements: list[dict[str, Any]], trace_path: str | No
 
 def snapshot(
     browser: SentienceBrowser,
-    screenshot: bool | None = None,
-    limit: int | None = None,
-    filter: dict[str, Any] | None = None,
-    use_api: bool | None = None,
-    save_trace: bool = False,
-    trace_path: str | None = None,
-    show_overlay: bool = False,
+    options: SnapshotOptions | None = None,
 ) -> Snapshot:
     """
     Take a snapshot of the current page
 
     Args:
         browser: SentienceBrowser instance
-        screenshot: Whether to capture screenshot (bool or dict with format/quality)
-        limit: Limit number of elements returned
-        filter: Filter options (min_area, allowed_roles, min_z_index)
-        use_api: Force use of server-side API if True, local extension if False.
-                 If None, uses API if api_key is set, otherwise uses local extension.
-        save_trace: Whether to save raw_elements to JSON for benchmarking/training
-        trace_path: Path to save trace file. If None, uses "trace_{timestamp}.json"
-        show_overlay: Show visual overlay highlighting elements in browser
+        options: Snapshot options (screenshot, limit, filter, etc.)
+                If None, uses default options.
 
     Returns:
         Snapshot object
+
+    Example:
+        # Basic snapshot with defaults
+        snap = snapshot(browser)
+
+        # With options
+        snap = snapshot(browser, SnapshotOptions(
+            screenshot=True,
+            limit=100,
+            show_overlay=True
+        ))
     """
-    # Build SnapshotOptions from individual parameters
-    options = SnapshotOptions(
-        screenshot=screenshot if screenshot is not None else False,
-        limit=limit if limit is not None else 50,
-        filter=filter,
-        use_api=use_api,
-        save_trace=save_trace,
-        trace_path=trace_path,
-        show_overlay=show_overlay,
-    )
+    # Use default options if none provided
+    if options is None:
+        options = SnapshotOptions()
 
     # Determine if we should use server-side API
     should_use_api = (

sentience/wait.py

@@ -5,7 +5,7 @@ Wait functionality - wait_for element matching selector
 import time
 
 from .browser import SentienceBrowser
-from .models import WaitResult
+from .models import SnapshotOptions, WaitResult
 from .query import find
 from .snapshot import snapshot
 
@@ -46,7 +46,7 @@ def wait_for(
 
     while time.time() - start_time < timeout:
         # Take snapshot (may be local extension or remote API)
-        snap = snapshot(browser, use_api=use_api)
+        snap = snapshot(browser, SnapshotOptions(use_api=use_api))
 
         # Try to find element
         element = find(snap, selector)