numinous 0.1.0__tar.gz

numinous-0.1.0/LICENSE

@@ -0,0 +1,6 @@
+Apache License 2.0 — Copyright 2026 Numinous
+
+Licensed under the Apache License, Version 2.0 (the "License"); you may not
+use this software except in compliance with the License. You may obtain a
+copy at http://www.apache.org/licenses/LICENSE-2.0. Distributed on an
+"AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND.

numinous-0.1.0/PKG-INFO

@@ -0,0 +1,7 @@
+Metadata-Version: 2.5
+Name: numinous
+Version: 0.1.0
+Summary: Python SDK for Numinous Cloud sandboxes
+License-File: LICENSE
+Requires-Python: >=3.9
+Requires-Dist: httpx>=0.24

numinous-0.1.0/README.md

@@ -0,0 +1,51 @@
+# numinous
+
+Python SDK for [Numinous Cloud](https://cloud.numinous.technology) — build &
+test environments with hard TTLs, typed failure causes,
+export-that-survives-teardown, and per-second metering. Everything
+non-preemptible.
+
+## Install
+
+```bash
+curl -fsSL https://cloud.numinous.technology/install.sh | sh
+```
+
+Installs the `numinous` CLI + Python SDK (via pipx/uv/pip, whichever exists).
+
+## Use
+
+```python
+from numinous import Numinous
+
+nc = Numinous()  # NUMINOUS_API_URL / NUMINOUS_API_KEY from env
+
+tpl = nc.templates.pack("build-env", image="ubuntu:24.04",
+                        warm_cmd="apt-get update && apt-get install -y build-essential")
+
+sb = nc.sandboxes.create(template_id=tpl["id"], vcpu=4, mem_gib=8,
+                         ttl_seconds=7200, launch_token="job-1-attempt-1",
+                         labels={"trial_id": "tr_1"})
+
+nc.sandboxes.exec(sb["id"], "make -j test")
+nc.sandboxes.export(sb["id"], "/logs", to="s3://bucket/tr_1/")  # works after death too
+out = nc.sandboxes.destroy(sb["id"])
+out["teardown_proof"]                      # {"verified_absent": true, ...}
+nc.usage.query(label="trial_id:tr_1")      # per-second spans, typed unbilled faults
+```
+
+## Typed errors
+
+```python
+from numinous import Numinous, NuminousError
+
+try:
+    nc.sandboxes.create(...)
+except NuminousError as e:
+    e.cause              # "provider_capacity" | "user_image_build_failed" | ...
+    e.is_provider_fault  # provider_* causes are never billed
+    e.retryable
+```
+
+API reference: the control plane serves its own OpenAPI spec at
+`GET /openapi.json`.

numinous-0.1.0/install.sh

@@ -0,0 +1,33 @@
+#!/bin/sh
+# Numinous Cloud CLI installer
+#   curl -fsSL https://cloud.numinous.technology/install.sh | sh
+set -eu
+
+REPO="https://github.com/numinous-technology/numinous-python"
+BIN_DIR="${NUMINOUS_BIN:-$HOME/.local/bin}"
+
+say() { printf '\033[1;34mnuminous\033[0m %s\n' "$*"; }
+
+command -v python3 >/dev/null 2>&1 || {
+  echo "python3 is required" >&2; exit 1; }
+
+say "installing CLI from $REPO"
+
+if command -v pipx >/dev/null 2>&1; then
+  pipx install --force "numinous @ git+$REPO" >/dev/null
+elif command -v uv >/dev/null 2>&1; then
+  uv tool install --force "numinous @ git+$REPO" >/dev/null
+else
+  python3 -m pip install --user --upgrade "numinous @ git+$REPO" >/dev/null
+fi
+
+mkdir -p "$BIN_DIR"
+case ":$PATH:" in
+  *":$BIN_DIR:"*) ;;
+  *) say "add $BIN_DIR to your PATH" ;;
+esac
+
+say "installed. next:"
+say '  export NUMINOUS_API_URL=... NUMINOUS_API_KEY=...'
+say '  numinous capacity'
+say '  numinous template pack --name build-env --image ubuntu:24.04'

numinous-0.1.0/numinous/__init__.py

@@ -0,0 +1,17 @@
+"""numinous — Python SDK for the Numinous Cloud sandbox API.
+
+>>> from numinous import Numinous
+>>> nc = Numinous()  # NUMINOUS_API_URL / NUMINOUS_API_KEY from env
+>>> tpl = nc.templates.pack("build-env", image="ubuntu:24.04",
+...                         warm_cmd="apt-get update && apt-get install -y build-essential")
+>>> sb = nc.sandboxes.create(template_id=tpl["id"], vcpu=4, mem_gib=8,
+...                          ttl_seconds=7200, labels={"trial_id": "tr_1"})
+>>> nc.sandboxes.exec(sb["id"], "make -j test")
+>>> nc.sandboxes.export(sb["id"], "/logs", to="s3://bucket/tr_1/")
+>>> nc.sandboxes.destroy(sb["id"])
+"""
+
+from .client import Numinous, NuminousError
+
+__all__ = ["Numinous", "NuminousError"]
+__version__ = "0.1.0"

