sentienceapi 0.95.0__py3-none-any.whl

sentience/browser_evaluator.py

@@ -0,0 +1,299 @@
+"""
+Browser evaluation helper for common window.sentience API patterns.
+
+Consolidates repeated patterns for:
+- Waiting for extension injection
+- Calling window.sentience methods
+- Error handling with diagnostics
+"""
+
+from typing import Any, Optional, Union
+
+from playwright.async_api import Page as AsyncPage
+from playwright.sync_api import Page
+
+from .browser import AsyncSentienceBrowser, SentienceBrowser
+from .sentience_methods import SentienceMethod
+
+
+class BrowserEvaluator:
+    """Helper class for common browser evaluation patterns"""
+
+    @staticmethod
+    def wait_for_extension(
+        page: Page | AsyncPage,
+        timeout_ms: int = 5000,
+    ) -> None:
+        """
+        Wait for window.sentience API to be available.
+
+        Args:
+            page: Playwright Page instance (sync or async)
+            timeout_ms: Timeout in milliseconds (default: 5000)
+
+        Raises:
+            RuntimeError: If extension fails to inject within timeout
+        """
+        if hasattr(page, "wait_for_function"):
+            # Sync page
+            try:
+                page.wait_for_function(
+                    "typeof window.sentience !== 'undefined'",
+                    timeout=timeout_ms,
+                )
+            except Exception as e:
+                diag = BrowserEvaluator._gather_diagnostics(page)
+                raise RuntimeError(
+                    f"Sentience extension failed to inject window.sentience API. "
+                    f"Is the extension loaded? Diagnostics: {diag}"
+                ) from e
+        else:
+            # Async page - should use async version
+            raise TypeError("Use wait_for_extension_async for async pages")
+
+    @staticmethod
+    async def wait_for_extension_async(
+        page: AsyncPage,
+        timeout_ms: int = 5000,
+    ) -> None:
+        """
+        Wait for window.sentience API to be available (async).
+
+        Args:
+            page: Playwright AsyncPage instance
+            timeout_ms: Timeout in milliseconds (default: 5000)
+
+        Raises:
+            RuntimeError: If extension fails to inject within timeout
+        """
+        try:
+            await page.wait_for_function(
+                "typeof window.sentience !== 'undefined'",
+                timeout=timeout_ms,
+            )
+        except Exception as e:
+            diag = await BrowserEvaluator._gather_diagnostics_async(page)
+            raise RuntimeError(
+                f"Sentience extension failed to inject window.sentience API. "
+                f"Is the extension loaded? Diagnostics: {diag}"
+            ) from e
+
+    @staticmethod
+    def _gather_diagnostics(page: Page | AsyncPage) -> dict[str, Any]:
+        """
+        Gather diagnostics about extension state.
+
+        Args:
+            page: Playwright Page instance
+
+        Returns:
+            Dictionary with diagnostic information
+        """
+        try:
+            if hasattr(page, "evaluate"):
+                # Sync page
+                return page.evaluate(
+                    """() => ({
+                        sentience_defined: typeof window.sentience !== 'undefined',
+                        extension_id: document.documentElement.dataset.sentienceExtensionId || 'not set',
+                        url: window.location.href
+                    })"""
+                )
+            else:
+                return {"error": "Could not gather diagnostics - invalid page type"}
+        except Exception:
+            return {"error": "Could not gather diagnostics"}
+
+    @staticmethod
+    async def _gather_diagnostics_async(page: AsyncPage) -> dict[str, Any]:
+        """
+        Gather diagnostics about extension state (async).
+
+        Args:
+            page: Playwright AsyncPage instance
+
+        Returns:
+            Dictionary with diagnostic information
+        """
+        try:
+            return await page.evaluate(
+                """() => ({
+                    sentience_defined: typeof window.sentience !== 'undefined',
+                    extension_id: document.documentElement.dataset.sentienceExtensionId || 'not set',
+                    url: window.location.href
+                })"""
+            )
+        except Exception:
+            return {"error": "Could not gather diagnostics"}
+
+    @staticmethod
+    def invoke(
+        page: Page,
+        method: SentienceMethod | str,
+        *args: Any,
+        **kwargs: Any,
+    ) -> Any:
+        """
+        Invoke a window.sentience method with error handling (sync).
+
+        Args:
+            page: Playwright Page instance (sync)
+            method: SentienceMethod enum value or method name string (e.g., SentienceMethod.SNAPSHOT or "snapshot")
+            *args: Positional arguments to pass to the method
+            **kwargs: Keyword arguments to pass to the method
+
+        Returns:
+            Result from the method call
+
+        Raises:
+            RuntimeError: If method is not available or call fails
+
+        Example:
+            ```python
+            result = BrowserEvaluator.invoke(page, SentienceMethod.SNAPSHOT, limit=50)
+            success = BrowserEvaluator.invoke(page, SentienceMethod.CLICK, element_id)
+            ```
+        """
+        # Convert enum to string if needed
+        method_name = method.value if isinstance(method, SentienceMethod) else method
+
+        # Build JavaScript call
+        if args and kwargs:
+            # Both args and kwargs - use object spread
+            js_code = f"""
+            (args, kwargs) => {{
+                return window.sentience.{method_name}(...args, kwargs);
+            }}
+            """
+            result = page.evaluate(js_code, list(args), kwargs)
+        elif args:
+            # Only args
+            js_code = f"""
+            (args) => {{
+                return window.sentience.{method_name}(...args);
+            }}
+            """
+            result = page.evaluate(js_code, list(args))
+        elif kwargs:
+            # Only kwargs - pass as single object
+            js_code = f"""
+            (options) => {{
+                return window.sentience.{method_name}(options);
+            }}
+            """
+            result = page.evaluate(js_code, kwargs)
+        else:
+            # No arguments
+            js_code = f"""
+            () => {{
+                return window.sentience.{method_name}();
+            }}
+            """
+            result = page.evaluate(js_code)
+
+        return result
+
+    @staticmethod
+    async def invoke_async(
+        page: AsyncPage,
+        method: SentienceMethod | str,
+        *args: Any,
+        **kwargs: Any,
+    ) -> Any:
+        """
+        Invoke a window.sentience method with error handling (async).
+
+        Args:
+            page: Playwright AsyncPage instance
+            method: SentienceMethod enum value or method name string (e.g., SentienceMethod.SNAPSHOT or "snapshot")
+            *args: Positional arguments to pass to the method
+            **kwargs: Keyword arguments to pass to the method
+
+        Returns:
+            Result from the method call
+
+        Raises:
+            RuntimeError: If method is not available or call fails
+
+        Example:
+            ```python
+            result = await BrowserEvaluator.invoke_async(page, SentienceMethod.SNAPSHOT, limit=50)
+            success = await BrowserEvaluator.invoke_async(page, SentienceMethod.CLICK, element_id)
+            ```
+        """
+        # Convert enum to string if needed
+        method_name = method.value if isinstance(method, SentienceMethod) else method
+
+        # Build JavaScript call
+        if args and kwargs:
+            js_code = f"""
+            (args, kwargs) => {{
+                return window.sentience.{method_name}(...args, kwargs);
+            }}
+            """
+            result = await page.evaluate(js_code, list(args), kwargs)
+        elif args:
+            js_code = f"""
+            (args) => {{
+                return window.sentience.{method_name}(...args);
+            }}
+            """
+            result = await page.evaluate(js_code, list(args))
+        elif kwargs:
+            js_code = f"""
+            (options) => {{
+                return window.sentience.{method_name}(options);
+            }}
+            """
+            result = await page.evaluate(js_code, kwargs)
+        else:
+            js_code = f"""
+            () => {{
+                return window.sentience.{method_name}();
+            }}
+            """
+            result = await page.evaluate(js_code)
+
+        return result
+
+    @staticmethod
+    def verify_method_exists(
+        page: Page,
+        method: SentienceMethod | str,
+    ) -> bool:
+        """
+        Verify that a window.sentience method exists.
+
+        Args:
+            page: Playwright Page instance (sync)
+            method: SentienceMethod enum value or method name string
+
+        Returns:
+            True if method exists, False otherwise
+        """
+        method_name = method.value if isinstance(method, SentienceMethod) else method
+        try:
+            return page.evaluate(f"typeof window.sentience.{method_name} !== 'undefined'")
+        except Exception:
+            return False
+
+    @staticmethod
+    async def verify_method_exists_async(
+        page: AsyncPage,
+        method: SentienceMethod | str,
+    ) -> bool:
+        """
+        Verify that a window.sentience method exists (async).
+
+        Args:
+            page: Playwright AsyncPage instance
+            method: SentienceMethod enum value or method name string
+
+        Returns:
+            True if method exists, False otherwise
+        """
+        method_name = method.value if isinstance(method, SentienceMethod) else method
+        try:
+            return await page.evaluate(f"typeof window.sentience.{method_name} !== 'undefined'")
+        except Exception:
+            return False

