sai-sdk 0.1.0__py3-none-any.whl

sai/__init__.py

@@ -0,0 +1,107 @@
+"""Python SDK for the Sai API.
+
+- `sai.sessions`: give Sai a task on a computer and get the answer back.
+- `sai.learn`, `sai.judge`: turn recorded turns into Simulang code, repair it, judge turns.
+- `sai.control`: drive a cloud computer yourself with Simulang.
+- `sai.machines`, `sai.models`, `sai.files`, `sai.account`.
+- `sai.tenants`, `sai.tenant_machines`: your customers under an Organisation (an Organisation Key).
+"""
+
+from ._client import Sai
+from ._errors import (
+    AuthenticationError,
+    BadRequestError,
+    BlockError,
+    ConflictError,
+    ConnectionError,
+    GoneError,
+    LinkOnlyApprovalError,
+    NotFoundError,
+    PermissionDeniedError,
+    RateLimitError,
+    SaiError,
+    ServiceUnavailableError,
+    SpendCapReachedError,
+)
+from ._version import __version__
+from .control import ControlLease
+from .machines import Machine
+from .sessions import Session, Turn
+from .tenants import Enrollment, Tenant, TenantMachine, TenantPage, TenantToken
+from .types import (
+    Account,
+    Approval,
+    Attachment,
+    Check,
+    CriterionResult,
+    Evaluation,
+    Event,
+    Evidence,
+    ExecError,
+    ExecResult,
+    Judgement,
+    LearnIteration,
+    LearnParameter,
+    LearnReset,
+    LearnResult,
+    LearnRollout,
+    LearnRun,
+    LearnTestResult,
+    LiveView,
+    Model,
+    TurnRecord,
+    TrajectoryStep,
+    TurnResult,
+    Usage,
+)
+
+__all__ = [
+    "Sai",
+    "Session",
+    "Turn",
+    "ControlLease",
+    "Machine",
+    "Tenant",
+    "TenantPage",
+    "TenantMachine",
+    "Enrollment",
+    "TenantToken",
+    "Account",
+    "Approval",
+    "Attachment",
+    "Check",
+    "CriterionResult",
+    "Evaluation",
+    "Event",
+    "Evidence",
+    "ExecError",
+    "ExecResult",
+    "Judgement",
+    "LearnIteration",
+    "LearnParameter",
+    "LearnReset",
+    "LearnResult",
+    "LearnRollout",
+    "LearnRun",
+    "LearnTestResult",
+    "LiveView",
+    "Model",
+    "TurnRecord",
+    "TrajectoryStep",
+    "TurnResult",
+    "Usage",
+    "SaiError",
+    "AuthenticationError",
+    "BadRequestError",
+    "BlockError",
+    "ConflictError",
+    "ConnectionError",
+    "GoneError",
+    "LinkOnlyApprovalError",
+    "NotFoundError",
+    "PermissionDeniedError",
+    "RateLimitError",
+    "ServiceUnavailableError",
+    "SpendCapReachedError",
+    "__version__",
+]

sai/_client.py