numinous-0.1.0/numinous/cli.py

@@ -0,0 +1,110 @@
+"""numinous — CLI for Numinous Cloud.
+
+Install:  curl -fsSL https://cloud.numinous.technology/install.sh | sh
+Auth:     export NUMINOUS_API_URL=... NUMINOUS_API_KEY=...
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+
+from .client import Numinous, NuminousError
+
+
+def _out(obj) -> None:
+    print(json.dumps(obj, indent=2, default=str))
+
+
+def main(argv: list[str] | None = None) -> int:
+    p = argparse.ArgumentParser(prog="numinous", description=__doc__)
+    sub = p.add_subparsers(dest="cmd", required=True)
+
+    tp = sub.add_parser("template", help="manage templates")
+    tps = tp.add_subparsers(dest="tcmd", required=True)
+    pack = tps.add_parser("pack", help="pack an environment into a template")
+    pack.add_argument("--name", required=True)
+    pack.add_argument("--image", help="base docker image")
+    pack.add_argument("--warm", help="command to run before snapshotting")
+    tps.add_parser("list", help="list templates")
+
+    boot = sub.add_parser("boot", help="boot sandboxes from a template")
+    boot.add_argument("template_id")
+    boot.add_argument("--vcpu", type=int, default=2)
+    boot.add_argument("--mem", type=float, default=4.0, help="GiB")
+    boot.add_argument("--ttl", type=int, default=0, help="seconds; 0=default")
+    boot.add_argument("--count", type=int, default=1)
+    boot.add_argument("--label", action="append", default=[], help="k=v")
+    boot.add_argument("--token", help="launch token (idempotency)")
+
+    ex = sub.add_parser("exec", help="run a command in a sandbox")
+    ex.add_argument("sandbox_id")
+    ex.add_argument("command")
+    ex.add_argument("--timeout", type=float, default=300)
+
+    for name in ("suspend", "resume", "destroy"):
+        c = sub.add_parser(name, help=f"{name} a sandbox")
+        c.add_argument("sandbox_id")
+
+    exp = sub.add_parser("export", help="export a path (works after death)")
+    exp.add_argument("sandbox_id")
+    exp.add_argument("path")
+    exp.add_argument("--to", help="s3://bucket/prefix")
+
+    ls = sub.add_parser("ls", help="list sandboxes")
+    ls.add_argument("--label")
+    ls.add_argument("--state")
+
+    us = sub.add_parser("usage", help="usage spans by label")
+    us.add_argument("--label")
+
+    sub.add_parser("capacity", help="free capacity")
+    sub.add_parser("pricing", help="current rates")
+
+    a = p.parse_args(argv)
+    nc = Numinous()
+    try:
+        if a.cmd == "template" and a.tcmd == "pack":
+            _out(nc.templates.pack(a.name, image=a.image, warm_cmd=a.warm))
+        elif a.cmd == "template" and a.tcmd == "list":
+            _out(nc.templates.list())
+        elif a.cmd == "boot":
+            labels = dict(kv.split("=", 1) for kv in a.label)
+            out = []
+            for i in range(a.count):
+                tok = f"{a.token}-{i}" if a.token and a.count > 1 else a.token
+                out.append(nc.sandboxes.create(
+                    template_id=a.template_id, vcpu=a.vcpu, mem_gib=a.mem,
+                    ttl_seconds=a.ttl, labels=labels, launch_token=tok))
+            _out(out if a.count > 1 else out[0])
+        elif a.cmd == "exec":
+            r = nc.sandboxes.exec(a.sandbox_id, a.command, timeout_sec=a.timeout)
+            sys.stdout.write(r["stdout"])
+            sys.stderr.write(r["stderr"])
+            return r["exit_code"]
+        elif a.cmd == "suspend":
+            _out(nc.sandboxes.suspend(a.sandbox_id))
+        elif a.cmd == "resume":
+            _out(nc.sandboxes.resume(a.sandbox_id))
+        elif a.cmd == "destroy":
+            _out(nc.sandboxes.destroy(a.sandbox_id))
+        elif a.cmd == "export":
+            _out(nc.sandboxes.export(a.sandbox_id, a.path, to=a.to))
+        elif a.cmd == "ls":
+            _out(nc.sandboxes.list(label=a.label, state=a.state))
+        elif a.cmd == "usage":
+            _out(nc.usage.query(label=a.label))
+        elif a.cmd == "capacity":
+            _out(nc.capacity.get())
+        elif a.cmd == "pricing":
+            _out(nc.pricing())
+        return 0
+    except NuminousError as e:
+        print(f"error [{e.cause}]: {e.message}", file=sys.stderr)
+        # provider faults are retryable and unbilled; exit codes reflect class
+        return 75 if e.is_provider_fault else 1
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

numinous-0.1.0/numinous/client.py

@@ -0,0 +1,214 @@
+from __future__ import annotations
+
+import os
+import time
+from typing import Any, Optional
+
+import httpx
+
+
+class NuminousError(RuntimeError):
+    """API error carrying the typed cause.
+
+    err.cause is one of: user_image_build_failed, user_oom, user_timeout,
+    provider_capacity, provider_infra, policy_killed_ttl, policy_killed_quota,
+    auth, state, not_found.
+    """
+
+    def __init__(self, cause: str, message: str, status: int):
+        super().__init__(f"[{cause}] {message}")
+        self.cause = cause
+        self.message = message
+        self.status = status
+
+    @property
+    def is_provider_fault(self) -> bool:
+        return self.cause.startswith("provider_")
+
+    @property
+    def retryable(self) -> bool:
+        # capacity clears (or use reservations); infra may clear; user_* will not.
+        return self.cause.startswith("provider_")
+
+
+class _Resource:
+    def __init__(self, c: "Numinous"):
+        self._c = c
+
+
+class Templates(_Resource):
+    def pack(self, name: str, *, image: str | None = None,
+             dockerfile: str | None = None, context: str | None = None,
+             warm_cmd: str | None = None) -> dict:
+        source: dict[str, Any] = {}
+        if image:
+            source = {"type": "image", "image": image, "warm_cmd": warm_cmd}
+        elif dockerfile:
+            source = {"type": "dockerfile", "dockerfile": dockerfile,
+                      "context": context or ".", "warm_cmd": warm_cmd}
+        return self._c._post("/v1/templates", {"name": name, "source": source},
+                             timeout=1800)
+
+    def list(self) -> list[dict]:
+        return self._c._get("/v1/templates")
+
+    def get(self, template_id: str) -> dict:
+        return self._c._get(f"/v1/templates/{template_id}")
+
+
+class Roms(_Resource):
+    def create(self, name: str, files: dict[str, str]) -> dict:
+        return self._c._post("/v1/roms", {"name": name, "files": files})
+
+
+class Sandboxes(_Resource):
+    def create(self, *, template_id: str | None = None, image: str | None = None,
+               rom_id: str | None = None, vcpu: int = 2, mem_gib: float = 4.0,
+               ttl_seconds: int = 0, launch_token: str | None = None,
+               labels: dict[str, str] | None = None,
+               egress: str = "allow", allow: list[str] | None = None,
+               env: dict[str, str] | None = None) -> dict:
+        return self._c._post("/v1/sandboxes", {
+            "template_id": template_id, "image": image, "rom_id": rom_id,
+            "vcpu": vcpu, "mem_gib": mem_gib, "ttl_seconds": ttl_seconds,
+            "launch_token": launch_token, "labels": labels or {},
+            "network": {"egress": egress, "allow": allow or []},
+            "env": env or {},
+        }, timeout=600)
+
+    def get(self, sandbox_id: str) -> dict:
+        return self._c._get(f"/v1/sandboxes/{sandbox_id}")
+
+    def list(self, *, label: str | None = None, state: str | None = None) -> list[dict]:
+        params = {}
+        if label:
+            params["label"] = label
+        if state:
+            params["state"] = state
+        return self._c._get("/v1/sandboxes", params=params)
+
+    def exec(self, sandbox_id: str, command: str, timeout_sec: float = 300,
+             *, cwd: str | None = None, env: dict[str, str] | None = None,
+             user: str | None = None) -> dict:
+        return self._c._post(f"/v1/sandboxes/{sandbox_id}/exec",
+                             {"command": command, "timeout_sec": timeout_sec,
+                              "cwd": cwd, "env": env or {}, "user": user},
+                             timeout=timeout_sec + 30)
+
+    def logs(self, sandbox_id: str, tail: int = 500) -> str:
+        return self._c._get(f"/v1/sandboxes/{sandbox_id}/logs",
+                            params={"tail": tail})["logs"]
+
+    def suspend(self, sandbox_id: str) -> dict:
+        return self._c._post(f"/v1/sandboxes/{sandbox_id}/suspend", {})
+
+    def resume(self, sandbox_id: str) -> dict:
+        return self._c._post(f"/v1/sandboxes/{sandbox_id}/resume", {})
+
+    def export(self, sandbox_id: str, path: str, to: str | None = None) -> dict:
+        """Works during the run and after the sandbox terminated."""
+        return self._c._post(f"/v1/sandboxes/{sandbox_id}/export",
+                             {"path": path, "to": to}, timeout=1800)
+
+    def destroy(self, sandbox_id: str) -> dict:
+        """Returns the sandbox with teardown_proof attached."""
+        return self._c._delete(f"/v1/sandboxes/{sandbox_id}")
+
+
+    def put_file(self, sandbox_id: str, path: str, data: bytes) -> dict:
+        import base64
+        return self._c._put(f"/v1/sandboxes/{sandbox_id}/files",
+                            {"path": path,
+                             "content_b64": base64.b64encode(data).decode()})
+
+    def get_file(self, sandbox_id: str, path: str) -> bytes:
+        import base64
+        out = self._c._get(f"/v1/sandboxes/{sandbox_id}/files",
+                           params={"path": path})
+        return base64.b64decode(out["content_b64"])
+
+    def events(self, sandbox_id: str) -> list[dict]:
+        return self._c._get(f"/v1/sandboxes/{sandbox_id}/events")
+
+    def wait(self, sandbox_id: str, *, until: str = "terminated",
+             timeout: float = 600, poll: float = 2.0) -> dict:
+        deadline = time.monotonic() + timeout
+        while time.monotonic() < deadline:
+            sb = self.get(sandbox_id)
+            if sb["state"] in (until, "failed", "terminated"):
+                return sb
+            time.sleep(poll)
+        raise TimeoutError(f"{sandbox_id} not {until} after {timeout}s")
+
+
+class Usage(_Resource):
+    def query(self, *, label: str | None = None) -> dict:
+        params = {"label": label} if label else {}
+        return self._c._get("/v1/usage", params=params)
+
+
+class Capacity(_Resource):
+    def get(self) -> dict:
+        return self._c._get("/v1/capacity")
+
+    def reserve(self, *, vcpu: int, mem_gib: float, count: int,
+                duration_minutes: int = 120,
+                labels: dict[str, str] | None = None) -> dict:
+        return self._c._post("/v1/reservations", {
+            "vcpu": vcpu, "mem_gib": mem_gib, "count": count,
+            "duration_minutes": duration_minutes, "labels": labels or {}})
+
+
+class Numinous:
+    def __init__(self, api_url: str | None = None, api_key: str | None = None):
+        self.api_url = (api_url or os.environ.get(
+            "NUMINOUS_API_URL", "http://127.0.0.1:8400")).rstrip("/")
+        self.api_key = api_key or os.environ.get("NUMINOUS_API_KEY", "nk_local_dev")
+        self._http = httpx.Client(
+            base_url=self.api_url,
+            headers={"Authorization": f"Bearer {self.api_key}"},
+            timeout=60,
+        )
+        self.templates = Templates(self)
+        self.roms = Roms(self)
+        self.sandboxes = Sandboxes(self)
+        self.usage = Usage(self)
+        self.capacity = Capacity(self)
+
+    def pricing(self) -> dict:
+        return self._get("/v1/pricing")
+
+    def healthz(self) -> dict:
+        return self._get("/v1/healthz")
+
+    # -- transport ----------------------------------------------------------
+
+    def _raise_for(self, r: httpx.Response) -> None:
+        if r.status_code < 400:
+            return
+        try:
+            detail = r.json().get("detail", {})
+        except Exception:
+            detail = {}
+        raise NuminousError(detail.get("cause", "unknown"),
+                            detail.get("message", r.text[:300]), r.status_code)
+
+    def _get(self, path: str, params: dict | None = None) -> Any:
+        r = self._http.get(path, params=params)
+        self._raise_for(r)
+        return r.json()
+
+    def _post(self, path: str, body: dict, timeout: float = 120) -> Any:
+        r = self._http.post(path, json=body, timeout=timeout)
+        self._raise_for(r)
+        return r.json()
+
+    def _put(self, path: str, body: dict, timeout: float = 600) -> Any:
+        r = self._http.put(path, json=body, timeout=timeout)
+        self._raise_for(r)
+        return r.json()
+
+    def _delete(self, path: str) -> Any:
+        r = self._http.delete(path)
+        self._raise_for(r)
+        return r.json()

numinous-0.1.0/pyproject.toml

@@ -0,0 +1,16 @@
+[project]
+name = "numinous"
+version = "0.1.0"
+description = "Python SDK for Numinous Cloud sandboxes"
+requires-python = ">=3.9"
+dependencies = ["httpx>=0.24"]
+
+[project.scripts]
+numinous = "numinous.cli:main"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["numinous"]