Python SDK - Simultaneous

Installation

pip install simultaneous

Verify installation:

python -c "from simultaneous import SimClient, Browsers, Models; print('✅ Installed')"

Quick Start

Here’s everything you need to get started:

import asyncio
from simultaneous import SimClient, Browsers, Models

async def main():
    # Initialize client (replace with your project ID)
    sim = SimClient(project_id="your-project-id")
    
    # Create a browser client
    browser = sim.browser_client(
        provider=Browsers.BROWSERBASE,
        model_name=Models.O4_MINI,
    )
    
    # Use the browser
    async with browser:
        page = browser.page
        await page.goto("https://example.com")
        await page.act("click the login button")
        await page.screenshot(path="screenshot.png")

asyncio.run(main())

Client Setup

Basic Initialization

from simultaneous import SimClient

# Simplest way - uses environment variables
sim = SimClient()

# Or specify project ID directly
sim = SimClient(project_id="your-project-id")

# With API key (optional)
sim = SimClient(
    project_id="your-project-id",
    api_key="SIM_...",
)

Environment Variables

Set these in your environment or .env file:

SIMULTANEOUS_PROJECT_ID=your-project-id    # Required
SIMULTANEOUS_API_KEY=your-api-key           # Optional
OPENAI_API_KEY=sk-...                       # Required for AI features

Then use:

sim = SimClient()  # Automatically reads from environment

Browser Client Usage

Creating a Browser Client

The browser_client() method creates a BrowserClient that automatically manages browser sessions:

from simultaneous import SimClient, Browsers, Models

sim = SimClient(project_id="your-project-id")

# Create browser client with default settings
browser = sim.browser_client(
    provider=Browsers.BROWSERBASE,
    model_name=Models.O4_MINI,
)

# Or with custom configuration
browser = sim.browser_client(
    provider=Browsers.BROWSERBASE,
    model_name=Models.GPT4O,
    model_api_key="sk-...",  # Optional: defaults to OPENAI_API_KEY env var
    adapter_config={
        "region": "sfo",  # Browserbase region
        "projectId": "proj_xxx",  # Browserbase project ID
    },
)

Using BrowserClient

Always use the context manager - it ensures proper cleanup:

async with browser:
    page = browser.page
    await page.goto("https://example.com")
    await page.act("click the login button")
    # Session automatically closed on exit

Page Automation Methods

The page object (from Stagehand) provides AI-powered browser automation:

# Navigate to a URL
await page.goto("https://example.com")

# Wait for navigation
await page.wait_for_load_state("networkidle")

AI-Powered Actions

# Use natural language to interact with the page
await page.act("search for 'python tutorials'")
await page.act("click the submit button")
await page.act("fill in the form with name John and email john@example.com")
await page.act("scroll down to the footer")

Screenshots

# Take a screenshot
await page.screenshot(path="screenshot.png")

# Screenshot of specific element
await page.screenshot(path="button.png", selector="button#submit")

Element Interaction

# Click an element
await page.click("button#submit")

# Type text
await page.type("input#search", "search query")

# Fill a form field
await page.fill("input#email", "user@example.com")

# Select dropdown option
await page.select_option("select#country", "US")

Waiting

# Wait for element to appear
await page.wait_for_selector("div#results")

# Wait for text to appear
await page.wait_for_text("Results found")

# Wait for navigation
await page.wait_for_url("https://example.com/success")

Evaluation

# Execute JavaScript
result = await page.evaluate("document.title")

# Get element text
text = await page.text_content("h1")

# Get element attribute
href = await page.get_attribute("a#link", "href")

Advanced Examples

Web Scraping Example

import asyncio
from simultaneous import SimClient, Browsers, Models

async def scrape_job_listings():
    sim = SimClient(project_id="your-project-id")
    
    browser = sim.browser_client(
        provider=Browsers.BROWSERBASE,
        model_name=Models.O4_MINI,
    )
    
    async with browser:
        page = browser.page
        
        # Navigate to job board
        await page.goto("https://example-jobs.com")
        
        # Search for jobs
        await page.act("search for 'software engineer'")
        await asyncio.sleep(2)  # Wait for results
        
        # Extract job listings
        jobs = await page.evaluate("""
            () => {
                const listings = document.querySelectorAll('.job-listing');
                return Array.from(listings).map(job => ({
                    title: job.querySelector('.title')?.textContent,
                    company: job.querySelector('.company')?.textContent,
                    location: job.querySelector('.location')?.textContent,
                }));
            }
        """)
        
        return jobs

# Run the scraper
results = asyncio.run(scrape_job_listings())
print(f"Found {len(results)} jobs")

Form Filling Example

import asyncio
from simultaneous import SimClient, Browsers, Models

