browsa 0.2.0__tar.gz → 0.3.1__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -1,6 +1,6 @@
1
1
  MIT License
2
2
 
3
- Copyright (c) 2026 neout
3
+ Copyright (c) 2026 Browsa Technologies LLC
4
4
 
5
5
  Permission is hereby granted, free of charge, to any person obtaining a copy
6
6
  of this software and associated documentation files (the "Software"), to deal
@@ -1,14 +1,15 @@
1
1
  Metadata-Version: 2.4
2
2
  Name: browsa
3
- Version: 0.2.0
3
+ Version: 0.3.1
4
4
  Summary: Official Python SDK for Browsa: real cloud browsers for AI agents (browsa.io)
5
5
  Author-email: Browsa <support@browsa.io>
6
6
  License: MIT
7
7
  Project-URL: Homepage, https://browsa.io
8
8
  Project-URL: Documentation, https://browsa.io/docs
9
- Project-URL: Source, https://pypi.org/project/browsa/
10
- Project-URL: Issues, https://browsa.io/docs
11
- Keywords: browser-automation,ai-agents,browser-use,real-browser,captcha-solver,scraping,playwright
9
+ Project-URL: Source, https://github.com/browsa-io/browsa/tree/main/browsa-python
10
+ Project-URL: Issues, https://github.com/browsa-io/browsa/issues
11
+ Project-URL: Changelog, https://github.com/browsa-io/browsa/releases
12
+ Keywords: browser-automation,ai-agents,browser-use,real-browser,scraping,playwright
12
13
  Classifier: Development Status :: 4 - Beta
13
14
  Classifier: Intended Audience :: Developers
14
15
  Classifier: License :: OSI Approved :: MIT License
@@ -17,6 +18,7 @@ Classifier: Programming Language :: Python :: 3.9
17
18
  Classifier: Programming Language :: Python :: 3.10
18
19
  Classifier: Programming Language :: Python :: 3.11
19
20
  Classifier: Programming Language :: Python :: 3.12
21
+ Classifier: Typing :: Typed
20
22
  Classifier: Topic :: Internet :: WWW/HTTP :: Browsers
21
23
  Classifier: Topic :: Software Development :: Libraries :: Python Modules
22
24
  Requires-Python: >=3.9
@@ -55,14 +57,17 @@ from browsa import Client
55
57
  c = Client(api_key="agt_live_...")
56
58
  job = c.run_task(
57
59
  task="Go to news.ycombinator.com and return the top story title.",
58
- llm="claude-opus-5-5",
59
- llm_api_key="sk-ant-...",
60
+ llm="browsa",
61
+ on_progress=lambda j: j.live_url and print("watch live:", j.live_url),
60
62
  )
61
- print(job.final_result)
62
- print("watch live:", job.live_url)
63
+ print(job.outcome, job.final_result)
63
64
  ```
64
65
 
65
- That runs a real Chromium fork (Phantom, our real browser) inside an isolated burner session, driven by [browser-use](https://browser-use.com) + Claude Opus. The agent navigates, extracts, and returns. A live noVNC stream URL is available the moment the burner spawns.
66
+ That runs Phantom, our Chromium build, in a temporary cloud browser, driven by Browsa's hosted model: no LLM key needed. To use your own model instead, pass `llm="anthropic:claude-sonnet-5-5"` with `llm_api_key`, or save the key once (below).
67
+
68
+ `job.status` says the run ended; `job.outcome` says how. `outcome == "failed"` with `status == "completed"` means the agent finished but could not do the task, and `final_result` says what stopped it.
69
+
70
+ `live_url` is a Phantom Live link to watch the browser. It exists only while the task runs (so read it in `on_progress` or from `create_task`), and each link opens once.
66
71
 
67
72
  ## Saved LLM keys
68
73
 
@@ -81,7 +86,7 @@ job = c.run_task(task="Return the title of example.com")
81
86
  job = c.run_task(task="...", llm="anthropic:claude-sonnet-5-5", llm_key_id=key.id)
82
87
  ```
83
88
 
84
- Which key a task uses, first match wins: `llm_api_key` (per task), then `llm_key_id`, then the workspace's default saved key for the provider of `llm` (with `llm` omitted: the first default in the order anthropic, openai, google), then `llm="browsa"` (Browsa's hosted model).
89
+ Which key a task uses, first match wins: `llm_api_key` (per task), then `llm_key_id`, then the workspace's default saved key for the provider of `llm` (with `llm` omitted: the first default in the order anthropic, openai, google), then a hosted tier such as `llm="browsa"` (see [Models](#models)).
85
90
 