@@ -0,0 +1,131 @@
+from __future__ import annotations
+
+import os
+import urllib.parse
+from pathlib import Path
+from typing import Callable, Optional, Union
+
+import httpx
+
+from ._http import DEFAULT_BASE_URL, HTTP
+from .control import Control
+from .machines import Machines
+from .sessions import Sessions
+from .turns import Turns
+from .learn import Judge, Learn
+from .tenants import TenantMachines, Tenants
+from .types import Account, Attachment, Model
+
+
+class Sai:
+    """The Sai API client.
+
+    ```python
+    sai = Sai()  # SAI_API_KEY, and SAI_API_URL if set
+    session = sai.sessions.create()
+    print(session.run("Open Notepad and type hello").text)
+    ```
+    """
+
+    def __init__(
+        self,
+        api_key: Optional[str] = None,
+        *,
+        base_url: Optional[str] = None,
+        timeout: float = 60.0,
+        version_tag: Optional[str] = None,
+        transport: Optional[httpx.BaseTransport] = None,
+        org_id: Optional[str] = None,
+        _token: Optional[Callable[[], str]] = None,
+    ) -> None:
+        """`org_id` (default `SAI_ORG_ID`) is the Organisation that `tenants.token()` and
+        `tenants.client()` exchange for; only an Organisation Key needs it."""
+        key = _token or api_key or os.environ.get("SAI_API_KEY")
+        if not key:
+            raise ValueError("No API key: pass api_key= or set SAI_API_KEY. Create one at https://platform.simular.ai.")
+        self._base_url = base_url or os.environ.get("SAI_API_URL") or DEFAULT_BASE_URL
+        self._timeout = timeout
+        self._version_tag = version_tag
+        self._transport = transport
+        self._org_id = org_id or os.environ.get("SAI_ORG_ID")
+        self._http = HTTP(
+            key,
+            self._base_url,
+            timeout=timeout,
+            version_tag=version_tag,
+            transport=transport,
+        )
+        self.machines = Machines(self)
+        self.sessions = Sessions(self)
+        self.turns = Turns(self)
+        self.learn = Learn(self)
+        """Recorded turns → Simulang code, and code repair (research preview)."""
+        self.judge = Judge(self)
+        """Judge recorded turns against new criteria (research preview)."""
+        self.control = Control(self)
+        self.models = _Models(self)
+        self.files = _Files(self)
+        self.account = _Account(self)
+        self.tenants = Tenants(self)
+        """Your customers under an Organisation. Takes an Organisation Key."""
+        self.tenant_machines = TenantMachines(self)
+        """A Tenant's computers: enrolled, and cloud machines Sai hosts. Takes an Organisation Key."""
+
+    def _with_token(self, token: Callable[[], str]) -> Sai:
+        return Sai(
+            base_url=self._base_url,
+            timeout=self._timeout,
+            version_tag=self._version_tag,
+            transport=self._transport,
+            org_id=self._org_id,
+            _token=token,
+        )
+
+    def close(self) -> None:
+        self._http.close()
+
+    def __enter__(self) -> Sai:
+        return self
+
+    def __exit__(self, *exc: object) -> None:
+        self.close()
+
+
+class _Models:
+    def __init__(self, sai: Sai) -> None:
+        self._sai = sai
+
+    def list(self) -> list[Model]:
+        """Models a session can run on; `allowed` says whether this plan may use each."""
+        d = self._sai._http.json("GET", "/v1/agents/models")
+        return [Model.parse(m) for m in d.get("models") or []]
+
+
+class _Files:
+    def __init__(self, sai: Sai) -> None:
+        self._sai = sai
+
+    def upload(self, file: Union[str, Path], *, name: Optional[str] = None) -> Attachment:
+        """Upload one file (max 25 MB) to attach to a message."""
+        path = Path(file)
+        d = self._sai._http.json(
+            "POST",
+            "/v1/agents/upload",
+            content=path.read_bytes(),
+            # The server reads only a body that has a Content-Type; it derives the MIME type from the name.
+            headers={
+                "Content-Type": "application/octet-stream",
+                "x-filename": urllib.parse.quote(name or path.name),
+            },
+            timeout=120,
+        )
+        return Attachment.parse(d)
+
+
+class _Account:
+    def __init__(self, sai: Sai) -> None:
+        self._sai = sai
+
+    def get(self) -> Account:
+        """Plan and spendable credit. Slow-ish (billing lookup): not for a poll loop."""
+        return Account.parse(self._sai._http.json("GET", "/v1/agents/account"))

sai/_errors.py

