browser-agent-protocol 0.1.0a1__py3-none-any.whl

browser_agent_protocol-0.1.0a1.dist-info/METADATA

@@ -0,0 +1,306 @@
+Metadata-Version: 2.4
+Name: browser-agent-protocol
+Version: 0.1.0a1
+Summary: Python SDK for the Browser Agent Protocol (BAP) - control browsers with AI agents
+Project-URL: Homepage, https://github.com/anthropics/browser-agent-protocol
+Project-URL: Documentation, https://github.com/anthropics/browser-agent-protocol#readme
+Project-URL: Repository, https://github.com/anthropics/browser-agent-protocol
+Project-URL: Issues, https://github.com/anthropics/browser-agent-protocol/issues
+Author: BAP Contributors
+License: Apache-2.0
+Keywords: agent,ai,automation,browser,json-rpc,llm,mcp,playwright,puppeteer,websocket
+Classifier: Development Status :: 3 - Alpha
+Classifier: Framework :: AsyncIO
+Classifier: Framework :: Pydantic :: 2
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Internet :: WWW/HTTP :: Browsers
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: Software Development :: Testing
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Requires-Dist: aiohttp>=3.9.0
+Requires-Dist: anyio>=4.0.0
+Requires-Dist: httpx-sse>=0.4.0
+Requires-Dist: httpx>=0.27.0
+Requires-Dist: pydantic>=2.0.0
+Provides-Extra: dev
+Requires-Dist: mypy>=1.8.0; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.23.0; extra == 'dev'
+Requires-Dist: pytest>=8.0.0; extra == 'dev'
+Requires-Dist: ruff>=0.1.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# browser-agent-protocol
+
+Python SDK for the Browser Agent Protocol (BAP) - control browsers with AI agents.
+
+## Installation
+
+```bash
+pip install browser-agent-protocol
+```
+
+## Quick Start
+
+### Async API (recommended)
+
+```python
+import asyncio
+from browseragentprotocol import BAPClient, role, text, label
+
+async def main():
+    async with BAPClient("ws://localhost:9222") as client:
+        # Launch browser
+        await client.launch(browser="chromium", headless=True)
+
+        # Create page and navigate
+        await client.create_page(url="https://example.com")
+
+        # Click using semantic selectors
+        await client.click(role("button", "Submit"))
+
+        # Fill form fields
+        await client.fill(label("Email"), "user@example.com")
+
+        # Take screenshot
+        screenshot = await client.screenshot()
+        print(f"Screenshot: {len(screenshot.data)} bytes")
+
+        # Get accessibility tree (ideal for AI agents)
+        tree = await client.accessibility()
+        print(f"Found {len(tree.tree)} nodes")
+
+asyncio.run(main())
+```
+
+### High-Level Session Helper
+
+```python
+from browseragentprotocol.context import bap_session, role
+
+async with bap_session(
+    "ws://localhost:9222",
+    start_url="https://example.com"
+) as client:
+    await client.click(role("button", "Accept"))
+    content = await client.content()
+```
+
+### Sync API (for scripts and notebooks)
+
+```python
+from browseragentprotocol import BAPClientSync, role
+
+with BAPClientSync("ws://localhost:9222") as client:
+    client.launch(browser="chromium", headless=True)
+    client.create_page(url="https://example.com")
+
+    client.click(role("button", "Submit"))
+    screenshot = client.screenshot()
+```
+
+### CLI
+
+```bash
+# Test connection to a BAP server
+bap connect ws://localhost:9222
+
+# Get server info (with JSON output)
+bap info ws://localhost:9222 --json
+```
+
+## Semantic Selectors
+
+BAP uses semantic selectors instead of brittle CSS selectors:
+
+```python
+from browseragentprotocol import role, text, label, css, xpath, test_id, ref
+
+# Recommended: Semantic selectors
+role("button", "Submit")           # ARIA role + accessible name
+text("Sign in")                    # Visible text content
+label("Email address")             # Associated label
+
+# Developer-controlled identifiers
+test_id("submit-button")           # data-testid attribute
+
+# Stable element references
+ref("@submitBtn")                  # Element ref from agent/observe
+
+# Fallback: CSS/XPath
+css(".btn-primary")
+xpath("//button[@type='submit']")
+```
+
+## AI Agent Methods
+
+BAP provides three composite methods optimized for AI agents:
+
+### agent/observe - Get AI-optimized page snapshots
+
+```python
+observation = await client.observe(
+    include_accessibility=True,
+    include_interactive_elements=True,
+    include_screenshot=True,
+    max_elements=50,
+    annotate_screenshot=True,  # Set-of-Marks style annotation
+)
+
+# Interactive elements with stable refs
+for element in observation.interactive_elements:
+    print(f"{element.ref}: {element.role} - {element.name}")
+    # @e1: button - Submit
+    # @e2: textbox - Email
+
+# Screenshot with numbered badges linking to elements
+if observation.annotation_map:
+    for annotation in observation.annotation_map:
+        print(f"[{annotation.label}] -> {annotation.ref}")
+```
+
+### agent/act - Execute multi-step sequences atomically
+
+```python
+from browseragentprotocol import BAPClient
+
+result = await client.act([
+    BAPClient.step("action/fill", {"selector": label("Email"), "value": "user@example.com"}),
+    BAPClient.step("action/fill", {"selector": label("Password"), "value": "secret123"}),
+    BAPClient.step("action/click", {"selector": role("button", "Sign In")}),
+])
+
+print(f"Completed {result.completed}/{result.total} steps")
+print(f"Success: {result.success}")
+```
+
+### agent/extract - Extract structured data
+
+```python
+data = await client.extract(
+    instruction="Extract all product names and prices",
+    schema={
+        "type": "array",
+        "items": {
+            "type": "object",
+            "properties": {
+                "name": {"type": "string"},
+                "price": {"type": "number"},
+            },
+        },
+    },
+)
+
+if data.success:
+    for product in data.data:
+        print(f"{product['name']}: ${product['price']}")
+```
+
+## Multi-Context Support
+
+Create isolated browser contexts with separate cookies/storage:
+
+```python
+# Create isolated context
+context = await client.create_context(
+    context_id="user-session",
+    options={
+        "viewport": {"width": 1920, "height": 1080},
+        "locale": "en-US",
+    },
+)
+
+# Create page in specific context
+page = await client.create_page(
+    url="https://example.com",
+    context_id=context.context_id,
+)
+
+# Clean up
+await client.destroy_context(context.context_id)
+```
+
+## Frame Support
+
+Navigate iframes and cross-origin frames:
+
+```python
+# List frames
+frames = await client.list_frames()
+for frame in frames.frames:
+    print(f"{frame.frame_id}: {frame.url}")
+
+# Switch to iframe
+await client.switch_frame(selector=css("iframe#payment"))
+
+# Interact within frame
+await client.fill(label("Card number"), "4242424242424242")
+
+# Return to main frame
+await client.main_frame()
+```
+
+## Human-in-the-Loop Approval
+
+Handle approval requests for sensitive actions:
+
+```python
+def handle_approval(params):
+    print(f"Approval needed: {params.rule}")
+    print(f"Action: {params.original_request}")
+    # In a real app, show UI to user
+    return "approve"
+
+client.on_approval_required(handle_approval)
+
+# Respond to approval request
+await client.respond_to_approval(
+    request_id="...",
+    decision="approve",  # or "deny", "approve-session"
+    reason="User approved the action",
+)
+```
+
+## Error Handling
+
+```python
+from browseragentprotocol import (
+    BAPError,
+    BAPTimeoutError,
+    BAPElementNotFoundError,
+    BAPApprovalDeniedError,
+)
+
+try:
+    await client.click(role("button", "Missing"))
+except BAPTimeoutError as e:
+    print(f"Timeout: {e.message}")
+    if e.retryable:
+        # Retry the operation
+        pass
+except BAPElementNotFoundError as e:
+    print(f"Element not found: {e.details}")
+except BAPApprovalDeniedError as e:
+    print(f"Action denied: {e.message}")
+except BAPError as e:
+    print(f"Error {e.code}: {e.message}")
+```
+
+## Requirements
+
+- Python 3.10+
+- aiohttp >= 3.9.0
+- pydantic >= 2.0.0
+- anyio >= 4.0.0
+- httpx >= 0.27.0
+- httpx-sse >= 0.4.0
+
+## License
+
+Apache-2.0