86
91
  | Method | Endpoint |
87
92
  |---|---|
@@ -95,6 +100,43 @@ Which key a task uses, first match wins: `llm_api_key` (per task), then `llm_key
95
100
 
96
101
  Providers: `anthropic`, `openai`, `google`, `openai_compatible` (needs `base_url`). Each returns an `LLMKey` (or nothing, for delete). The API never returns the secret, only `masked` (prefix + last 4). Keys are checked with a free model-list call when saved or rotated; an invalid key raises `APIError` with code `LLM_KEY_INVALID` and nothing changes. Rotating keeps the id, so schedules and queued runs pick up the new secret. Jobs show `llm_key_id`, `llm_key_masked` and `llm_key_source` (`"saved"` or `"default"`).
97
102
 
103
+ ## Models
104
+
105
+ A task runs on one of Browsa's hosted tiers, or on any provider model with your own key.
106
+
107
+ | `llm` | What it is |
108
+ |---|---|
109
+ | `"browsa"` | The default hosted model |
110
+ | `"browsa-fast"` | Fastest and lightest |
111
+ | `"browsa-smart"` | For harder tasks |
112
+ | anything else, e.g. `"anthropic:claude-sonnet-5-5"` | A provider model, run with your own key (`llm_api_key`, `llm_key_id` or the workspace default) |
113
+
114
+ Hosted tiers need no LLM key and add a flat number of credits per task. Which model each tier runs on, and what it costs, are server settings that can change, so read them from `models()` (free, read-only) instead of hardcoding them:
115
+
116
+ ```python
117
+ m = c.models()
118
+ for tier in m.hosted:
119
+ print(tier.id, tier.model, tier.reasoning, tier.credits_per_task, tier.default)
120
+ print(m.own_key.providers, m.own_key.default_models)
121
+ ```
122
+
123
+ `reasoning` sets how much the model reasons: `"low"`, `"medium"` or `"high"`. Leave it out for the tier's or the provider's default. It is accepted by `create_task`, `run_task`, `create_session`, `send_message`, `run_message` and `create_schedule`; the API answers 400 for any other value.
124
+
125
+ ```python
126
+ job = c.run_task(
127
+ task="Go to news.ycombinator.com and return the top story title.",
128
+ llm="browsa-smart",
129
+ reasoning="high",
130
+ )
131
+ print(job.final_result)
132
+ print(job.llm_tier, job.reasoning) # browsa-smart high
133
+ if job.usage:
134
+ print(job.usage.input_tokens, job.usage.output_tokens, job.usage.requests)
135
+ print(job.llm_cost_usd) # None for hosted runs
136
+ ```
137
+
138
+ A finished job has `usage` (`input_tokens`, `output_tokens`, `cache_read_tokens`, `cache_write_tokens`, `requests`), `llm_cost_usd`, `llm_tier` and `reasoning` (the level that was applied). `llm_cost_usd` is an estimate from public list prices for runs with your own key; it is `None` when unknown and always `None` for hosted runs, which are paid in credits. All four are `None` on jobs that do not have them, such as jobs run before these fields existed.
139
+
98
140
  ## Async
99
141
 
100
142
  ```python
@@ -136,10 +178,12 @@ if not ok:
136
178
  |---|---|
137
179
  | Sync + async clients | `Client` + `AsyncClient`, same surface |
138
180
  | Real `Job` envelope | Typed dataclass + `.raw` escape hatch |
181
+ | Hosted tiers + reasoning | `llm="browsa" / "browsa-fast" / "browsa-smart"`, `reasoning=`, `models()`, `job.usage` |
139
182
  | Long-poll waits | `wait_for_job(timeout=...)` uses server-side `?wait=30` |
140
183
  | Live step events | `for ev in client.stream_job_events(job_id, after=0)`; resume with `after=<last n>` |
141
184
  | Webhook signature verify | HMAC-SHA256, constant-time compare, skew check |
142
- | Canonical error envelope | `AuthError`, `InvalidIDError`, `RateLimitError`, etc. |
185
+ | Canonical error envelope | `AuthError`, `InvalidIDError`, `RateLimitError`, `TimeoutError`, etc.; every one is a `BrowsaError` |
186
+ | Typed | Ships `py.typed`; works with `mypy --strict` and pyright |
143
187
  | `X-Request-Id` propagation | Every error carries the server's request id |
144
188
  | Zero deps | Single wheel, audit-friendly, no transitive surface |
145
189
 
@@ -204,6 +248,42 @@ job = c.run_task(
204
248
  )