sentience/canonicalization.py

@@ -0,0 +1,207 @@
+"""
+Shared canonicalization utilities for snapshot comparison and indexing.
+
+This module provides consistent normalization functions used by both:
+- trace_indexing/indexer.py (for computing stable digests)
+- snapshot_diff.py (for computing diff_status labels)
+
+By sharing these helpers, we ensure consistent behavior:
+- Same text normalization (whitespace, case, length)
+- Same bbox rounding (2px precision)
+- Same change detection thresholds
+"""
+
+from typing import Any
+
+
+def normalize_text(text: str | None, max_len: int = 80) -> str:
+    """
+    Normalize text for canonical comparison.
+
+    Transforms:
+    - Trims leading/trailing whitespace
+    - Collapses internal whitespace to single spaces
+    - Lowercases
+    - Caps length
+
+    Args:
+        text: Input text (may be None)
+        max_len: Maximum length to retain (default: 80)
+
+    Returns:
+        Normalized text string (empty string if input is None)
+
+    Examples:
+        >>> normalize_text("  Hello   World  ")
+        'hello world'
+        >>> normalize_text(None)
+        ''
+    """
+    if not text:
+        return ""
+    # Trim and collapse whitespace
+    normalized = " ".join(text.split())
+    # Lowercase
+    normalized = normalized.lower()
+    # Cap length
+    if len(normalized) > max_len:
+        normalized = normalized[:max_len]
+    return normalized
+
+
+def round_bbox(bbox: dict[str, float], precision: int = 2) -> dict[str, int]:
+    """
+    Round bbox coordinates to reduce noise.
+
+    Snaps coordinates to grid of `precision` pixels to ignore
+    sub-pixel rendering differences.
+
+    Args:
+        bbox: Bounding box with x, y, width, height
+        precision: Grid size in pixels (default: 2)
+
+    Returns:
+        Rounded bbox with integer coordinates
+
+    Examples:
+        >>> round_bbox({"x": 101, "y": 203, "width": 50, "height": 25})
+        {'x': 100, 'y': 202, 'width': 50, 'height': 24}
+    """
+    return {
+        "x": round(bbox.get("x", 0) / precision) * precision,
+        "y": round(bbox.get("y", 0) / precision) * precision,
+        "width": round(bbox.get("width", 0) / precision) * precision,
+        "height": round(bbox.get("height", 0) / precision) * precision,
+    }
+
+
+def bbox_equal(bbox1: dict[str, Any], bbox2: dict[str, Any], threshold: float = 5.0) -> bool:
+    """
+    Check if two bboxes are equal within a threshold.
+
+    Args:
+        bbox1: First bounding box
+        bbox2: Second bounding box
+        threshold: Maximum allowed difference in pixels (default: 5.0)
+
+    Returns:
+        True if all bbox properties differ by less than threshold
+
+    Examples:
+        >>> bbox_equal({"x": 100, "y": 200, "width": 50, "height": 25},
+        ...            {"x": 102, "y": 200, "width": 50, "height": 25})
+        True  # 2px difference is below 5px threshold
+    """
+    return (
+        abs(bbox1.get("x", 0) - bbox2.get("x", 0)) <= threshold
+        and abs(bbox1.get("y", 0) - bbox2.get("y", 0)) <= threshold
+        and abs(bbox1.get("width", 0) - bbox2.get("width", 0)) <= threshold
+        and abs(bbox1.get("height", 0) - bbox2.get("height", 0)) <= threshold
+    )
+
+
+def bbox_changed(bbox1: dict[str, Any], bbox2: dict[str, Any], threshold: float = 5.0) -> bool:
+    """
+    Check if two bboxes differ beyond the threshold.
+
+    This is the inverse of bbox_equal, provided for semantic clarity
+    in diff detection code.
+
+    Args:
+        bbox1: First bounding box
+        bbox2: Second bounding box
+        threshold: Maximum allowed difference in pixels (default: 5.0)
+
+    Returns:
+        True if any bbox property differs by more than threshold
+    """
+    return not bbox_equal(bbox1, bbox2, threshold)
+
+
+def canonicalize_element(elem: dict[str, Any]) -> dict[str, Any]:
+    """
+    Create canonical representation of an element for comparison/hashing.
+
+    Extracts and normalizes the fields that matter for identity:
+    - id, role, normalized text, rounded bbox
+    - is_primary, is_clickable from visual_cues
+
+    Args:
+        elem: Raw element dictionary
+
+    Returns:
+        Canonical element dictionary with normalized fields
+
+    Examples:
+        >>> canonicalize_element({
+        ...     "id": 1,
+        ...     "role": "button",
+        ...     "text": "  Click Me  ",
+        ...     "bbox": {"x": 101, "y": 200, "width": 50, "height": 25},
+        ...     "visual_cues": {"is_primary": True, "is_clickable": True}
+        ... })
+        {'id': 1, 'role': 'button', 'text_norm': 'click me', 'bbox': {'x': 100, 'y': 200, 'width': 50, 'height': 24}, 'is_primary': True, 'is_clickable': True}
+    """
+    # Extract is_primary and is_clickable from visual_cues if present
+    visual_cues = elem.get("visual_cues", {})
+    is_primary = (
+        visual_cues.get("is_primary", False)
+        if isinstance(visual_cues, dict)
+        else elem.get("is_primary", False)
+    )
+    is_clickable = (
+        visual_cues.get("is_clickable", False)
+        if isinstance(visual_cues, dict)
+        else elem.get("is_clickable", False)
+    )
+
+    return {
+        "id": elem.get("id"),
+        "role": elem.get("role", ""),
+        "text_norm": normalize_text(elem.get("text")),
+        "bbox": round_bbox(elem.get("bbox", {"x": 0, "y": 0, "width": 0, "height": 0})),
+        "is_primary": is_primary,
+        "is_clickable": is_clickable,
+    }
+
+
+def content_equal(elem1: dict[str, Any], elem2: dict[str, Any]) -> bool:
+    """
+    Check if two elements have equal content (ignoring position).
+
+    Compares normalized text, role, and visual cues.
+
+    Args:
+        elem1: First element (raw or canonical)
+        elem2: Second element (raw or canonical)
+
+    Returns:
+        True if content is equal after normalization
+    """
+    # Normalize both elements
+    c1 = canonicalize_element(elem1)
+    c2 = canonicalize_element(elem2)
+
+    return (
+        c1["role"] == c2["role"]
+        and c1["text_norm"] == c2["text_norm"]
+        and c1["is_primary"] == c2["is_primary"]
+        and c1["is_clickable"] == c2["is_clickable"]
+    )
+
+
+def content_changed(elem1: dict[str, Any], elem2: dict[str, Any]) -> bool:
+    """
+    Check if two elements have different content (ignoring position).
+
+    This is the inverse of content_equal, provided for semantic clarity
+    in diff detection code.
+
+    Args:
+        elem1: First element
+        elem2: Second element
+
+    Returns:
+        True if content differs after normalization
+    """
+    return not content_equal(elem1, elem2)