@@ -0,0 +1,139 @@
+from __future__ import annotations
+
+from typing import Any, Optional
+
+
+class SaiError(Exception):
+    """A non-2xx response from the Sai API.
+
+    `code` is the machine-readable `error` string when the server sent one
+    (`machine_busy`, `link_only`, `insufficient_credits`, ...); `message` is the
+    human text. `body` is the parsed JSON body, unchanged.
+    """
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        status: int = 0,
+        code: Optional[str] = None,
+        body: Optional[dict[str, Any]] = None,
+        retry_after: Optional[float] = None,
+    ) -> None:
+        super().__init__(message)
+        self.message = message
+        self.status = status
+        self.code = code
+        self.body = body or {}
+        self.retry_after = retry_after
+
+    def __repr__(self) -> str:
+        return f"{type(self).__name__}(status={self.status}, code={self.code!r}, message={self.message!r})"
+
+
+class ConnectionError(SaiError):
+    """The API could not be reached (DNS, TLS, timeout)."""
+
+
+class BadRequestError(SaiError):
+    """400: the request was invalid, e.g. several computers and no `machine`."""
+
+
+class AuthenticationError(SaiError):
+    """401: no key, or the key is unknown or revoked."""
+
+
+class PermissionDeniedError(SaiError):
+    """403: the key is valid but the account may not do this (plan, ownership)."""
+
+
+class NotFoundError(SaiError):
+    """404."""
+
+
+class ConflictError(SaiError):
+    """409: e.g. `machine_busy`, `link_only`, approval no longer pending."""
+
+
+class GoneError(SaiError):
+    """410 `control_closed`: the control lease has ended. Open a new one.
+
+    `body["reason"]` says why: `closed`, `idle_timeout`, `lock_lost` (a Sai task
+    took the computer) or `unresponsive` (the computer stopped answering).
+    """
+
+
+class RateLimitError(SaiError):
+    """429: a rate limit, or a free-plan budget that resets daily."""
+
+
+class ServiceUnavailableError(SaiError):
+    """503: the computer did not come online, or no capacity. Honor `retry_after`."""
+
+
+class BlockError(SaiError):
+    """A control helper's Simulang block failed on the computer. `kind` is
+    `exception`, `timeout` or `interrupted`."""
+
+    def __init__(self, kind: str, message: str) -> None:
+        super().__init__(f"{kind}: {message}", code=kind)
+        self.kind = kind
+
+
+class LinkOnlyApprovalError(ConflictError):
+    """The approval must be answered by a human in a browser: open `approval_url`."""
+
+    @property
+    def approval_url(self) -> Optional[str]:
+        return self.body.get("approvalUrl")
+
+
+class SpendCapReachedError(PermissionDeniedError):
+    """403 `spend_cap_reached`: the key reached its monthly spend limit, or (on a cloud machine
+    create, `body["scope"] == "tenant"`) the Tenant reached its budget.
+
+    Not retryable: the limit resets at `resets_at` (ISO 8601, 00:00 UTC on the
+    1st), or raise it for the key in the portal.
+    """
+
+    @property
+    def resets_at(self) -> Optional[str]:
+        at = self.body.get("resetsAt")
+        return at if isinstance(at, str) else None
+
+
+_BY_CODE: dict[str, type[SaiError]] = {
+    "link_only": LinkOnlyApprovalError,
+    "spend_cap_reached": SpendCapReachedError,
+}
+
+_BY_STATUS = {
+    400: BadRequestError,
+    401: AuthenticationError,
+    403: PermissionDeniedError,
+    404: NotFoundError,
+    409: ConflictError,
+    410: GoneError,
+    429: RateLimitError,
+    503: ServiceUnavailableError,
+}
+
+
+def error_for(status: int, body: dict[str, Any], retry_after: Optional[float]) -> SaiError:
+    err = body.get("error")
+    detail = body.get("message")
+    # Two body shapes: `{ error: "<human text>" }` (/v1/agents) and
+    # `{ error: "<code>", message: "<human text>" }` (/v1/machines/{id}/control, newer errors).
+    code = err if isinstance(err, str) and (detail is not None or _looks_like_code(err)) else None
+    message = detail if isinstance(detail, str) else (err if isinstance(err, str) else f"HTTP {status}")
+    if status == 401:
+        message += " (SAI_API_KEY was rejected: it may be revoked.)"
+    cls = _BY_CODE.get(code or "") or _BY_STATUS.get(status, SaiError)
+    # The `Retry-After` header wins; `retryAfterSeconds` is the same value in the body (`rate_limited`).
+    if retry_after is None and isinstance(body.get("retryAfterSeconds"), (int, float)):
+        retry_after = float(body["retryAfterSeconds"])
+    return cls(message, status=status, code=code, body=body, retry_after=retry_after)
+
+
+def _looks_like_code(s: str) -> bool:
+    return bool(s) and " " not in s and s == s.lower()

sai/_http.py

