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

sentience/__init__.py

@@ -2,9 +2,39 @@
 Sentience Python SDK - AI Agent Browser Automation
 """
 
-from .actions import click, click_rect, press, type_text
+# Extension helpers (for browser-use integration)
+from ._extension_loader import (
+    get_extension_dir,
+    get_extension_version,
+    verify_extension_injected,
+    verify_extension_injected_async,
+    verify_extension_version,
+    verify_extension_version_async,
+)
+from .actions import click, click_rect, press, scroll_to, type_text
 from .agent import SentienceAgent, SentienceAgentAsync
 from .agent_config import AgentConfig
+from .agent_runtime import AgentRuntime, AssertionHandle
+
+# Backend-agnostic actions (aliased to avoid conflict with existing actions)
+# Browser backends (for browser-use integration)
+from .backends import (
+    BrowserBackend,
+    BrowserUseAdapter,
+    BrowserUseCDPTransport,
+    CachedSnapshot,
+    CDPBackendV0,
+    CDPTransport,
+    LayoutMetrics,
+    PlaywrightBackend,
+    ViewportInfo,
+)
+from .backends import click as backend_click
+from .backends import scroll as backend_scroll
+from .backends import scroll_to_element as backend_scroll_to_element
+from .backends import snapshot as backend_snapshot
+from .backends import type_text as backend_type_text
+from .backends import wait_for_stable as backend_wait_for_stable
 
 # Agent Layer (Phase 1 & 2)
 from .base_agent import BaseAgent
@@ -13,6 +43,7 @@ from .browser import SentienceBrowser
 # Tracing (v0.12.0+)
 from .cloud_tracing import CloudTraceSink, SentienceLogger
 from .conversational_agent import ConversationalAgent
+from .cursor_policy import CursorPolicy
 from .expect import expect
 from .generator import ScriptGenerator, generate
 from .inspector import Inspector, inspect
@@ -21,6 +52,8 @@ from .llm_provider import (
     LLMProvider,
     LLMResponse,
     LocalLLMProvider,
+    LocalVisionLLMProvider,
+    MLXVLMProvider,
     OpenAIProvider,
 )
 from .models import (  # Agent Layer Models
@@ -47,6 +80,9 @@ from .models import (  # Agent Layer Models
     ViewportRect,
     WaitResult,
 )
+
+# Ordinal support (Phase 3)
+from .ordinal import OrdinalIntent, boost_ordinal_elements, detect_ordinal_intent, select_by_ordinal
 from .overlay import clear_overlay, show_overlay
 from .query import find, query
 from .read import read
@@ -70,12 +106,59 @@ from .utils import (
 
 # Formatting (v0.12.0+)
 from .utils.formatting import format_snapshot_for_llm
+
+# Verification (agent assertion loop)
+from .verification import (
+    AssertContext,
+    AssertOutcome,
+    Predicate,
+    all_of,
+    any_of,
+    custom,
+    element_count,
+    exists,
+    is_checked,
+    is_collapsed,
+    is_disabled,
+    is_enabled,
+    is_expanded,
+    is_unchecked,
+    not_exists,
+    url_contains,
+    url_matches,
+    value_contains,
+    value_equals,
+)
 from .visual_agent import SentienceVisualAgent, SentienceVisualAgentAsync
 from .wait import wait_for
 
-__version__ = "0.92.2"
+__version__ = "0.98.0"
 
 __all__ = [
+    # Extension helpers (for browser-use integration)
+    "get_extension_dir",
+    "get_extension_version",
+    "verify_extension_injected",
+    "verify_extension_injected_async",
+    "verify_extension_version",
+    "verify_extension_version_async",
+    # Browser backends (for browser-use integration)
+    "BrowserBackend",
+    "CDPTransport",
+    "CDPBackendV0",
+    "PlaywrightBackend",
+    "BrowserUseAdapter",
+    "BrowserUseCDPTransport",
+    "ViewportInfo",
+    "LayoutMetrics",
+    "backend_snapshot",
+    "CachedSnapshot",
+    # Backend-agnostic actions (prefixed to avoid conflicts)
+    "backend_click",
+    "backend_type_text",
+    "backend_scroll",
+    "backend_scroll_to_element",
+    "backend_wait_for_stable",
     # Core SDK
     "SentienceBrowser",
     "Snapshot",
@@ -90,7 +173,9 @@ __all__ = [
     "click",
     "type_text",
     "press",
+    "scroll_to",
     "click_rect",
+    "CursorPolicy",
     "wait_for",
     "expect",
     "Inspector",
@@ -119,6 +204,8 @@ __all__ = [
     "OpenAIProvider",
     "AnthropicProvider",
     "LocalLLMProvider",
+    "LocalVisionLLMProvider",
+    "MLXVLMProvider",
     "SentienceAgent",
     "SentienceAgentAsync",
     "SentienceVisualAgent",
@@ -159,4 +246,22 @@ __all__ = [
     # Enums
     "SentienceMethod",
     "AgentAction",
+    # Verification (agent assertion loop)
+    "AgentRuntime",
+    "AssertContext",
+    "AssertOutcome",
+    "Predicate",
+    "url_matches",
+    "url_contains",
+    "exists",
+    "not_exists",
+    "element_count",
+    "all_of",
+    "any_of",
+    "custom",
+    # Ordinal support (Phase 3)
+    "OrdinalIntent",
+    "detect_ordinal_intent",
+    "select_by_ordinal",
+    "boost_ordinal_elements",
 ]

sentience/_extension_loader.py

@@ -1,8 +1,19 @@
 """
