browsa 0.1.2__tar.gz → 0.2.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/PKG-INFO ADDED
@@ -0,0 +1,215 @@
1
+ Metadata-Version: 2.4
2
+ Name: browsa
3
+ Version: 0.2.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://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
12
+ Classifier: Development Status :: 4 - Beta
13
+ Classifier: Intended Audience :: Developers
14
+ Classifier: License :: OSI Approved :: MIT License
15
+ Classifier: Programming Language :: Python :: 3
16
+ Classifier: Programming Language :: Python :: 3.9
17
+ Classifier: Programming Language :: Python :: 3.10
18
+ Classifier: Programming Language :: Python :: 3.11
19
+ Classifier: Programming Language :: Python :: 3.12
20
+ Classifier: Topic :: Internet :: WWW/HTTP :: Browsers
21
+ Classifier: Topic :: Software Development :: Libraries :: Python Modules
22
+ Requires-Python: >=3.9
23
+ Description-Content-Type: text/markdown
24
+ License-File: LICENSE
25
+ Provides-Extra: dev
26
+ Requires-Dist: pytest>=7; extra == "dev"
27
+ Requires-Dist: pytest-asyncio>=0.21; extra == "dev"
28
+ Requires-Dist: ruff>=0.1; extra == "dev"
29
+ Dynamic: license-file
30
+
31
+ <p align="center">
32
+ <a href="https://browsa.io"><img src="https://browsa.io/browsa-logo-lockup.png" alt="Browsa" width="340"></a>
33
+ </p>
34
+
35
+ # browsa (Python)
36
+
37
+ Real browsers for AI agents: the official Python SDK for [browsa.io](https://browsa.io).
38
+
39
+ [![PyPI version](https://img.shields.io/pypi/v/browsa.svg)](https://pypi.org/project/browsa/)
40
+ [![Python](https://img.shields.io/pypi/pyversions/browsa.svg)](https://pypi.org/project/browsa/)
41
+
42
+ ## Install
43
+
44
+ ```bash
45
+ pip install browsa
46
+ ```
47
+
48
+ Zero dependencies. Pure stdlib. Single-file wheel.
49
+
50
+ ## Five-line hello world
51
+
52
+ ```python
53
+ from browsa import Client
54
+
55
+ c = Client(api_key="agt_live_...")
56
+ job = c.run_task(
57
+ 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
+ )
61
+ print(job.final_result)
62
+ print("watch live:", job.live_url)
63
+ ```
64
+
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
+
67
+ ## Saved LLM keys
68
+
69
+ 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:
70
+
71
+ ```python
72
+ import os
73
+
74
+ key = c.create_llm_key("anthropic", os.environ["ANTHROPIC_API_KEY"], name="Prod Anthropic")
75
+ print(key.id, key.masked, key.status) # 3f6c... sk-ant-…a1b2 valid
76
+
77
+ # The first key of a provider becomes its default, so this needs no key at all:
78
+ job = c.run_task(task="Return the title of example.com")
79
+
80
+ # Or pick a saved key by id (also on create_task, create_schedule and auto):
81
+ job = c.run_task(task="...", llm="anthropic:claude-sonnet-5-5", llm_key_id=key.id)
82
+ ```
83
+
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
+
86
+ | Method | Endpoint |
87
+ |---|---|
88
+ | `create_llm_key(provider, api_key, *, name=None, base_url=None, default=None)` | `POST /v1/llm-keys` |
89
+ | `list_llm_keys()` | `GET /v1/llm-keys` |
90
+ | `get_llm_key(llm_key_id)` | `GET /v1/llm-keys/{id}` |
91
+ | `validate_llm_key(llm_key_id)` | `POST /v1/llm-keys/{id}/validate` |
92
+ | `rotate_llm_key(llm_key_id, api_key, *, base_url=None)` | `POST /v1/llm-keys/{id}/rotate` |
93
+ | `update_llm_key(llm_key_id, *, name=None, default=None)` | `POST /v1/llm-keys/{id}` |
94
+ | `delete_llm_key(llm_key_id)` | `DELETE /v1/llm-keys/{id}` |
95
+
96
+ 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
+ ## Async
99
+
100
+ ```python
101
+ import asyncio
102
+ from browsa import AsyncClient
103
+
104
+ async def main():
105
+ async with AsyncClient(api_key="agt_live_...") as c:
106
+ job = await c.run_task(
107
+ task="Scrape the top 5 products on producthunt.com today.",
108
+ llm="claude-opus-5-5",
109
+ llm_api_key="sk-ant-...",
110
+ country="US",
111
+ )
112
+ print(job.final_result)
113
+
114
+ asyncio.run(main())
115
+ ```
116
+
117
+ ## Webhooks
118
+
119
+ ```python
120
+ from browsa import webhooks
121
+
122
+ # In your receiver (Flask/FastAPI/whatever):
123
+ ok = webhooks.verify_signature(
124
+ body=raw_request_body,
125
+ header=request.headers["X-Agents-Signature"],
126
+ secret=os.environ["BROWSA_WEBHOOK_SECRET"], # hex-encoded
127
+ )
128
+ if not ok:
129
+ return 401
130
+ # Trust the payload only after this point.
131
+ ```
132
+
133
+ ## What you get
134
+
135
+ | Capability | Notes |
136
+ |---|---|
137
+ | Sync + async clients | `Client` + `AsyncClient`, same surface |
138
+ | Real `Job` envelope | Typed dataclass + `.raw` escape hatch |
139
+ | Long-poll waits | `wait_for_job(timeout=...)` uses server-side `?wait=30` |
140
+ | Live step events | `for ev in client.stream_job_events(job_id, after=0)`; resume with `after=<last n>` |
141
+ | Webhook signature verify | HMAC-SHA256, constant-time compare, skew check |
142
+ | Canonical error envelope | `AuthError`, `InvalidIDError`, `RateLimitError`, etc. |
143
+ | `X-Request-Id` propagation | Every error carries the server's request id |
144
+ | Zero deps | Single wheel, audit-friendly, no transitive surface |
145
+
146
+ ## Advanced
147
+
148
+ ### Long-running tasks with progress callback
149
+
150
+ ```python
151
+ def show(job):
152
+ print(f" step {job.step_count}/{job.progress_total} status={job.status}")
153
+
154
+ job = c.run_task(
155
+ task="Open-ended research: scrape arxiv for papers on test-time compute, return top 10 by citation.",
156
+ llm="claude-opus-5-5",
157
+ llm_api_key="sk-ant-...",
158
+ max_steps=80,
159
+ on_progress=show,
160
+ )
161
+ ```
162
+
163
+ ### Interactive (input_required) tasks
164
+
165
+ If your task can pause for human input (captcha, decision point), watch for status `input_required` and respond:
166
+
167
+ ```python
168
+ job = c.create_task(task="...", llm="...", llm_api_key="...")
169
+ while not job.is_terminal:
170
+ job = c.get_job(job.id, wait=30)
171
+ if job.status == "input_required":
172
+ answer = input(f"Agent asks: {job.input_question}\n> ")
173
+ job = c.respond_to_job(job.id, answer)
174
+ ```
175
+
176
+ ### Sessions: follow-up messages on the same browser
177
+
178
+ 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.
179
+
180
+ ```python
181
+ s = c.create_session("Go to example.com and return the H1.", llm="browsa")
182
+ first = c.wait_for_job(s.id)
183
+ print(first.final_result)
184
+
185
+ turn = c.run_message(s.session_id, "Now open the Learn more link and tell me its URL and H1")
186
+ print(turn.final_result)
187
+
188
+ session = c.get_session(s.session_id)
189
+ print(session.status, session.browser.expires_in_seconds, [t.final_result for t in session.turns])
190
+ c.stop_session(s.session_id)
191
+ ```
192
+
193
+ `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"`.
194
+
195
+ ### JA3-spoofed sessions
196
+
197
+ Some sites fingerprint TLS handshake shape. Set a profile to spoof macOS Chrome:
198
+
199
+ ```python
200
+ job = c.run_task(
201
+ task="Go to a TLS-fingerprint-fingerprinted site",
202
+ llm="claude-opus-5-5", llm_api_key="sk-...",
203
+ ja3_profile="macos_chrome_137", # uses utls
204
+ )
205
+ ```
206
+
207
+ ## Docs
208
+
209
+ - API reference: <https://browsa.io/docs>
210
+ - Docs: <https://browsa.io/docs>
211
+ - Support: <mailto:support@browsa.io>
212
+
213
+ ## License
214
+
215
+ MIT.
browsa-0.2.0/README.md ADDED
@@ -0,0 +1,185 @@
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 `llm="browsa"` (Browsa's hosted model).
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
+ ## Async
69
+
70
+ ```python
71
+ import asyncio
72
+ from browsa import AsyncClient
73
+
74
+ async def main():
75
+ async with AsyncClient(api_key="agt_live_...") as c:
76
+ job = await c.run_task(
77
+ task="Scrape the top 5 products on producthunt.com today.",
78
+ llm="claude-opus-5-5",
79
+ llm_api_key="sk-ant-...",
80
+ country="US",
81
+ )
82
+ print(job.final_result)
83
+
84
+ asyncio.run(main())
85
+ ```
86
+
87
+ ## Webhooks
88
+
89
+ ```python
90
+ from browsa import webhooks
91
+
92
+ # In your receiver (Flask/FastAPI/whatever):
93
+ ok = webhooks.verify_signature(
94
+ body=raw_request_body,
95
+ header=request.headers["X-Agents-Signature"],
96
+ secret=os.environ["BROWSA_WEBHOOK_SECRET"], # hex-encoded
97
+ )
98
+ if not ok:
99
+ return 401
100
+ # Trust the payload only after this point.
101
+ ```
102
+
103
+ ## What you get
104
+
105
+ | Capability | Notes |
106
+ |---|---|
107
+ | Sync + async clients | `Client` + `AsyncClient`, same surface |
108
+ | Real `Job` envelope | Typed dataclass + `.raw` escape hatch |
109
+ | Long-poll waits | `wait_for_job(timeout=...)` uses server-side `?wait=30` |
110
+ | Live step events | `for ev in client.stream_job_events(job_id, after=0)`; resume with `after=<last n>` |
111
+ | Webhook signature verify | HMAC-SHA256, constant-time compare, skew check |
112
+ | Canonical error envelope | `AuthError`, `InvalidIDError`, `RateLimitError`, etc. |
113
+ | `X-Request-Id` propagation | Every error carries the server's request id |
114
+ | Zero deps | Single wheel, audit-friendly, no transitive surface |
115
+
116
+ ## Advanced
117
+
118
+ ### Long-running tasks with progress callback
119
+
120
+ ```python
121
+ def show(job):
122
+ print(f" step {job.step_count}/{job.progress_total} status={job.status}")
123
+
124
+ job = c.run_task(
125
+ task="Open-ended research: scrape arxiv for papers on test-time compute, return top 10 by citation.",
126
+ llm="claude-opus-5-5",
127
+ llm_api_key="sk-ant-...",
128
+ max_steps=80,
129
+ on_progress=show,
130
+ )
131
+ ```
132
+
133
+ ### Interactive (input_required) tasks
134
+
135
+ If your task can pause for human input (captcha, decision point), watch for status `input_required` and respond:
136
+
137
+ ```python
138
+ job = c.create_task(task="...", llm="...", llm_api_key="...")
139
+ while not job.is_terminal:
140
+ job = c.get_job(job.id, wait=30)
141
+ if job.status == "input_required":
142
+ answer = input(f"Agent asks: {job.input_question}\n> ")
143
+ job = c.respond_to_job(job.id, answer)
144
+ ```
145
+
146
+ ### Sessions: follow-up messages on the same browser
147
+
148
+ 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.
149
+
150
+ ```python
151
+ s = c.create_session("Go to example.com and return the H1.", llm="browsa")
152
+ first = c.wait_for_job(s.id)
153
+ print(first.final_result)
154
+
155
+ turn = c.run_message(s.session_id, "Now open the Learn more link and tell me its URL and H1")
156
+ print(turn.final_result)
157
+
158
+ session = c.get_session(s.session_id)
159
+ print(session.status, session.browser.expires_in_seconds, [t.final_result for t in session.turns])
160
+ c.stop_session(s.session_id)
161
+ ```
162
+
163
+ `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"`.
164
+
165
+ ### JA3-spoofed sessions
166
+
167
+ Some sites fingerprint TLS handshake shape. Set a profile to spoof macOS Chrome:
168
+
169
+ ```python
170
+ job = c.run_task(
171
+ task="Go to a TLS-fingerprint-fingerprinted site",
172
+ llm="claude-opus-5-5", llm_api_key="sk-...",
173
+ ja3_profile="macos_chrome_137", # uses utls
174
+ )
175
+ ```
176
+
177
+ ## Docs
178
+
179
+ - API reference: <https://browsa.io/docs>
180
+ - Docs: <https://browsa.io/docs>
181
+ - Support: <mailto:support@browsa.io>
182
+
183
+ ## License
184
+
185
+ 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,14 @@ 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 Job, JobFile, JobStatus, LLMKey, Schedule, Session, SessionBrowser, SessionTurn, Webhook
33
33
  from .errors import (
34
34
  BrowsaError,
35
- NeoutError, # deprecated alias of BrowsaError — kept for backwards compat
36
35
  APIError,
37
36
  AuthError,
38
37
  RateLimitError,
@@ -42,16 +41,21 @@ from .errors import (
42
41
  )
43
42
  from . import webhooks
44
43
 
45
- __version__ = "0.1.2"
44
+ from ._version import __version__
46
45
 
47
46
  __all__ = [
48
47
  "Client",
49
48
  "AsyncClient",
50
49
  "Job",
50
+ "JobFile",
51
51
  "JobStatus",
52
+ "LLMKey",
53
+ "Schedule",
54
+ "Session",
55
+ "SessionBrowser",
56
+ "SessionTurn",
52
57
  "Webhook",
53
58
  "BrowsaError",
54
- "NeoutError",
55
59
  "APIError",
56
60
  "AuthError",
57
61
  "RateLimitError",
@@ -0,0 +1 @@
1
+ __version__ = "0.2.0"