@@ -0,0 +1,92 @@
+from __future__ import annotations
+
+from typing import Any, Callable, Optional, Union
+
+import httpx
+
+from ._errors import ConnectionError, SaiError, error_for
+from ._version import __version__
+
+DEFAULT_BASE_URL = "https://api.simular.ai"
+
+
+class HTTP:
+    """The one place requests are made: auth header, error mapping, timeouts."""
+
+    def __init__(
+        self,
+        api_key: Union[str, Callable[[], str]],
+        base_url: str,
+        *,
+        timeout: float,
+        version_tag: Optional[str],
+        transport: Optional[httpx.BaseTransport],
+    ) -> None:
+        """`api_key` is the bearer token, or a function that returns it before each request."""
+        self._token = api_key if callable(api_key) else None
+        headers = {"User-Agent": f"sai-python/{__version__}"}
+        if not callable(api_key):
+            headers["Authorization"] = f"Bearer {api_key}"
+        if version_tag:
+            # routes the request to a tagged API revision
+            headers["x-sai-version"] = version_tag
+        self._client = httpx.Client(
+            base_url=base_url.rstrip("/"), headers=headers, timeout=timeout, transport=transport
+        )
+
+    def close(self) -> None:
+        self._client.close()
+
+    def request(
+        self,
+        method: str,
+        path: str,
+        *,
+        json: Any = None,
+        params: Optional[dict[str, Any]] = None,
+        content: Optional[bytes] = None,
+        headers: Optional[dict[str, str]] = None,
+        timeout: Optional[float] = None,
+    ) -> httpx.Response:
+        kwargs: dict[str, Any] = {}
+        if timeout is not None:
+            kwargs["timeout"] = timeout
+        if self._token is not None:
+            headers = {**(headers or {}), "Authorization": f"Bearer {self._token()}"}
+        try:
+            res = self._client.request(
+                method, path, json=json, params=params, content=content, headers=headers, **kwargs
+            )
+        except httpx.TimeoutException as e:
+            raise ConnectionError(f"Request to {self._client.base_url.host} timed out.") from e
+        except httpx.TransportError as e:
+            raise ConnectionError(
+                f"Could not reach the Sai API at {self._client.base_url.host}: {e}. "
+                "Check the network and SAI_API_URL."
+            ) from e
+        if res.status_code >= 400:
+            raise _to_error(res)
+        return res
+
+    def json(self, method: str, path: str, **kwargs: Any) -> Any:
+        res = self.request(method, path, **kwargs)
+        if res.status_code == 204 or not res.content:
+            return None
+        return res.json()
+
+
+def _to_error(res: httpx.Response) -> SaiError:
+    try:
+        body = res.json()
+        if not isinstance(body, dict):
+            body = {"error": str(body)}
+    except ValueError:
+        body = {"error": res.text[:500] or res.reason_phrase}
+    retry_after: Optional[float] = None
+    raw = res.headers.get("retry-after")
+    if raw:
+        try:
+            retry_after = float(raw)
+        except ValueError:
+            retry_after = None
+    return error_for(res.status_code, body, retry_after)

sai/_version.py

@@ -0,0 +1 @@
+__version__ = "0.1.0"

sai/control.py

