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

sentience/backends/exceptions.py

@@ -0,0 +1,211 @@
+"""
+Custom exceptions for Sentience backends.
+
+These exceptions provide clear, actionable error messages when things go wrong
+during browser-use integration or backend operations.
+"""
+
+from dataclasses import dataclass
+from typing import Any
+
+
+class SentienceBackendError(Exception):
+    """Base exception for all Sentience backend errors."""
+
+    pass
+
+
+@dataclass
+class ExtensionDiagnostics:
+    """Diagnostics collected when extension loading fails."""
+
+    sentience_defined: bool = False
+    sentience_snapshot: bool = False
+    url: str = ""
+    error: str | None = None
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> "ExtensionDiagnostics":
+        """Create from diagnostic dict returned by browser eval."""
+        return cls(
+            sentience_defined=data.get("sentience_defined", False),
+            sentience_snapshot=data.get("sentience_snapshot", False),
+            url=data.get("url", ""),
+            error=data.get("error"),
+        )
+
+    def to_dict(self) -> dict[str, Any]:
+        """Convert to dict for serialization."""
+        return {
+            "sentience_defined": self.sentience_defined,
+            "sentience_snapshot": self.sentience_snapshot,
+            "url": self.url,
+            "error": self.error,
+        }
+
+
+class ExtensionNotLoadedError(SentienceBackendError):
+    """
+    Raised when the Sentience extension is not loaded in the browser.
+
+    This typically means:
+    1. Browser was launched without --load-extension flag
+    2. Extension path is incorrect
+    3. Extension failed to initialize
+
+    Example fix for browser-use:
+        from sentience import get_extension_dir
+        from browser_use import BrowserSession, BrowserProfile
+
+        profile = BrowserProfile(
+            args=[f"--load-extension={get_extension_dir()}"],
+        )
+        session = BrowserSession(browser_profile=profile)
+    """
+
+    def __init__(
+        self,
+        message: str,
+        timeout_ms: int | None = None,
+        diagnostics: ExtensionDiagnostics | None = None,
+    ) -> None:
+        self.timeout_ms = timeout_ms
+        self.diagnostics = diagnostics
+        super().__init__(message)
+
+    @classmethod
+    def from_timeout(
+        cls,
+        timeout_ms: int,
+        diagnostics: ExtensionDiagnostics | None = None,
+    ) -> "ExtensionNotLoadedError":
+        """Create error from timeout during extension wait."""
+        diag_info = ""
+        if diagnostics:
+            if diagnostics.error:
+                diag_info = f"\n  Error: {diagnostics.error}"
+            else:
+                diag_info = (
+                    f"\n  window.sentience defined: {diagnostics.sentience_defined}"
+                    f"\n  window.sentience.snapshot available: {diagnostics.sentience_snapshot}"
+                    f"\n  Page URL: {diagnostics.url}"
+                )
+
+        message = (
+            f"Sentience extension not loaded after {timeout_ms}ms.{diag_info}\n\n"
+            "To fix this, ensure the extension is loaded when launching the browser:\n\n"
+            "  from sentience import get_extension_dir\n"
+            "  from browser_use import BrowserSession, BrowserProfile\n\n"
+            "  profile = BrowserProfile(\n"
+            f'      args=[f"--load-extension={{get_extension_dir()}}"],\n'
+            "  )\n"
+            "  session = BrowserSession(browser_profile=profile)\n"
+        )
+        return cls(message, timeout_ms=timeout_ms, diagnostics=diagnostics)
+
+
+class ExtensionInjectionError(SentienceBackendError):
+    """
+    Raised when window.sentience API is not available on the page.
+
+    This can happen when:
+    1. Page loaded before extension could inject
+    2. Page has Content Security Policy blocking extension
+    3. Extension crashed or was disabled
+
+    Call snapshot() with a longer timeout or wait for page load.
+    """
+
+    def __init__(
+        self,
+        message: str,
+        url: str | None = None,
+    ) -> None:
+        self.url = url
+        super().__init__(message)
+
+    @classmethod
+    def from_page(cls, url: str) -> "ExtensionInjectionError":
+        """Create error for a specific page."""
+        message = (
+            f"window.sentience API not available on page: {url}\n\n"
+            "Possible causes:\n"
+            "  1. Page loaded before extension could inject (try increasing timeout)\n"
+            "  2. Page has Content Security Policy blocking the extension\n"
+            "  3. Extension was disabled or crashed\n\n"
+            "Try:\n"
+            "  snap = await snapshot(backend, options=SnapshotOptions(timeout_ms=10000))"
+        )
+        return cls(message, url=url)
+
+
+class BackendEvalError(SentienceBackendError):
+    """
+    Raised when JavaScript evaluation fails in the browser.
+
+    This wraps underlying CDP or Playwright errors with context.
+    """
+
+    def __init__(
+        self,
+        message: str,
+        expression: str | None = None,
+        original_error: Exception | None = None,
+    ) -> None:
+        self.expression = expression
+        self.original_error = original_error
+        super().__init__(message)
+
+
+class SnapshotError(SentienceBackendError):
+    """
+    Raised when taking a snapshot fails.
+
+    This can happen when:
+    1. Extension returned null or invalid data
+    2. Page is in an invalid state
+    3. Extension threw an error
+    """
+
+    def __init__(
+        self,
+        message: str,
+        url: str | None = None,
+        raw_result: Any = None,
+    ) -> None:
+        self.url = url
+        self.raw_result = raw_result
+        super().__init__(message)
+
+    @classmethod
+    def from_null_result(cls, url: str | None = None) -> "SnapshotError":
+        """Create error for null snapshot result."""
+        message = (
+            "window.sentience.snapshot() returned null.\n\n"
+            "Possible causes:\n"
+            "  1. Extension is not properly initialized\n"
+            "  2. Page DOM is in an invalid state\n"
+            "  3. Extension encountered an internal error\n\n"
+            "Try refreshing the page and taking a new snapshot."
+        )
+        if url:
+            message = f"{message}\n  Page URL: {url}"
+        return cls(message, url=url, raw_result=None)
+
+
+class ActionError(SentienceBackendError):
+    """
+    Raised when a browser action (click, type, scroll) fails.
+    """
+
+    def __init__(
+        self,
+        action: str,
+        message: str,
+        coordinates: tuple[float, float] | None = None,
+        original_error: Exception | None = None,
+    ) -> None:
+        self.action = action
+        self.coordinates = coordinates
+        self.original_error = original_error
+        super().__init__(f"{action} failed: {message}")

