roborama-sdk 0.1.0__tar.gz

roborama_sdk-0.1.0/.gitignore

@@ -0,0 +1,7 @@
+__pycache__/
+*.pyc
+dist/
+build/
+*.egg-info/
+.venv/
+.pytest_cache/

roborama_sdk-0.1.0/LICENSE

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

roborama_sdk-0.1.0/PKG-INFO

@@ -0,0 +1,92 @@
+Metadata-Version: 2.5
+Name: roborama-sdk
+Version: 0.1.0
+Summary: Official Python SDK for the Roborama API — statistically defensible evaluation of robot policies on physical hardware.
+Project-URL: Homepage, https://roborama.com
+Project-URL: Documentation, https://roborama.com/docs
+Project-URL: API Reference, https://roborama.com/docs/api-reference
+Project-URL: OpenAPI, https://roborama.com/openapi.json
+Author-email: Roborama <api@roborama.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: api,benchmark,evaluation,robotics,robots,sdk
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+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 :: Scientific/Engineering
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
+Requires-Python: >=3.9
+Requires-Dist: httpx>=0.24
+Description-Content-Type: text/markdown
+
+# roborama-sdk
+
+Official Python SDK for [Roborama](https://roborama.com) — real robots as an API. Statistically defensible evaluation of robot policies on physical hardware: every result carries `n` and a 95% confidence interval, everything is versioned (robots pin firmware, environments and suites pin revisions), and both meters (robot-hours × environment-hours) are visible in every quote.
+
+> **Status.** The API surface is a **stable draft** of [openapi.json](https://roborama.com/openapi.json); hosted execution is in **private preview**. This SDK ships a deterministic **mock mode** so you (and your agents) can integrate today — set `ROBORAMA_MOCK=1` and every call returns fixture-shaped results with honest statistics, no hardware and no API key required.
+
+```bash
+pip install roborama-sdk
+```
+
+The distribution is `roborama-sdk`; the module is `roborama` — import statements are exactly as documented (`import roborama`).
+
+## First call
+
+Authentication reads `ROBORAMA_API_KEY` (keys carry the `rbr_live_` prefix) from the environment, so it's an export, not an argument.
+
+```python
+import roborama  # reads ROBORAMA_API_KEY from the environment
+
+run = roborama.run(
+    robot="g1-edu-pro@fw2.3",            # embodiment @ pinned firmware
+    environment="kitchen-std@v1.2",      # versioned catalogue scene
+    policy=roborama.Policy.checkpoint(   # openpi / lerobot checkpoints,
+        hf="acme/skill-v4",              # containers, or hosted endpoints
+        runtime="openpi",
+    ),
+    task="load_dishwasher@v2",
+    episodes="auto(ci=0.95, moe=0.03)",  # size n for ±3% at 95% — or an int
+    max_budget_usd=4_000,                # hard stop, metered live
+)
+
+print(run.result())
+#  n=612  success_rate=0.874  ci95=(0.846, 0.898)
+#  failure_clusters: [grasp_slip: 41, perception_miss: 22, collision: 9]
+#  robot_hours=20.4  environment_hours=20.4  cost_usd=3812
+#  artifacts: ground_truth, mcap, report_pdf, video
+```
+
+## Mock mode — runnable today
+
+```bash
+ROBORAMA_MOCK=1 python your_script.py   # or: roborama.Client(mock=True)
+```
+
+Mock mode is deterministic and fixture-shaped: quote math follows the [public rate card](https://roborama.com/pricing), run results are shaped like the canonical runs, `max_budget_usd` hard stops raise `roborama.BudgetExceeded` with an honest `partial_result`, and Wilson intervals are computed exactly as documented. The same code runs unchanged against the hosted API once you have a key.
+
+## The surface
+
+- **Primitives** (module-level, one call per physical question): `roborama.run()`, `roborama.eval()`, `roborama.verify()`, `roborama.matrix()`, `roborama.threshold()`, `roborama.compare()`, `roborama.transfer()` — plus `roborama.quote()` and `roborama.usage()`.
+- **Resources**: `roborama.runs`, `roborama.robots`, `roborama.environments`, `roborama.suites`, `roborama.tasks`, `roborama.kits`, `roborama.streams`, `roborama.keys`, `roborama.budgets`, `roborama.data`, `roborama.calibration`, `roborama.scenarios` — with the `list()`/`get()` shapes you'd expect.
+- **Policies**: `roborama.Policy.container(...)`, `.checkpoint(...)`, `.endpoint(...)` — declared contracts, validated before any motor moves.
+- **Results**: `run.result()` (n, rate, ci95, clusters, both meters), `run.episodes[i]` (video, MCAP, replay spec), `run.watch()` (live), `run.export(format="lerobot")`, `run.report(format="pdf")`.
+- **Errors**: `roborama.RoboramaError` base; every code in [the error reference](https://roborama.com/docs/errors/) maps to a subclass (`budget_exceeded` → `roborama.BudgetExceeded`, carrying `err.partial_result`).
+
+Docs: [quickstart](https://roborama.com/docs/quickstart/) · [primitives](https://roborama.com/docs/primitives/run/) · [errors](https://roborama.com/docs/errors/) · [OpenAPI](https://roborama.com/openapi.json)
+
+## Requirements
+
+Python ≥ 3.9. One dependency: [`httpx`](https://www.python-httpx.org/). Fully typed (`py.typed`).
+
+## License
+
+MIT

roborama_sdk-0.1.0/README.md

@@ -0,0 +1,63 @@
+# roborama-sdk
+
+Official Python SDK for [Roborama](https://roborama.com) — real robots as an API. Statistically defensible evaluation of robot policies on physical hardware: every result carries `n` and a 95% confidence interval, everything is versioned (robots pin firmware, environments and suites pin revisions), and both meters (robot-hours × environment-hours) are visible in every quote.
+
+> **Status.** The API surface is a **stable draft** of [openapi.json](https://roborama.com/openapi.json); hosted execution is in **private preview**. This SDK ships a deterministic **mock mode** so you (and your agents) can integrate today — set `ROBORAMA_MOCK=1` and every call returns fixture-shaped results with honest statistics, no hardware and no API key required.
+
+```bash
+pip install roborama-sdk
+```
+
+The distribution is `roborama-sdk`; the module is `roborama` — import statements are exactly as documented (`import roborama`).
+
+## First call
+
+Authentication reads `ROBORAMA_API_KEY` (keys carry the `rbr_live_` prefix) from the environment, so it's an export, not an argument.
+
+```python
+import roborama  # reads ROBORAMA_API_KEY from the environment
+
+run = roborama.run(
+    robot="g1-edu-pro@fw2.3",            # embodiment @ pinned firmware
+    environment="kitchen-std@v1.2",      # versioned catalogue scene
+    policy=roborama.Policy.checkpoint(   # openpi / lerobot checkpoints,
+        hf="acme/skill-v4",              # containers, or hosted endpoints
+        runtime="openpi",
+    ),
+    task="load_dishwasher@v2",
+    episodes="auto(ci=0.95, moe=0.03)",  # size n for ±3% at 95% — or an int
+    max_budget_usd=4_000,                # hard stop, metered live
+)
+
+print(run.result())
+#  n=612  success_rate=0.874  ci95=(0.846, 0.898)
+#  failure_clusters: [grasp_slip: 41, perception_miss: 22, collision: 9]
+#  robot_hours=20.4  environment_hours=20.4  cost_usd=3812
+#  artifacts: ground_truth, mcap, report_pdf, video
+```
+
+## Mock mode — runnable today
+
+```bash
+ROBORAMA_MOCK=1 python your_script.py   # or: roborama.Client(mock=True)
+```
+
+Mock mode is deterministic and fixture-shaped: quote math follows the [public rate card](https://roborama.com/pricing), run results are shaped like the canonical runs, `max_budget_usd` hard stops raise `roborama.BudgetExceeded` with an honest `partial_result`, and Wilson intervals are computed exactly as documented. The same code runs unchanged against the hosted API once you have a key.
+
+## The surface
+
+- **Primitives** (module-level, one call per physical question): `roborama.run()`, `roborama.eval()`, `roborama.verify()`, `roborama.matrix()`, `roborama.threshold()`, `roborama.compare()`, `roborama.transfer()` — plus `roborama.quote()` and `roborama.usage()`.
+- **Resources**: `roborama.runs`, `roborama.robots`, `roborama.environments`, `roborama.suites`, `roborama.tasks`, `roborama.kits`, `roborama.streams`, `roborama.keys`, `roborama.budgets`, `roborama.data`, `roborama.calibration`, `roborama.scenarios` — with the `list()`/`get()` shapes you'd expect.
+- **Policies**: `roborama.Policy.container(...)`, `.checkpoint(...)`, `.endpoint(...)` — declared contracts, validated before any motor moves.
+- **Results**: `run.result()` (n, rate, ci95, clusters, both meters), `run.episodes[i]` (video, MCAP, replay spec), `run.watch()` (live), `run.export(format="lerobot")`, `run.report(format="pdf")`.
+- **Errors**: `roborama.RoboramaError` base; every code in [the error reference](https://roborama.com/docs/errors/) maps to a subclass (`budget_exceeded` → `roborama.BudgetExceeded`, carrying `err.partial_result`).
+
+Docs: [quickstart](https://roborama.com/docs/quickstart/) · [primitives](https://roborama.com/docs/primitives/run/) · [errors](https://roborama.com/docs/errors/) · [OpenAPI](https://roborama.com/openapi.json)
+
+## Requirements
+
+Python ≥ 3.9. One dependency: [`httpx`](https://www.python-httpx.org/). Fully typed (`py.typed`).
+
+## License
+
+MIT

roborama_sdk-0.1.0/pyproject.toml

@@ -0,0 +1,48 @@
+[build-system]
+requires = ["hatchling>=1.25"]
+build-backend = "hatchling.build"
+
+[project]
+name = "roborama-sdk"
+version = "0.1.0"
+description = "Official Python SDK for the Roborama API — statistically defensible evaluation of robot policies on physical hardware."
+readme = "README.md"
+requires-python = ">=3.9"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{ name = "Roborama", email = "api@roborama.com" }]
+keywords = ["robotics", "evaluation", "benchmark", "api", "sdk", "robots"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "Intended Audience :: Science/Research",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Scientific/Engineering",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+    "Typing :: Typed",
+]
+dependencies = ["httpx>=0.24"]
+
+[project.urls]
+Homepage = "https://roborama.com"
+Documentation = "https://roborama.com/docs"
+"API Reference" = "https://roborama.com/docs/api-reference"
+OpenAPI = "https://roborama.com/openapi.json"
+
+[dependency-groups]
+dev = ["pytest>=7"]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/roborama"]
+
+[tool.hatch.build.targets.sdist]
+include = ["src/roborama", "README.md", "LICENSE", "pyproject.toml"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

roborama_sdk-0.1.0/src/roborama/__init__.py

@@ -0,0 +1,391 @@
+"""Roborama — real robots as an API.
+
+Statistically defensible evaluation of robot policies on physical hardware.
+Every result carries ``n`` and a confidence interval; everything is
+versioned; the two meters (robot-hour × environment-hour) are visible in
+every quote.
+
+Authentication reads ``ROBORAMA_API_KEY`` from the environment, so it is an
+export, not an argument::
+
+    import roborama  # reads ROBORAMA_API_KEY from the environment
+
+    run = roborama.run(
+        robot="g1-edu-pro@fw2.3",
+        environment="kitchen-std@v1.2",
+        task="pick_place@v1",
+        episodes="auto(ci=0.95, moe=0.03)",
+    )
+    print(run.result())  # n=612  rate=0.874  ci95=(0.846, 0.898)
+
+Hosted execution is in private preview. Set ``ROBORAMA_MOCK=1`` (or use
+``roborama.Client(mock=True)``) to integrate today against a deterministic,
+fixture-shaped mock backend — same surface, same shapes, no hardware.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Dict, List, Optional, Union
+
+from ._client import DEFAULT_BASE_URL
+from ._errors import (
+    ERROR_TYPES,
+    BudgetExceeded,
+    ContractValidationFailed,
+    EnvironmentUnavailable,
+    EpisodesInvalid,
+    EstopTriggered,
+    FirmwarePinUnavailable,
+    InsufficientScope,
+    InvalidAPIKey,
+    MonthlyBudgetExceeded,
+    NotFound,
+    PolicyEndpointTimeout,
+    PublishForbidden,
+    QueueTimeout,
+    QuoteExpired,
+    RateLimited,
+    RetentionExpired,
+    RoboramaError,
+    ScenarioFormatInvalid,
+    TaskUnknown,
+)
+from ._models import (
+    Budget,
+    Environment,
+    Episode,
+    Export,
+    Gate,
+    InstructionRate,
+    Key,
+    Kit,
+    Pilot,
+    Policy,
+    PolicyStream,
+    PurgeReceipt,
+    Quote,
+    Report,
+    Result,
+    Robot,
+    Scenarios,
+    StageRate,
+    Stream,
+    Suite,
+    TransferReport,
+    Usage,
+    WatchEvent,
+)
+from ._resources import (
+    Client,
+    CompareRun,
+    EvalRun,
+    MatrixResult,
+    MatrixRun,
+    Run,
+    Task,
+    ThresholdContract,
+    TransferRun,
+    VerifyRun,
+)
+from ._stats import EpisodesSpec, wilson_ci
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "__version__",
+    # primitives
+    "run",
+    "eval",
+    "verify",
+    "matrix",
+    "threshold",
+    "compare",
+    "transfer",
+    "quote",
+    "usage",
+    "gate",
+    # namespaces
+    "runs",
+    "robots",
+    "environments",
+    "suites",
+    "tasks",
+    "kits",
+    "streams",
+    "keys",
+    "budgets",
+    "data",
+    "calibration",
+    "gates",
+    "scenarios",
+    # building blocks
+    "Policy",
+    "PolicyStream",
+    "Scenarios",
+    "Client",
+    "wilson_ci",
+    "DEFAULT_BASE_URL",
+    # models
+    "Result",
+    "Quote",
+    "Usage",
+    "Budget",
+    "Robot",
+    "Environment",
+    "Suite",
+    "Episode",
+    "Export",
+    "Report",
+    "Gate",
+    "Stream",
+    "Key",
+    "Kit",
+    "Pilot",
+    "PurgeReceipt",
+    "TransferReport",
+    "StageRate",
+    "InstructionRate",
+    "WatchEvent",
+    "EpisodesSpec",
+    # handles
+    "Run",
+    "Task",
+    "CompareRun",
+    "EvalRun",
+    "VerifyRun",
+    "MatrixRun",
+    "MatrixResult",
+    "ThresholdContract",
+    "TransferRun",
+    # errors
+    "RoboramaError",
+    "InvalidAPIKey",
+    "InsufficientScope",
+    "NotFound",
+    "PublishForbidden",
+    "RateLimited",
+    "ContractValidationFailed",
+    "FirmwarePinUnavailable",
+    "EnvironmentUnavailable",
+    "TaskUnknown",
+    "ScenarioFormatInvalid",
+    "EpisodesInvalid",
+    "QuoteExpired",
+    "BudgetExceeded",
+    "MonthlyBudgetExceeded",
+    "QueueTimeout",
+    "PolicyEndpointTimeout",
+    "EstopTriggered",
+    "RetentionExpired",
+    "ERROR_TYPES",
+]
+
+_default_client: Optional[Client] = None
+
+
+def default_client() -> Client:
+    """The lazily created client behind the module-level surface."""
+
+    global _default_client
+    if _default_client is None:
+        _default_client = Client()
+    return _default_client
+
+
+class _NamespaceProxy:
+    """Binds a module-level namespace (``roborama.runs`` …) to the lazy default client."""
+
+    def __init__(self, attr: str) -> None:
+        self._attr = attr
+
+    def __getattr__(self, name: str) -> Any:
+        return getattr(getattr(default_client(), self._attr), name)
+
+    def __repr__(self) -> str:
+        return f"<roborama.{self._attr}>"
+
+
+runs = _NamespaceProxy("runs")
+robots = _NamespaceProxy("robots")
+environments = _NamespaceProxy("environments")
+suites = _NamespaceProxy("suites")
+tasks = _NamespaceProxy("tasks")
+kits = _NamespaceProxy("kits")
+streams = _NamespaceProxy("streams")
+keys = _NamespaceProxy("keys")
+budgets = _NamespaceProxy("budgets")
+data = _NamespaceProxy("data")
+calibration = _NamespaceProxy("calibration")
+gates = _NamespaceProxy("gates")
+scenarios = _NamespaceProxy("scenarios")
+
+
+def run(
+    robot: str,
+    environment: str,
+    task: str,
+    policy: Optional[Union[Policy, Dict[str, Any]]] = None,
+    episodes: EpisodesSpec = "auto(ci=0.95, moe=0.03)",
+    perturbation: Optional[Dict[str, Any]] = None,
+    data: Optional[Dict[str, Any]] = None,
+    priority: Optional[str] = None,
+    max_budget_usd: Optional[float] = None,
+    interventions: Optional[str] = None,
+    **extra: Any,
+) -> Run:
+    """One statistically defensible answer on physical hardware.
+
+    ``episodes`` is a positive int or ``auto(ci=..., moe=...)``, which sizes
+    n for a target margin of error. ``max_budget_usd`` is a hard stop,
+    metered live.
+    """
+
+    return default_client().run(
+        robot=robot,
+        environment=environment,
+        task=task,
+        policy=policy,
+        episodes=episodes,
+        perturbation=perturbation,
+        data=data,
+        priority=priority,
+        max_budget_usd=max_budget_usd,
+        interventions=interventions,
+        **extra,
+    )
+
+
+def eval(  # noqa: A001 - documented public name
+    policy: Union[Policy, Dict[str, Any]],
+    suite: str,
+    robots: List[str],
+    publish: str = "private",
+    **extra: Any,
+) -> EvalRun:
+    """Run a frozen, versioned suite; returns a citable attestation."""
+
+    return default_client().eval(
+        policy=policy, suite=suite, robots=robots, publish=publish, **extra
+    )
+
+
+def verify(
+    policy: Union[Policy, Dict[str, Any]],
+    scenarios: Union[Scenarios, Dict[str, Any]],
+    robots: List[str],
+    task: Optional[str] = None,
+    audit_sample: Optional[float] = None,
+    return_ground_truth: Optional[bool] = None,
+    **extra: Any,
+) -> VerifyRun:
+    """Physically verify the scenarios your simulator flagged."""
+
+    return default_client().verify(
+        policy=policy,
+        scenarios=scenarios,
+        robots=robots,
+        task=task,
+        audit_sample=audit_sample,
+        return_ground_truth=return_ground_truth,
+        **extra,
+    )
+
+
+def matrix(
+    policy: Union[Policy, Dict[str, Any]],
+    robots: List[str],
+    environments: List[str],
+    task: str,
+    episodes_per_cell: EpisodesSpec = "auto(ci=0.95, moe=0.05)",
+    interventions: Optional[str] = None,
+    **extra: Any,
+) -> MatrixRun:
+    """The embodiment × environment sweep behind a cross-embodiment claim."""
+
+    return default_client().matrix(
+        policy=policy,
+        robots=robots,
+        environments=environments,
+        task=task,
+        episodes_per_cell=episodes_per_cell,
+        interventions=interventions,
+        **extra,
+    )
+
+
+def threshold(
+    policy_stream: Union[PolicyStream, Dict[str, Any]],
+    target: Dict[str, Any],
+    iterate_on: str,
+    escalate_to: str,
+    monthly_cap_usd: Optional[float] = None,
+    **extra: Any,
+) -> ThresholdContract:
+    """An outcome contract: push checkpoints, receive physical verdicts."""
+
+    return default_client().threshold(
+        policy_stream=policy_stream,
+        target=target,
+        iterate_on=iterate_on,
+        escalate_to=escalate_to,
+        monthly_cap_usd=monthly_cap_usd,
+        **extra,
+    )
+
+
+def compare(
+    policies: Dict[str, Union[Policy, Dict[str, Any]]],
+    robot: str,
+    task: str,
+    paired: bool = True,
+    **extra: Any,
+) -> CompareRun:
+    """Paired A/B on the same initial conditions — halves the n you need."""
+
+    return default_client().compare(
+        policies=policies, robot=robot, task=task, paired=paired, **extra
+    )
+
+
+def transfer(
+    policy: Union[Policy, Dict[str, Any]],
+    source: str,
+    target: str,
+    task: str,
+    **extra: Any,
+) -> TransferRun:
+    """Quantify the embodiment transfer gap, source vs. target."""
+
+    return default_client().transfer(
+        policy=policy, source=source, target=target, task=task, **extra
+    )
+
+
+def quote(
+    robot: str,
+    environment: str,
+    episodes: EpisodesSpec,
+    priority: Optional[str] = None,
+) -> Quote:
+    """Both meters, dollars, and a queue ETA — before you commit."""
+
+    return default_client().quote(
+        robot=robot, environment=environment, episodes=episodes, priority=priority
+    )
+
+
+def usage(period: Optional[str] = None) -> Usage:
+    """Metered usage for a period (``YYYY-MM``): hours by tier, dollars, budget."""
+
+    return default_client().usage(period=period)
+
+
+def gate(
+    on: str,
+    suite: str,
+    robots: List[str],
+    fail_if: Dict[str, Any],
+) -> Gate:
+    """Register a CI gate: run the suite on matching refs, fail on regression."""
+
+    return default_client().gate(on=on, suite=suite, robots=robots, fail_if=fail_if)