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

sentience/overlay.py

@@ -2,9 +2,9 @@
 Visual overlay utilities - show/clear element highlights in browser
 """
 
-from typing import Any
+from typing import Any, Optional
 
-from .browser import SentienceBrowser
+from .browser import AsyncSentienceBrowser, SentienceBrowser
 from .models import Element, Snapshot
 
 
@@ -113,3 +113,110 @@ def clear_overlay(browser: SentienceBrowser) -> None:
         }
         """
     )
+
+
+async def show_overlay_async(
+    browser: AsyncSentienceBrowser,
+    elements: list[Element] | list[dict[str, Any]] | Snapshot,
+    target_element_id: int | None = None,
+) -> None:
+    """
+    Display visual overlay highlighting elements in the browser (async)
+
+    This function shows a Shadow DOM overlay with color-coded borders around
+    detected elements. Useful for debugging, learning, and validating element detection.
+
+    Args:
+        browser: AsyncSentienceBrowser instance
+        elements: Can be:
+            - List of Element objects (from snapshot.elements)
+            - List of raw element dicts (from snapshot result or API response)
+            - Snapshot object (will use snapshot.elements)
+        target_element_id: Optional ID of element to highlight in red (default: None)
+
+    Color Coding:
+        - Red: Target element (when target_element_id is specified)
+        - Blue: Primary elements (is_primary=true)
+        - Green: Regular interactive elements
+
+    Visual Indicators:
+        - Border thickness and opacity scale with importance score
+        - Semi-transparent fill for better visibility
+        - Importance badges showing scores
+        - Star icon for primary elements
+        - Target emoji for the target element
+
+    Auto-clear: Overlay automatically disappears after 5 seconds
+
+    Example:
+        # Show overlay from snapshot
+        snap = await snapshot_async(browser)
+        await show_overlay_async(browser, snap)
+
+        # Show overlay with custom elements
+        elements = [{"id": 1, "bbox": {"x": 100, "y": 100, "width": 200, "height": 50}, ...}]
+        await show_overlay_async(browser, elements)
+
+        # Show overlay with target element highlighted in red
+        await show_overlay_async(browser, snap, target_element_id=42)
+
+        # Clear overlay manually before 5 seconds
+        await clear_overlay_async(browser)
+    """
+    if not browser.page:
+        raise RuntimeError("Browser not started. Call await browser.start() first.")
+
+    # Handle different input types
+    if isinstance(elements, Snapshot):
+        # Extract elements from Snapshot object
+        elements_list = [el.model_dump() for el in elements.elements]
+    elif isinstance(elements, list) and len(elements) > 0:
+        # Check if it's a list of Element objects or dicts
+        if hasattr(elements[0], "model_dump"):
+            # List of Element objects
+            elements_list = [el.model_dump() for el in elements]
+        else:
+            # Already a list of dicts
+            elements_list = elements
+    else:
+        raise ValueError("elements must be a Snapshot, list of Element objects, or list of dicts")
+
+    # Call extension API
+    await browser.page.evaluate(
+        """
+        (args) => {
+            if (window.sentience && window.sentience.showOverlay) {
+                window.sentience.showOverlay(args.elements, args.targetId);
+            } else {
+                console.warn('[Sentience SDK] showOverlay not available - is extension loaded?');
+            }
+        }
+        """,
+        {"elements": elements_list, "targetId": target_element_id},
+    )
+
+
+async def clear_overlay_async(browser: AsyncSentienceBrowser) -> None:
+    """
+    Clear the visual overlay manually (before 5-second auto-clear) (async)
+
+    Args:
+        browser: AsyncSentienceBrowser instance
+
+    Example:
+        await show_overlay_async(browser, snap)
+        # ... inspect overlay ...
+        await clear_overlay_async(browser)  # Remove immediately
+    """
+    if not browser.page:
+        raise RuntimeError("Browser not started. Call await browser.start() first.")
+
+    await browser.page.evaluate(
+        """
+        () => {
+            if (window.sentience && window.sentience.clearOverlay) {
+                window.sentience.clearOverlay();
+            }
+        }
+        """
+    )

sentience/protocols.py