sentience/backends/playwright_backend.py

@@ -0,0 +1,194 @@
+"""
+Playwright backend implementation for BrowserBackend protocol.
+
+This wraps existing SentienceBrowser/AsyncSentienceBrowser to provide
+a unified interface, enabling code that works with both browser-use
+(CDPBackendV0) and native Playwright (PlaywrightBackend).
+
+Usage:
+    from sentience import SentienceBrowserAsync
+    from sentience.backends import PlaywrightBackend, snapshot_from_backend
+
+    browser = SentienceBrowserAsync()
+    await browser.start()
+    await browser.goto("https://example.com")
+
+    # Create backend from existing browser
+    backend = PlaywrightBackend(browser.page)
+
+    # Use backend-agnostic functions
+    snap = await snapshot_from_backend(backend)
+    await click(backend, element.bbox)
+"""
+
+import asyncio
+import base64
+import time
+from typing import TYPE_CHECKING, Any, Literal
+
+from .protocol import BrowserBackend, LayoutMetrics, ViewportInfo
+
+if TYPE_CHECKING:
+    from playwright.async_api import Page as AsyncPage
+
+
+class PlaywrightBackend:
+    """
+    Playwright-based implementation of BrowserBackend.
+
+    Wraps a Playwright async Page to provide the standard backend interface.
+    This enables using backend-agnostic actions with existing SentienceBrowser code.
+    """
+
+    def __init__(self, page: "AsyncPage") -> None:
+        """
+        Initialize Playwright backend.
+
+        Args:
+            page: Playwright async Page object
+        """
+        self._page = page
+        self._cached_viewport: ViewportInfo | None = None
+
+    @property
+    def page(self) -> "AsyncPage":
+        """Access the underlying Playwright page."""
+        return self._page
+
+    async def refresh_page_info(self) -> ViewportInfo:
+        """Cache viewport + scroll offsets; cheap & safe to call often."""
+        result = await self._page.evaluate(
+            """
+            (() => ({
+                width: window.innerWidth,
+                height: window.innerHeight,
+                scroll_x: window.scrollX,
+                scroll_y: window.scrollY,
+                content_width: document.documentElement.scrollWidth,
+                content_height: document.documentElement.scrollHeight
+            }))()
+        """
+        )
+
+        self._cached_viewport = ViewportInfo(
+            width=result.get("width", 0),
+            height=result.get("height", 0),
+            scroll_x=result.get("scroll_x", 0),
+            scroll_y=result.get("scroll_y", 0),
+            content_width=result.get("content_width"),
+            content_height=result.get("content_height"),
+        )
+        return self._cached_viewport
+
+    async def eval(self, expression: str) -> Any:
+        """Evaluate JavaScript expression in page context."""
+        return await self._page.evaluate(expression)
+
+    async def call(
+        self,
+        function_declaration: str,
+        args: list[Any] | None = None,
+    ) -> Any:
+        """Call JavaScript function with arguments."""
+        if args:
+            return await self._page.evaluate(function_declaration, *args)
+        return await self._page.evaluate(f"({function_declaration})()")
+
+    async def get_layout_metrics(self) -> LayoutMetrics:
+        """Get page layout metrics."""
+        # Playwright doesn't expose CDP directly in the same way,
+        # so we approximate using JavaScript
+        result = await self._page.evaluate(
+            """
+            (() => ({
+                viewport_x: window.scrollX,
+                viewport_y: window.scrollY,
+                viewport_width: window.innerWidth,
+                viewport_height: window.innerHeight,
+                content_width: document.documentElement.scrollWidth,
+                content_height: document.documentElement.scrollHeight,
+                device_scale_factor: window.devicePixelRatio || 1
+            }))()
+        """
+        )
+
+        return LayoutMetrics(
+            viewport_x=result.get("viewport_x", 0),
+            viewport_y=result.get("viewport_y", 0),
+            viewport_width=result.get("viewport_width", 0),
+            viewport_height=result.get("viewport_height", 0),
+            content_width=result.get("content_width", 0),
+            content_height=result.get("content_height", 0),
+            device_scale_factor=result.get("device_scale_factor", 1.0),
+        )
+
+    async def screenshot_png(self) -> bytes:
+        """Capture viewport screenshot as PNG bytes."""
+        return await self._page.screenshot(type="png")
+
+    async def mouse_move(self, x: float, y: float) -> None:
+        """Move mouse to viewport coordinates."""
+        await self._page.mouse.move(x, y)
+
+    async def mouse_click(
+        self,
+        x: float,
+        y: float,
+        button: Literal["left", "right", "middle"] = "left",
+        click_count: int = 1,
+    ) -> None:
+        """Click at viewport coordinates."""
+        await self._page.mouse.click(x, y, button=button, click_count=click_count)
+
+    async def wheel(
+        self,
+        delta_y: float,
+        x: float | None = None,
+        y: float | None = None,
+    ) -> None:
+        """Scroll using mouse wheel."""
+        # Get viewport center if coordinates not provided
+        if x is None or y is None:
+            if self._cached_viewport is None:
+                await self.refresh_page_info()
+            assert self._cached_viewport is not None
+            x = x if x is not None else self._cached_viewport.width / 2
+            y = y if y is not None else self._cached_viewport.height / 2
+
+        await self._page.mouse.wheel(0, delta_y)
+
+    async def type_text(self, text: str) -> None:
+        """Type text using keyboard input."""
+        await self._page.keyboard.type(text)
+
+    async def wait_ready_state(
+        self,
+        state: Literal["interactive", "complete"] = "interactive",
+        timeout_ms: int = 15000,
+    ) -> None:
+        """Wait for document.readyState to reach target state."""
+        acceptable_states = {"complete"} if state == "complete" else {"interactive", "complete"}
+
+        start = time.monotonic()
+        timeout_sec = timeout_ms / 1000.0
+
+        while True:
+            elapsed = time.monotonic() - start
+            if elapsed >= timeout_sec:
+                raise TimeoutError(
+                    f"Timed out waiting for document.readyState='{state}' " f"after {timeout_ms}ms"
+                )
+
+            current_state = await self._page.evaluate("document.readyState")
+            if current_state in acceptable_states:
+                return
+
+            await asyncio.sleep(0.1)
+
+    async def get_url(self) -> str:
+        """Get current page URL."""
+        return self._page.url
+
+
+# Verify protocol compliance at import time
+assert isinstance(PlaywrightBackend.__new__(PlaywrightBackend), BrowserBackend)

