sentienceapi 0.90.9__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:
@@ -33,6 +34,9 @@ class SentienceBrowser:
         proxy: str | None = None,
         user_data_dir: str | None = None,
         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
@@ -57,6 +61,19 @@ class SentienceBrowser:
                           - StorageState object
                           - Dictionary with 'cookies' and/or 'origins' keys
                           If provided, browser starts with pre-injected authentication.
+            record_video_dir: Optional directory path to save video recordings.
+                            If provided, browser will record video of all pages.
+                            Videos are saved as .webm files in the specified directory.
+                            If None, no video recording is performed.
+            record_video_size: Optional video resolution as dict with 'width' and 'height' keys.
+                             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)
@@ -80,6 +97,18 @@ class SentienceBrowser:
         self.user_data_dir = user_data_dir
         self.storage_state = storage_state
 
+        # Video recording support
+        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
@@ -133,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
@@ -197,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",
         }
@@ -209,6 +218,17 @@ class SentienceBrowser:
             launch_params["ignore_https_errors"] = True
             print(f"🌐 [Sentience] Using proxy: {proxy_config.server}")
 
+        # Add video recording if configured
+        if self.record_video_dir:
+            video_dir = Path(self.record_video_dir)
+            video_dir.mkdir(parents=True, exist_ok=True)
+            launch_params["record_video_dir"] = str(video_dir)
+            launch_params["record_video_size"] = self.record_video_size
+            print(f"🎥 [Sentience] Recording video to: {video_dir}")
+            print(
+                f"   Resolution: {self.record_video_size['width']}x{self.record_video_size['height']}"
+            )
+
         # Launch persistent context (required for extensions)
         # Note: We pass headless=False to launch_persistent_context because we handle
         # headless mode via the --headless=new arg above. This is a Playwright workaround.
@@ -390,15 +410,162 @@ class SentienceBrowser:
 
         return False
 
-    def close(self) -> None:
-        """Close browser and cleanup"""
+    def close(self, output_path: str | Path | None = None) -> str | None:
+        """
+        Close browser and cleanup
+
+        Args:
+            output_path: Optional path to rename the video file to.
+                        If provided, the recorded video will be moved to this location.
+                        Useful for giving videos meaningful names instead of random hashes.
+
+        Returns:
+            Path to video file if recording was enabled, None otherwise
+            Note: Video files are saved automatically by Playwright when context closes.
+            If multiple pages exist, returns the path to the first page's video.
+        """
+        temp_video_path = None
+
+        # Get video path before closing (if recording was enabled)
+        # Note: Playwright saves videos when pages/context close, but we can get the
+        # expected path before closing. The actual file will be available after close.
+        if self.record_video_dir:
+            try:
+                # Try to get video path from the first page
+                if self.page and self.page.video:
+                    temp_video_path = self.page.video.path()
+                # If that fails, check all pages in the context
+                elif self.context:
+                    for page in self.context.pages:
+                        if page.video:
+                            temp_video_path = page.video.path()
+                            break
+            except Exception:
+                # Video path might not be available until after close
+                # In that case, we'll return None and user can check the directory
+                pass
+
+        # Close context (this triggers video file finalization)
         if self.context:
             self.context.close()
+
+        # Close playwright
         if self.playwright:
             self.playwright.stop()
+
+        # Clean up extension directory
         if self._extension_path and os.path.exists(self._extension_path):
             shutil.rmtree(self._extension_path)
 
+        # Rename/move video if output_path is specified
+        final_path = temp_video_path
+        if temp_video_path and output_path and os.path.exists(temp_video_path):
+            try:
+                output_path = str(output_path)
+                # Ensure parent directory exists
+                Path(output_path).parent.mkdir(parents=True, exist_ok=True)
+                shutil.move(temp_video_path, output_path)
+                final_path = output_path
+            except Exception as e:
+                import warnings
+
+                warnings.warn(f"Failed to rename video file: {e}")
+                # Return original path if rename fails
+                final_path = temp_video_path
+
+        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

@@ -213,7 +213,10 @@ class CloudTraceSink(TraceSink):
                 if on_progress:
                     on_progress(compressed_size, compressed_size)
 
-                # Call /v1/traces/complete to report file sizes (NEW)
+                # Upload trace index file
+                self._upload_index()
+
+                # Call /v1/traces/complete to report file sizes
                 self._complete_trace()
 
                 # Delete file only on successful upload
@@ -244,6 +247,93 @@ class CloudTraceSink(TraceSink):
             # Non-fatal: log but don't crash
             print(f"⚠️  Failed to generate trace index: {e}")
 
+    def _upload_index(self) -> None:
+        """
+        Upload trace index file to cloud storage.
+
+        Called after successful trace upload to provide fast timeline rendering.
+        The index file enables O(1) step lookups without parsing the entire trace.
+        """
+        # Construct index file path (same as trace file with .index.json extension)
+        index_path = Path(str(self._path).replace(".jsonl", ".index.json"))
+
+        if not index_path.exists():
+            if self.logger:
+                self.logger.warning("Index file not found, skipping index upload")
+            return
+
+        try:
+            # Request index upload URL from API
+            if not self.api_key:
+                # No API key - skip index upload
+                if self.logger:
+                    self.logger.info("No API key provided, skipping index upload")
+                return
+
+            response = requests.post(
+                f"{self.api_url}/v1/traces/index_upload",
+                headers={"Authorization": f"Bearer {self.api_key}"},
+                json={"run_id": self.run_id},
+                timeout=10,
+            )
+
+            if response.status_code != 200:
+                if self.logger:
+                    self.logger.warning(
+                        f"Failed to get index upload URL: HTTP {response.status_code}"
+                    )
+                return
+
+            upload_data = response.json()
+            index_upload_url = upload_data.get("upload_url")
+
+            if not index_upload_url:
+                if self.logger:
+                    self.logger.warning("No upload URL in index upload response")
+                return
+
+            # Read and compress index file
+            with open(index_path, "rb") as f:
+                index_data = f.read()
+
+            compressed_index = gzip.compress(index_data)
+            index_size = len(compressed_index)
+
+            if self.logger:
+                self.logger.info(f"Index file size: {index_size / 1024:.2f} KB")
+
+            print(f"📤 [Sentience] Uploading trace index ({index_size} bytes)...")
+
+            # Upload index to cloud storage
+            index_response = requests.put(
+                index_upload_url,
+                data=compressed_index,
+                headers={
+                    "Content-Type": "application/json",
+                    "Content-Encoding": "gzip",
+                },
+                timeout=30,
+            )
+
+            if index_response.status_code == 200:
+                print("✅ [Sentience] Trace index uploaded successfully")
+
+                # Delete local index file after successful upload
+                try:
+                    os.remove(index_path)
+                except Exception:
+                    pass  # Ignore cleanup errors
+            else:
+                if self.logger:
+                    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:
+            # Non-fatal: log but don't crash
+            if self.logger:
+                self.logger.warning(f"Error uploading trace index: {e}")
+            print(f"⚠️  [Sentience] Error uploading trace index: {e}")
+
     def _complete_trace(self) -> None:
         """
         Call /v1/traces/complete to report file sizes to gateway.

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": 0,
+      "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"""