sentience/cli.py

@@ -0,0 +1,130 @@
+"""
+CLI commands for Sentience SDK
+"""
+
+import argparse
+import sys
+
+from .browser import SentienceBrowser
+from .generator import ScriptGenerator
+from .inspector import inspect
+from .recorder import Trace, record
+
+
+def cmd_inspect(args):
+    """Start inspector mode"""
+    browser = SentienceBrowser(headless=False)
+    try:
+        browser.start()
+        print("✅ Inspector started. Hover elements to see info, click to see full details.")
+        print("Press Ctrl+C to stop.")
+
+        with inspect(browser):
+            # Keep running until interrupted
+            import time
+
+            try:
+                while True:
+                    time.sleep(1)
+            except KeyboardInterrupt:
+                print("\n👋 Inspector stopped.")
+    finally:
+        browser.close()
+
+
+def cmd_record(args):
+    """Start recording mode"""
+    browser = SentienceBrowser(headless=False)
+    try:
+        browser.start()
+
+        # Navigate to start URL if provided
+        if args.url:
+            browser.page.goto(args.url)
+            browser.page.wait_for_load_state("networkidle")
+
+        print("✅ Recording started. Perform actions in the browser.")
+        print("Press Ctrl+C to stop and save trace.")
+
+        with record(browser, capture_snapshots=args.snapshots) as rec:
+            # Add mask patterns if provided
+            for pattern in args.mask or []:
+                rec.add_mask_pattern(pattern)
+
+            # Keep running until interrupted
+            import time
+
+            try:
+                while True:
+                    time.sleep(1)
+            except KeyboardInterrupt:
+                print("\n💾 Saving trace...")
+                output = args.output or "trace.json"
+                rec.save(output)
+                print(f"✅ Trace saved to {output}")
+    finally:
+        browser.close()
+
+
+def cmd_gen(args):
+    """Generate script from trace"""
+    # Load trace
+    trace = Trace.load(args.trace)
+
+    # Generate script
+    generator = ScriptGenerator(trace)
+
+    if args.lang == "py":
+        output = args.output or "generated.py"
+        generator.save_python(output)
+    elif args.lang == "ts":
+        output = args.output or "generated.ts"
+        generator.save_typescript(output)
+    else:
+        print(f"❌ Unsupported language: {args.lang}")
+        sys.exit(1)
+
+    print(f"✅ Generated {args.lang.upper()} script: {output}")
+
+
+def main():
+    """Main CLI entry point"""
+    parser = argparse.ArgumentParser(description="Sentience SDK CLI")
+    subparsers = parser.add_subparsers(dest="command", help="Commands")
+
+    # Inspect command
+    inspect_parser = subparsers.add_parser("inspect", help="Start inspector mode")
+    inspect_parser.set_defaults(func=cmd_inspect)
+
+    # Record command
+    record_parser = subparsers.add_parser("record", help="Start recording mode")
+    record_parser.add_argument("--url", help="Start URL")
+    record_parser.add_argument("--output", "-o", help="Output trace file", default="trace.json")
+    record_parser.add_argument(
+        "--snapshots", action="store_true", help="Capture snapshots at each step"
+    )
+    record_parser.add_argument(
+        "--mask",
+        action="append",
+        help="Pattern to mask in recorded text (e.g., password)",
+    )
+    record_parser.set_defaults(func=cmd_record)
+
+    # Generate command
+    gen_parser = subparsers.add_parser("gen", help="Generate script from trace")
+    gen_parser.add_argument("trace", help="Trace JSON file")
+    gen_parser.add_argument("--lang", choices=["py", "ts"], default="py", help="Output language")
+    gen_parser.add_argument("--output", "-o", help="Output script file")
+    gen_parser.set_defaults(func=cmd_gen)
+
+    args = parser.parse_args()
+
+    if not args.command:
+        parser.print_help()
+        sys.exit(1)
+
+    args.func(args)
+
+
+if __name__ == "__main__":
+    main()