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.
@@ -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.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://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
@@ -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"` (Browsa's hosted model).
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"` (Browsa's hosted model).
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 Job, JobFile, JobStatus, LLMKey, Schedule, Session, SessionBrowser, SessionTurn, Webhook
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"