205
249
  ```
206
250
 
251
+ ### Observe and act (no Playwright)
252
+
253
+ Read a running browser's page as compact text with element ids, then act on the ids. Each `act` returns what changed, not the whole page.
254
+
255
+ ```python
256
+ b = c.create_agent(ttl="10m")
257
+ c.act(b["id"], "navigate", url="https://example.com/login")
258
+ view = c.observe(b["id"])
259
+ print(view["text"]) # [3] textbox "Email" empty …
260
+ r = c.act(b["id"], "type", id=3, text="ada@example.com")
261
+ print(r["status"], r["text"]) # ok ~ [3] textbox "Email" value "ada@example.com"
262
+ c.act(b["id"], "click", role="button", name="Sign in")
263
+ ```
264
+
265
+ `status` is `ok`, `failed`, `blocked`, `challenge` or `stale`; none of them raises. `stale` means the ids came from a view the server no longer has (`ids_reset` is true): nothing was done and `text` carries a new view. Both calls are free. Format and actions: <https://browsa.io/docs#agents-observe>.
266
+
267
+ ### Downloads and Phantom Live
268
+
269
+ Files a browser downloads are kept with the browser, not on your machine, so Playwright's `download.save_as()` cannot reach them. List and fetch them through the API before you stop the browser:
270
+
271
+ ```python
272
+ files = c.list_downloads(b["id"]) # [{"name", "size", "modified_at"}]
273
+ data = c.download_file(b["id"], files[0]["name"]) # bytes
274
+ ```
275
+
276
+ With Playwright the name is the last part of `download.path()`.
277
+
278
+ `create_live_link` gives a link that shows a running browser in any web browser, to watch or to take over:
279
+
280
+ ```python
281
+ link = c.create_live_link(b["id"], scope="control", ttl_seconds=600)
282
+ print(link["live_url"]) # opens once; make one per person
283
+ ```
284
+
285
+ `scope` is `"view"` (default) or `"control"`. Both calls are free.
286
+
207
287
  ## Docs
208
288
 
209
289
  - API reference: <https://browsa.io/docs>
@@ -25,14 +25,17 @@ from browsa import Client
25
25
  c = Client(api_key="agt_live_...")
26
26
  job = c.run_task(
27
27
  task="Go to news.ycombinator.com and return the top story title.",
28
- llm="claude-opus-5-5",
29
- llm_api_key="sk-ant-...",
28
+ llm="browsa",
29
+ on_progress=lambda j: j.live_url and print("watch live:", j.live_url),
30
30
  )
31
- print(job.final_result)
32
- print("watch live:", job.live_url)
31
+ print(job.outcome, job.final_result)
33
32
  ```
34
33
 
