$ show browserbase/stagehand-python
Stagehand is a Python SDK for the Stagehand API, an AI-driven browser automation framework. The SDK provides sync and async clients (`Stagehand`, `AsyncStagehand`) that interact with remote or local browser sessions via natural language commands like `observe`, `act`, `extract`, and `execute`. It supports both cloud-based (via REST API) and local execution modes, the latter using a compiled SEA binary managed by `SeaServerManager`. The codebase is primarily auto-generated by Stainless from an OpenAPI spec, with hand-written custom modules for session binding, binary management, and local server orchestration. The architecture follows a resource-based client pattern: the main client holds resource objects (e.g., `sessions`) that expose typed methods returning Pydantic models. Request parameters are defined as `TypedDict` subclasses with camelCase aliases, and responses are deserialized into strongly-typed models. The SDK includes comprehensive error handling (hierarchy of `APIError` subclasses), configurable retries and timeouts, SSE streaming support, and Pydantic v1/v2 compatibility. External dependencies include `httpx` for HTTP, `pydantic` for models, and optional `aiohttp`, `playwright`, or `pydoll` for advanced browser control. Key entry points are the `Stagehand` and `AsyncStagehand` classes, which can be instantiated with an API key and base URL. Sessions are started via `client.sessions.start()`, then methods like `session.act()`, `session.extract()`, `session.observe()`, and `session.execute()` perform browser automation tasks. The `_custom/session.py` module wraps the generated resource to provide a bound session object with page-aware frame handling. The SDK also ships a `_sea` binary for local execution, packaged via custom Hatch build hooks.
The LLM identified 3 files worth highlighting for reuse:
Implements SSE (Server-Sent Events) decoding and iteration for both sync and async clients. Provides `Stream` and `AsyncStream` classes that wrap an HTTP response and yield typed events as they arrive. The decoder handles multiple event formats and line endings. This module is relatively self-contained (depends only on standard library and internal exception types) and can be extracted to add SSE support to any HTTP client with minimal modification.
Defines a clean, hierarchical exception structure for API errors: `APIError` base class, `APIStatusError` with HTTP status code, `APIConnectionError`, `APITimeoutError`, `APIResponseValidationError`, and `BadRequestError` (400). Includes `make_status_error` factory function. This pattern is reusable across any API client and demonstrates proper separation of error types for client-side error handling.
Manages the lifecycle of a local SEA binary subprocess that serves as a Stagehand runtime. `SeaServerManager` handles starting the binary with platform-specific arguments, waiting for readiness via health-check endpoint, and graceful shutdown. It encapsulates timeout, port assignment, and error reporting. This pattern can be reused for any project that needs to manage a long-running child process server with health checks.