sentience/backends/protocol.py

@@ -0,0 +1,216 @@
+"""
+v0 BrowserBackend Protocol - Minimal interface for browser-use integration.
+
+This protocol defines the minimal interface required to:
+- Take Sentience snapshots (DOM/geometry via extension)
+- Compute viewport-coord clicks
+- Scroll + re-snapshot + click
+- Stabilize after action
+
+No navigation API required (browser-use already handles navigation).
+
+Design principle: Keep it so small that nothing can break.
+"""
+
+from typing import Any, Literal, Protocol, runtime_checkable
+
+from pydantic import BaseModel
+
+
+class ViewportInfo(BaseModel):
+    """Viewport and scroll position information."""
+
+    width: int
+    height: int
+    scroll_x: float = 0.0
+    scroll_y: float = 0.0
+    content_width: float | None = None
+    content_height: float | None = None
+
+
+class LayoutMetrics(BaseModel):
+    """Page layout metrics from CDP Page.getLayoutMetrics."""
+
+    # Viewport dimensions
+    viewport_x: float = 0.0
+    viewport_y: float = 0.0
+    viewport_width: float = 0.0
+    viewport_height: float = 0.0
+
+    # Content dimensions (scrollable area)
+    content_width: float = 0.0
+    content_height: float = 0.0
+
+    # Device scale factor
+    device_scale_factor: float = 1.0
+
+
+@runtime_checkable
+class BrowserBackend(Protocol):
+    """
+    Minimal backend protocol for v0 proof-of-concept.
+
+    This is enough to:
+    - Take Sentience snapshots (DOM/geometry via extension)
+    - Execute JavaScript for element interaction
+    - Perform mouse operations (move, click, scroll)
+    - Wait for page stability
+
+    Implementers:
+    - CDPBackendV0: For browser-use integration via CDP
+    - PlaywrightBackend: Wrapper around existing SentienceBrowser (future)
+    """
+
+    async def refresh_page_info(self) -> ViewportInfo:
+        """
+        Cache viewport + scroll offsets + url; cheap & safe to call often.
+
+        Returns:
+            ViewportInfo with current viewport state
+        """
+        ...
+
+    async def eval(self, expression: str) -> Any:
+        """
+        Evaluate JavaScript expression in page context.
+
+        Uses CDP Runtime.evaluate with returnByValue=True.
+
+        Args:
+            expression: JavaScript expression to evaluate
+
+        Returns:
+            Result value (JSON-serializable)
+        """
+        ...
+
+    async def call(
+        self,
+        function_declaration: str,
+        args: list[Any] | None = None,
+    ) -> Any:
+        """
+        Call a JavaScript function with arguments.
+
+        Uses CDP Runtime.callFunctionOn for safe argument passing.
+        Safer than eval() for passing complex arguments.
+
+        Args:
+            function_declaration: JavaScript function body, e.g., "(x, y) => x + y"
+            args: Arguments to pass to the function
+
+        Returns:
+            Result value (JSON-serializable)
+        """
+        ...
+
+    async def get_layout_metrics(self) -> LayoutMetrics:
+        """
+        Get page layout metrics.
+
+        Uses CDP Page.getLayoutMetrics to get viewport and content dimensions.
+
+        Returns:
+            LayoutMetrics with viewport and content size info
+        """
+        ...
+
+    async def screenshot_png(self) -> bytes:
+        """
+        Capture viewport screenshot as PNG bytes.
+
+        Uses CDP Page.captureScreenshot.
+
+        Returns:
+            PNG image bytes
+        """
+        ...
+
+    async def mouse_move(self, x: float, y: float) -> None:
+        """
+        Move mouse to viewport coordinates.
+
+        Uses CDP Input.dispatchMouseEvent with type="mouseMoved".
+
+        Args:
+            x: X coordinate in viewport
+            y: Y coordinate in viewport
+        """
+        ...
+
+    async def mouse_click(
+        self,
+        x: float,
+        y: float,
+        button: Literal["left", "right", "middle"] = "left",
+        click_count: int = 1,
+    ) -> None:
+        """
+        Click at viewport coordinates.
+
+        Uses CDP Input.dispatchMouseEvent with mousePressed + mouseReleased.
+
+        Args:
+            x: X coordinate in viewport
+            y: Y coordinate in viewport
+            button: Mouse button to click
+            click_count: Number of clicks (1 for single, 2 for double)
+        """
+        ...
+
+    async def wheel(
+        self,
+        delta_y: float,
+        x: float | None = None,
+        y: float | None = None,
+    ) -> None:
+        """
+        Scroll using mouse wheel.
+
+        Uses CDP Input.dispatchMouseEvent with type="mouseWheel".
+
+        Args:
+            delta_y: Scroll amount (positive = down, negative = up)
+            x: X coordinate for scroll (default: viewport center)
+            y: Y coordinate for scroll (default: viewport center)
+        """
+        ...
+
+    async def type_text(self, text: str) -> None:
+        """
+        Type text using keyboard input.
+
+        Uses CDP Input.dispatchKeyEvent for each character.
+
+        Args:
+            text: Text to type
+        """
+        ...
+
+    async def wait_ready_state(
+        self,
+        state: Literal["interactive", "complete"] = "interactive",
+        timeout_ms: int = 15000,
+    ) -> None:
+        """
+        Wait for document.readyState to reach target state.
+
+        Uses polling instead of CDP events (no leak from unregistered listeners).
+
+        Args:
+            state: Target state ("interactive" or "complete")
+            timeout_ms: Maximum time to wait in milliseconds
+
+        Raises:
+            TimeoutError: If state not reached within timeout
+        """
+        ...
+
+    async def get_url(self) -> str:
+        """
+        Get current page URL.
+
+        Returns:
+            Current page URL (window.location.href)
+        """
+        ...