35
- That runs a real Chromium fork (Phantom, our real browser) inside an isolated burner session, driven by [browser-use](https://browser-use.com) + Claude Opus. The agent navigates, extracts, and returns. A live noVNC stream URL is available the moment the burner spawns.
34
+ That runs Phantom, our Chromium build, in a temporary cloud browser, driven by Browsa's hosted model: no LLM key needed. To use your own model instead, pass `llm="anthropic:claude-sonnet-5-5"` with `llm_api_key`, or save the key once (below).
35
+
36
+ `job.status` says the run ended; `job.outcome` says how. `outcome == "failed"` with `status == "completed"` means the agent finished but could not do the task, and `final_result` says what stopped it.
37
+
38
+ `live_url` is a Phantom Live link to watch the browser. It exists only while the task runs (so read it in `on_progress` or from `create_task`), and each link opens once.
36
39
 
37
40
  ## Saved LLM keys
38
41
 
@@ -51,7 +54,7 @@ job = c.run_task(task="Return the title of example.com")
51
54
  job = c.run_task(task="...", llm="anthropic:claude-sonnet-5-5", llm_key_id=key.id)
52
55
  ```
53
56
 
54
- Which key a task uses, first match wins: `llm_api_key` (per task), then `llm_key_id`, then the workspace's default saved key for the provider of `llm` (with `llm` omitted: the first default in the order anthropic, openai, google), then `llm="browsa"` (Browsa's hosted model).
57
+ Which key a task uses, first match wins: `llm_api_key` (per task), then `llm_key_id`, then the workspace's default saved key for the provider of `llm` (with `llm` omitted: the first default in the order anthropic, openai, google), then a hosted tier such as `llm="browsa"` (see [Models](#models)).
55
58
 
56
59
  | Method | Endpoint |
57
60
  |---|---|
@@ -65,6 +68,43 @@ Which key a task uses, first match wins: `llm_api_key` (per task), then `llm_key
65
68
 
66
69
  Providers: `anthropic`, `openai`, `google`, `openai_compatible` (needs `base_url`). Each returns an `LLMKey` (or nothing, for delete). The API never returns the secret, only `masked` (prefix + last 4). Keys are checked with a free model-list call when saved or rotated; an invalid key raises `APIError` with code `LLM_KEY_INVALID` and nothing changes. Rotating keeps the id, so schedules and queued runs pick up the new secret. Jobs show `llm_key_id`, `llm_key_masked` and `llm_key_source` (`"saved"` or `"default"`).
67
70
 
71
+ ## Models
72
+
73
+ A task runs on one of Browsa's hosted tiers, or on any provider model with your own key.
74
+
75
+ | `llm` | What it is |
76
+ |---|---|
77
+ | `"browsa"` | The default hosted model |
78
+ | `"browsa-fast"` | Fastest and lightest |
79
+ | `"browsa-smart"` | For harder tasks |
80
+ | anything else, e.g. `"anthropic:claude-sonnet-5-5"` | A provider model, run with your own key (`llm_api_key`, `llm_key_id` or the workspace default) |
81
+
82
+ Hosted tiers need no LLM key and add a flat number of credits per task. Which model each tier runs on, and what it costs, are server settings that can change, so read them from `models()` (free, read-only) instead of hardcoding them:
83
+
84
+ ```python
85
+ m = c.models()
86
+ for tier in m.hosted:
87
+ print(tier.id, tier.model, tier.reasoning, tier.credits_per_task, tier.default)
88
+ print(m.own_key.providers, m.own_key.default_models)
89
+ ```
90
+
91
+ `reasoning` sets how much the model reasons: `"low"`, `"medium"` or `"high"`. Leave it out for the tier's or the provider's default. It is accepted by `create_task`, `run_task`, `create_session`, `send_message`, `run_message` and `create_schedule`; the API answers 400 for any other value.
92
+
93
+ ```python
94
+ job = c.run_task(
95
+ task="Go to news.ycombinator.com and return the top story title.",
96
+ llm="browsa-smart",
97
+ reasoning="high",
98
+ )
99
+ print(job.final_result)
100
+ print(job.llm_tier, job.reasoning) # browsa-smart high
101
+ if job.usage:
102
+ print(job.usage.input_tokens, job.usage.output_tokens, job.usage.requests)
103
+ print(job.llm_cost_usd) # None for hosted runs
104
+ ```
105
+
106
+ A finished job has `usage` (`input_tokens`, `output_tokens`, `cache_read_tokens`, `cache_write_tokens`, `requests`), `llm_cost_usd`, `llm_tier` and `reasoning` (the level that was applied). `llm_cost_usd` is an estimate from public list prices for runs with your own key; it is `None` when unknown and always `None` for hosted runs, which are paid in credits. All four are `None` on jobs that do not have them, such as jobs run before these fields existed.
107
+
68
108
  ## Async
69
109
 
70
110
  ```python
@@ -106,10 +146,12 @@ if not ok:
106
146
  |---|---|
107
147
  | Sync + async clients | `Client` + `AsyncClient`, same surface |
108
148
  | Real `Job` envelope | Typed dataclass + `.raw` escape hatch |
149
+ | Hosted tiers + reasoning | `llm="browsa" / "browsa-fast" / "browsa-smart"`, `reasoning=`, `models()`, `job.usage` |
109
150
  | Long-poll waits | `wait_for_job(timeout=...)` uses server-side `?wait=30` |
110
151
  | Live step events | `for ev in client.stream_job_events(job_id, after=0)`; resume with `after=<last n>` |
111
152
  | Webhook signature verify | HMAC-SHA256, constant-time compare, skew check |
112
- | Canonical error envelope | `AuthError`, `InvalidIDError`, `RateLimitError`, etc. |
153
+ | Canonical error envelope | `AuthError`, `InvalidIDError`, `RateLimitError`, `TimeoutError`, etc.; every one is a `BrowsaError` |
154
+ | Typed | Ships `py.typed`; works with `mypy --strict` and pyright |
113
155
  | `X-Request-Id` propagation | Every error carries the server's request id |
114
156
  | Zero deps | Single wheel, audit-friendly, no transitive surface |
115
157
 
@@ -174,6 +216,42 @@ job = c.run_task(
174
216
  )
175
217
  ```
176
218
 
219
+ ### Observe and act (no Playwright)
220
+
221
+ Read a running browser's page as compact text with element ids, then act on the ids. Each `act` returns what changed, not the whole page.
222
+
223
+ ```python
224
+ b = c.create_agent(ttl="10m")
225
+ c.act(b["id"], "navigate", url="https://example.com/login")
226
+ view = c.observe(b["id"])
227
+ print(view["text"]) # [3] textbox "Email" empty …
228
+ r = c.act(b["id"], "type", id=3, text="ada@example.com")
229
+ print(r["status"], r["text"]) # ok ~ [3] textbox "Email" value "ada@example.com"
230
+ c.act(b["id"], "click", role="button", name="Sign in")
231
+ ```
232
+
233
+ `status` is `ok`, `failed`, `blocked`, `challenge` or `stale`; none of them raises. `stale` means the ids came from a view the server no longer has (`ids_reset` is true): nothing was done and `text` carries a new view. Both calls are free. Format and actions: <https://browsa.io/docs#agents-observe>.
234
+
235
+ ### Downloads and Phantom Live
236
+
237
+ Files a browser downloads are kept with the browser, not on your machine, so Playwright's `download.save_as()` cannot reach them. List and fetch them through the API before you stop the browser:
238
+
239
+ ```python
240
+ files = c.list_downloads(b["id"]) # [{"name", "size", "modified_at"}]
241
+ data = c.download_file(b["id"], files[0]["name"]) # bytes
242
+ ```
243
+
244
+ With Playwright the name is the last part of `download.path()`.
245
+
246
+ `create_live_link` gives a link that shows a running browser in any web browser, to watch or to take over:
247
+
248
+ ```python
249
+ link = c.create_live_link(b["id"], scope="control", ttl_seconds=600)
250
+ print(link["live_url"]) # opens once; make one per person
251
+ ```
252
+
253
+ `scope` is `"view"` (default) or `"control"`. Both calls are free.
254
+
177
255
  ## Docs
178
256
 
179
257
  - API reference: <https://browsa.io/docs>
@@ -7,29 +7,31 @@ Quickstart:
7
7
 
8
8
  client = Client(api_key="agt_live_...")
9
9
 
10
- # Run a task synchronously (blocks until the agent finishes)
10
+ # Run a task and wait for it (hosted model: no LLM key needed)
11
11
  job = client.run_task(
12
12
  task="Go to news.ycombinator.com and return the top story title.",
13
- llm="claude-opus-5-5",
14
- llm_api_key="sk-ant-...",
13
+ llm="browsa",
15
14
  )
16
- print(job.final_result)
17
- print(f"Live stream: {job.live_url}")
15
+ print(job.outcome, job.final_result)
18
16
 
19
- That's it. Five lines of Python to drive a real browser through
20
- an AI agent, get back structured output, and a live noVNC viewer URL.
17
+ job.status says the run ended; job.outcome says how ("failed" with status
18
+ "completed": the agent finished but could not do the task).
21
19
 
22
20
  For async usage:
23
21
 
24
22
  from browsa import AsyncClient
25
23
 
26
24
  async with AsyncClient(api_key="agt_live_...") as c:
27
- job = await c.run_task(task="...", llm="claude-opus-5-5", ...)
25
+ job = await c.run_task(task="...", llm="browsa")
28
26
 
29
27
  For webhooks see browsa.webhooks.verify_signature.
30
28
  """
31
29
  from .client import Client, AsyncClient
32
- from .types import Job, JobFile, JobStatus, LLMKey, Schedule, Session, SessionBrowser, SessionTurn, Webhook
30
+ from .types import (
31
+ HostedModel, Job, JobFile, JobStatus, LLMKey, Models, OwnKeyModels, Schedule,
32
+ Session, SessionBrowser, SessionTurn, Usage, Webhook,
33
+ NetworkProxy, Proxy, ProxyConfig, ProxyNetwork, ProxyNetworkTier,
34
+ )
33
35
  from .errors import (
34
36
  BrowsaError,
35
37
  APIError,
@@ -46,15 +48,24 @@ from ._version import __version__
46
48
  __all__ = [
47
49
  "Client",
48
50
  "AsyncClient",
51
+ "HostedModel",
49
52
  "Job",
50
53
  "JobFile",
51
54
  "JobStatus",
52
55
  "LLMKey",
56
+ "Models",
57
+ "OwnKeyModels",
53
58
  "Schedule",
54
59
  "Session",
55
60
  "SessionBrowser",
56
61
  "SessionTurn",
62
+ "Usage",
57
63
  "Webhook",
64
+ "NetworkProxy",
65
+ "Proxy",
66
+ "ProxyConfig",
67
+ "ProxyNetwork",
68
+ "ProxyNetworkTier",
58
69
  "BrowsaError",
59
70
  "APIError",
60
71
  "AuthError",
@@ -0,0 +1 @@
1
+ __version__ = "0.3.1"