sai-sdk 0.1.0a1__tar.gz

sai_sdk-0.1.0a1/.gitignore

@@ -0,0 +1,5 @@
+__pycache__/
+*.pyc
+.venv/
+.pytest_cache/
+dist/

sai_sdk-0.1.0a1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Simular, Inc.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

sai_sdk-0.1.0a1/PKG-INFO

@@ -0,0 +1,161 @@
+Metadata-Version: 2.5
+Name: sai-sdk
+Version: 0.1.0a1
+Summary: Python SDK for the Sai API: delegate desktop work to Sai, or drive a cloud computer directly.
+Project-URL: Documentation, https://platform.simular.ai/documentation
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Development Status :: 3 - Alpha
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Typing :: Typed
+Requires-Python: >=3.9
+Requires-Dist: httpx<1,>=0.25
+Description-Content-Type: text/markdown
+
+# sai-sdk (Python)
+
+Python SDK for the [Sai API](https://platform.simular.ai/documentation). Hand desktop work to Sai on a
+computer (a Sai cloud computer, or your own PC with the Sai app) and get the answer back, or drive a cloud
+computer yourself.
+
+Status: **alpha (0.1)**. The surface may still change before 1.0.
+
+| Layer                  | What it is                                        | Status          |
+| ---------------------- | ------------------------------------------------- | --------------- |
+| `sai.sessions`         | A conversation with Sai on one computer           | available       |
+| `sai.control_sessions` | Drive a cloud computer directly with Simulang     | research preview |
+| `sai.runs`             | Typed tasks: inputs, output schema, evidence      | not yet         |
+
+## Install
+
+```bash
+pip install sai-sdk          # import name: sai
+export SAI_API_KEY=sapi_...  # create one at https://platform.simular.ai
+```
+
+Python 3.9+. One dependency, `httpx`.
+
+## Give Sai a task
+
+```python
+from sai import Sai
+
+sai = Sai()
+pc = sai.machines.list()[0]
+
+session = sai.sessions.create(machine=pc)      # a fresh conversation
+result = session.run("Open Notepad, type hello, save it to the desktop as hello.txt")
+
+print(result.status)   # idle | needs_approval | error
+print(result.text)     # Sai's answer
+print(result.usage)    # tokens and cost for this task
+```
+
+`machine` can be left out when the account has one computer. Further `session.run(...)` calls continue
+the same conversation; `sai.sessions.create()` starts a new one with no memory of the old.
+
+### Watch it work
+
+```python
+turn = session.send("Find last month's invoices in Downloads and total them")
+for ev in turn.events():
+    if ev.kind == "step":
+        print("  ", ev.text)
+    elif ev.kind == "approval":
+        print("Sai asks:", ev.approval.title, ev.approval.command)
+        turn.respond(ev.approval, "yes")       # or "no", or "task" for the rest of the task
+result = turn.wait()
+```
+
+`ev.kind` is one of `step`, `message`, `approval`, `tool_error`, `error`, `finished`.
+`turn.events(raw=True)` adds the wire frames (reasoning, tool calls) as `other`.
+
+### Approvals
+
+Sai asks before risky actions. `run()` / `wait()` return with `status == "needs_approval"` unless you pass
+a handler:
+
+```python
+def decide(approval):
+    if approval.is_link_only:
+        print("Approve in a browser:", approval.url)   # a human answers; keep waiting
+        return None
+    if approval.type == "choice":
+        return ("yes", [[q["options"][0]["value"]] for q in approval.questions])
+    return "yes" if approval.command and "del " not in approval.command else "no"
+
+result = session.run("Clean up the temp folder", on_approval=decide)
+```
+
+### Files, models, stopping
+
+```python
+report = sai.files.upload("report.pdf")
+session.run("Summarise the attached report", attachments=[report])
+
+[m.id for m in sai.models.list() if m.allowed]
+session.run("...", model="anthropic/claude-opus-5-5")   # sticks to the session
+
+turn = session.send("...")
+turn.abort()
+```
+
+## Drive a computer yourself
+
+Control sessions run [Simulang](https://platform.simular.ai/documentation/concepts/direct-control)
+blocks on a cloud computer. No agent, no model cost. While one is open, Sai's own tasks on that
+computer wait, so always close it (a `with` block does).
+
+```python
+with sai.control_sessions.open(machine=pc) as cs:
+    print(cs.shell("hostname")["stdout"])
+
+    r = cs.exec("""
+        var page = await machine.browser.newtab('https://news.ycombinator.com')
+        var snap = await page.snapshot()
+        snap.snapshot.grep('points')
+    """)
+    print(r.result)
+    open("hn.png", "wb").write(r.screenshot_png)   # a page or app snapshot carries a screenshot
+```
+
+`cs.screenshot()` grabs the whole screen. It needs the computer's screen-capture service; where that is
+off it raises `BlockError`, and a page or app snapshot is the way to get an image.
+
+`exec()` returns an `ExecResult`; a block that threw is still a result, so check `r.error`
+(`exception`, `timeout`, `interrupted`). Use `var`, not `let`/`const`, for values the next block needs.
+
+## Errors
+
+Every non-2xx response raises a `SaiError` subclass with `status`, `code`, `message` and `retry_after`:
+
+| Exception                 | When                                                                  |
+| ------------------------- | --------------------------------------------------------------------- |
+| `AuthenticationError`     | 401: the key is missing, unknown or revoked                           |
+| `PermissionDeniedError`   | 403: plan or ownership (`model_not_allowed_for_plan`, ...)            |
+| `BadRequestError`         | 400: e.g. several computers and no `machine=`                         |
+| `ConflictError`           | 409: `machine_busy`, approval no longer pending, ...                  |
+| `LinkOnlyApprovalError`   | the approval must be answered in a browser: `e.approval_url`          |
+| `GoneError`               | 410: the control session lost its computer; open a new one           |
+| `RateLimitError`          | 429: a rate limit, or the free plan's daily budget                    |
+| `ServiceUnavailableError` | 503: the computer did not come online; honor `retry_after`            |
+
+A task that ran out of credit ends with `result.status == "error"` and `result.error_code` set to
+`insufficient_credits` or `free_computer_time_exhausted`: stop retrying for today.
+
+## Configuration
+
+| Argument      | Env           | Default                  |
+| ------------- | ------------- | ------------------------ |
+| `api_key`     | `SAI_API_KEY` | required                 |
+| `base_url`    | `SAI_API_URL` | `https://api.simular.ai` |
+| `timeout`     |               | 60 s per request         |
+
+## Development
+
+```bash
+cd python
+uv sync
+uv run pytest
+```

sai_sdk-0.1.0a1/README.md

@@ -0,0 +1,146 @@
+# sai-sdk (Python)
+
+Python SDK for the [Sai API](https://platform.simular.ai/documentation). Hand desktop work to Sai on a
+computer (a Sai cloud computer, or your own PC with the Sai app) and get the answer back, or drive a cloud
+computer yourself.
+
+Status: **alpha (0.1)**. The surface may still change before 1.0.
+
+| Layer                  | What it is                                        | Status          |
+| ---------------------- | ------------------------------------------------- | --------------- |
+| `sai.sessions`         | A conversation with Sai on one computer           | available       |
+| `sai.control_sessions` | Drive a cloud computer directly with Simulang     | research preview |
+| `sai.runs`             | Typed tasks: inputs, output schema, evidence      | not yet         |
+
+## Install
+
+```bash
+pip install sai-sdk          # import name: sai
+export SAI_API_KEY=sapi_...  # create one at https://platform.simular.ai
+```
+
+Python 3.9+. One dependency, `httpx`.
+
+## Give Sai a task
+
+```python
+from sai import Sai
+
+sai = Sai()
+pc = sai.machines.list()[0]
+
+session = sai.sessions.create(machine=pc)      # a fresh conversation
+result = session.run("Open Notepad, type hello, save it to the desktop as hello.txt")
+
+print(result.status)   # idle | needs_approval | error
+print(result.text)     # Sai's answer
+print(result.usage)    # tokens and cost for this task
+```
+
+`machine` can be left out when the account has one computer. Further `session.run(...)` calls continue
+the same conversation; `sai.sessions.create()` starts a new one with no memory of the old.
+
+### Watch it work
+
+```python
+turn = session.send("Find last month's invoices in Downloads and total them")
+for ev in turn.events():
+    if ev.kind == "step":
+        print("  ", ev.text)
+    elif ev.kind == "approval":
+        print("Sai asks:", ev.approval.title, ev.approval.command)
+        turn.respond(ev.approval, "yes")       # or "no", or "task" for the rest of the task
+result = turn.wait()
+```
+
+`ev.kind` is one of `step`, `message`, `approval`, `tool_error`, `error`, `finished`.
+`turn.events(raw=True)` adds the wire frames (reasoning, tool calls) as `other`.
+
+### Approvals
+
+Sai asks before risky actions. `run()` / `wait()` return with `status == "needs_approval"` unless you pass
+a handler:
+
+```python
+def decide(approval):
+    if approval.is_link_only:
+        print("Approve in a browser:", approval.url)   # a human answers; keep waiting
+        return None
+    if approval.type == "choice":
+        return ("yes", [[q["options"][0]["value"]] for q in approval.questions])
+    return "yes" if approval.command and "del " not in approval.command else "no"
+
+result = session.run("Clean up the temp folder", on_approval=decide)
+```
+
+### Files, models, stopping
+
+```python
+report = sai.files.upload("report.pdf")
+session.run("Summarise the attached report", attachments=[report])
+
+[m.id for m in sai.models.list() if m.allowed]
+session.run("...", model="anthropic/claude-opus-5-5")   # sticks to the session
+
+turn = session.send("...")
+turn.abort()
+```
+
+## Drive a computer yourself
+
+Control sessions run [Simulang](https://platform.simular.ai/documentation/concepts/direct-control)
+blocks on a cloud computer. No agent, no model cost. While one is open, Sai's own tasks on that
+computer wait, so always close it (a `with` block does).
+
+```python
+with sai.control_sessions.open(machine=pc) as cs:
+    print(cs.shell("hostname")["stdout"])
+
+    r = cs.exec("""
+        var page = await machine.browser.newtab('https://news.ycombinator.com')
+        var snap = await page.snapshot()
+        snap.snapshot.grep('points')
+    """)
+    print(r.result)
+    open("hn.png", "wb").write(r.screenshot_png)   # a page or app snapshot carries a screenshot
+```
+
+`cs.screenshot()` grabs the whole screen. It needs the computer's screen-capture service; where that is
+off it raises `BlockError`, and a page or app snapshot is the way to get an image.
+
+`exec()` returns an `ExecResult`; a block that threw is still a result, so check `r.error`
+(`exception`, `timeout`, `interrupted`). Use `var`, not `let`/`const`, for values the next block needs.
+
+## Errors
+
+Every non-2xx response raises a `SaiError` subclass with `status`, `code`, `message` and `retry_after`:
+
+| Exception                 | When                                                                  |
+| ------------------------- | --------------------------------------------------------------------- |
+| `AuthenticationError`     | 401: the key is missing, unknown or revoked                           |
+| `PermissionDeniedError`   | 403: plan or ownership (`model_not_allowed_for_plan`, ...)            |
+| `BadRequestError`         | 400: e.g. several computers and no `machine=`                         |
+| `ConflictError`           | 409: `machine_busy`, approval no longer pending, ...                  |
+| `LinkOnlyApprovalError`   | the approval must be answered in a browser: `e.approval_url`          |
+| `GoneError`               | 410: the control session lost its computer; open a new one           |
+| `RateLimitError`          | 429: a rate limit, or the free plan's daily budget                    |
+| `ServiceUnavailableError` | 503: the computer did not come online; honor `retry_after`            |
+
+A task that ran out of credit ends with `result.status == "error"` and `result.error_code` set to
+`insufficient_credits` or `free_computer_time_exhausted`: stop retrying for today.
+
+## Configuration
+
+| Argument      | Env           | Default                  |
+| ------------- | ------------- | ------------------------ |
+| `api_key`     | `SAI_API_KEY` | required                 |
+| `base_url`    | `SAI_API_URL` | `https://api.simular.ai` |
+| `timeout`     |               | 60 s per request         |
+
+## Development
+
+```bash
+cd python
+uv sync
+uv run pytest
+```

sai_sdk-0.1.0a1/pyproject.toml

@@ -0,0 +1,31 @@
+[project]
+name = "sai-sdk"
+version = "0.1.0a1"
+description = "Python SDK for the Sai API: delegate desktop work to Sai, or drive a cloud computer directly."
+readme = "README.md"
+requires-python = ">=3.9"
+license = "MIT"
+license-files = ["LICENSE"]
+dependencies = ["httpx>=0.25,<1"]
+classifiers = [
+  "Development Status :: 3 - Alpha",
+  "Programming Language :: Python :: 3",
+  "Operating System :: OS Independent",
+  "Typing :: Typed",
+]
+
+[project.urls]
+Documentation = "https://platform.simular.ai/documentation"
+
+[dependency-groups]
+dev = ["pytest>=8"]
+
+[build-system]
+requires = ["hatchling>=1.24"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/sai"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

sai_sdk-0.1.0a1/src/sai/__init__.py

@@ -0,0 +1,69 @@
+"""Python SDK for the Sai API.
+
+- `sai.sessions`: give Sai a task on a computer and get the answer back.
+- `sai.control_sessions`: drive a cloud computer yourself with Simulang.
+- `sai.machines`, `sai.models`, `sai.files`, `sai.account`.
+"""
+
+from ._client import Sai
+from ._errors import (
+    AuthenticationError,
+    BadRequestError,
+    BlockError,
+    ConflictError,
+    ConnectionError,
+    GoneError,
+    LinkOnlyApprovalError,
+    NotFoundError,
+    PermissionDeniedError,
+    RateLimitError,
+    SaiError,
+    ServiceUnavailableError,
+)
+from ._version import __version__
+from .control import ControlSession
+from .machines import Machine
+from .sessions import Session, Turn
+from .types import (
+    Account,
+    Approval,
+    Attachment,
+    Event,
+    ExecError,
+    ExecResult,
+    LiveView,
+    Model,
+    TurnResult,
+    Usage,
+)
+
+__all__ = [
+    "Sai",
+    "Session",
+    "Turn",
+    "ControlSession",
+    "Machine",
+    "Account",
+    "Approval",
+    "Attachment",
+    "Event",
+    "ExecError",
+    "ExecResult",
+    "LiveView",
+    "Model",
+    "TurnResult",
+    "Usage",
+    "SaiError",
+    "AuthenticationError",
+    "BadRequestError",
+    "BlockError",
+    "ConflictError",
+    "ConnectionError",
+    "GoneError",
+    "LinkOnlyApprovalError",
+    "NotFoundError",
+    "PermissionDeniedError",
+    "RateLimitError",
+    "ServiceUnavailableError",
+    "__version__",
+]

sai_sdk-0.1.0a1/src/sai/_client.py

@@ -0,0 +1,96 @@
+from __future__ import annotations
+
+import os
+import urllib.parse
+from pathlib import Path
+from typing import Optional, Union
+
+import httpx
+
+from ._http import DEFAULT_BASE_URL, HTTP
+from .control import ControlSessions
+from .machines import Machines
+from .sessions import Sessions
+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,
+    ) -> None:
+        key = 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._http = HTTP(
+            key,
+            base_url or os.environ.get("SAI_API_URL") or DEFAULT_BASE_URL,
+            timeout=timeout,
+            version_tag=version_tag,
+            transport=transport,
+        )
+        self.machines = Machines(self)
+        self.sessions = Sessions(self)
+        self.control_sessions = ControlSessions(self)
+        self.models = _Models(self)
+        self.files = _Files(self)
+        self.account = _Account(self)
+
+    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(),
+            headers={"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_sdk-0.1.0a1/src/sai/_errors.py

@@ -0,0 +1,113 @@
+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: the control session was closed or sat idle. Open a new one."""
+
+
+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-session 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")
+
+
+_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/sessions, 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 = LinkOnlyApprovalError if code == "link_only" else _BY_STATUS.get(status, SaiError)
+    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()