Quick Start Guide

Get started with Sentience SDK in 5 minutes. This guide walks you through a complete login automation example.

1 Install the SDK

Install the Sentience SDK for your preferred language:

# Install the Python SDK
pip install sentienceapi

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

2 Get Your API Key (Optional)

API key enables smarter filtering and saves LLM token usage

Sign up at www.sentienceapi.com to get your API key. You can also test locally without an API key.

export SENTIENCE_API_KEY="sk_..."

3 Write Your First Automation

Login Form Example

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")

Key Concepts:

• snapshot() captures current page state
• find() uses semantic queries to locate elements
• click() and type_text() perform actions
• wait_for() waits for elements using semantic conditions

4 Run Your Script

python login_example.py

The browser will open, navigate to the login page, fill in the form, and submit it automatically.

What You Learned

• How to create a browser instance with the Sentience extension
• How to capture page snapshots with semantic element data
• How to find elements using semantic queries (role, text)
• How to perform actions (click, type) on found elements
• How to wait for elements using semantic conditions

Common Questions

Do I need an API key to test locally?

No! You can use use_api=False to process everything locally. This won't charge credits but also won't include importance ranking.

How do semantic queries work?

Queries use operators like role=button, text~"Submit" (contains), importance>500. See the full reference for all operators.

What if an element isn't found?

Use wait_for() to wait for elements to appear. Check element visibility with element.in_viewport and element.is_occluded.

Next Steps

• SDK Reference → - Explore all SDK functions
• Examples → - See more real-world use cases
• Playground → - Try demos on GitHub