sentienceapi 0.95.0__py3-none-any.whl

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)
+        """
+        ...