browser_agent_protocol-0.1.0a1.dist-info/RECORD

@@ -0,0 +1,20 @@
+browseragentprotocol/__init__.py,sha256=PWyVlexYL0Q4Ox8DGvCYndEl2MN-ZknsSwUINXL5bQY,7669
+browseragentprotocol/cli.py,sha256=TpYhJKrz1ScvlHHfXvWs41AIm2yqXMTG1ATwviTmKq8,4414
+browseragentprotocol/client.py,sha256=m39pP3mGF8DvEVC0qEe3ao2kc_0eQWqOB1Airvk1c1c,51669
+browseragentprotocol/context.py,sha256=7RWsX3VhoNWG3qN4DWCqTRfHaMy8SlbJ_nUOGnZJvzE,3666
+browseragentprotocol/errors.py,sha256=35U5zqDB9RjYRrS3iBfNxENxyJW66Y2eKtHMRag103s,19235
+browseragentprotocol/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+browseragentprotocol/sse.py,sha256=FrrXvGhWDOhFGNy9HW-tKPKrpyg-GXcWWqV94dAvCVA,4567
+browseragentprotocol/sync_client.py,sha256=xsgLTCjl1msEbTOUqnpax2inz-5DXdkZ0-FlCZH-S-o,20652
+browseragentprotocol/transport.py,sha256=fyzIsBXozFV3tmz3Mmxjghg04xugBwC3-wFdm_MqW6U,5934
+browseragentprotocol/types/__init__.py,sha256=FUc9GMiQ8dH1aHx1GlS_9HLbQrkXyyv1ySrW9u63FC4,5336
+browseragentprotocol/types/agent.py,sha256=VjUO_MHW5Xt_7DgG4QgX7_LESGp2YAuDQV0Wdm3M3D0,10681
+browseragentprotocol/types/common.py,sha256=umeZZFUPEDv69zHAusB7AY25DH_xBuQm78tpLfmk_PE,6853
+browseragentprotocol/types/events.py,sha256=eL5zKKSWMX3-fFgnOjQrf20iYm_H1jaIP2qkd4loSP0,4665
+browseragentprotocol/types/methods.py,sha256=cnMPL7VVMaJ9t6xr4_CmDULMyDlNle3bIucwVxZn9Aw,9494
+browseragentprotocol/types/protocol.py,sha256=oHhtgbZAL-b-AfNlCz_iEZu6ZQ9I88_2aV8_3R8WC4E,6085
+browseragentprotocol/types/selectors.py,sha256=5Ytq3xDBkgB85aYDsEDykFi7YygahmPChrknC8EhJ5E,6044
+browser_agent_protocol-0.1.0a1.dist-info/METADATA,sha256=ztJZ2unzKZCUTEnKfX5zMJjfzFo7jRURowHnMq4_VKY,8143
+browser_agent_protocol-0.1.0a1.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
+browser_agent_protocol-0.1.0a1.dist-info/entry_points.txt,sha256=MK4MD5NAXwu4DzlZ42y4kTi8RJKiUEawPdCvEGUjYYs,54
+browser_agent_protocol-0.1.0a1.dist-info/RECORD,,