@@ -0,0 +1,228 @@
+"""
+Protocol definitions for testability and dependency injection.
+
+These protocols define the minimal interface required by agent classes,
+enabling better testability through mocking while maintaining type safety.
+"""
+
+from typing import TYPE_CHECKING, Any, Optional, Protocol, runtime_checkable
+
+if TYPE_CHECKING:
+    from playwright.async_api import Page as AsyncPage
+    from playwright.sync_api import Page
+
+    from .models import Snapshot
+
+
+@runtime_checkable
+class PageProtocol(Protocol):
+    """
+    Protocol for Playwright Page operations used by agents.
+
+    This protocol defines the minimal interface required from Playwright's Page object.
+    Agents use this interface to interact with the browser page.
+    """
+
+    @property
+    def url(self) -> str:
+        """Current page URL."""
+        ...
+
+    def evaluate(self, script: str, *args: Any, **kwargs: Any) -> Any:
+        """
+        Evaluate JavaScript in the page context.
+
+        Args:
+            script: JavaScript code to evaluate
+            *args: Arguments to pass to the script
+            **kwargs: Keyword arguments to pass to the script
+
+        Returns:
+            Result of the JavaScript evaluation
+        """
+        ...
+
+    def goto(self, url: str, **kwargs: Any) -> Any | None:
+        """
+        Navigate to a URL.
+
+        Args:
+            url: URL to navigate to
+            **kwargs: Additional navigation options
+
+        Returns:
+            Response object or None
+        """
+        ...
+
+    def wait_for_timeout(self, timeout: int) -> None:
+        """
+        Wait for a specified timeout.
+
+        Args:
+            timeout: Timeout in milliseconds
+        """
+        ...
+
+    def wait_for_load_state(self, state: str = "load", timeout: int | None = None) -> None:
+        """
+        Wait for page load state.
+
+        Args:
+            state: Load state to wait for (e.g., "load", "domcontentloaded", "networkidle")
+            timeout: Optional timeout in milliseconds
+        """
+        ...
+
+
+@runtime_checkable
+class BrowserProtocol(Protocol):
+    """
+    Protocol for browser operations used by agents.
+
+    This protocol defines the minimal interface required from SentienceBrowser.
+    Agents use this interface to interact with the browser and take snapshots.
+
+    Note: SentienceBrowser naturally implements this protocol, so no changes
+    are required to existing code. This protocol enables better testability
+    through mocking.
+    """
+
+    @property
+    def page(self) -> PageProtocol | None:
+        """
+        Current Playwright Page object.
+
+        Returns:
+            Page object if browser is started, None otherwise
+        """
+        ...
+
+    def start(self) -> None:
+        """Start the browser session."""
+        ...
+
+    def close(self, output_path: str | None = None) -> str | None:
+        """
+        Close the browser session.
+
+        Args:
+            output_path: Optional path to save browser state/output
+
+        Returns:
+            Path to saved output or None
+        """
+        ...
+
+    def goto(self, url: str) -> None:
+        """
+        Navigate to a URL.
+
+        Args:
+            url: URL to navigate to
+        """
+        ...
+
+
+@runtime_checkable
+class AsyncPageProtocol(Protocol):
+    """
+    Protocol for async Playwright Page operations.
+
+    Similar to PageProtocol but for async operations.
+    """
+
+    @property
+    def url(self) -> str:
+        """Current page URL."""
+        ...
+
+    async def evaluate(self, script: str, *args: Any, **kwargs: Any) -> Any:
+        """
+        Evaluate JavaScript in the page context (async).
+
+        Args:
+            script: JavaScript code to evaluate
+            *args: Arguments to pass to the script
+            **kwargs: Keyword arguments to pass to the script
+
+        Returns:
+            Result of the JavaScript evaluation
+        """
+        ...
+
+    async def goto(self, url: str, **kwargs: Any) -> Any | None:
+        """
+        Navigate to a URL (async).
+
+        Args:
+            url: URL to navigate to
+            **kwargs: Additional navigation options
+
+        Returns:
+            Response object or None
+        """
+        ...
+
+    async def wait_for_timeout(self, timeout: int) -> None:
+        """
+        Wait for a specified timeout (async).
+
+        Args:
+            timeout: Timeout in milliseconds
+        """
+        ...
+
+    async def wait_for_load_state(self, state: str = "load", timeout: int | None = None) -> None:
+        """
+        Wait for page load state (async).
+
+        Args:
+            state: Load state to wait for (e.g., "load", "domcontentloaded", "networkidle")
+            timeout: Optional timeout in milliseconds
+        """
+        ...
+
+
+@runtime_checkable
+class AsyncBrowserProtocol(Protocol):
+    """
+    Protocol for async browser operations.
+
+    Similar to BrowserProtocol but for async operations.
+    """
+
+    @property
+    def page(self) -> AsyncPageProtocol | None:
+        """
+        Current Playwright AsyncPage object.
+
+        Returns:
+            AsyncPage object if browser is started, None otherwise
+        """
+        ...
+
+    async def start(self) -> None:
+        """Start the browser session (async)."""
+        ...
+
+    async def close(self, output_path: str | None = None) -> str | None:
+        """
+        Close the browser session (async).
+
+        Args:
+            output_path: Optional path to save browser state/output
+
+        Returns:
+            Path to saved output or None
+        """
+        ...
+
+    async def goto(self, url: str) -> None:
+        """
+        Navigate to a URL (async).
+
+        Args:
+            url: URL to navigate to
+        """
+        ...

