Quick Start Guide

# Install the Python SDK
pip install sentienceapi

# Install Chromium browser (required for automation)
playwright install chromium

import asyncio

from sentience import SentienceDebugger
from sentience.tracing import Tracer, JsonlTraceSink
from sentience.verification import exists, url_contains


class MyAgent:
    """
    Your existing agent/framework.
    It owns the browser and returns a Playwright Page.
    """

    def __init__(self, page):
        self.page = page  # playwright.async_api.Page

    async def step(self) -> None:
        # Example "action" - replace with your real agent step
        await self.page.click("text=Checkout")


async def main() -> None:
    # 1) Your agent/framework provides the Playwright page
    page = agent.get_page()  # playwright.async_api.Page

    # 2) Create tracer (writes trace.jsonl)
    tracer = Tracer(run_id="quickstart-run", sink=JsonlTraceSink("trace.jsonl"))

    # 3) Attach SentienceDebugger to your existing page (sidecar mode)
    dbg = SentienceDebugger.attach(page, tracer=tracer)

    # 4) Your agent loop runs as usual…
    await agent.step()

    # 5) …and you verify outcomes with Sentience (deterministic)
    # Local-only snapshot (no API key required):
    await dbg.snapshot(use_api=False, goal="verify:after-step", limit=120)

    # Checks can be added dynamically (LLM can decide what to verify):
    dbg.check(url_contains("checkout"), label="navigated_to_checkout", required=True).once()
    dbg.check(exists("role=heading text~'Checkout'"), label="checkout_heading_visible").once()

    # Optional: group checks into a step boundary (creates a clean trace segment)
    async with dbg.step("verify:checkout"):
        await dbg.snapshot(use_api=False)
        await dbg.check(exists("role=button text~'Place Order'"), label="place_order_visible", required=True).eventually()


if __name__ == "__main__":
    asyncio.run(main())

python your_script.py

from sentience import SentienceBrowser, snapshot, find, type_text, click, wait_for

# Create browser instance
with SentienceBrowser(api_key="sk_...") as browser:
    # Navigate to login page
    browser.page.goto("https://example.com/login")

    # PERCEPTION: Take snapshot and find elements
    snap = snapshot(browser)
    email_input = find(snap, "role=textbox text~'email'")
    password_input = find(snap, "role=textbox text~'password'")
    submit_btn = find(snap, "role=button text~'sign in'")

    # ACTION: Interact with the page
    type_text(browser, email_input.id, "user@example.com")
    type_text(browser, password_input.id, "password123")
    click(browser, submit_btn.id)

    # VERIFICATION: Wait for success
    result = wait_for(browser, "role=heading text~'Dashboard'", timeout=5.0)

    if result.found:
        print("✓ Login successful!")
    else:
        print("✗ Login failed")