orkestr 0.1.0a1__tar.gz

orkestr-0.1.0a1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Orkestr
+
+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.

orkestr-0.1.0a1/PKG-INFO

@@ -0,0 +1,201 @@
+Metadata-Version: 2.4
+Name: orkestr
+Version: 0.1.0a1
+Summary: EU-hosted sandbox VMs for AI agents - official Python SDK
+Author-email: Orkestr <hello@orkestr.eu>
+License-Expression: MIT
+Project-URL: Homepage, https://orkestr.eu/sandboxes
+Project-URL: Documentation, https://orkestr.eu/docs
+Keywords: orkestr,sandbox,ai,agents,code-execution,eu
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: httpx>=0.27
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == "dev"
+Requires-Dist: respx>=0.21; extra == "dev"
+Requires-Dist: ruff>=0.6; extra == "dev"
+Dynamic: license-file
+
+# orkestr Python SDK
+
+EU-hosted sandbox VMs for AI agents. Type-safe Python client for the
+`api.orkestr.eu/v1/sandboxes` REST API.
+
+> **Status: private beta pre-release (`0.1.0a1`).** The client surface is
+> stable and tested, but the `api.orkestr.eu/v1/sandboxes` backend is not
+> live yet - every endpoint returns `501 Not Implemented` until the public
+> beta. This release exists so you can pin the package and review the API.
+> See `docs/sandbox-mvp-plan.md` in the orkestr repo for the timeline.
+
+## Install
+
+```bash
+pip install --pre orkestr
+```
+
+Requires Python 3.10+. The `--pre` flag is needed while the SDK is a
+pre-release; it is dropped once `0.1.0` ships with the public beta.
+
+## Authenticate
+
+Mint an API token in the orkestr console with the `sandboxes:write` scope.
+
+```bash
+export ORKESTR_API_KEY="sp_live_..."
+```
+
+The SDK picks the key up from `ORKESTR_API_KEY` or you pass it explicitly.
+
+## Quick start
+
+One-shot execution inside a fresh sandbox. The `with` block auto-terminates
+the sandbox on exit, preventing runaway costs if the caller crashes.
+
+```python
+from orkestr import Sandbox
+
+with Sandbox.create(template="python-3.12") as sbx:
+    sbx.files.write("/workspace/main.py", "print(sum(range(1_000_000)))")
+    result = sbx.exec("python /workspace/main.py")
+    print(result.stdout)        # 499999500000
+    print(result.duration_ms)   # ~120
+```
+
+## API
+
+### Create a sandbox
+
+```python
+sbx = Sandbox.create(
+    template="python-3.12",          # one of the templates listed below
+    cpu=1.0,                         # vCPU (default 1, plan-capped)
+    memory_mb=2048,                  # RAM (default 2048, plan-capped)
+    network="off",                   # "off" | "restricted" | "open"
+    timeout_seconds=600,             # auto-terminate after this many seconds
+    env={"OPENAI_API_KEY": "sk-..."},
+    metadata={"agent_run": "r_123"},
+    region="fsn1",                   # "fsn1" (DE) | "hel1" (FI) | None for auto
+    api_key=None,                    # falls back to ORKESTR_API_KEY
+)
+print(sbx.id)             # "sbx_01HXYZ..."
+print(sbx.status)         # "running"
+```
+
+### Templates
+
+| Template            | Description                              |
+|---------------------|------------------------------------------|
+| `python-3.12`       | CPython 3.12 with pip and common libs    |
+| `python-3.12-bare`  | CPython 3.12 only, faster start          |
+| `node-22`           | Node 22 with npm                         |
+| `ubuntu-24.04`      | Minimal Ubuntu shell environment         |
+
+### Run a command
+
+```python
+result = sbx.exec("python /workspace/main.py", timeout_seconds=60)
+result.stdout       # str
+result.stderr       # str
+result.exit_code    # int
+result.duration_ms  # int
+```
+
+### Stream a long command
+
+```python
+for chunk in sbx.exec_stream("python long_task.py"):
+    if chunk.stream == "stdout":
+        print(chunk.data, end="", flush=True)
+    else:
+        print(chunk.data, end="", flush=True, file=sys.stderr)
+```
+
+### Files
+
+```python
+sbx.files.write("/workspace/data.json", '{"x": 1}')
+sbx.files.write_bytes("/workspace/blob.bin", b"\x00\x01\x02")
+
+content = sbx.files.read("/workspace/out.txt")       # returns str
+raw = sbx.files.read_bytes("/workspace/blob.bin")     # returns bytes
+
+for entry in sbx.files.list("/workspace"):
+    print(entry.name, entry.is_dir, entry.size)
+
+sbx.files.delete("/workspace/out.txt")
+```
+
+### Pause + resume
+
+Pausing snapshots the sandbox memory + disk and stops the compute meter.
+Resume restores it on the same or a different host. `pause()` returns
+the sandbox id; persist it across processes and pass to `Sandbox.resume`.
+
+```python
+sbx = Sandbox.create(template="node-22", network="restricted")
+sandbox_id = sbx.pause()
+# ... minutes or hours later, from any worker:
+sbx = Sandbox.resume(sandbox_id)
+```
+
+Snapshot retention is plan-capped (free: 1, pro: 3, team: 10). Calling
+`pause()` over the cap raises `SnapshotCapReached`.
+
+### Terminate
+
+Context-manager exit calls `terminate()`. Outside `with`:
+
+```python
+sbx.terminate()
+```
+
+After `terminate()` the sandbox row stays in your account history but
+the VM and any in-memory state are gone.
+
+### List your sandboxes
+
+```python
+for sbx in Sandbox.list(status="running"):
+    print(sbx.id, sbx.template, sbx.created_at)
+```
+
+## Errors
+
+All SDK errors inherit from `orkestr.OrkestrError`.
+
+| Exception                | When                                              |
+|--------------------------|---------------------------------------------------|
+| `AuthError`              | Missing / invalid / expired API key, or scope mismatch |
+| `RateLimitError`         | Plan rate limit hit                               |
+| `PlanLimitError`         | Sandbox limit, concurrent limit, snapshot cap     |
+| `SandboxNotFound`        | `sandbox_id` doesn't exist or isn't yours         |
+| `SandboxNotReady`        | Operation called on a paused / terminated sandbox |
+| `ExecTimeout`            | `exec()` exceeded `timeout_seconds`               |
+| `NetworkPolicyError`     | Command tried to reach a host the policy blocks   |
+| `OrkestrError`           | Any other API-level error                         |
+
+## Async support
+
+The MVP SDK is sync only. Async (`AsyncSandbox`) lands in v0.2.0 if a
+design partner blocks on it; the wire format is identical.
+
+## Versioning
+
+Follows [Semantic Versioning](https://semver.org). The SDK targets the
+`/v1/sandboxes` API; bumps to v1 of the API are non-breaking for SDK
+callers. v2 of the API will require an SDK major.
+
+## Links
+
+- [Sandbox waitlist](https://orkestr.eu/sandboxes)
+- [Public API docs](https://orkestr.eu/docs)
+- Questions and bug reports during the private beta: <hello@orkestr.eu>

orkestr-0.1.0a1/README.md

@@ -0,0 +1,174 @@
+# orkestr Python SDK
+
+EU-hosted sandbox VMs for AI agents. Type-safe Python client for the
+`api.orkestr.eu/v1/sandboxes` REST API.
+
+> **Status: private beta pre-release (`0.1.0a1`).** The client surface is
+> stable and tested, but the `api.orkestr.eu/v1/sandboxes` backend is not
+> live yet - every endpoint returns `501 Not Implemented` until the public
+> beta. This release exists so you can pin the package and review the API.
+> See `docs/sandbox-mvp-plan.md` in the orkestr repo for the timeline.
+
+## Install
+
+```bash
+pip install --pre orkestr
+```
+
+Requires Python 3.10+. The `--pre` flag is needed while the SDK is a
+pre-release; it is dropped once `0.1.0` ships with the public beta.
+
+## Authenticate
+
+Mint an API token in the orkestr console with the `sandboxes:write` scope.
+
+```bash
+export ORKESTR_API_KEY="sp_live_..."
+```
+
+The SDK picks the key up from `ORKESTR_API_KEY` or you pass it explicitly.
+
+## Quick start
+
+One-shot execution inside a fresh sandbox. The `with` block auto-terminates
+the sandbox on exit, preventing runaway costs if the caller crashes.
+
+```python
+from orkestr import Sandbox
+
+with Sandbox.create(template="python-3.12") as sbx:
+    sbx.files.write("/workspace/main.py", "print(sum(range(1_000_000)))")
+    result = sbx.exec("python /workspace/main.py")
+    print(result.stdout)        # 499999500000
+    print(result.duration_ms)   # ~120
+```
+
+## API
+
+### Create a sandbox
+
+```python
+sbx = Sandbox.create(
+    template="python-3.12",          # one of the templates listed below
+    cpu=1.0,                         # vCPU (default 1, plan-capped)
+    memory_mb=2048,                  # RAM (default 2048, plan-capped)
+    network="off",                   # "off" | "restricted" | "open"
+    timeout_seconds=600,             # auto-terminate after this many seconds
+    env={"OPENAI_API_KEY": "sk-..."},
+    metadata={"agent_run": "r_123"},
+    region="fsn1",                   # "fsn1" (DE) | "hel1" (FI) | None for auto
+    api_key=None,                    # falls back to ORKESTR_API_KEY
+)
+print(sbx.id)             # "sbx_01HXYZ..."
+print(sbx.status)         # "running"
+```
+
+### Templates
+
+| Template            | Description                              |
+|---------------------|------------------------------------------|
+| `python-3.12`       | CPython 3.12 with pip and common libs    |
+| `python-3.12-bare`  | CPython 3.12 only, faster start          |
+| `node-22`           | Node 22 with npm                         |
+| `ubuntu-24.04`      | Minimal Ubuntu shell environment         |
+
+### Run a command
+
+```python
+result = sbx.exec("python /workspace/main.py", timeout_seconds=60)
+result.stdout       # str
+result.stderr       # str
+result.exit_code    # int
+result.duration_ms  # int
+```
+
+### Stream a long command
+
+```python
+for chunk in sbx.exec_stream("python long_task.py"):
+    if chunk.stream == "stdout":
+        print(chunk.data, end="", flush=True)
+    else:
+        print(chunk.data, end="", flush=True, file=sys.stderr)
+```
+
+### Files
+
+```python
+sbx.files.write("/workspace/data.json", '{"x": 1}')
+sbx.files.write_bytes("/workspace/blob.bin", b"\x00\x01\x02")
+
+content = sbx.files.read("/workspace/out.txt")       # returns str
+raw = sbx.files.read_bytes("/workspace/blob.bin")     # returns bytes
+
+for entry in sbx.files.list("/workspace"):
+    print(entry.name, entry.is_dir, entry.size)
+
+sbx.files.delete("/workspace/out.txt")
+```
+
+### Pause + resume
+
+Pausing snapshots the sandbox memory + disk and stops the compute meter.
+Resume restores it on the same or a different host. `pause()` returns
+the sandbox id; persist it across processes and pass to `Sandbox.resume`.
+
+```python
+sbx = Sandbox.create(template="node-22", network="restricted")
+sandbox_id = sbx.pause()
+# ... minutes or hours later, from any worker:
+sbx = Sandbox.resume(sandbox_id)
+```
+
+Snapshot retention is plan-capped (free: 1, pro: 3, team: 10). Calling
+`pause()` over the cap raises `SnapshotCapReached`.
+
+### Terminate
+
+Context-manager exit calls `terminate()`. Outside `with`:
+
+```python
+sbx.terminate()
+```
+
+After `terminate()` the sandbox row stays in your account history but
+the VM and any in-memory state are gone.
+
+### List your sandboxes
+
+```python
+for sbx in Sandbox.list(status="running"):
+    print(sbx.id, sbx.template, sbx.created_at)
+```
+
+## Errors
+
+All SDK errors inherit from `orkestr.OrkestrError`.
+
+| Exception                | When                                              |
+|--------------------------|---------------------------------------------------|
+| `AuthError`              | Missing / invalid / expired API key, or scope mismatch |
+| `RateLimitError`         | Plan rate limit hit                               |
+| `PlanLimitError`         | Sandbox limit, concurrent limit, snapshot cap     |
+| `SandboxNotFound`        | `sandbox_id` doesn't exist or isn't yours         |
+| `SandboxNotReady`        | Operation called on a paused / terminated sandbox |
+| `ExecTimeout`            | `exec()` exceeded `timeout_seconds`               |
+| `NetworkPolicyError`     | Command tried to reach a host the policy blocks   |
+| `OrkestrError`           | Any other API-level error                         |
+
+## Async support
+
+The MVP SDK is sync only. Async (`AsyncSandbox`) lands in v0.2.0 if a
+design partner blocks on it; the wire format is identical.
+
+## Versioning
+
+Follows [Semantic Versioning](https://semver.org). The SDK targets the
+`/v1/sandboxes` API; bumps to v1 of the API are non-breaking for SDK
+callers. v2 of the API will require an SDK major.
+
+## Links
+
+- [Sandbox waitlist](https://orkestr.eu/sandboxes)
+- [Public API docs](https://orkestr.eu/docs)
+- Questions and bug reports during the private beta: <hello@orkestr.eu>

orkestr-0.1.0a1/orkestr/__init__.py

@@ -0,0 +1,59 @@
+"""orkestr Python SDK.
+
+EU-hosted sandbox VMs for AI agents. See README.md or
+https://orkestr.eu/sandboxes for the full API.
+
+    from orkestr import Sandbox
+
+    with Sandbox.create(template="python-3.12") as sbx:
+        sbx.files.write("/workspace/main.py", "print(2+2)")
+        result = sbx.exec("python /workspace/main.py")
+        print(result.stdout)
+"""
+
+from __future__ import annotations
+
+from ._client import OrkestrClient, get_default_client, set_default_client
+from .errors import (
+    APIError,
+    AuthError,
+    ConnectionError,
+    ExecKilled,
+    ExecTimeout,
+    NetworkPolicyError,
+    OrkestrError,
+    PlanLimitError,
+    RateLimitError,
+    SandboxNotFound,
+    SandboxNotReady,
+    SnapshotCapReached,
+)
+from .sandbox import ExecChunk, ExecResult, FileEntry, Sandbox
+
+__version__ = "0.1.0a1"
+
+__all__ = [
+    # Core
+    "Sandbox",
+    "ExecResult",
+    "ExecChunk",
+    "FileEntry",
+    # Client (advanced)
+    "OrkestrClient",
+    "get_default_client",
+    "set_default_client",
+    # Errors
+    "OrkestrError",
+    "AuthError",
+    "RateLimitError",
+    "PlanLimitError",
+    "SnapshotCapReached",
+    "SandboxNotFound",
+    "SandboxNotReady",
+    "ExecTimeout",
+    "ExecKilled",
+    "NetworkPolicyError",
+    "APIError",
+    "ConnectionError",
+    "__version__",
+]

orkestr-0.1.0a1/orkestr/_client.py

@@ -0,0 +1,239 @@
+"""HTTP client for the orkestr API.
+
+Wraps httpx.Client with bearer-token auth, error mapping, and a
+configurable base URL. Most users go through Sandbox / Sandbox.create
+rather than constructing this directly.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+from collections.abc import Iterator
+from typing import Any
+
+import httpx
+
+from .errors import (
+    AuthError,
+    OrkestrError,
+    from_response,
+)
+from .errors import (
+    ConnectionError as OrkestrConnectionError,
+)
+
+DEFAULT_BASE_URL = "https://api.orkestr.eu"
+DEFAULT_TIMEOUT_SECONDS = 30.0
+_VERSION = "0.1.0"
+_USER_AGENT = f"orkestr-python/{_VERSION}"
+
+
+class OrkestrClient:
+    """Thin HTTPX wrapper with auth and error mapping.
+
+    Constructed lazily by the SDK; users usually only see it through
+    ``Sandbox.create(api_key=...)``. Holding a single client and reusing
+    it lets httpx keep its connection pool warm across calls.
+    """
+
+    def __init__(
+        self,
+        api_key: str | None = None,
+        base_url: str | None = None,
+        timeout: float = DEFAULT_TIMEOUT_SECONDS,
+    ) -> None:
+        resolved_key = api_key or os.environ.get("ORKESTR_API_KEY")
+        if not resolved_key:
+            raise AuthError(
+                "ORKESTR_API_KEY is not set. Pass api_key=... or export "
+                "ORKESTR_API_KEY before calling the SDK."
+            )
+
+        resolved_base = (
+            base_url
+            or os.environ.get("ORKESTR_BASE_URL")
+            or DEFAULT_BASE_URL
+        ).rstrip("/")
+
+        self._api_key = resolved_key
+        self._base_url = resolved_base
+        self._http = httpx.Client(
+            base_url=resolved_base,
+            timeout=timeout,
+            headers={
+                "Authorization": f"Bearer {resolved_key}",
+                "User-Agent": _USER_AGENT,
+                "Accept": "application/json",
+            },
+        )
+
+    # ------------------------------------------------------------------
+    # Lifecycle
+    # ------------------------------------------------------------------
+
+    def close(self) -> None:
+        self._http.close()
+
+    def __enter__(self) -> OrkestrClient:
+        return self
+
+    def __exit__(self, *args: object) -> None:
+        self.close()
+
+    # ------------------------------------------------------------------
+    # Request helpers
+    # ------------------------------------------------------------------
+
+    def request(
+        self,
+        method: str,
+        path: str,
+        *,
+        json_body: dict[str, Any] | None = None,
+        params: dict[str, Any] | None = None,
+    ) -> dict[str, Any] | None:
+        """Issue a request and return the parsed JSON body (or None for 204).
+
+        Non-2xx responses are mapped to the right SDK exception via
+        errors.from_response. Transport-level failures (DNS, connection
+        refused, timeout before bytes arrive) become OrkestrConnectionError.
+        """
+        try:
+            response = self._http.request(
+                method, path, json=json_body, params=params
+            )
+        except httpx.TimeoutException as exc:
+            raise OrkestrConnectionError(
+                f"Timeout connecting to {self._base_url}{path}"
+            ) from exc
+        except httpx.TransportError as exc:
+            raise OrkestrConnectionError(
+                f"Transport error reaching {self._base_url}: {exc}"
+            ) from exc
+
+        return self._handle_response(response)
+
+    def get(self, path: str, *, params: dict[str, Any] | None = None) -> dict[str, Any] | None:
+        return self.request("GET", path, params=params)
+
+    def post(
+        self,
+        path: str,
+        *,
+        json_body: dict[str, Any] | None = None,
+        params: dict[str, Any] | None = None,
+    ) -> dict[str, Any] | None:
+        return self.request("POST", path, json_body=json_body, params=params)
+
+    def delete(
+        self,
+        path: str,
+        *,
+        params: dict[str, Any] | None = None,
+    ) -> dict[str, Any] | None:
+        return self.request("DELETE", path, params=params)
+
+    def stream(
+        self,
+        method: str,
+        path: str,
+        *,
+        json_body: dict[str, Any] | None = None,
+    ) -> Iterator[str]:
+        """Open a streaming response and yield raw decoded text lines.
+
+        Used by the streaming-exec path to parse SSE. Caller is responsible
+        for closing iteration; the underlying response is closed when the
+        generator exits.
+        """
+        try:
+            with self._http.stream(
+                method, path, json=json_body
+            ) as response:
+                if response.status_code >= 400:
+                    # Drain the body so we can map the error. Streaming
+                    # responses with an error usually carry a small JSON
+                    # body, so the cost is negligible.
+                    body_text = response.read().decode(errors="replace")
+                    self._raise_for_status(response, body_text=body_text)
+                yield from response.iter_lines()
+        except httpx.TimeoutException as exc:
+            raise OrkestrConnectionError(
+                f"Timeout streaming from {self._base_url}{path}"
+            ) from exc
+        except httpx.TransportError as exc:
+            raise OrkestrConnectionError(
+                f"Transport error reaching {self._base_url}: {exc}"
+            ) from exc
+
+    # ------------------------------------------------------------------
+    # Internals
+    # ------------------------------------------------------------------
+
+    def _handle_response(self, response: httpx.Response) -> dict[str, Any] | None:
+        if response.status_code == 204:
+            return None
+        if 200 <= response.status_code < 300:
+            if not response.content:
+                return None
+            try:
+                return response.json()
+            except json.JSONDecodeError as exc:
+                raise OrkestrError(
+                    f"Non-JSON 2xx response from {response.url}: "
+                    f"{response.text[:200]}",
+                    status_code=response.status_code,
+                ) from exc
+
+        self._raise_for_status(response)
+        return None  # unreachable
+
+    def _raise_for_status(
+        self,
+        response: httpx.Response,
+        *,
+        body_text: str | None = None,
+    ) -> None:
+        request_id = response.headers.get("x-request-id")
+        text = body_text if body_text is not None else response.text
+        body: dict[str, Any] | None
+        try:
+            body = json.loads(text) if text else None
+        except json.JSONDecodeError:
+            body = None
+        raise from_response(response.status_code, body, request_id=request_id)
+
+
+# ---------------------------------------------------------------------------
+# Default client management
+# ---------------------------------------------------------------------------
+
+_default_client: OrkestrClient | None = None
+
+
+def get_default_client() -> OrkestrClient:
+    """Lazily create the module-level client used by Sandbox classmethods.
+
+    Constructed on first use from ``ORKESTR_API_KEY`` and ``ORKESTR_BASE_URL``.
+    Tests can override via ``set_default_client``.
+    """
+    global _default_client
+    if _default_client is None:
+        _default_client = OrkestrClient()
+    return _default_client
+
+
+def set_default_client(client: OrkestrClient | None) -> None:
+    """Override (or clear) the module-level client. Test seam."""
+    global _default_client
+    _default_client = client
+
+
+__all__ = [
+    "OrkestrClient",
+    "DEFAULT_BASE_URL",
+    "DEFAULT_TIMEOUT_SECONDS",
+    "get_default_client",
+    "set_default_client",
+]