This release is a pre-release and may not be stable for production use.
browserwhale (Python)
Python client for the hosted Browserwhale API: give it a URL and a task in plain language, and a web agent does the task in a real, disposable browser.
Not published yet: it will go to PyPI as browserwhale with the npm packages
(#86). Python 3.9 or later, no dependencies (it uses the standard library).
Run a task
Set your keys in the environment, out of source code:
export BROWSERWHALE_API_KEY="bw_…"
export BROWSERWHALE_BASE_URL="https://…" # published when the hosted API launches
export OPENAI_API_KEY="sk-…" # your own model provider key
export OPENAI_MODEL="gpt-5.4-mini" # the model to use
from browserwhale import Whale
whale = Whale() # BROWSERWHALE_API_KEY and BROWSERWHALE_BASE_URL
task = whale.run(
url="https://example.com",
task="Find the page's main heading.",
output={"type": "object", "properties": {"heading": {"type": "string"}}},
)
print(task["output"]) # {'heading': 'Example Domain'}
for step in task["steps"]:
print(step["n"], step["description"]) # 1 Opening the website
Tasks run on your own model provider account. A task without model takes
your key and model name from the environment, the same variables the
browserwhale package reads:
| Provider | Variables |
|---|---|
| OpenAI | OPENAI_API_KEY, OPENAI_MODEL, optional OPENAI_BASE_URL |
| Anthropic | ANTHROPIC_API_KEY, ANTHROPIC_MODEL, optional ANTHROPIC_BASE_URL |
GEMINI_API_KEY (or GOOGLE_API_KEY), GEMINI_MODEL, optional GEMINI_BASE_URL |
|
| Azure OpenAI | AZURE_OPENAI_API_KEY, AZURE_OPENAI_DEPLOYMENT, AZURE_OPENAI_ENDPOINT |
When keys for several providers are set, BROWSERWHALE_PROVIDER picks one;
otherwise the order is OpenAI, Anthropic, Google, then Azure. A key without
its model name is an error: the client never picks a model for you. The key
is used only for that task and never stored, logged or returned.
To choose the model in code instead, pass model with a task, or once as a
client default with Whale(model=...); a task's own model wins:
import os
task = whale.run(
url="https://example.com",
task="Find the page's main heading.",
model={
"provider": "openai", # or openai-compatible, azure, anthropic, google
"name": "gpt-5.4-mini",
"api_key": os.environ["OPENAI_API_KEY"],
},
)
base_url sets your provider's https endpoint (required for
openai-compatible and azure). Whale(model=False) sends no model from
the environment. model_from_environment(os.environ) returns the model the
client would read.
run() creates the task, waits until it finishes and returns the task
when it is completed. Tasks are plain dicts typed with TypedDict
(Task), with the API's snake_case field names.
Live progress
Pass on_progress to see each step as it happens:
task = whale.run(
url="https://example.com",
task="Find the page's main heading.",
on_progress=lambda step: print(f"Step {step['n']} · {step['description']}"),
)
For more control, whale.tasks.events(task_id) yields every step, each
status change and finally done with the task. It reconnects on its own,
resuming after the last step it saw:
for event in whale.tasks.events(task["id"]):
if event["type"] == "step":
print(event["step"]["description"])
elif event["type"] == "done":
print(event["task"]["status"])
Answering a question
Before a step that needs your go-ahead, a task can ask one yes/no question.
Pass on_confirm to answer it; return True to carry out the step, False
to end the task without it:
task = whale.run(
url="https://admin.example.com/users",
task="Remove the user Jordan Ortiz.",
on_confirm=lambda confirmation, task: input(confirmation["question"] + " [y/N] ") == "y",
)
Without on_confirm, run() creates the task with
confirmations="decline", so it never waits on an answer. A task created
with whale.tasks.create that waits has the status
waiting_for_confirmation and a confirmation; answer it with
whale.tasks.confirm(task_id, task["confirmation"]["id"], "yes") or "no"
before confirmation["expires_at"] (5 minutes). No answer counts as no, and
a yes doesn't carry out a step the page changed under while you decided.
Opt-in features
All off by default:
task = whale.run(
url="https://shop.example",
task="Add the cheapest kettle to the cart.",
skills="auto", # or ["shopping"]
vision=False, # never look at the screen (on by default, for drawn content such as seat maps)
cache="read-write", # reuse an earlier completed run of the same request
)
cache keeps data between the tasks of one API key (never
shared with another key), and only servers that store
task data accept them.
Tasks that do not complete
Any other final status raises TaskFailedError; its task keeps the partial
results, the limitations with plain reasons, and the cause
(site_blocked, unavailable, limit_reached, could_not_complete,
cancelled, model_error, internal_error). run(timeout=...) (seconds, default 15
minutes) raises WaitTimeoutError when it stops waiting; the task may still
be running. Interrupting run() (Ctrl+C) cancels the task.
Errors
| Error | When |
|---|---|
AuthenticationError |
Missing or invalid API key (401). |
InvalidRequestError |
The request failed validation (400, 413, 422); param names the field. |
NotFoundError |
No such task for this key (404). |
ConflictError |
An idempotency key reused with a different body (409). |
RateLimitError |
Rate limit or concurrent-task cap reached (429). retry_after is in seconds; code is rate_limit_exceeded, concurrency_limit_exceeded or quota_exceeded (the month's tasks are used up; not retried). |
InternalServerError |
A server error (5xx). |
APIConnectionError |
No response: a network failure or request timeout. |
All derive from WhaleError; the HTTP ones from ApiError (status, type,
param, request_id). The client retries 429, 5xx and network failures
(max_retries, default 2), honouring Retry-After. Every create carries an
Idempotency-Key, reused across retries, so a retried create never starts a
second task.
Usage and cost
whale.usage(month="2026-11") returns the key's tasks, model calls, tokens,
browser time and cost for a calendar month (UTC; the current month by
default). Tasks that never started or failed with internal_error cost
nothing.
Lower-level control
whale.tasks.create(params), get(id, wait=30), list(limit=, cursor=),
events(id) and cancel(id) map one-to-one to the REST endpoints.
Development
python3 -m unittest discover -s packages/sdk-python/tests # unit and contract tests
pnpm test:api # also runs them against the local API
tests/test_client.py checks the types against api/openapi.json, so a
contract change that the client misses fails. tests/test_live_api.py runs
against a server started by test/integration/python-sdk.pg.test.ts.
Metadata
Release files for browserwhale 0.1.0b2
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| browserwhale-0.1.0b2.tar.gz | 18.4 kB | Without provenance | Details for browserwhale-0.1.0b2.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| browserwhale-0.1.0b2-py3-none-any.whl | Python 3 | none | any | Details for browserwhale-0.1.0b2-py3-none-any.whl |
Total release size: 40.3 kB
Release files / browserwhale-0.1.0b2.tar.gz
| Download URL | browserwhale-0.1.0b2.tar.gz |
|---|---|
| Size | 18.4 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
bbdc1e968330c4b10a35d9f7e31e562d0c3b8a073a0d7b11ba545a305e3c5d85
|
|
BLAKE2b-256 checksum How to use checksums |
03a8f7afc3cb807f6ec70a839054b7ac79a1484d240efe70af7e1f3ffa9f17a5
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.12.16
|
Release files / browserwhale-0.1.0b2-py3-none-any.whl
| Download URL | browserwhale-0.1.0b2-py3-none-any.whl |
|---|---|
| Size | 21.8 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
4cf3fd59e27b350593232da820a86aab870d99a13405ead70514194feb7e6f9a
|
|
BLAKE2b-256 checksum How to use checksums |
81508fade5ac31f5317ef734ae09fe2a38c91016b807d0705cc655cd84987d83
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.12.16
|
Security for browserwhale 0.1.0b2
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.