browsa 0.1.3__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
browsa-0.3.0/PKG-INFO ADDED
@@ -0,0 +1,270 @@
1
+ Metadata-Version: 2.4
2
+ Name: browsa
3
+ Version: 0.3.0
4
+ Summary: Official Python SDK for Browsa: real cloud browsers for AI agents (browsa.io)
5
+ Author-email: Browsa <support@browsa.io>
6
+ License: MIT
7
+ Project-URL: Homepage, https://browsa.io
8
+ Project-URL: Documentation, https://browsa.io/docs
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
13
+ Classifier: Development Status :: 4 - Beta
14
+ Classifier: Intended Audience :: Developers
15
+ Classifier: License :: OSI Approved :: MIT License
16
+ Classifier: Programming Language :: Python :: 3
17
+ Classifier: Programming Language :: Python :: 3.9
18
+ Classifier: Programming Language :: Python :: 3.10
19
+ Classifier: Programming Language :: Python :: 3.11
20
+ Classifier: Programming Language :: Python :: 3.12
21
+ Classifier: Topic :: Internet :: WWW/HTTP :: Browsers
22
+ Classifier: Topic :: Software Development :: Libraries :: Python Modules
23
+ Requires-Python: >=3.9
24
+ Description-Content-Type: text/markdown
25
+ License-File: LICENSE
26
+ Provides-Extra: dev
27
+ Requires-Dist: pytest>=7; extra == "dev"
28
+ Requires-Dist: pytest-asyncio>=0.21; extra == "dev"
29
+ Requires-Dist: ruff>=0.1; extra == "dev"
30
+ Dynamic: license-file
31
+
32
+ <p align="center">
33
+ <a href="https://browsa.io"><img src="https://browsa.io/browsa-logo-lockup.png" alt="Browsa" width="340"></a>
34
+ </p>
35
+
36
+ # browsa (Python)
37
+
38
+ Real browsers for AI agents: the official Python SDK for [browsa.io](https://browsa.io).
39
+
40
+ [![PyPI version](https://img.shields.io/pypi/v/browsa.svg)](https://pypi.org/project/browsa/)
41
+ [![Python](https://img.shields.io/pypi/pyversions/browsa.svg)](https://pypi.org/project/browsa/)
42
+
43
+ ## Install
44
+
45
+ ```bash
46
+ pip install browsa
47
+ ```
48
+
49
+ Zero dependencies. Pure stdlib. Single-file wheel.
50
+
51
+ ## Five-line hello world
52
+
53
+ ```python
54
+ from browsa import Client
55
+
56
+ c = Client(api_key="agt_live_...")
57
+ job = c.run_task(
58
+ task="Go to news.ycombinator.com and return the top story title.",
59
+ llm="claude-opus-5-5",
60
+ llm_api_key="sk-ant-...",
61
+ )
62
+ print(job.final_result)
63
+ print("watch live:", job.live_url)
64
+ ```
65
+
66
+ 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.
67
+
68
+ ## Saved LLM keys
69
+
70
+ Save your LLM provider key once in the workspace (dashboard: <https://app.browsa.io/dashboard/llm-keys>, or the API) and tasks use it without the secret in your code:
71
+
72
+ ```python
73
+ import os
74
+
75
+ key = c.create_llm_key("anthropic", os.environ["ANTHROPIC_API_KEY"], name="Prod Anthropic")
76
+ print(key.id, key.masked, key.status) # 3f6c... sk-ant-…a1b2 valid
77
+
78
+ # The first key of a provider becomes its default, so this needs no key at all:
79
+ job = c.run_task(task="Return the title of example.com")
80
+
81
+ # Or pick a saved key by id (also on create_task, create_schedule and auto):
82
+ job = c.run_task(task="...", llm="anthropic:claude-sonnet-5-5", llm_key_id=key.id)
83
+ ```
84
+
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)).
86
+
87
+ | Method | Endpoint |
88
+ |---|---|
89
+ | `create_llm_key(provider, api_key, *, name=None, base_url=None, default=None)` | `POST /v1/llm-keys` |
90
+ | `list_llm_keys()` | `GET /v1/llm-keys` |
91
+ | `get_llm_key(llm_key_id)` | `GET /v1/llm-keys/{id}` |
92
+ | `validate_llm_key(llm_key_id)` | `POST /v1/llm-keys/{id}/validate` |
93
+ | `rotate_llm_key(llm_key_id, api_key, *, base_url=None)` | `POST /v1/llm-keys/{id}/rotate` |
94
+ | `update_llm_key(llm_key_id, *, name=None, default=None)` | `POST /v1/llm-keys/{id}` |
95
+ | `delete_llm_key(llm_key_id)` | `DELETE /v1/llm-keys/{id}` |
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"`).
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
+
136
+ ## Async
137
+
138
+ ```python
139
+ import asyncio
140
+ from browsa import AsyncClient
141
+
142
+ async def main():
143
+ async with AsyncClient(api_key="agt_live_...") as c:
144
+ job = await c.run_task(
145
+ task="Scrape the top 5 products on producthunt.com today.",
146
+ llm="claude-opus-5-5",
147
+ llm_api_key="sk-ant-...",
148
+ country="US",
149
+ )
150
+ print(job.final_result)
151
+
152
+ asyncio.run(main())
153
+ ```
154
+
155
+ ## Webhooks
156
+
157
+ ```python
158
+ from browsa import webhooks
159
+
160
+ # In your receiver (Flask/FastAPI/whatever):
161
+ ok = webhooks.verify_signature(
162
+ body=raw_request_body,
163
+ header=request.headers["X-Agents-Signature"],
164
+ secret=os.environ["BROWSA_WEBHOOK_SECRET"], # hex-encoded
165
+ )
166
+ if not ok:
167
+ return 401
168
+ # Trust the payload only after this point.
169
+ ```
170
+
171
+ ## What you get
172
+
173
+ | Capability | Notes |
174
+ |---|---|
175
+ | Sync + async clients | `Client` + `AsyncClient`, same surface |
176
+ | Real `Job` envelope | Typed dataclass + `.raw` escape hatch |
177
+ | Hosted tiers + reasoning | `llm="browsa" / "browsa-fast" / "browsa-smart"`, `reasoning=`, `models()`, `job.usage` |
178
+ | Long-poll waits | `wait_for_job(timeout=...)` uses server-side `?wait=30` |
179
+ | Live step events | `for ev in client.stream_job_events(job_id, after=0)`; resume with `after=<last n>` |
180
+ | Webhook signature verify | HMAC-SHA256, constant-time compare, skew check |
181
+ | Canonical error envelope | `AuthError`, `InvalidIDError`, `RateLimitError`, etc. |
182
+ | `X-Request-Id` propagation | Every error carries the server's request id |
183
+ | Zero deps | Single wheel, audit-friendly, no transitive surface |
184
+
185
+ ## Advanced
186
+
187
+ ### Long-running tasks with progress callback
188
+
189
+ ```python
190
+ def show(job):
191
+ print(f" step {job.step_count}/{job.progress_total} status={job.status}")
192
+
193
+ job = c.run_task(
194
+ task="Open-ended research: scrape arxiv for papers on test-time compute, return top 10 by citation.",
195
+ llm="claude-opus-5-5",
196
+ llm_api_key="sk-ant-...",
197
+ max_steps=80,
198
+ on_progress=show,
199
+ )
200
+ ```
201
+
202
+ ### Interactive (input_required) tasks
203
+
204
+ If your task can pause for human input (captcha, decision point), watch for status `input_required` and respond:
205
+
206
+ ```python
207
+ job = c.create_task(task="...", llm="...", llm_api_key="...")
208
+ while not job.is_terminal:
209
+ job = c.get_job(job.id, wait=30)
210
+ if job.status == "input_required":
211
+ answer = input(f"Agent asks: {job.input_question}\n> ")
212
+ job = c.respond_to_job(job.id, answer)
213
+ ```
214
+
215
+ ### Sessions: follow-up messages on the same browser
216
+
217
+ Start a task with `create_session` and the browser stays up after it ends (15 minutes by default, `browser_ttl_seconds` up to 3600), so you can send follow-ups that continue on the same page. A follow-up pays no new browser, only the task's base and step credits.
218
+
219
+ ```python
220
+ s = c.create_session("Go to example.com and return the H1.", llm="browsa")
221
+ first = c.wait_for_job(s.id)
222
+ print(first.final_result)
223
+
224
+ turn = c.run_message(s.session_id, "Now open the Learn more link and tell me its URL and H1")
225
+ print(turn.final_result)
226
+
227
+ session = c.get_session(s.session_id)
228
+ print(session.status, session.browser.expires_in_seconds, [t.final_result for t in session.turns])
229
+ c.stop_session(s.session_id)
230
+ ```
231
+
232
+ `send_message` returns the new turn's `Job` right away (use `run_message` to wait). Model fields you leave out reuse the previous turn's model, but a BYOK `llm_api_key` must be sent again on every message. A closed browser raises `APIError` with `code == "BROWSER_EXPIRED"`; a turn still running raises `code == "SESSION_BUSY"`.
233
+
234
+ ### JA3-spoofed sessions
235
+
236
+ Some sites fingerprint TLS handshake shape. Set a profile to spoof macOS Chrome:
237
+
238
+ ```python
239
+ job = c.run_task(
240
+ task="Go to a TLS-fingerprint-fingerprinted site",
241
+ llm="claude-opus-5-5", llm_api_key="sk-...",
242
+ ja3_profile="macos_chrome_137", # uses utls
243
+ )
244
+ ```
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
+
262
+ ## Docs
263
+
264
+ - API reference: <https://browsa.io/docs>
265
+ - Docs: <https://browsa.io/docs>
266
+ - Support: <mailto:support@browsa.io>
267
+
268
+ ## License
269
+
270
+ MIT.
browsa-0.3.0/README.md ADDED
@@ -0,0 +1,239 @@
1
+ <p align="center">
2
+ <a href="https://browsa.io"><img src="https://browsa.io/browsa-logo-lockup.png" alt="Browsa" width="340"></a>
3
+ </p>
4
+
5
+ # browsa (Python)
6
+
7
+ Real browsers for AI agents: the official Python SDK for [browsa.io](https://browsa.io).
8
+
9
+ [![PyPI version](https://img.shields.io/pypi/v/browsa.svg)](https://pypi.org/project/browsa/)
10
+ [![Python](https://img.shields.io/pypi/pyversions/browsa.svg)](https://pypi.org/project/browsa/)
11
+
12
+ ## Install
13
+
14
+ ```bash
15
+ pip install browsa
16
+ ```
17
+
18
+ Zero dependencies. Pure stdlib. Single-file wheel.
19
+
20
+ ## Five-line hello world
21
+
22
+ ```python
23
+ from browsa import Client
24
+
25
+ c = Client(api_key="agt_live_...")
26
+ job = c.run_task(
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-...",
30
+ )
31
+ print(job.final_result)
32
+ print("watch live:", job.live_url)
33
+ ```
34
+
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.
36
+
37
+ ## Saved LLM keys
38
+
39
+ Save your LLM provider key once in the workspace (dashboard: <https://app.browsa.io/dashboard/llm-keys>, or the API) and tasks use it without the secret in your code:
40
+
41
+ ```python
42
+ import os
43
+
44
+ key = c.create_llm_key("anthropic", os.environ["ANTHROPIC_API_KEY"], name="Prod Anthropic")
45
+ print(key.id, key.masked, key.status) # 3f6c... sk-ant-…a1b2 valid
46
+
47
+ # The first key of a provider becomes its default, so this needs no key at all:
48
+ job = c.run_task(task="Return the title of example.com")
49
+
50
+ # Or pick a saved key by id (also on create_task, create_schedule and auto):
51
+ job = c.run_task(task="...", llm="anthropic:claude-sonnet-5-5", llm_key_id=key.id)
52
+ ```
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 a hosted tier such as `llm="browsa"` (see [Models](#models)).
55
+
56
+ | Method | Endpoint |
57
+ |---|---|
58
+ | `create_llm_key(provider, api_key, *, name=None, base_url=None, default=None)` | `POST /v1/llm-keys` |
59
+ | `list_llm_keys()` | `GET /v1/llm-keys` |
60
+ | `get_llm_key(llm_key_id)` | `GET /v1/llm-keys/{id}` |
61
+ | `validate_llm_key(llm_key_id)` | `POST /v1/llm-keys/{id}/validate` |
62
+ | `rotate_llm_key(llm_key_id, api_key, *, base_url=None)` | `POST /v1/llm-keys/{id}/rotate` |
63
+ | `update_llm_key(llm_key_id, *, name=None, default=None)` | `POST /v1/llm-keys/{id}` |
64
+ | `delete_llm_key(llm_key_id)` | `DELETE /v1/llm-keys/{id}` |
65
+
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
+
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
+
105
+ ## Async
106
+
107
+ ```python
108
+ import asyncio
109
+ from browsa import AsyncClient
110
+
111
+ async def main():
112
+ async with AsyncClient(api_key="agt_live_...") as c:
113
+ job = await c.run_task(
114
+ task="Scrape the top 5 products on producthunt.com today.",
115
+ llm="claude-opus-5-5",
116
+ llm_api_key="sk-ant-...",
117
+ country="US",
118
+ )
119
+ print(job.final_result)
120
+
121
+ asyncio.run(main())
122
+ ```
123
+
124
+ ## Webhooks
125
+
126
+ ```python
127
+ from browsa import webhooks
128
+
129
+ # In your receiver (Flask/FastAPI/whatever):
130
+ ok = webhooks.verify_signature(
131
+ body=raw_request_body,
132
+ header=request.headers["X-Agents-Signature"],
133
+ secret=os.environ["BROWSA_WEBHOOK_SECRET"], # hex-encoded
134
+ )
135
+ if not ok:
136
+ return 401
137
+ # Trust the payload only after this point.
138
+ ```
139
+
140
+ ## What you get
141
+
142
+ | Capability | Notes |
143
+ |---|---|
144
+ | Sync + async clients | `Client` + `AsyncClient`, same surface |
145
+ | Real `Job` envelope | Typed dataclass + `.raw` escape hatch |
146
+ | Hosted tiers + reasoning | `llm="browsa" / "browsa-fast" / "browsa-smart"`, `reasoning=`, `models()`, `job.usage` |
147
+ | Long-poll waits | `wait_for_job(timeout=...)` uses server-side `?wait=30` |
148
+ | Live step events | `for ev in client.stream_job_events(job_id, after=0)`; resume with `after=<last n>` |
149
+ | Webhook signature verify | HMAC-SHA256, constant-time compare, skew check |
150
+ | Canonical error envelope | `AuthError`, `InvalidIDError`, `RateLimitError`, etc. |
151
+ | `X-Request-Id` propagation | Every error carries the server's request id |
152
+ | Zero deps | Single wheel, audit-friendly, no transitive surface |
153
+
154
+ ## Advanced
155
+
156
+ ### Long-running tasks with progress callback
157
+
158
+ ```python
159
+ def show(job):
160
+ print(f" step {job.step_count}/{job.progress_total} status={job.status}")
161
+
162
+ job = c.run_task(
163
+ task="Open-ended research: scrape arxiv for papers on test-time compute, return top 10 by citation.",
164
+ llm="claude-opus-5-5",
165
+ llm_api_key="sk-ant-...",
166
+ max_steps=80,
167
+ on_progress=show,
168
+ )
169
+ ```
170
+
171
+ ### Interactive (input_required) tasks
172
+
173
+ If your task can pause for human input (captcha, decision point), watch for status `input_required` and respond:
174
+
175
+ ```python
176
+ job = c.create_task(task="...", llm="...", llm_api_key="...")
177
+ while not job.is_terminal:
178
+ job = c.get_job(job.id, wait=30)
179
+ if job.status == "input_required":
180
+ answer = input(f"Agent asks: {job.input_question}\n> ")
181
+ job = c.respond_to_job(job.id, answer)
182
+ ```
183
+
184
+ ### Sessions: follow-up messages on the same browser
185
+
186
+ Start a task with `create_session` and the browser stays up after it ends (15 minutes by default, `browser_ttl_seconds` up to 3600), so you can send follow-ups that continue on the same page. A follow-up pays no new browser, only the task's base and step credits.
187
+
188
+ ```python
189
+ s = c.create_session("Go to example.com and return the H1.", llm="browsa")
190
+ first = c.wait_for_job(s.id)
191
+ print(first.final_result)
192
+
193
+ turn = c.run_message(s.session_id, "Now open the Learn more link and tell me its URL and H1")
194
+ print(turn.final_result)
195
+
196
+ session = c.get_session(s.session_id)
197
+ print(session.status, session.browser.expires_in_seconds, [t.final_result for t in session.turns])
198
+ c.stop_session(s.session_id)
199
+ ```
200
+
201
+ `send_message` returns the new turn's `Job` right away (use `run_message` to wait). Model fields you leave out reuse the previous turn's model, but a BYOK `llm_api_key` must be sent again on every message. A closed browser raises `APIError` with `code == "BROWSER_EXPIRED"`; a turn still running raises `code == "SESSION_BUSY"`.
202
+
203
+ ### JA3-spoofed sessions
204
+
205
+ Some sites fingerprint TLS handshake shape. Set a profile to spoof macOS Chrome:
206
+
207
+ ```python
208
+ job = c.run_task(
209
+ task="Go to a TLS-fingerprint-fingerprinted site",
210
+ llm="claude-opus-5-5", llm_api_key="sk-...",
211
+ ja3_profile="macos_chrome_137", # uses utls
212
+ )
213
+ ```
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
+
231
+ ## Docs
232
+
233
+ - API reference: <https://browsa.io/docs>
234
+ - Docs: <https://browsa.io/docs>
235
+ - Support: <mailto:support@browsa.io>
236
+
237
+ ## License
238
+
239
+ MIT.
@@ -1,5 +1,5 @@
1
1
  """
2
- browsa — anti-detect browsers for AI agents.
2
+ browsa — real browsers for AI agents.
3
3
 
4
4
  Quickstart:
5
5
 
@@ -10,13 +10,13 @@ Quickstart:
10
10
  # Run a task synchronously (blocks until the agent finishes)
11
11
  job = client.run_task(
12
12
  task="Go to news.ycombinator.com and return the top story title.",
13
- llm="claude-opus-4-7",
13
+ llm="claude-opus-5-5",
14
14
  llm_api_key="sk-ant-...",
15
15
  )
16
16
  print(job.final_result)
17
17
  print(f"Live stream: {job.live_url}")
18
18
 
19
- That's it. Five lines of Python to drive a real anti-detect browser through
19
+ That's it. Five lines of Python to drive a real browser through
20
20
  an AI agent, get back structured output, and a live noVNC viewer URL.
21
21
 
22
22
  For async usage:
@@ -24,15 +24,18 @@ For async usage:
24
24
  from browsa import AsyncClient
25
25
 
26
26
  async with AsyncClient(api_key="agt_live_...") as c:
27
- job = await c.run_task(task="...", llm="claude-opus-4-7", ...)
27
+ job = await c.run_task(task="...", llm="claude-opus-5-5", ...)
28
28
 
29
29
  For webhooks see browsa.webhooks.verify_signature.
30
30
  """
31
31
  from .client import Client, AsyncClient
32
- from .types import Job, JobStatus, 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
- NeoutError, # deprecated alias of BrowsaError — kept for backwards compat
36
39
  APIError,
37
40
  AuthError,
38
41
  RateLimitError,
@@ -47,11 +50,25 @@ from ._version import __version__
47
50
  __all__ = [
48
51
  "Client",
49
52
  "AsyncClient",
53
+ "HostedModel",
50
54
  "Job",
55
+ "JobFile",
51
56
  "JobStatus",
57
+ "LLMKey",
58
+ "Models",
59
+ "OwnKeyModels",
60
+ "Schedule",
61
+ "Session",
62
+ "SessionBrowser",
63
+ "SessionTurn",
64
+ "Usage",
52
65
  "Webhook",
66
+ "NetworkProxy",
67
+ "Proxy",
68
+ "ProxyConfig",
69
+ "ProxyNetwork",
70
+ "ProxyNetworkTier",
53
71
  "BrowsaError",
54
- "NeoutError",
55
72
  "APIError",
56
73
  "AuthError",
57
74
  "RateLimitError",
@@ -0,0 +1 @@
1
+ __version__ = "0.3.0"