-Shared extension loading logic for sync and async implementations
+Shared extension loading logic for sync and async implementations.
+
+Provides:
+- get_extension_dir(): Returns path to bundled extension (for browser-use integration)
+- verify_extension_injected(): Verifies window.sentience API is available
+- get_extension_version(): Gets extension version from manifest
+- verify_extension_version(): Checks SDK-extension version compatibility
 """
 
+import json
 from pathlib import Path
+from typing import TYPE_CHECKING, Any
+
+if TYPE_CHECKING:
+    from .protocols import AsyncPageProtocol, PageProtocol
 
 
 def find_extension_path() -> Path:
@@ -38,3 +49,147 @@ def find_extension_path() -> Path:
             f"2. {dev_ext_path}\n"
             "Make sure the extension is built and 'sentience/extension' directory exists."
         )
+
+
+def get_extension_dir() -> str:
+    """
+    Get path to the bundled Sentience extension directory.
+
+    Use this to load the extension into browser-use or other Chromium-based browsers:
+
+        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)
+
+    Returns:
+        Absolute path to extension directory as string
+
+    Raises:
+        FileNotFoundError: If extension not found in package
+    """
+    return str(find_extension_path())
+
+
+def get_extension_version() -> str:
+    """
+    Get the version of the bundled extension from manifest.json.
+
+    Returns:
+        Version string (e.g., "2.2.0")
+
+    Raises:
+        FileNotFoundError: If extension or manifest not found
+    """
+    ext_path = find_extension_path()
+    manifest_path = ext_path / "manifest.json"
+    with open(manifest_path) as f:
+        manifest = json.load(f)
+    return manifest.get("version", "unknown")
+
+
+def verify_extension_injected(page: "PageProtocol") -> bool:
+    """
+    Verify the Sentience extension injected window.sentience API (sync).
+
+    Call this after navigating to a page to confirm the extension is working:
+
+        browser.goto("https://example.com")
+        if not verify_extension_injected(browser.page):
+            raise RuntimeError("Extension not injected")
+
+    Args:
+        page: Playwright Page object (sync)
+
+    Returns:
+        True if window.sentience.snapshot is available, False otherwise
+    """
+    try:
+        result = page.evaluate(
+            "(() => !!(window.sentience && typeof window.sentience.snapshot === 'function'))()"
+        )
+        return bool(result)
+    except Exception:
+        return False
+
+
+async def verify_extension_injected_async(page: "AsyncPageProtocol") -> bool:
+    """
+    Verify the Sentience extension injected window.sentience API (async).
+
+    Call this after navigating to a page to confirm the extension is working:
+
+        await browser.goto("https://example.com")
+        if not await verify_extension_injected_async(browser.page):
+            raise RuntimeError("Extension not injected")
+
+    Args:
+        page: Playwright Page object (async)
+
+    Returns:
+        True if window.sentience.snapshot is available, False otherwise
+    """
+    try:
+        result = await page.evaluate(
+            "(() => !!(window.sentience && typeof window.sentience.snapshot === 'function'))()"
+        )
+        return bool(result)
+    except Exception:
+        return False
+
+
+def verify_extension_version(page: "PageProtocol", expected: str | None = None) -> str | None:
+    """
+    Check extension version exposed in page (sync).
+
+    The extension sets window.__SENTIENCE_EXTENSION_VERSION__ when injected.
+
+    Args:
+        page: Playwright Page object (sync)
+        expected: If provided, raises RuntimeError on mismatch
+
+    Returns:
+        Version string if found, None if not set (page may not have injected yet)
+
+    Raises:
+        RuntimeError: If expected version provided and doesn't match
+    """
+    try:
+        got = page.evaluate("window.__SENTIENCE_EXTENSION_VERSION__ || null")
+    except Exception:
+        got = None
+
+    if expected and got and got != expected:
+        raise RuntimeError(f"Sentience extension version mismatch: expected {expected}, got {got}")
+    return got
+
+
+async def verify_extension_version_async(
+    page: "AsyncPageProtocol", expected: str | None = None
+) -> str | None:
+    """
+    Check extension version exposed in page (async).
+
+    The extension sets window.__SENTIENCE_EXTENSION_VERSION__ when injected.
+
+    Args:
+        page: Playwright Page object (async)
+        expected: If provided, raises RuntimeError on mismatch
+
+    Returns:
+        Version string if found, None if not set (page may not have injected yet)
+
+    Raises:
+        RuntimeError: If expected version provided and doesn't match
+    """
+    try:
+        got = await page.evaluate("window.__SENTIENCE_EXTENSION_VERSION__ || null")
+    except Exception:
+        got = None
+
+    if expected and got and got != expected:
+        raise RuntimeError(f"Sentience extension version mismatch: expected {expected}, got {got}")
+    return got

sentience/action_executor.py

@@ -96,6 +96,7 @@ class ActionExecutor:
                 "element_id": element_id,
                 "outcome": result.outcome,
                 "url_changed": result.url_changed,
+                "cursor": getattr(result, "cursor", None),
             }
 
         # Parse TYPE(42, "hello world")
@@ -170,6 +171,7 @@ class ActionExecutor:
                 "element_id": element_id,
                 "outcome": result.outcome,
                 "url_changed": result.url_changed,
+                "cursor": getattr(result, "cursor", None),
             }
 
         # Parse TYPE(42, "hello world")