browser_agent_protocol-0.1.0a1.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.28.0
+Root-Is-Purelib: true
+Tag: py3-none-any

browser_agent_protocol-0.1.0a1.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+bap = browseragentprotocol.cli:main

browseragentprotocol/__init__.py

@@ -0,0 +1,335 @@
+"""
+Browser Agent Protocol (BAP) Python SDK
+
+A Python client for controlling browsers via the Browser Agent Protocol.
+Designed for AI agents and automation tasks, with both async and sync APIs.
+
+Example (async context manager):
+    ```python
+    from browseragentprotocol import BAPClient, role
+
+    async def main():
+        async with BAPClient("ws://localhost:9222") as client:
+            await client.launch(browser="chromium", headless=True)
+            await client.create_page(url="https://example.com")
+
+            await client.click(role("button", "Submit"))
+            screenshot = await client.screenshot()
+
+    import asyncio
+    asyncio.run(main())
+    ```
+
+Example (high-level session helper):
+    ```python
+    from browseragentprotocol.context import bap_session
+
+    async with bap_session(
+        "ws://localhost:9222",
+        start_url="https://example.com"
+    ) as client:
+        await client.click(role("button", "Accept"))
+        content = await client.content()
+    ```
+
+For synchronous usage:
+    ```python
+    from browseragentprotocol import BAPClientSync, role
+
+    with BAPClientSync("ws://localhost:9222") as client:
+        client.launch(browser="chromium", headless=True)
+        client.create_page(url="https://example.com")
+
+        client.click(role("button", "Submit"))
+        screenshot = client.screenshot()
+    ```
+
+CLI usage:
+    ```bash
+    # Test connection
+    bap connect ws://localhost:9222
+
+    # Get server info
+    bap info ws://localhost:9222 --json
+    ```
+"""
+
+__version__ = "0.1.0a1"
+
+# Main client classes
+from browseragentprotocol.client import BAPClient
+from browseragentprotocol.sync_client import BAPClientSync
+
+# Transport layers
+from browseragentprotocol.transport import WebSocketTransport
+from browseragentprotocol.sse import SSETransport
+
+# Context managers
+from browseragentprotocol.context import bap_client, bap_session
+
+# Errors
+from browseragentprotocol.errors import (
+    BAPError,
+    BAPConnectionError,
+    BAPParseError,
+    BAPInvalidRequestError,
+    BAPMethodNotFoundError,
+    BAPInvalidParamsError,
+    BAPNotInitializedError,
+    BAPAlreadyInitializedError,
+    BAPBrowserNotLaunchedError,
+    BAPPageNotFoundError,
+    BAPElementNotFoundError,
+    BAPElementNotVisibleError,
+    BAPElementNotEnabledError,
+    BAPSelectorAmbiguousError,
+    BAPNavigationError,
+    BAPTimeoutError,
+    BAPActionError,
+    BAPTargetClosedError,
+    BAPExecutionContextDestroyedError,
+    BAPContextNotFoundError,
+    BAPResourceLimitExceededError,
+    BAPApprovalDeniedError,
+    BAPApprovalTimeoutError,
+    BAPApprovalRequiredError,
+    BAPFrameNotFoundError,
+    BAPDomainNotAllowedError,
+    BAPStreamNotFoundError,
+    BAPStreamCancelledError,
+)
+
+# Selector factory functions
+from browseragentprotocol.types.selectors import (
+    css,
+    xpath,
+    role,
+    text,
+    label,
+    placeholder,
+    test_id,
+    semantic,
+    coords,
+    ref,
+    # Selector types
+    AriaRole,
+    BAPSelector,
+    CSSSelector,
+    XPathSelector,
+    RoleSelector,
+    TextSelector,
+    LabelSelector,
+    PlaceholderSelector,
+    TestIdSelector,
+    SemanticSelector,
+    CoordinatesSelector,
+    RefSelector,
+)
+
+# Protocol types
+from browseragentprotocol.types.protocol import (
+    BAP_VERSION,
+    ErrorCodes,
+)
+
+# Common types
+from browseragentprotocol.types.common import (
+    AccessibilityNode,
+    ActionOptions,
+    BoundingBox,
+    ClickOptions,
+    ContentFormat,
+    Cookie,
+    Page,
+    PageStatus,
+    ScreenshotFormat,
+    ScreenshotOptions,
+    ScrollDirection,
+    ScrollOptions,
+    StorageState,
+    TypeOptions,
+    Viewport,
+    WaitUntilState,
+)
+
+# Agent types
+from browseragentprotocol.types.agent import (
+    ActionHint,
+    AgentActParams,
+    AgentActResult,
+    AgentExtractParams,
+    AgentExtractResult,
+    AgentObserveParams,
+    AgentObserveResult,
+    AnnotationOptions,
+    ExecutionStep,
+    InteractiveElement,
+    StepCondition,
+    StepErrorHandling,
+    StepResult,
+)
+
+# Method types
+from browseragentprotocol.types.methods import (
+    ApprovalRequiredParams,
+    ApprovalRespondParams,
+    BrowserLaunchParams,
+    BrowserLaunchResult,
+    ContextCreateParams,
+    ContextCreateResult,
+    ContextListResult,
+    FrameInfo,
+    FrameListResult,
+    FrameSwitchParams,
+    FrameSwitchResult,
+    InitializeResult,
+    ObserveAccessibilityResult,
+    ObserveAriaSnapshotResult,
+    ObserveContentResult,
+    ObserveDOMResult,
+    ObserveElementResult,
+    ObservePDFResult,
+    ObserveScreenshotResult,
+    PageNavigateResult,
+    StreamChunkParams,
+    StreamEndParams,
+)
+
+# Event types
+from browseragentprotocol.types.events import (
+    ConsoleEvent,
+    DialogEvent,
+    DownloadEvent,
+    NetworkEvent,
+    PageEvent,
+)
+
+__all__ = [
+    # Version
+    "__version__",
+    # Main classes
+    "BAPClient",
+    "BAPClientSync",
+    # Transport layers
+    "WebSocketTransport",
+    "SSETransport",
+    # Context managers
+    "bap_client",
+    "bap_session",
+    # Errors
+    "BAPError",
+    "BAPConnectionError",
+    "BAPParseError",
+    "BAPInvalidRequestError",
+    "BAPMethodNotFoundError",
+    "BAPInvalidParamsError",
+    "BAPNotInitializedError",
+    "BAPAlreadyInitializedError",
+    "BAPBrowserNotLaunchedError",
+    "BAPPageNotFoundError",
+    "BAPElementNotFoundError",
+    "BAPElementNotVisibleError",
+    "BAPElementNotEnabledError",
+    "BAPSelectorAmbiguousError",
+    "BAPNavigationError",
+    "BAPTimeoutError",
+    "BAPActionError",
+    "BAPTargetClosedError",
+    "BAPExecutionContextDestroyedError",
+    "BAPContextNotFoundError",
+    "BAPResourceLimitExceededError",
+    "BAPApprovalDeniedError",
+    "BAPApprovalTimeoutError",
+    "BAPApprovalRequiredError",
+    "BAPFrameNotFoundError",
+    "BAPDomainNotAllowedError",
+    "BAPStreamNotFoundError",
+    "BAPStreamCancelledError",
+    # Selector factories
+    "css",
+    "xpath",
+    "role",
+    "text",
+    "label",
+    "placeholder",
+    "test_id",
+    "semantic",
+    "coords",
+    "ref",
+    # Selector types
+    "AriaRole",
+    "BAPSelector",
+    "CSSSelector",
+    "XPathSelector",
+    "RoleSelector",
+    "TextSelector",
+    "LabelSelector",
+    "PlaceholderSelector",
+    "TestIdSelector",
+    "SemanticSelector",
+    "CoordinatesSelector",
+    "RefSelector",
+    # Protocol
+    "BAP_VERSION",
+    "ErrorCodes",
+    # Common types
+    "AccessibilityNode",
+    "ActionOptions",
+    "BoundingBox",
+    "ClickOptions",
+    "ContentFormat",
+    "Cookie",
+    "Page",
+    "PageStatus",
+    "ScreenshotFormat",
+    "ScreenshotOptions",
+    "ScrollDirection",
+    "ScrollOptions",
+    "StorageState",
+    "TypeOptions",
+    "Viewport",
+    "WaitUntilState",
+    # Agent types
+    "ActionHint",
+    "AgentActParams",
+    "AgentActResult",
+    "AgentExtractParams",
+    "AgentExtractResult",
+    "AgentObserveParams",
+    "AgentObserveResult",
+    "AnnotationOptions",
+    "ExecutionStep",
+    "InteractiveElement",
+    "StepCondition",
+    "StepErrorHandling",
+    "StepResult",
+    # Method types
+    "ApprovalRequiredParams",
+    "ApprovalRespondParams",
+    "BrowserLaunchParams",
+    "BrowserLaunchResult",
+    "ContextCreateParams",
+    "ContextCreateResult",
+    "ContextListResult",
+    "FrameInfo",
+    "FrameListResult",
+    "FrameSwitchParams",
+    "FrameSwitchResult",
+    "InitializeResult",
+    "ObserveAccessibilityResult",
+    "ObserveAriaSnapshotResult",
+    "ObserveContentResult",
+    "ObserveDOMResult",
+    "ObserveElementResult",
+    "ObservePDFResult",
+    "ObserveScreenshotResult",
+    "PageNavigateResult",
+    "StreamChunkParams",
+    "StreamEndParams",
+    # Event types
+    "ConsoleEvent",
+    "DialogEvent",
+    "DownloadEvent",
+    "NetworkEvent",
+    "PageEvent",
+]