oya-browser 0.2.0__py3-none-any.whl
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.
- oya_browser/__init__.py +21 -0
- oya_browser/_browser_base.py +41 -0
- oya_browser/_config.py +83 -0
- oya_browser/_constants.py +68 -0
- oya_browser/_http.py +89 -0
- oya_browser/_namespace.py +36 -0
- oya_browser/_ops.py +196 -0
- oya_browser/_run_watch.py +95 -0
- oya_browser/_start.py +46 -0
- oya_browser/async_browser.py +185 -0
- oya_browser/browser.py +193 -0
- oya_browser/client.py +224 -0
- oya_browser/control.py +106 -0
- oya_browser/desktop.py +144 -0
- oya_browser/errors.py +12 -0
- oya_browser/file.py +62 -0
- oya_browser/key_config.py +21 -0
- oya_browser/persona_groups.py +35 -0
- oya_browser/personas.py +108 -0
- oya_browser/playbooks.py +54 -0
- oya_browser/proxies.py +31 -0
- oya_browser/py.typed +0 -0
- oya_browser/run.py +148 -0
- oya_browser/signup.py +70 -0
- oya_browser-0.2.0.dist-info/METADATA +144 -0
- oya_browser-0.2.0.dist-info/RECORD +28 -0
- oya_browser-0.2.0.dist-info/WHEEL +4 -0
- oya_browser-0.2.0.dist-info/licenses/LICENSE +21 -0
oya_browser/__init__.py
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
"""oya-browser: real browsers for AI agents, from Python.
|
|
2
|
+
|
|
3
|
+
from oya_browser import Oya
|
|
4
|
+
|
|
5
|
+
with Oya() as oya, oya.browser.start() as browser:
|
|
6
|
+
browser.goto("https://example.com")
|
|
7
|
+
print(browser.ask("What is the page title?"))
|
|
8
|
+
|
|
9
|
+
With browser-use (pip install "oya-browser[browser-use]"):
|
|
10
|
+
|
|
11
|
+
agent = Agent(task, llm, browser=browser.for_browser_use())
|
|
12
|
+
"""
|
|
13
|
+
|
|
14
|
+
from .browser import AsyncBrowser, Browser
|
|
15
|
+
from .client import AsyncOya, Oya
|
|
16
|
+
from .errors import OyaError
|
|
17
|
+
from .file import MAX_FILE_BYTES, file
|
|
18
|
+
from .run import AsyncRun, Run
|
|
19
|
+
|
|
20
|
+
__all__ = ["MAX_FILE_BYTES", "AsyncBrowser", "AsyncOya", "AsyncRun", "Browser", "Oya", "OyaError", "Run", "file"]
|
|
21
|
+
__version__ = "0.2.0"
|
|
@@ -0,0 +1,41 @@
|
|
|
1
|
+
"""What Browser and AsyncBrowser share: what a browser knows about itself, its links, and the browser-use hand-off."""
|
|
2
|
+
|
|
3
|
+
from typing import Any
|
|
4
|
+
|
|
5
|
+
from . import _ops as ops
|
|
6
|
+
from ._http import AsyncHttp, Http
|
|
7
|
+
|
|
8
|
+
NO_CDP = "This browser has no CDP endpoint (its provider does not offer one), so browser-use cannot drive it."
|
|
9
|
+
|
|
10
|
+
|
|
11
|
+
def browser_use(cdp_url: str | None) -> Any:
|
|
12
|
+
"""A browser_use.Browser on `cdp_url`; browser-use is an optional extra, imported only when asked for."""
|
|
13
|
+
if not cdp_url:
|
|
14
|
+
raise ValueError(NO_CDP)
|
|
15
|
+
try:
|
|
16
|
+
from browser_use import Browser as BrowserUseBrowser
|
|
17
|
+
except ImportError as e:
|
|
18
|
+
raise ImportError('browser-use is not installed: pip install "oya-browser[browser-use]"') from e
|
|
19
|
+
return BrowserUseBrowser(cdp_url=cdp_url)
|
|
20
|
+
|
|
21
|
+
|
|
22
|
+
class BrowserBase:
|
|
23
|
+
"""What every browser knows about itself."""
|
|
24
|
+
|
|
25
|
+
def __init__(self, http: Http | AsyncHttp, info: dict[str, Any], auto_captcha: bool) -> None:
|
|
26
|
+
self.id: str = info["id"]
|
|
27
|
+
self.provider: str = info.get("provider") or "cdp"
|
|
28
|
+
self.persona: str = info.get("persona") or "default"
|
|
29
|
+
self.cdp_url: str | None = info.get("cdpUrl")
|
|
30
|
+
"""Where Playwright, Puppeteer or browser-use connect; single use, see fresh_cdp_url()."""
|
|
31
|
+
self.reused: bool = info.get("reused") is True
|
|
32
|
+
"""True when start() handed over a browser that was already running, such as the desktop app."""
|
|
33
|
+
self._auto_captcha = auto_captcha
|
|
34
|
+
self._base_url = http.origin.base_url
|
|
35
|
+
|
|
36
|
+
def live_view_url(self) -> str:
|
|
37
|
+
"""Watch it work: the console, opened on this browser. Carries no credential; frames are live_stream_url()."""
|
|
38
|
+
return ops.live_view_url(self._base_url, self.id)
|
|
39
|
+
|
|
40
|
+
def __repr__(self) -> str:
|
|
41
|
+
return f"<{type(self).__name__} {self.id} on {self.provider}>"
|
oya_browser/_config.py
ADDED
|
@@ -0,0 +1,83 @@
|
|
|
1
|
+
"""Where the key and the address come from: the option, then OYA_API_KEY / OYA_BASE_URL, then ~/.oya/config.json.
|
|
2
|
+
|
|
3
|
+
The same order as the TypeScript SDK and the `oya` CLI, so a key saved by `oya login` works here unchanged.
|
|
4
|
+
A saved key is only used for the deployment it was saved for, so a staging key never goes to production.
|
|
5
|
+
"""
|
|
6
|
+
|
|
7
|
+
import json
|
|
8
|
+
import os
|
|
9
|
+
from dataclasses import dataclass
|
|
10
|
+
from pathlib import Path
|
|
11
|
+
from urllib.parse import urlsplit
|
|
12
|
+
|
|
13
|
+
from ._constants import DEFAULT_BASE_URL, JSON_INDENT, PRIVATE_DIR, PRIVATE_FILE
|
|
14
|
+
|
|
15
|
+
NO_KEY = "No API key. Get one at https://oyabrowser.com, then set OYA_API_KEY or pass api_key=..."
|
|
16
|
+
|
|
17
|
+
|
|
18
|
+
@dataclass(frozen=True)
|
|
19
|
+
class Origin:
|
|
20
|
+
"""The key and the address the client calls."""
|
|
21
|
+
|
|
22
|
+
api_key: str
|
|
23
|
+
base_url: str
|
|
24
|
+
|
|
25
|
+
|
|
26
|
+
def config_file() -> Path:
|
|
27
|
+
"""The CLI's config file: OYA_CONFIG_HOME, else ~/.oya, then config.json."""
|
|
28
|
+
return Path(os.environ.get("OYA_CONFIG_HOME") or str(Path.home() / ".oya")) / "config.json"
|
|
29
|
+
|
|
30
|
+
|
|
31
|
+
def _saved() -> dict[str, str]:
|
|
32
|
+
"""The CLI's saved config, or nothing when there is none or it does not parse."""
|
|
33
|
+
try:
|
|
34
|
+
data = json.loads(config_file().read_text())
|
|
35
|
+
except (OSError, ValueError):
|
|
36
|
+
return {}
|
|
37
|
+
return {k: v for k, v in data.items() if isinstance(v, str)} if isinstance(data, dict) else {}
|
|
38
|
+
|
|
39
|
+
|
|
40
|
+
def _host(url: str) -> str:
|
|
41
|
+
"""The deployment a URL belongs to: its host, port included."""
|
|
42
|
+
return urlsplit(url).netloc
|
|
43
|
+
|
|
44
|
+
|
|
45
|
+
def save_key(api_key: str, base_url: str) -> bool:
|
|
46
|
+
"""Saves a key where `oya login` would, unless one is there already, owner-only; True when it wrote."""
|
|
47
|
+
if _saved().get("apiKey"):
|
|
48
|
+
return False
|
|
49
|
+
path = config_file()
|
|
50
|
+
path.parent.mkdir(mode=PRIVATE_DIR, parents=True, exist_ok=True)
|
|
51
|
+
text = json.dumps({**_saved(), "apiKey": api_key, "baseUrl": base_url}, indent=JSON_INDENT)
|
|
52
|
+
_write_private(path, text)
|
|
53
|
+
return True
|
|
54
|
+
|
|
55
|
+
|
|
56
|
+
def _write_private(path: Path, text: str) -> None:
|
|
57
|
+
"""Writes `text` to `path` readable by its owner only, whatever was there before.
|
|
58
|
+
|
|
59
|
+
Opening the file itself with O_TRUNC would keep the mode of a file that already exists (a config left
|
|
60
|
+
world-readable stays so) and would follow a symlink planted at the path. So the key goes to a new file,
|
|
61
|
+
created exclusively and not through a link, and is renamed over the config in one step.
|
|
62
|
+
"""
|
|
63
|
+
tmp = path.with_name(f".{path.name}.{os.getpid()}.tmp")
|
|
64
|
+
fd = os.open(tmp, os.O_WRONLY | os.O_CREAT | os.O_EXCL | getattr(os, "O_NOFOLLOW", 0), PRIVATE_FILE)
|
|
65
|
+
try:
|
|
66
|
+
with os.fdopen(fd, "w") as f:
|
|
67
|
+
f.write(text)
|
|
68
|
+
os.replace(tmp, path)
|
|
69
|
+
except BaseException:
|
|
70
|
+
tmp.unlink(missing_ok=True)
|
|
71
|
+
raise
|
|
72
|
+
|
|
73
|
+
|
|
74
|
+
def resolve(api_key: str | None = None, base_url: str | None = None) -> Origin:
|
|
75
|
+
"""The key and address to use; raises without a key."""
|
|
76
|
+
saved = _saved()
|
|
77
|
+
address = (base_url or os.environ.get("OYA_BASE_URL") or saved.get("baseUrl") or DEFAULT_BASE_URL).rstrip("/")
|
|
78
|
+
saved_base = saved.get("baseUrl", DEFAULT_BASE_URL)
|
|
79
|
+
saved_key = saved.get("apiKey") if _host(saved_base) == _host(address) else None
|
|
80
|
+
key = (api_key or os.environ.get("OYA_API_KEY") or saved_key or "").strip()
|
|
81
|
+
if not key:
|
|
82
|
+
raise ValueError(NO_KEY)
|
|
83
|
+
return Origin(api_key=key, base_url=address)
|
|
@@ -0,0 +1,68 @@
|
|
|
1
|
+
"""Every number the SDK uses, by name, in seconds: the same budgets as the TypeScript SDK's constants.ts."""
|
|
2
|
+
|
|
3
|
+
DEFAULT_BASE_URL = "https://oyabrowser.com"
|
|
4
|
+
"""The hosted control plane, used when no option, environment variable or saved config names one."""
|
|
5
|
+
|
|
6
|
+
DEFAULT_TIMEOUT_S = 60.0
|
|
7
|
+
"""A plain API call."""
|
|
8
|
+
START_TIMEOUT_S = 120.0
|
|
9
|
+
"""Starting a browser: the start call itself, before any wait for a cloud browser to dial in."""
|
|
10
|
+
READY_TIMEOUT_S = 120.0
|
|
11
|
+
"""How long a starting cloud browser has to dial in."""
|
|
12
|
+
READY_POLL_S = 2.0
|
|
13
|
+
"""How often the fleet is checked while a cloud browser is starting."""
|
|
14
|
+
NAVIGATE_TIMEOUT_S = 120.0
|
|
15
|
+
"""A navigation, which waits for the page to load."""
|
|
16
|
+
CHALLENGE_TIMEOUT_S = 180.0
|
|
17
|
+
"""Solving a CAPTCHA or completing MFA."""
|
|
18
|
+
AGENT_TIMEOUT_S = 600.0
|
|
19
|
+
"""An agent task or a playbook replay; the server keeps the connection alive meanwhile."""
|
|
20
|
+
PLAYBOOK_TIMEOUT_S = 120.0
|
|
21
|
+
"""Saving a playbook."""
|
|
22
|
+
STOP_TIMEOUT_S = 60.0
|
|
23
|
+
"""Stopping a browser, which destroys a cloud sandbox."""
|
|
24
|
+
WAIT_FOR_DEFAULT_S = 30.0
|
|
25
|
+
"""How long wait_for() waits for a selector by default."""
|
|
26
|
+
WAIT_FOR_GRACE_S = 5.0
|
|
27
|
+
"""Extra request time on top of wait_for()'s own timeout, so the server answers first."""
|
|
28
|
+
MS_PER_SECOND = 1000
|
|
29
|
+
"""The API takes wait_for()'s timeout in milliseconds."""
|
|
30
|
+
AIMED_SCROLL_AMOUNT = 500
|
|
31
|
+
"""Pixels an aimed scroll (scroll(at=...)) moves when no amount is given."""
|
|
32
|
+
SHARE_EXPIRES_S = 3600
|
|
33
|
+
"""How long a share_url() link works by default."""
|
|
34
|
+
RUN_POLL_S = 2.0
|
|
35
|
+
"""How often a submitted run is polled by default."""
|
|
36
|
+
MAX_RUN_POLL_ERRORS = 5
|
|
37
|
+
"""Failed polls in a row before a run is reported as failed."""
|
|
38
|
+
DESKTOP_TIMEOUT_S = 300.0
|
|
39
|
+
"""How long desktop.connect() waits for a person to click Connect (and allow the keychain prompt)."""
|
|
40
|
+
DESKTOP_PROVIDER = "oya-desktop"
|
|
41
|
+
"""The provider the server names the Oya desktop app by."""
|
|
42
|
+
DESKTOP_DOWNLOAD_URL = "https://oyabrowser.com/#download"
|
|
43
|
+
"""Where the desktop app is downloaded."""
|
|
44
|
+
BYTES_PER_MB = 1_048_576
|
|
45
|
+
"""Bytes in a megabyte, for file limits and messages."""
|
|
46
|
+
MAX_FILE_MB = 10
|
|
47
|
+
"""Largest task file: bigger and the server would refuse the body anyway."""
|
|
48
|
+
PRIVATE_FILE = 0o600
|
|
49
|
+
"""Owner read and write only: the saved config holds a key."""
|
|
50
|
+
PRIVATE_DIR = 0o700
|
|
51
|
+
"""~/.oya, created owner-only, so no other user can list or replace the key file in it."""
|
|
52
|
+
JSON_INDENT = 2
|
|
53
|
+
"""Indent of the saved config, as `oya login` writes it."""
|
|
54
|
+
|
|
55
|
+
STATUS_UNKNOWN = 0
|
|
56
|
+
"""A failure that was not an HTTP answer, such as a run that could not be polled."""
|
|
57
|
+
STATUS_NOT_FOUND = 404
|
|
58
|
+
"""A session not recorded yet, which is fine while a browser starts."""
|
|
59
|
+
STATUS_CONFLICT = 409
|
|
60
|
+
"""A browser whose creation ended."""
|
|
61
|
+
STATUS_UNPROCESSABLE = 422
|
|
62
|
+
"""A command that ran and failed."""
|
|
63
|
+
STATUS_SERVER_ERROR = 500
|
|
64
|
+
"""An agent failure reported without a status."""
|
|
65
|
+
STATUS_GATEWAY_TIMEOUT = 504
|
|
66
|
+
"""A browser that did not dial in before its budget ran out."""
|
|
67
|
+
STATUS_BAD_REQUEST_FLOOR = 400
|
|
68
|
+
"""Responses from here up are errors."""
|
oya_browser/_http.py
ADDED
|
@@ -0,0 +1,89 @@
|
|
|
1
|
+
"""The one HTTP path every call takes, sync and async: the same headers, timeouts and error handling for both.
|
|
2
|
+
|
|
3
|
+
Errors come back as OyaError with the server's message, so a caller reads "Browser abc not found", not a status code.
|
|
4
|
+
"""
|
|
5
|
+
|
|
6
|
+
from typing import Any
|
|
7
|
+
from urllib.parse import quote
|
|
8
|
+
|
|
9
|
+
import httpx
|
|
10
|
+
|
|
11
|
+
from ._config import Origin
|
|
12
|
+
from ._constants import DEFAULT_TIMEOUT_S, STATUS_BAD_REQUEST_FLOOR
|
|
13
|
+
from .errors import OyaError
|
|
14
|
+
|
|
15
|
+
USER_AGENT = "oya-browser-python"
|
|
16
|
+
|
|
17
|
+
|
|
18
|
+
def segment(value: object, field: str = "id") -> str:
|
|
19
|
+
"""One path segment, encoded; refused when it is empty or would change the path ("/", "." or "..")."""
|
|
20
|
+
if not isinstance(value, str) or not value:
|
|
21
|
+
raise ValueError(f"{field} must be a non-empty string, not {value!r}")
|
|
22
|
+
if "/" in value or value in (".", ".."):
|
|
23
|
+
raise ValueError(f"{field} must be a single path segment, not {value!r}")
|
|
24
|
+
return quote(value, safe="")
|
|
25
|
+
|
|
26
|
+
|
|
27
|
+
def _headers(origin: Origin, extra: dict[str, str] | None) -> dict[str, str]:
|
|
28
|
+
"""The key, the client name, and any per-call headers."""
|
|
29
|
+
return {"Authorization": f"Bearer {origin.api_key}", "User-Agent": USER_AGENT, **(extra or {})}
|
|
30
|
+
|
|
31
|
+
|
|
32
|
+
def _parsed(response: httpx.Response, call: str) -> Any:
|
|
33
|
+
"""The JSON body, or an OyaError carrying the server's message when the call failed."""
|
|
34
|
+
try:
|
|
35
|
+
body: Any = response.json() if response.content else None
|
|
36
|
+
except ValueError:
|
|
37
|
+
body = response.text
|
|
38
|
+
if response.status_code >= STATUS_BAD_REQUEST_FLOOR:
|
|
39
|
+
message = body.get("error") if isinstance(body, dict) else None
|
|
40
|
+
raise OyaError(message or f"{call} failed ({response.status_code})", response.status_code, body)
|
|
41
|
+
return body
|
|
42
|
+
|
|
43
|
+
|
|
44
|
+
class Http:
|
|
45
|
+
"""Synchronous calls to the control plane."""
|
|
46
|
+
|
|
47
|
+
def __init__(self, origin: Origin, client: httpx.Client | None = None, headers: dict[str, str] | None = None):
|
|
48
|
+
self.origin = origin
|
|
49
|
+
self._client = client or httpx.Client(base_url=origin.base_url)
|
|
50
|
+
self._extra = headers
|
|
51
|
+
|
|
52
|
+
def with_headers(self, headers: dict[str, str]) -> "Http":
|
|
53
|
+
"""The same client sending `headers` on every call too."""
|
|
54
|
+
return Http(self.origin, self._client, {**(self._extra or {}), **headers})
|
|
55
|
+
|
|
56
|
+
def request(self, method: str, path: str, body: Any = None, timeout: float = DEFAULT_TIMEOUT_S, **kw: Any) -> Any:
|
|
57
|
+
"""One call; returns the parsed JSON body."""
|
|
58
|
+
headers = _headers(self.origin, {**(self._extra or {}), **kw.get("headers", {})})
|
|
59
|
+
response = self._client.request(method, path, json=body, headers=headers, timeout=timeout)
|
|
60
|
+
return _parsed(response, f"{method} {path}")
|
|
61
|
+
|
|
62
|
+
def close(self) -> None:
|
|
63
|
+
"""Closes the connection pool."""
|
|
64
|
+
self._client.close()
|
|
65
|
+
|
|
66
|
+
|
|
67
|
+
class AsyncHttp:
|
|
68
|
+
"""Asynchronous calls to the control plane."""
|
|
69
|
+
|
|
70
|
+
def __init__(self, origin: Origin, client: httpx.AsyncClient | None = None, headers: dict[str, str] | None = None):
|
|
71
|
+
self.origin = origin
|
|
72
|
+
self._client = client or httpx.AsyncClient(base_url=origin.base_url)
|
|
73
|
+
self._extra = headers
|
|
74
|
+
|
|
75
|
+
def with_headers(self, headers: dict[str, str]) -> "AsyncHttp":
|
|
76
|
+
"""The same client sending `headers` on every call too."""
|
|
77
|
+
return AsyncHttp(self.origin, self._client, {**(self._extra or {}), **headers})
|
|
78
|
+
|
|
79
|
+
async def request(
|
|
80
|
+
self, method: str, path: str, body: Any = None, timeout: float = DEFAULT_TIMEOUT_S, **kw: Any
|
|
81
|
+
) -> Any:
|
|
82
|
+
"""One call; returns the parsed JSON body."""
|
|
83
|
+
headers = _headers(self.origin, {**(self._extra or {}), **kw.get("headers", {})})
|
|
84
|
+
response = await self._client.request(method, path, json=body, headers=headers, timeout=timeout)
|
|
85
|
+
return _parsed(response, f"{method} {path}")
|
|
86
|
+
|
|
87
|
+
async def aclose(self) -> None:
|
|
88
|
+
"""Closes the connection pool."""
|
|
89
|
+
await self._client.aclose()
|
|
@@ -0,0 +1,36 @@
|
|
|
1
|
+
"""The base of every namespace whose methods are one call each (oya.personas, oya.control, ...).
|
|
2
|
+
|
|
3
|
+
One class serves both clients: on Oya a method returns the answer, on AsyncOya the same method returns an awaitable
|
|
4
|
+
of it. Each call is written once, so the sync and async surfaces cannot drift apart.
|
|
5
|
+
"""
|
|
6
|
+
|
|
7
|
+
from typing import Any
|
|
8
|
+
|
|
9
|
+
from ._http import AsyncHttp, Http
|
|
10
|
+
from ._ops import Call
|
|
11
|
+
|
|
12
|
+
|
|
13
|
+
def _picked(result: Any, pick: str | None) -> Any:
|
|
14
|
+
"""The answer, or the one field of it a list endpoint wraps its items in."""
|
|
15
|
+
return result.get(pick) if pick and isinstance(result, dict) else result
|
|
16
|
+
|
|
17
|
+
|
|
18
|
+
class Namespace:
|
|
19
|
+
"""One call per method, sync or async depending on the client that built it."""
|
|
20
|
+
|
|
21
|
+
def __init__(self, http: Http | AsyncHttp) -> None:
|
|
22
|
+
self._http = http
|
|
23
|
+
|
|
24
|
+
@property
|
|
25
|
+
def _is_async(self) -> bool:
|
|
26
|
+
return isinstance(self._http, AsyncHttp)
|
|
27
|
+
|
|
28
|
+
def _do(self, call: Call, pick: str | None = None) -> Any:
|
|
29
|
+
"""Makes the call; on AsyncOya returns a coroutine to await."""
|
|
30
|
+
if isinstance(self._http, AsyncHttp):
|
|
31
|
+
return self._ado(self._http, call, pick)
|
|
32
|
+
return _picked(self._http.request(call.method, call.path, call.body, call.timeout, headers=call.headers), pick)
|
|
33
|
+
|
|
34
|
+
@staticmethod
|
|
35
|
+
async def _ado(http: AsyncHttp, call: Call, pick: str | None) -> Any:
|
|
36
|
+
return _picked(await http.request(call.method, call.path, call.body, call.timeout, headers=call.headers), pick)
|
oya_browser/_ops.py
ADDED
|
@@ -0,0 +1,196 @@
|
|
|
1
|
+
"""Every browser call written once, as data: the sync and async Browser only differ in whether they await.
|
|
2
|
+
|
|
3
|
+
Paths, bodies and timeouts match the TypeScript SDK's browser.ts call for call.
|
|
4
|
+
"""
|
|
5
|
+
|
|
6
|
+
import uuid
|
|
7
|
+
from dataclasses import dataclass, field
|
|
8
|
+
from typing import Any
|
|
9
|
+
from urllib.parse import quote
|
|
10
|
+
|
|
11
|
+
from ._constants import (
|
|
12
|
+
AGENT_TIMEOUT_S,
|
|
13
|
+
AIMED_SCROLL_AMOUNT,
|
|
14
|
+
CHALLENGE_TIMEOUT_S,
|
|
15
|
+
DEFAULT_TIMEOUT_S,
|
|
16
|
+
MS_PER_SECOND,
|
|
17
|
+
NAVIGATE_TIMEOUT_S,
|
|
18
|
+
PLAYBOOK_TIMEOUT_S,
|
|
19
|
+
STATUS_CONFLICT,
|
|
20
|
+
STATUS_SERVER_ERROR,
|
|
21
|
+
STATUS_UNPROCESSABLE,
|
|
22
|
+
STOP_TIMEOUT_S,
|
|
23
|
+
WAIT_FOR_GRACE_S,
|
|
24
|
+
)
|
|
25
|
+
from ._http import segment
|
|
26
|
+
from .errors import OyaError
|
|
27
|
+
|
|
28
|
+
LANE_HEADER = "X-Oya-Agent"
|
|
29
|
+
"""A desktop browser handed to start() gives each lane a tab of its own, so the person keeps theirs."""
|
|
30
|
+
|
|
31
|
+
|
|
32
|
+
def sdk_lane() -> str:
|
|
33
|
+
"""A lane name of this SDK's own, unique per Browser object."""
|
|
34
|
+
return f"sdk-{uuid.uuid4()}"
|
|
35
|
+
|
|
36
|
+
|
|
37
|
+
@dataclass(frozen=True)
|
|
38
|
+
class Call:
|
|
39
|
+
"""One HTTP call: method, path, JSON body and time budget."""
|
|
40
|
+
|
|
41
|
+
method: str
|
|
42
|
+
path: str
|
|
43
|
+
body: Any = None
|
|
44
|
+
timeout: float = DEFAULT_TIMEOUT_S
|
|
45
|
+
headers: dict[str, str] = field(default_factory=dict)
|
|
46
|
+
|
|
47
|
+
|
|
48
|
+
def command(browser_id: str, action: str, params: dict[str, Any], timeout: float = DEFAULT_TIMEOUT_S) -> Call:
|
|
49
|
+
"""A browser command, such as navigate, analyze, click or type."""
|
|
50
|
+
return Call("POST", f"/api/browsers/{segment(browser_id)}/command", {"action": action, "params": params}, timeout)
|
|
51
|
+
|
|
52
|
+
|
|
53
|
+
def command_data(result: Any, action: str) -> Any:
|
|
54
|
+
"""A command's data; a command that ran and failed raises."""
|
|
55
|
+
if isinstance(result, dict) and result.get("ok") is False:
|
|
56
|
+
raise OyaError(result.get("error") or f"{action} failed", STATUS_UNPROCESSABLE, result)
|
|
57
|
+
return result.get("data") if isinstance(result, dict) else result
|
|
58
|
+
|
|
59
|
+
|
|
60
|
+
def agent_answer(result: Any) -> dict[str, Any]:
|
|
61
|
+
"""An agent answer; the server sends 200 up front to keep long runs alive, so failures arrive in the body."""
|
|
62
|
+
if not isinstance(result, dict):
|
|
63
|
+
raise OyaError("The agent sent no answer", STATUS_SERVER_ERROR, result)
|
|
64
|
+
if result.get("error"):
|
|
65
|
+
raise OyaError(str(result["error"]), int(result.get("status") or STATUS_SERVER_ERROR), result)
|
|
66
|
+
return result
|
|
67
|
+
|
|
68
|
+
|
|
69
|
+
def element(element_id: int | str) -> dict[str, Any]:
|
|
70
|
+
"""The params that address an element by its id from analyze()."""
|
|
71
|
+
try:
|
|
72
|
+
number = int(element_id)
|
|
73
|
+
except (TypeError, ValueError):
|
|
74
|
+
raise ValueError(f"element ids come from analyze(); {element_id!r} is not one") from None
|
|
75
|
+
return {"element_id": number, "selector": f'[data-ac-id="{number}"]'}
|
|
76
|
+
|
|
77
|
+
|
|
78
|
+
def navigate(browser_id: str, url: str) -> Call:
|
|
79
|
+
"""Opens `url` and waits for it to load."""
|
|
80
|
+
return command(browser_id, "navigate", {"url": url}, NAVIGATE_TIMEOUT_S)
|
|
81
|
+
|
|
82
|
+
|
|
83
|
+
def wait_for(browser_id: str, selector: str, timeout_s: float) -> Call:
|
|
84
|
+
"""Waits until `selector` matches."""
|
|
85
|
+
params = {"selector": selector, "timeout": int(timeout_s * MS_PER_SECOND)}
|
|
86
|
+
return command(browser_id, "wait", params, timeout_s + WAIT_FOR_GRACE_S)
|
|
87
|
+
|
|
88
|
+
|
|
89
|
+
def challenge(browser_id: str, kind: str) -> Call:
|
|
90
|
+
"""Solves a CAPTCHA ("captcha") or completes MFA ("mfa")."""
|
|
91
|
+
return Call("POST", f"/api/browsers/{segment(browser_id)}/{kind}", {}, CHALLENGE_TIMEOUT_S)
|
|
92
|
+
|
|
93
|
+
|
|
94
|
+
def ask(browser_id: str, prompt: str, data: Any, secrets: Any, schema: Any = None) -> Call:
|
|
95
|
+
"""A task in plain language; with `schema`, the answer comes back as data in that shape."""
|
|
96
|
+
body: dict[str, Any] = {"messages": [{"role": "user", "content": prompt}], "data": data, "secrets": secrets}
|
|
97
|
+
if schema is not None:
|
|
98
|
+
body["schema"] = schema
|
|
99
|
+
return Call("POST", f"/api/browsers/{segment(browser_id)}/chat", body, AGENT_TIMEOUT_S)
|
|
100
|
+
|
|
101
|
+
|
|
102
|
+
def to_playbook(browser_id: str, name: str) -> Call:
|
|
103
|
+
"""Saves the last ask() on this browser as a named playbook."""
|
|
104
|
+
return Call("POST", f"/api/browsers/{segment(browser_id)}/playbooks", {"name": name}, PLAYBOOK_TIMEOUT_S)
|
|
105
|
+
|
|
106
|
+
|
|
107
|
+
def play(browser_id: str, name: str, data: Any, auto_heal: bool) -> Call:
|
|
108
|
+
"""Replays a playbook with no model in the loop."""
|
|
109
|
+
path = f"/api/browsers/{segment(browser_id)}/playbooks/{segment(name, 'name')}/play"
|
|
110
|
+
return Call("POST", path, {"variables": data or {}, "autoHeal": auto_heal}, AGENT_TIMEOUT_S)
|
|
111
|
+
|
|
112
|
+
|
|
113
|
+
def stop(browser_id: str, reused: bool) -> Call:
|
|
114
|
+
"""Stops a browser this SDK started; for one it borrowed (a person's desktop), ends only its own lane."""
|
|
115
|
+
action = "lane/end" if reused else "stop"
|
|
116
|
+
return Call("POST", f"/api/browsers/{segment(browser_id)}/{action}", {}, STOP_TIMEOUT_S)
|
|
117
|
+
|
|
118
|
+
|
|
119
|
+
def scroll(direction: str, amount: int | None, at: tuple[int, int] | None = None) -> dict[str, Any]:
|
|
120
|
+
"""Scroll params; `amount` left out scrolls about a screen.
|
|
121
|
+
|
|
122
|
+
With `at`, the wheel is aimed at that (x, y) point, an inner scroller such as a results panel, as one wheel
|
|
123
|
+
event: drivers only honour x/y in that mode, and it moves AIMED_SCROLL_AMOUNT pixels when no amount is given.
|
|
124
|
+
"""
|
|
125
|
+
if at is None:
|
|
126
|
+
return {"direction": direction} if amount is None else {"direction": direction, "amount": amount}
|
|
127
|
+
x, y = at
|
|
128
|
+
return {
|
|
129
|
+
"direction": direction,
|
|
130
|
+
"amount": AIMED_SCROLL_AMOUNT if amount is None else amount,
|
|
131
|
+
"x": x,
|
|
132
|
+
"y": y,
|
|
133
|
+
"smooth": False,
|
|
134
|
+
}
|
|
135
|
+
|
|
136
|
+
|
|
137
|
+
def active_url(tabs: list[dict[str, Any]]) -> str:
|
|
138
|
+
"""The active tab's URL, or empty when there is none."""
|
|
139
|
+
return next((str(t.get("url") or "") for t in tabs if t.get("active")), "")
|
|
140
|
+
|
|
141
|
+
|
|
142
|
+
def handle_dialog(browser_id: str, accept: bool, prompt_text: str | None) -> Call:
|
|
143
|
+
"""Answers a confirm() or prompt() holding the page."""
|
|
144
|
+
params: dict[str, Any] = {"accept": accept}
|
|
145
|
+
if prompt_text is not None:
|
|
146
|
+
params["prompt_text"] = prompt_text
|
|
147
|
+
return command(browser_id, "handle_dialog", params)
|
|
148
|
+
|
|
149
|
+
|
|
150
|
+
def open_tab(browser_id: str, url: str | None) -> Call:
|
|
151
|
+
"""Opens a tab, at `url` when given; it may load a page, so it gets a navigation's budget."""
|
|
152
|
+
return command(browser_id, "open_tab", {} if url is None else {"url": url}, NAVIGATE_TIMEOUT_S)
|
|
153
|
+
|
|
154
|
+
|
|
155
|
+
def assert_captcha_cleared(result: dict[str, Any]) -> None:
|
|
156
|
+
"""After captcha="auto": a CAPTCHA still on screen needs a person, so goto() raises 409 rather than go on."""
|
|
157
|
+
if not result.get("present") or result.get("solved") or result.get("invisible"):
|
|
158
|
+
return
|
|
159
|
+
message = result.get("error") or "CAPTCHA needs attention. Call solve_captcha() again or open the live view."
|
|
160
|
+
raise OyaError(str(message), STATUS_CONFLICT, result)
|
|
161
|
+
|
|
162
|
+
|
|
163
|
+
def session(browser_id: str, action: str) -> Call:
|
|
164
|
+
"""A control-plane call on this browser's session: "ticket" for the live stream, "share" for a link."""
|
|
165
|
+
return Call("POST", f"/api/control/sessions/{segment(browser_id)}/{action}", {})
|
|
166
|
+
|
|
167
|
+
|
|
168
|
+
def share(browser_id: str, control: bool, expires_in_s: int) -> Call:
|
|
169
|
+
"""Mints a credential scoped to this one browser, for a share link."""
|
|
170
|
+
body = {"control": control, "expiresIn": expires_in_s}
|
|
171
|
+
return Call("POST", f"/api/control/sessions/{segment(browser_id)}/share", body)
|
|
172
|
+
|
|
173
|
+
|
|
174
|
+
def live_stream_url(base_url: str, browser_id: str, ticket: str) -> str:
|
|
175
|
+
"""The SSE frame stream; EventSource cannot set headers, so the single-use ticket rides in the query."""
|
|
176
|
+
return f"{base_url}/api/live/{segment(browser_id)}?ticket={quote(ticket, safe='')}"
|
|
177
|
+
|
|
178
|
+
|
|
179
|
+
def share_link(base_url: str, browser_id: str, credential: dict[str, Any]) -> dict[str, Any]:
|
|
180
|
+
"""The public live-view link; the token rides in the fragment, so no server log or Referer sees it."""
|
|
181
|
+
url = f"{base_url}/live/{segment(browser_id)}#t={quote(str(credential['token']), safe='')}"
|
|
182
|
+
return {"url": url, "id": credential["id"], "expiresAt": credential.get("expiresAt")}
|
|
183
|
+
|
|
184
|
+
|
|
185
|
+
def live_view_url(base_url: str, browser_id: str) -> str:
|
|
186
|
+
"""The console deep link: carries no credential, unlike a stream URL with the key in it would."""
|
|
187
|
+
return f"{base_url}/dashboard/?browser={quote(browser_id, safe='')}"
|
|
188
|
+
|
|
189
|
+
|
|
190
|
+
def submit(browser_id: str, prompt: str | None, playbook: str | None, values: dict[str, Any]) -> Call:
|
|
191
|
+
"""Starts a prompt or a playbook as a background run; exactly one of the two."""
|
|
192
|
+
if (prompt is None) == (playbook is None):
|
|
193
|
+
raise ValueError("submit() takes a prompt or playbook=..., exactly one")
|
|
194
|
+
task = {"prompt": prompt} if prompt is not None else {"playbook": playbook}
|
|
195
|
+
body = {**task, **{k: v for k, v in values.items() if v is not None}}
|
|
196
|
+
return Call("POST", f"/api/browsers/{segment(browser_id)}/runs", body)
|
|
@@ -0,0 +1,95 @@
|
|
|
1
|
+
"""What a submitted run's poll means, written once for Run and AsyncRun.
|
|
2
|
+
|
|
3
|
+
A poll is a new attention request, the result, or the failure. Same rules as the TypeScript SDK's run-watch.ts.
|
|
4
|
+
"""
|
|
5
|
+
|
|
6
|
+
import logging
|
|
7
|
+
from collections.abc import Callable
|
|
8
|
+
from dataclasses import dataclass
|
|
9
|
+
from typing import Any
|
|
10
|
+
from urllib.parse import urljoin
|
|
11
|
+
|
|
12
|
+
from ._constants import MAX_RUN_POLL_ERRORS, STATUS_SERVER_ERROR, STATUS_UNKNOWN
|
|
13
|
+
from ._http import segment
|
|
14
|
+
from ._ops import Call
|
|
15
|
+
from .errors import OyaError
|
|
16
|
+
|
|
17
|
+
log = logging.getLogger("oya_browser")
|
|
18
|
+
|
|
19
|
+
Callback = Callable[[Any], Any]
|
|
20
|
+
|
|
21
|
+
|
|
22
|
+
@dataclass(frozen=True)
|
|
23
|
+
class Callbacks:
|
|
24
|
+
"""What a run fires: on_success(result), on_failure(OyaError), on_human_attention(request), on_healed(result)."""
|
|
25
|
+
|
|
26
|
+
on_success: Callback | None = None
|
|
27
|
+
on_failure: Callback | None = None
|
|
28
|
+
on_human_attention: Callback | None = None
|
|
29
|
+
on_healed: Callback | None = None
|
|
30
|
+
|
|
31
|
+
|
|
32
|
+
@dataclass
|
|
33
|
+
class Step:
|
|
34
|
+
"""One poll's meaning: a new attention request to report, and the result or failure once the run ended."""
|
|
35
|
+
|
|
36
|
+
attention: dict[str, Any] | None = None
|
|
37
|
+
result: dict[str, Any] | None = None
|
|
38
|
+
failure: OyaError | None = None
|
|
39
|
+
|
|
40
|
+
|
|
41
|
+
@dataclass
|
|
42
|
+
class Watch:
|
|
43
|
+
"""What the loop carries between polls."""
|
|
44
|
+
|
|
45
|
+
base_url: str
|
|
46
|
+
respond: Callable[..., Any]
|
|
47
|
+
seen: str | None = None
|
|
48
|
+
errors: int = 0
|
|
49
|
+
|
|
50
|
+
def failed_poll(self, error: Exception) -> OyaError | None:
|
|
51
|
+
"""None while polls fail now and then; the failure once MAX_RUN_POLL_ERRORS have failed in a row."""
|
|
52
|
+
self.errors += 1
|
|
53
|
+
if self.errors < MAX_RUN_POLL_ERRORS:
|
|
54
|
+
return None
|
|
55
|
+
return error if isinstance(error, OyaError) else OyaError(str(error), STATUS_UNKNOWN)
|
|
56
|
+
|
|
57
|
+
def step(self, info: dict[str, Any]) -> Step:
|
|
58
|
+
"""Reads one successful poll; the attention request is reported once, however often it is polled."""
|
|
59
|
+
self.errors = 0
|
|
60
|
+
step = Step(attention=self._attention(info))
|
|
61
|
+
if info.get("status") == "succeeded":
|
|
62
|
+
step.result = info.get("result") or {}
|
|
63
|
+
elif info.get("status") == "failed":
|
|
64
|
+
status = info.get("errorStatus") or STATUS_SERVER_ERROR
|
|
65
|
+
step.failure = OyaError(info.get("error") or "Run failed", int(status), info)
|
|
66
|
+
return step
|
|
67
|
+
|
|
68
|
+
def _attention(self, info: dict[str, Any]) -> dict[str, Any] | None:
|
|
69
|
+
request = info.get("attention")
|
|
70
|
+
if info.get("status") != "needs_attention" or not request or request.get("id") == self.seen:
|
|
71
|
+
return None
|
|
72
|
+
self.seen = request.get("id")
|
|
73
|
+
link = request.get("liveViewUrl")
|
|
74
|
+
return {**request, "liveViewUrl": urljoin(self.base_url, link) if link else link, "respond": self.respond}
|
|
75
|
+
|
|
76
|
+
|
|
77
|
+
def fire(callback: Callback | None, value: Any) -> Any:
|
|
78
|
+
"""Calls a caller's callback; one that raises is logged, never allowed to break the loop."""
|
|
79
|
+
if callback is None:
|
|
80
|
+
return None
|
|
81
|
+
try:
|
|
82
|
+
return callback(value)
|
|
83
|
+
except Exception:
|
|
84
|
+
log.exception("run callback raised")
|
|
85
|
+
return None
|
|
86
|
+
|
|
87
|
+
|
|
88
|
+
def status_call(run_id: str) -> Call:
|
|
89
|
+
"""The run's current state."""
|
|
90
|
+
return Call("GET", f"/api/runs/{segment(run_id)}")
|
|
91
|
+
|
|
92
|
+
|
|
93
|
+
def respond_call(run_id: str, response: str) -> Call:
|
|
94
|
+
"""Answers the open attention request."""
|
|
95
|
+
return Call("POST", f"/api/runs/{segment(run_id)}/respond", {"response": response})
|