SDK Examples

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

def login_to_service(email: str, password: str):
    """Login to a web service using semantic element discovery."""

    with SentienceBrowser(api_key="sk_...", headless=False) as browser:
        # Navigate to login page
        browser.page.goto("https://example.com/login", wait_until="domcontentloaded")

        # Take snapshot to find form elements
        snap = snapshot(browser)

        # Find email input field semantically
        email_field = find(snap, "role=textbox text~'email'")
        password_field = find(snap, "role=textbox text~'password'")
        submit_button = find(snap, "role=button text~'sign in'")

        if not email_field or not password_field or not submit_button:
            raise Exception("Login form elements not found")

        # Fill in credentials
        type_text(browser, email_field.id, email)
        type_text(browser, password_field.id, password)

        # Submit form
        result = click(browser, submit_button.id)
        print(f"Form submitted: {result.success}")

        # Wait for successful login (dashboard appears)
        wait_result = wait_for(browser, "role=heading text~'Dashboard'", timeout=10.0)

        if wait_result.found:
            print(f"✅ Login successful! Dashboard loaded after {wait_result.duration_ms}ms")
            return True
        else:
            print("❌ Login failed - dashboard not found")
            return False

# Usage
login_to_service("user@example.com", "secret123")

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

def shop_for_product(search_query: str):
    """Search for a product and add it to cart."""

    with SentienceBrowser(api_key="sk_...", headless=False) as browser:
        # Step 1: Navigate to e-commerce site
        browser.page.goto("https://www.amazon.com", wait_until="domcontentloaded")
        time.sleep(2)  # Wait for dynamic content

        # Step 2: Find and use search bar
        snap = snapshot(browser)
        search_box = find(snap, "role=combobox text~'search'")

        if search_box:
            type_text(browser, search_box.id, search_query)
            # Press Enter to search
            from sentience import press
            press(browser, "Enter")
            time.sleep(2)

        # Step 3: Find product links (filter out ads)
        snap = snapshot(browser)

        # Get all product links in viewport
        products = [
            el for el in snap.elements
            if el.role == "link"
            and el.visual_cues.is_clickable
            and el.in_viewport
            and not el.is_occluded
            and el.bbox.y < 800  # Top results
            and "sponsored" not in (el.text or "").lower()  # Filter ads
        ]

        # Sort by position (top to bottom, left to right)
        products.sort(key=lambda e: (e.bbox.y, e.bbox.x))

        if products:
            first_product = products[0]
            print(f"Clicking product: {first_product.text}")
            click(browser, first_product.id)
            time.sleep(2)

        # Step 4: Add to cart
        snap = snapshot(browser)
        add_to_cart_btn = find(snap, "role=button text~'add to cart'")

        if add_to_cart_btn:
            result = click(browser, add_to_cart_btn.id)
            print(f"✅ Added to cart: {result.success}")

            # Verify cart confirmation
            wait_for(browser, "text~'added to cart'", timeout=5.0)
        else:
            print("❌ Add to cart button not found")

# Usage
shop_for_product("wireless headphones")

from sentience import SentienceBrowser, snapshot, find, query, type_text, press, click
import time

def google_search(search_query: str):
    """Perform a Google search and click the first organic result."""

    with SentienceBrowser(api_key="sk_...", headless=False) as browser:
        # Navigate to Google
        browser.page.goto("https://www.google.com", wait_until="domcontentloaded")
        time.sleep(1)

        # Find search box
        snap = snapshot(browser)
        search_box = find(snap, "role=combobox")  # Google search input

        if search_box:
            # Type search query and submit
            type_text(browser, search_box.id, search_query)
            press(browser, "Enter")
            time.sleep(2)

        # Get results and filter ads
        snap = snapshot(browser)

        # Find all links
        all_links = query(snap, "role=link")

        # Filter: organic results only (no ads, no navigation)
        organic_results = [
            link for link in all_links
            if link.text  # Has text
            and len(link.text) > 20  # Substantial text
            and link.in_viewport
            and not link.is_occluded
            and "ad" not in link.text.lower()
            and "sponsored" not in link.text.lower()
            and link.importance > 300  # Important enough
        ]

        # Sort by importance (most relevant first)
        organic_results.sort(key=lambda x: x.importance, reverse=True)

        if organic_results:
            top_result = organic_results[0]
            print(f"Clicking top result: {top_result.text[:60]}...")
            result = click(browser, top_result.id)

            if result.url_changed:
                print(f"✅ Navigated to: {browser.page.url}")
        else:
            print("❌ No organic results found")

# Usage
google_search("sentience browser automation")

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