@@ -0,0 +1,141 @@
+"""Direct control: drive a cloud computer with Simulang. No agent.
+
+Maps to `/v1/machines/{id}/control`, a lease on the machine: at most one per
+machine, so the machine id is the handle. Research preview, open to every account;
+model calls the code makes (`callLLM`, `ground`, `stateSatisfies`) are billed as usual.
+"""
+
+from __future__ import annotations
+
+import json
+from urllib.parse import quote
+from typing import TYPE_CHECKING, Any, Optional, Union
+
+from ._errors import BlockError, GoneError
+from .types import ExecResult, LearnResult
+
+if TYPE_CHECKING:
+    from ._client import Sai
+    from .machines import Machine
+
+
+
+def _control_path(machine_id: str) -> str:
+    return f"/v1/machines/{quote(machine_id, safe='')}/control"
+
+
+class Control:
+    def __init__(self, sai: Sai) -> None:
+        self._sai = sai
+
+    def open(self, machine: Union[Machine, str]) -> ControlLease:
+        """Take a cloud computer. Returns once the lease holds it, up to ~3 minutes
+        when a Sai task holds it or it has to start; at once if the lease is already
+        open. Use as a context manager so it is always released: Sai's tasks on that
+        computer wait until then."""
+        machine_id = machine if isinstance(machine, str) else machine.id
+        d = self._sai._http.json("POST", _control_path(machine_id), timeout=240)
+        return ControlLease(self._sai, machine_id, int(d.get("expiresAfterIdleSec", 0)))
+
+
+class ControlLease:
+    def __init__(self, sai: Sai, machine_id: str, idle_timeout_sec: int) -> None:
+        self._sai = sai
+        self.machine_id = machine_id
+        self._path = _control_path(machine_id)
+        self.idle_timeout_sec = idle_timeout_sec
+        self._closed = False
+
+    def __repr__(self) -> str:
+        return f"ControlLease(machine_id={self.machine_id!r})"
+
+    def __enter__(self) -> ControlLease:
+        return self
+
+    def __exit__(self, *exc: object) -> None:
+        self.close()
+
+    def exec(self, code: str, *, timeout_ms: Optional[int] = None) -> ExecResult:
+        """Run one Simulang (JavaScript) block. Use `var` for anything the next block needs.
+
+        A block that throws, times out or is interrupted still returns: check
+        `result.error`. Raises `GoneError` once the lease has ended (closed, idle,
+        taken by a Sai task, or the computer stopped answering): open again.
+        """
+        body: dict[str, Any] = {"code": code}
+        if timeout_ms is not None:
+            body["timeoutMs"] = timeout_ms
+        d = self._sai._http.json(
+            "POST", f"{self._path}/exec", json=body, timeout=(timeout_ms or 120_000) / 1000 + 45
+        )
+        return ExecResult.parse(d)
+
+
+    def run(
+        self,
+        learned: Union[LearnResult, str],
+        inputs: Optional[dict[str, Any]] = None,
+        *,
+        timeout_ms: Optional[int] = None,
+    ) -> ExecResult:
+        """Run code from `sai.learn.create()`: its `main` with `inputs` over the parameters'
+        defaults (an argument to `main` replaces its whole default object, so missing inputs
+        keep their defaults). `main`'s return value is `result.result`. A string runs as
+        code with `inputs` as is."""
+        if isinstance(learned, str):
+            code, params = learned, dict(inputs or {})
+        else:
+            code = learned.code
+            params = {p.name: p.default_value for p in learned.parameters} | (inputs or {})
+        return self.exec(f"{code}\nawait main({json.dumps(params)})", timeout_ms=timeout_ms)
+    def shell(self, command: str, *, cwd: Optional[str] = None, timeout_ms: Optional[int] = None) -> dict[str, Any]:
+        """Run a shell command: `{stdout, stderr, exitCode, timedOut}`."""
+        args: dict[str, Any] = {"command": command}
+        if cwd:
+            args["cwd"] = cwd
+        r = self.exec(f"await machine.exec({json.dumps(args)})", timeout_ms=timeout_ms)
+        _raise_on_block_error(r)
+        return r.result
+
+    def read_file(self, path: str) -> str:
+        r = self.exec(f"await machine.readFile({json.dumps({'path': path})})")
+        _raise_on_block_error(r)
+        return r.result
+
+    def write_file(self, path: str, text: str) -> None:
+        r = self.exec(f"await machine.writeToFile({json.dumps({'path': path, 'text': text, 'overwrite': True})})")
+        _raise_on_block_error(r)
+
+    def screenshot(self) -> bytes:
+        """The whole screen as image bytes (usually JPEG; use `exec` for the MIME type). Needs the
+        computer's screen-capture service; raises `BlockError` where it is off (a page or app
+        snapshot still carries an image)."""
+        r = self.exec("var __sai_page = await machine.pageContent(); null")
+        _raise_on_block_error(r)
+        if r.screenshot is None:
+            raise BlockError("exception", "screenshot too large to return" if r.screenshot_omitted else "no screenshot")
+        return r.screenshot
+
+    def interrupt(self) -> bool:
+        """Stop the running block at its next step. False if nothing was running."""
+        d = self._sai._http.json("POST", f"{self._path}/interrupt")
+        return bool(d and d.get("interrupted"))
+
+    def get(self) -> dict[str, Any]:
+        """`{status: open|closed, closedReason?, lastExecAt, ...}`."""
+        return self._sai._http.json("GET", self._path)
+
+    def close(self) -> None:
+        """Clear the REPL and release the computer. Safe to call twice."""
+        if self._closed:
+            return
+        try:
+            self._sai._http.request("DELETE", self._path)
+        except GoneError:
+            pass
+        self._closed = True
+
+
+def _raise_on_block_error(r: ExecResult) -> None:
+    if r.error:
+        raise BlockError(r.error.kind, r.error.message)