async def fill_contact_form():
    sim = SimClient(project_id="your-project-id")
    
    browser = sim.browser_client(
        provider=Browsers.BROWSERBASE,
        model_name=Models.GPT4O,
    )
    
    async with browser:
        page = browser.page
        
        await page.goto("https://example.com/contact")
        
        # Use AI to fill the form
        await page.act("fill in the contact form with name 'John Doe', email 'john@example.com', and message 'Hello, I am interested in your services'")
        
        # Take screenshot before submitting
        await page.screenshot(path="form-filled.png")
        
        # Submit the form
        await page.act("submit the form")
        
        # Wait for confirmation
        await page.wait_for_text("Thank you")

asyncio.run(fill_contact_form())

Multi-Page Workflow

import asyncio
from simultaneous import SimClient, Browsers, Models

async def multi_page_workflow():
    sim = SimClient(project_id="your-project-id")
    
    browser = sim.browser_client(
        provider=Browsers.BROWSERBASE,
        model_name=Models.O4_MINI,
    )
    
    async with browser:
        page = browser.page
        
        # Step 1: Search
        await page.goto("https://example.com")
        await page.act("search for 'python'")
        await asyncio.sleep(2)
        
        # Step 2: Click first result
        await page.act("click on the first search result")
        await asyncio.sleep(2)
        
        # Step 3: Extract information
        title = await page.evaluate("document.title")
        content = await page.text_content("main")
        
        # Step 4: Take screenshot
        await page.screenshot(path="result.png")
        
        return {"title": title, "content": content[:500]}

result = asyncio.run(multi_page_workflow())
print(result)

Available Models

The SDK supports multiple AI models for browser automation:

from simultaneous import Models

# OpenAI models
Models.GPT4O          # "openai/gpt-4o" (recommended)
Models.O4_MINI        # "openai/o4-mini" (Computer Use model)
Models.O4             # "openai/o4" (Computer Use model)

# Anthropic models
Models.CLAUDE_3_5     # "anthropic/claude-3.5"

Available Providers

from simultaneous import Browsers

Browsers.BROWSERBASE  # Browserbase provider

Environment Variables

Required:

SIMULTANEOUS_PROJECT_ID - Your project UUID
OPENAI_API_KEY - For AI-powered browser actions

Optional:

SIMULTANEOUS_API_KEY - API key for authentication
ANTHROPIC_API_KEY - For Claude models (if using Models.CLAUDE_3_5)
BROWSERBASE_PROJECT_ID - Browserbase project ID (if different from default)
BROWSERBASE_REGION - Browserbase region (default: “sfo”)

Error Handling

import asyncio
from simultaneous import SimClient, Browsers, Models

async def robust_example():
    sim = SimClient(project_id="your-project-id")
    
    browser = sim.browser_client(
        provider=Browsers.BROWSERBASE,
        model_name=Models.O4_MINI,
    )
    
    try:
        async with browser:
            page = browser.page
            await page.goto("https://example.com")
            await page.act("click the button")
    except Exception as e:
        print(f"Error occurred: {e}")
        # Browser session is automatically cleaned up

asyncio.run(robust_example())

Choosing a Model

Models.O4_MINI - Fast and cost-effective for simple tasks (recommended)
Models.GPT4O - More capable for complex interactions
Models.CLAUDE_3_5 - Alternative AI model (requires ANTHROPIC_API_KEY)

Best Practices

✅ Always use async with for automatic cleanup
✅ Set OPENAI_API_KEY environment variable
✅ Use O4_MINI for simple tasks to save costs
✅ Take screenshots for debugging (await page.screenshot())
✅ Wait for elements before interacting (await page.wait_for_selector())

Documentation Index

​Installation

​Quick Start

​Client Setup

​Basic Initialization

​Environment Variables

​Browser Client Usage

​Creating a Browser Client

​Using BrowserClient

​Page Automation Methods

​Navigation

​AI-Powered Actions

​Screenshots

​Element Interaction

​Waiting

​Evaluation

​Advanced Examples

​Web Scraping Example

​Form Filling Example

​Multi-Page Workflow

​Available Models

​Available Providers

​Environment Variables

​Error Handling

​Choosing a Model

​Best Practices

Installation

Quick Start

Client Setup

Basic Initialization

Environment Variables

Browser Client Usage

Creating a Browser Client

Using BrowserClient

Page Automation Methods

Navigation

AI-Powered Actions

Screenshots

Element Interaction

Waiting

Evaluation

Advanced Examples

Web Scraping Example

Form Filling Example

Multi-Page Workflow

Available Models

Available Providers

Environment Variables

Error Handling

Choosing a Model

Best Practices