openbot-sdk

openbot-sdk is the thin Python client for the OpenBot.ai platform API.

It handles API-key authentication, HTTP requests, timeouts, bounded retries, and typed errors. It does not process robot data and is not tied to a Hosted Data product.

Install

pip install openbot-sdk

Requires Python 3.9+.

Authentication

export OPENBOT_API_KEY="ob_..."

from openbot_sdk import Client

client = Client()  # reads OPENBOT_API_KEY
status = client.request("GET", "/status")
print(status)

You can also pass the key explicitly:

client = Client(api_key="ob_...")

Ego Semantic Annotation (0.2.0 candidate)

The first convenience wrapper creates an asynchronous, feature-gated annotation job. It requires a stable idempotency key because transport retries must not reserve credits or enqueue work twice:

job = client.create_ego_semantic_annotation(
    source_url="https://storage.example/episode-001.mp4",
    source_sha256="...64 hex characters...",
    duration_seconds=84,
    idempotency_key="episode-001-annotation-v1",
    context="prepare a cup of coffee",
    labels=[{"key": "reach"}, {"key": "grasp"}],
)

job = client.get_ego_semantic_annotation(job["id"])
if job["status"] == "completed":
    result = client.get_ego_semantic_annotation_result(job["id"])

The active API must expose the operation and the workspace must be in the internal canary. An unavailable gate is a real API error, not a local fallback.

Call platform APIs

Use request for JSON APIs and request_bytes for byte responses:

payload = client.request(
    "POST",
    "/some-resource",
    json={"name": "example"},
    headers={"Idempotency-Key": "request-123"},
)

content = client.request_bytes("GET", "/some-artifact")

Only call routes published in the current OpenBot OpenAPI document. As the platform adds real APIs, the SDK may add small convenience wrappers for those same contracts.

The SDK intentionally has no Bench, Synth, or Hosted Data resource wrapper. Convenience wrappers correspond to operations in the checked OpenAPI contract; request(...) remains the forward-compatible escape hatch.

Errors, retries, and security

from openbot_sdk import APIError, NetworkError

try:
    payload = client.request("GET", "/status")
except APIError as exc:
    print(exc.status_code)
except NetworkError as exc:
    print(exc)

The client retries idempotent methods and mutations carrying an Idempotency-Key on transport errors, 429, and transient 5xx responses. Plain HTTP base URLs are rejected by default; enable them only for explicit local testing.

Development

pip install -e ".[dev]"
python scripts/check_version.py
python scripts/check_openapi_contract.py /path/to/openapi.json
pytest -v
ruff check src tests
mypy src
python -m build

VERSION is the package version source of truth. Release tags use v<version>.

Package boundaries

• openbot-sdk: OpenBot platform API client.
• openbot-data: local robot/ego data processing library.
• OpenBot platform: server-side API implementation and infrastructure.

License

MIT