predicate-runtime-python/predicate/backends/__init__.py at 4aa3490de84fd8ea161a343cd34146aaa57a80fb · PredicateSystems/predicate-runtime-python · GitHub

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
"""
Browser backend abstractions for Sentience SDK.

This module provides backend protocols and implementations that allow
Sentience actions (click, type, scroll) to work with different browser
automation frameworks.

Supported Backends
------------------

**PlaywrightBackend**
    Wraps Playwright Page objects. Use this when integrating with existing
    SentienceBrowser or Playwright-based code.

**CDPBackendV0**
    Low-level CDP (Chrome DevTools Protocol) backend. Use this when you have
    direct access to a CDP client and session.

**BrowserUseAdapter**
    High-level adapter for browser-use framework. Automatically creates a
    CDPBackendV0 from a BrowserSession.

Quick Start with browser-use
----------------------------

.. code-block:: python

    from browser_use import BrowserSession, BrowserProfile
    from predicate import get_extension_dir, find
    from predicate.backends import BrowserUseAdapter, snapshot, click, type_text

    # Setup browser-use with Sentience extension
    profile = BrowserProfile(args=[f"--load-extension={get_extension_dir()}"])
    session = BrowserSession(browser_profile=profile)
    await session.start()

    # Create adapter and backend
    adapter = BrowserUseAdapter(session)
    backend = await adapter.create_backend()

    # Take snapshot and interact with elements
    snap = await snapshot(backend)
    search_box = find(snap, 'role=textbox[name*="Search"]')
    await click(backend, search_box.bbox)
    await type_text(backend, "Sentience AI")

Snapshot Caching
----------------

Use CachedSnapshot to reduce redundant snapshot calls in action loops:

.. code-block:: python

    from predicate.backends import CachedSnapshot

    cache = CachedSnapshot(backend, max_age_ms=2000)

    snap1 = await cache.get()  # Takes fresh snapshot
    snap2 = await cache.get()  # Returns cached if < 2s old

    await click(backend, element.bbox)
    cache.invalidate()  # Force refresh on next get()

Error Handling
--------------

The module provides specific exceptions for common failure modes:

- ``ExtensionNotLoadedError``: Extension not loaded in browser launch args
- ``SnapshotError``: window.sentience.snapshot() failed
- ``ActionError``: Click/type/scroll operation failed

All exceptions inherit from ``SentienceBackendError`` and include helpful
fix suggestions in their error messages.

.. code-block:: python

    from predicate.backends import ExtensionNotLoadedError, snapshot

    try:
        snap = await snapshot(backend)
    except ExtensionNotLoadedError as e:
        print(f"Fix suggestion: {e}")
"""

from .actions import click, scroll, scroll_to_element, type_text, wait_for_stable
from .browser_use_adapter import BrowserUseAdapter, BrowserUseCDPTransport
from .cdp_backend import CDPBackendV0, CDPTransport
from .exceptions import (
    ActionError,
    BackendEvalError,
    ExtensionDiagnostics,
    ExtensionInjectionError,
    ExtensionNotLoadedError,
    SentienceBackendError,
    SnapshotError,
)
from .playwright_backend import PlaywrightBackend
from .protocol import BrowserBackend, LayoutMetrics, ViewportInfo
from .sentience_context import (
    PredicateContext,
    PredicateContextState,
    SentienceContext,
    SentienceContextState,
    TopElementSelector,
)
from .snapshot import CachedSnapshot, snapshot

__all__ = [
    # Protocol
    "BrowserBackend",
    # Models
    "ViewportInfo",
    "LayoutMetrics",
    # CDP Backend
    "CDPTransport",
    "CDPBackendV0",
    # Playwright Backend
    "PlaywrightBackend",
    # browser-use adapter
    "BrowserUseAdapter",
    "BrowserUseCDPTransport",
    # SentienceContext (Token-Slasher Context Middleware)
    "SentienceContext",
    "SentienceContextState",
    # PredicateContext (rebrand alias)
    "PredicateContext",
    "PredicateContextState",
    "TopElementSelector",
    # Backend-agnostic functions
    "snapshot",
    "CachedSnapshot",
    "click",
    "type_text",
    "scroll",
    "scroll_to_element",
    "wait_for_stable",
    # Exceptions
    "SentienceBackendError",
    "ExtensionNotLoadedError",
    "ExtensionInjectionError",
    "ExtensionDiagnostics",
    "BackendEvalError",
    "SnapshotError",
    "ActionError",
]