browsa 0.2.0__tar.gz → 0.3.0__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.
- {browsa-0.2.0 → browsa-0.3.0}/LICENSE +1 -1
- {browsa-0.2.0 → browsa-0.3.0}/PKG-INFO +60 -5
- {browsa-0.2.0 → browsa-0.3.0}/README.md +55 -1
- {browsa-0.2.0 → browsa-0.3.0}/browsa/__init__.py +14 -1
- browsa-0.3.0/browsa/_version.py +1 -0
- {browsa-0.2.0 → browsa-0.3.0}/browsa/client.py +221 -11
- {browsa-0.2.0 → browsa-0.3.0}/browsa/types.py +251 -3
- {browsa-0.2.0 → browsa-0.3.0}/browsa.egg-info/PKG-INFO +60 -5
- {browsa-0.2.0 → browsa-0.3.0}/pyproject.toml +4 -3
- {browsa-0.2.0 → browsa-0.3.0}/tests/test_unit.py +316 -0
- browsa-0.2.0/browsa/_version.py +0 -1
- {browsa-0.2.0 → browsa-0.3.0}/browsa/errors.py +0 -0
- {browsa-0.2.0 → browsa-0.3.0}/browsa/webhooks.py +0 -0
- {browsa-0.2.0 → browsa-0.3.0}/browsa.egg-info/SOURCES.txt +0 -0
- {browsa-0.2.0 → browsa-0.3.0}/browsa.egg-info/dependency_links.txt +0 -0
- {browsa-0.2.0 → browsa-0.3.0}/browsa.egg-info/requires.txt +0 -0
- {browsa-0.2.0 → browsa-0.3.0}/browsa.egg-info/top_level.txt +0 -0
- {browsa-0.2.0 → browsa-0.3.0}/setup.cfg +0 -0
- {browsa-0.2.0 → browsa-0.3.0}/tests/test_live.py +0 -0
|
@@ -1,14 +1,15 @@
|
|
|
1
1
|
Metadata-Version: 2.4
|
|
2
2
|
Name: browsa
|
|
3
|
-
Version: 0.
|
|
3
|
+
Version: 0.3.0
|
|
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://
|
|
10
|
-
Project-URL: Issues, https://browsa
|
|
11
|
-
|
|
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
|
|
@@ -81,7 +82,7 @@ job = c.run_task(task="Return the title of example.com")
|
|
|
81
82
|
job = c.run_task(task="...", llm="anthropic:claude-sonnet-5-5", llm_key_id=key.id)
|
|
82
83
|
```
|
|
83
84
|
|
|
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"` (
|
|
85
|
+
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
86
|
|
|
86
87
|
| Method | Endpoint |
|
|
87
88
|
|---|---|
|
|
@@ -95,6 +96,43 @@ Which key a task uses, first match wins: `llm_api_key` (per task), then `llm_key
|
|
|
95
96
|
|
|
96
97
|
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
98
|
|
|
99
|
+
## Models
|
|
100
|
+
|
|
101
|
+
A task runs on one of Browsa's hosted tiers, or on any provider model with your own key.
|
|
102
|
+
|
|
103
|
+
| `llm` | What it is |
|
|
104
|
+
|---|---|
|
|
105
|
+
| `"browsa"` | The default hosted model |
|
|
106
|
+
| `"browsa-fast"` | Fastest and lightest |
|
|
107
|
+
| `"browsa-smart"` | For harder tasks |
|
|
108
|
+
| 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) |
|
|
109
|
+
|
|
110
|
+
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:
|
|
111
|
+
|
|
112
|
+
```python
|
|
113
|
+
m = c.models()
|
|
114
|
+
for tier in m.hosted:
|
|
115
|
+
print(tier.id, tier.model, tier.reasoning, tier.credits_per_task, tier.default)
|
|
116
|
+
print(m.own_key.providers, m.own_key.default_models)
|
|
117
|
+
```
|
|
118
|
+
|
|
119
|
+
`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.
|
|
120
|
+
|
|
121
|
+
```python
|
|
122
|
+
job = c.run_task(
|
|
123
|
+
task="Go to news.ycombinator.com and return the top story title.",
|
|
124
|
+
llm="browsa-smart",
|
|
125
|
+
reasoning="high",
|
|
126
|
+
)
|
|
127
|
+
print(job.final_result)
|
|
128
|
+
print(job.llm_tier, job.reasoning) # browsa-smart high
|
|
129
|
+
if job.usage:
|
|
130
|
+
print(job.usage.input_tokens, job.usage.output_tokens, job.usage.requests)
|
|
131
|
+
print(job.llm_cost_usd) # None for hosted runs
|
|
132
|
+
```
|
|
133
|
+
|
|
134
|
+
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.
|
|
135
|
+
|
|
98
136
|
## Async
|
|
99
137
|
|
|
100
138
|
```python
|
|
@@ -136,6 +174,7 @@ if not ok:
|
|
|
136
174
|
|---|---|
|
|
137
175
|
| Sync + async clients | `Client` + `AsyncClient`, same surface |
|
|
138
176
|
| Real `Job` envelope | Typed dataclass + `.raw` escape hatch |
|
|
177
|
+
| Hosted tiers + reasoning | `llm="browsa" / "browsa-fast" / "browsa-smart"`, `reasoning=`, `models()`, `job.usage` |
|
|
139
178
|
| Long-poll waits | `wait_for_job(timeout=...)` uses server-side `?wait=30` |
|
|
140
179
|
| Live step events | `for ev in client.stream_job_events(job_id, after=0)`; resume with `after=<last n>` |
|
|
141
180
|
| Webhook signature verify | HMAC-SHA256, constant-time compare, skew check |
|
|
@@ -204,6 +243,22 @@ job = c.run_task(
|
|
|
204
243
|
)
|
|
205
244
|
```
|
|
206
245
|
|
|
246
|
+
### Observe and act (no Playwright)
|
|
247
|
+
|
|
248
|
+
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.
|
|
249
|
+
|
|
250
|
+
```python
|
|
251
|
+
b = c.create_agent(ttl="10m")
|
|
252
|
+
c.act(b["id"], "navigate", url="https://example.com/login")
|
|
253
|
+
view = c.observe(b["id"])
|
|
254
|
+
print(view["text"]) # [3] textbox "Email" empty …
|
|
255
|
+
r = c.act(b["id"], "type", id=3, text="ada@example.com")
|
|
256
|
+
print(r["status"], r["text"]) # ok ~ [3] textbox "Email" value "ada@example.com"
|
|
257
|
+
c.act(b["id"], "click", role="button", name="Sign in")
|
|
258
|
+
```
|
|
259
|
+
|
|
260
|
+
`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>.
|
|
261
|
+
|
|
207
262
|
## Docs
|
|
208
263
|
|
|
209
264
|
- API reference: <https://browsa.io/docs>
|
|
@@ -51,7 +51,7 @@ job = c.run_task(task="Return the title of example.com")
|
|
|
51
51
|
job = c.run_task(task="...", llm="anthropic:claude-sonnet-5-5", llm_key_id=key.id)
|
|
52
52
|
```
|
|
53
53
|
|
|
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"` (
|
|
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 a hosted tier such as `llm="browsa"` (see [Models](#models)).
|
|
55
55
|
|
|
56
56
|
| Method | Endpoint |
|
|
57
57
|
|---|---|
|
|
@@ -65,6 +65,43 @@ Which key a task uses, first match wins: `llm_api_key` (per task), then `llm_key
|
|
|
65
65
|
|
|
66
66
|
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
67
|
|
|
68
|
+
## Models
|
|
69
|
+
|
|
70
|
+
A task runs on one of Browsa's hosted tiers, or on any provider model with your own key.
|
|
71
|
+
|
|
72
|
+
| `llm` | What it is |
|
|
73
|
+
|---|---|
|
|
74
|
+
| `"browsa"` | The default hosted model |
|
|
75
|
+
| `"browsa-fast"` | Fastest and lightest |
|
|
76
|
+
| `"browsa-smart"` | For harder tasks |
|
|
77
|
+
| 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) |
|
|
78
|
+
|
|
79
|
+
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:
|
|
80
|
+
|
|
81
|
+
```python
|
|
82
|
+
m = c.models()
|
|
83
|
+
for tier in m.hosted:
|
|
84
|
+
print(tier.id, tier.model, tier.reasoning, tier.credits_per_task, tier.default)
|
|
85
|
+
print(m.own_key.providers, m.own_key.default_models)
|
|
86
|
+
```
|
|
87
|
+
|
|
88
|
+
`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.
|
|
89
|
+
|
|
90
|
+
```python
|
|
91
|
+
job = c.run_task(
|
|
92
|
+
task="Go to news.ycombinator.com and return the top story title.",
|
|
93
|
+
llm="browsa-smart",
|
|
94
|
+
reasoning="high",
|
|
95
|
+
)
|
|
96
|
+
print(job.final_result)
|
|
97
|
+
print(job.llm_tier, job.reasoning) # browsa-smart high
|
|
98
|
+
if job.usage:
|
|
99
|
+
print(job.usage.input_tokens, job.usage.output_tokens, job.usage.requests)
|
|
100
|
+
print(job.llm_cost_usd) # None for hosted runs
|
|
101
|
+
```
|
|
102
|
+
|
|
103
|
+
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.
|
|
104
|
+
|
|
68
105
|
## Async
|
|
69
106
|
|
|
70
107
|
```python
|
|
@@ -106,6 +143,7 @@ if not ok:
|
|
|
106
143
|
|---|---|
|
|
107
144
|
| Sync + async clients | `Client` + `AsyncClient`, same surface |
|
|
108
145
|
| Real `Job` envelope | Typed dataclass + `.raw` escape hatch |
|
|
146
|
+
| Hosted tiers + reasoning | `llm="browsa" / "browsa-fast" / "browsa-smart"`, `reasoning=`, `models()`, `job.usage` |
|
|
109
147
|
| Long-poll waits | `wait_for_job(timeout=...)` uses server-side `?wait=30` |
|
|
110
148
|
| Live step events | `for ev in client.stream_job_events(job_id, after=0)`; resume with `after=<last n>` |
|
|
111
149
|
| Webhook signature verify | HMAC-SHA256, constant-time compare, skew check |
|
|
@@ -174,6 +212,22 @@ job = c.run_task(
|
|
|
174
212
|
)
|
|
175
213
|
```
|
|
176
214
|
|
|
215
|
+
### Observe and act (no Playwright)
|
|
216
|
+
|
|
217
|
+
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.
|
|
218
|
+
|
|
219
|
+
```python
|
|
220
|
+
b = c.create_agent(ttl="10m")
|
|
221
|
+
c.act(b["id"], "navigate", url="https://example.com/login")
|
|
222
|
+
view = c.observe(b["id"])
|
|
223
|
+
print(view["text"]) # [3] textbox "Email" empty …
|
|
224
|
+
r = c.act(b["id"], "type", id=3, text="ada@example.com")
|
|
225
|
+
print(r["status"], r["text"]) # ok ~ [3] textbox "Email" value "ada@example.com"
|
|
226
|
+
c.act(b["id"], "click", role="button", name="Sign in")
|
|
227
|
+
```
|
|
228
|
+
|
|
229
|
+
`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>.
|
|
230
|
+
|
|
177
231
|
## Docs
|
|
178
232
|
|
|
179
233
|
- API reference: <https://browsa.io/docs>
|
|
@@ -29,7 +29,11 @@ For async usage:
|
|
|
29
29
|
For webhooks see browsa.webhooks.verify_signature.
|
|
30
30
|
"""
|
|
31
31
|
from .client import Client, AsyncClient
|
|
32
|
-
from .types import
|
|
32
|
+
from .types import (
|
|
33
|
+
HostedModel, Job, JobFile, JobStatus, LLMKey, Models, OwnKeyModels, Schedule,
|
|
34
|
+
Session, SessionBrowser, SessionTurn, Usage, Webhook,
|
|
35
|
+
NetworkProxy, Proxy, ProxyConfig, ProxyNetwork, ProxyNetworkTier,
|
|
36
|
+
)
|
|
33
37
|
from .errors import (
|
|
34
38
|
BrowsaError,
|
|
35
39
|
APIError,
|
|
@@ -46,15 +50,24 @@ from ._version import __version__
|
|
|
46
50
|
__all__ = [
|
|
47
51
|
"Client",
|
|
48
52
|
"AsyncClient",
|
|
53
|
+
"HostedModel",
|
|
49
54
|
"Job",
|
|
50
55
|
"JobFile",
|
|
51
56
|
"JobStatus",
|
|
52
57
|
"LLMKey",
|
|
58
|
+
"Models",
|
|
59
|
+
"OwnKeyModels",
|
|
53
60
|
"Schedule",
|
|
54
61
|
"Session",
|
|
55
62
|
"SessionBrowser",
|
|
56
63
|
"SessionTurn",
|
|
64
|
+
"Usage",
|
|
57
65
|
"Webhook",
|
|
66
|
+
"NetworkProxy",
|
|
67
|
+
"Proxy",
|
|
68
|
+
"ProxyConfig",
|
|
69
|
+
"ProxyNetwork",
|
|
70
|
+
"ProxyNetworkTier",
|
|
58
71
|
"BrowsaError",
|
|
59
72
|
"APIError",
|
|
60
73
|
"AuthError",
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
__version__ = "0.3.0"
|