Metadata-Version: 2.5
Name: browserwhale
Version: 0.1.0b1
Summary: Python client for the hosted Browserwhale web agent API.
License-Expression: Apache-2.0
License-File: LICENSE
License-File: NOTICE
Keywords: agent,api,automation,browser,sdk,web-agent
Classifier: Programming Language :: Python :: 3
Classifier: Typing :: Typed
Requires-Python: >=3.9
Description-Content-Type: text/markdown

# browserwhale (Python)

Python client for the hosted Browserwhale API: give it a URL and a goal in
plain language, and a web agent does the task in a real, disposable browser.

Install it with `pip install --pre browserwhale` (beta). Python 3.9 or later, no
dependencies (it uses the standard library).

## Run a task

```python
from browserwhale import Whale

whale = Whale()  # BROWSERWHALE_API_KEY and BROWSERWHALE_BASE_URL

task = whale.run(
    url="https://example.com",
    goal="Find the page's main heading.",
    output_schema={"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
```

`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.

To run a task in an open session (see the API docs, "Sessions"),
pass `session_id=`; a later task in it may pass `url=None` to continue on the
current page. This client does not open or close sessions yet; use the HTTP
API for that.

## Live progress

Pass `on_progress` to see each step as it happens:

```python
task = whale.run(
    url="https://example.com",
    goal="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:

```python
for event in whale.tasks.events(task["id"]):
    if event["type"] == "step":
        print(event["step"]["description"])
    elif event["type"] == "done":
        print(event["task"]["status"])
```

## Opt-in features

All off by default:

```python
task = whale.run(
    url="https://shop.example",
    goal="Add the cheapest kettle to the cart.",
    notes="The catalogue is under Shop > Kitchen.",  # your own steps or hints
    skills="auto",  # or ["shopping"]
    vision="fallback",  # look at the screen for drawn content such as seat maps
    cache="read-write",  # reuse an earlier completed run of the same request
    site_context="read-write",  # remember how the site works between your tasks
)
```

`cache` and `site_context` keep data between the tasks of one API key (never
shared with another key, even in the same team), 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`, `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` or `concurrency_limit_exceeded`. |
| `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.