sentience/query.py

@@ -3,7 +3,7 @@ Query engine v1 - semantic selector matching
 """
 
 import re
-from typing import Any
+from typing import Any, Optional
 
 from .models import Element, Snapshot
 

sentience/read.py

@@ -4,14 +4,15 @@ Read page content - supports raw HTML, text, and markdown formats
 
 from typing import Literal
 
-from .browser import SentienceBrowser
+from .browser import AsyncSentienceBrowser, SentienceBrowser
+from .models import ReadResult
 
 
 def read(
     browser: SentienceBrowser,
     output_format: Literal["raw", "text", "markdown"] = "raw",
     enhance_markdown: bool = True,
-) -> dict:
+) -> ReadResult:
     """
     Read page content as raw HTML, text, or markdown
 
@@ -93,4 +94,95 @@ def read(
         {"format": output_format},
     )
 
-    return result
+    # Convert dict result to ReadResult model
+    return ReadResult(**result)
+
+
+async def read_async(
+    browser: AsyncSentienceBrowser,
+    output_format: Literal["raw", "text", "markdown"] = "raw",
+    enhance_markdown: bool = True,
+) -> ReadResult:
+    """
+    Read page content as raw HTML, text, or markdown (async)
+
+    Args:
+        browser: AsyncSentienceBrowser instance
+        output_format: Output format - "raw" (default, returns HTML for external processing),
+                        "text" (plain text), or "markdown" (lightweight or enhanced markdown).
+        enhance_markdown: If True and output_format is "markdown", uses markdownify for better conversion.
+                          If False, uses the extension's lightweight markdown converter.
+
+    Returns:
+        dict with:
+            - status: "success" or "error"
+            - url: Current page URL
+            - format: "raw", "text", or "markdown"
+            - content: Page content as string
+            - length: Content length in characters
+            - error: Error message if status is "error"
+
+    Examples:
+        # Get raw HTML (default) - can be used with markdownify for better conversion
+        result = await read_async(browser)
+        html_content = result["content"]
+
+        # Get high-quality markdown (uses markdownify internally)
+        result = await read_async(browser, output_format="markdown")
+        markdown = result["content"]
+
+        # Get plain text
+        result = await read_async(browser, output_format="text")
+        text = result["content"]
+    """
+    if not browser.page:
+        raise RuntimeError("Browser not started. Call await browser.start() first.")
+
+    if output_format == "markdown" and enhance_markdown:
+        # Get raw HTML from the extension first
+        raw_html_result = await browser.page.evaluate(
+            """
+            (options) => {
+                return window.sentience.read(options);
+            }
+            """,
+            {"format": "raw"},
+        )
+
+        if raw_html_result.get("status") == "success":
+            html_content = raw_html_result["content"]
+            try:
+                # Use markdownify for enhanced markdown conversion
+                from markdownify import MarkdownifyError, markdownify
+
+                markdown_content = markdownify(html_content, heading_style="ATX", wrap=True)
+                return {
+                    "status": "success",
+                    "url": raw_html_result["url"],
+                    "format": "markdown",
+                    "content": markdown_content,
+                    "length": len(markdown_content),
+                }
+            except ImportError:
+                print(
+                    "Warning: 'markdownify' not installed. Install with 'pip install markdownify' for enhanced markdown. Falling back to extension's markdown."
+                )
+            except MarkdownifyError as e:
+                print(f"Warning: markdownify failed ({e}), falling back to extension's markdown.")
+            except Exception as e:
+                print(
+                    f"Warning: An unexpected error occurred with markdownify ({e}), falling back to extension's markdown."
+                )
+
+    # If not enhanced markdown, or fallback, call extension with requested format
+    result = await browser.page.evaluate(
+        """
+        (options) => {
+            return window.sentience.read(options);
+        }
+        """,
+        {"format": output_format},
+    )
+
+    # Convert dict result to ReadResult model
+    return ReadResult(**result)