def fill_application_form(data: dict):
    """Fill out a complex multi-field application form."""

    with SentienceBrowser(api_key="sk_...", headless=False) as browser:
        browser.page.goto("https://example.com/apply", wait_until="domcontentloaded")

        # Take snapshot
        snap = snapshot(browser)

        # Fill text fields by label
        first_name = find(snap, "role=textbox text~'first name'")
        last_name = find(snap, "role=textbox text~'last name'")
        email = find(snap, "role=textbox text~'email'")
        phone = find(snap, "role=textbox text~'phone'")

        type_text(browser, first_name.id, data['first_name'])
        type_text(browser, last_name.id, data['last_name'])
        type_text(browser, email.id, data['email'])
        type_text(browser, phone.id, data['phone'])

        # Select dropdown option
        snap = snapshot(browser)
        country_dropdown = find(snap, "role=combobox text~'country'")

        if country_dropdown:
            # Click to open dropdown
            click(browser, country_dropdown.id)

            # Wait for options to appear
            wait_for(browser, "role=option", timeout=3.0)

            # Find and click desired option
            snap = snapshot(browser)
            usa_option = find(snap, "role=option text='United States'")
            click(browser, usa_option.id)

        # Check a checkbox (e.g., terms agreement)
        snap = snapshot(browser)
        terms_checkbox = find(snap, "role=checkbox text~'terms'")

        if terms_checkbox:
            click(browser, terms_checkbox.id)

        # Fill textarea
        snap = snapshot(browser)
        comments = find(snap, "role=textbox text~'comments'")

        if comments:
            type_text(browser, comments.id, data.get('comments', ''))

        # Submit form
        snap = snapshot(browser)
        submit_btn = find(snap, "role=button text~'submit'")

        if submit_btn:
            result = click(browser, submit_btn.id)
            print(f"✅ Form submitted: {result.success}")

            # Wait for confirmation
            wait_for(browser, "text~'thank you'", timeout=10.0)

# Usage
form_data = {
    'first_name': 'John',
    'last_name': 'Doe',
    'email': 'john@example.com',
    'phone': '+1-555-0123',
    'comments': 'Looking forward to hearing from you!'
}

fill_application_form(form_data)

from sentience import SentienceBrowser, snapshot, query, read
import json

def extract_article_data(url: str):
    """Extract article title, author, date, and content."""

    with SentienceBrowser(api_key="sk_...", headless=True) as browser:
        browser.page.goto(url, wait_until="domcontentloaded")

        # Take snapshot to find semantic elements
        snap = snapshot(browser)

        # Find article metadata
        title = None
        author = None
        date = None

        # Look for title (usually a heading)
        headings = query(snap, "role=heading")
        if headings:
            # Sort by importance and get top heading
            headings.sort(key=lambda h: h.importance, reverse=True)
            title = headings[0].text

        # Look for author info
        author_elem = query(snap, "text~'by ' text~'author'")
        if author_elem:
            author = author_elem[0].text

        # Extract main content as markdown
        content_result = read(browser, format="markdown")
        content = content_result["content"]

        # Extract all links
        links = query(snap, "role=link")
        external_links = [
            {"text": link.text, "href": link.text}
            for link in links
            if link.text and len(link.text) > 0
        ]

        article_data = {
            "url": url,
            "title": title,
            "author": author,
            "content": content,
            "links_count": len(external_links),
            "word_count": len(content.split()) if content else 0
        }

        print(json.dumps(article_data, indent=2))
        return article_data

# Usage
extract_article_data("https://example.com/blog/article")

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

def post_social_update(message: str):
    """Post an update on a social media platform."""

    with SentienceBrowser(api_key="sk_...", headless=False) as browser:
        # Navigate to social platform (example)
        browser.page.goto("https://twitter.com/compose/tweet", wait_until="domcontentloaded")
        time.sleep(2)

        # Find the compose textarea
        snap = snapshot(browser)
        compose_box = find(snap, "role=textbox text~'what'")

        if compose_box:
            # Type the message
            type_text(browser, compose_box.id, message)
            print(f"Typed message: {message}")

            # Wait a moment for auto-save
            time.sleep(1)

            # Find and click post button
            snap = snapshot(browser)
            post_button = find(snap, "role=button text~'post'")

            if post_button:
                result = click(browser, post_button.id)
                print(f"✅ Posted successfully: {result.success}")

                # Wait for confirmation
                wait_for(browser, "text~'your tweet was sent'", timeout=5.0)
            else:
                print("❌ Post button not found")
        else:
            print("❌ Compose box not found")

def like_recent_posts(count: int = 5):
    """Like the most recent posts in feed."""

    with SentienceBrowser(api_key="sk_...", headless=False) as browser:
        browser.page.goto("https://twitter.com/home", wait_until="domcontentloaded")
        time.sleep(2)

        liked_count = 0

        while liked_count < count:
            snap = snapshot(browser)

            # Find all "like" buttons in viewport
            like_buttons = [
                el for el in snap.elements
                if el.role == "button"
                and "like" in (el.text or "").lower()
                and el.in_viewport
                and not el.is_occluded
            ]

            if like_buttons:
                # Click the first unliked post
                first_like = like_buttons[0]
                click(browser, first_like.id)
                liked_count += 1
                print(f"Liked post {liked_count}/{count}")
                time.sleep(1)

                # Scroll down to load more
                browser.page.evaluate("window.scrollBy(0, 300)")
                time.sleep(1)
            else:
                print("No more posts to like")
                break

        print(f"✅ Liked {liked_count} posts")

# Usage
post_social_update("Excited to share my latest project! #AI #automation")
like_recent_posts(count=3)