BotManifold SDK

Official Python SDK and CLI for BotManifold: verify robot policies in simulation, manage datasets and training jobs, and run the teleop bridge for real arms.

Installation

pip install botmanifold

Optional extras:

pip install "botmanifold[bridge]"

The bridge extra pulls in lerobot and its dependencies (torch, opencv-python-headless, ...). The base install is a lightweight API client; verify users never pay for it.

Quick start

from botmanifold import BotManifoldClient

client = BotManifoldClient(api_key="bm_...")

report = client.verify.run("my_policy.zip", scenario="messy_room")
print(report.verdict)   # Verdict.SAFE, Verdict.UNSAFE or Verdict.ERROR
print(report.score)

CLI

botmanifold --help

# Verify a policy (a ZIP, or a running policy server)
botmanifold verify my_policy.zip --scenario messy_room
botmanifold verify --url http://localhost:8765 --scenario messy_room

# Local development
botmanifold serve my_policy.py --port 8765          # serve a policy over HTTP
botmanifold mock-server episode.jsonl --port 8765   # replay recorded episodes

# Datasets and scenarios
botmanifold datasets list
botmanifold datasets quality <dataset_id>
botmanifold datasets episodes <dataset_id>
botmanifold scenario validate <scenario>

# Managed training jobs
botmanifold train submit ...
botmanifold train status <job_id>      # also: list, logs, cancel, set-provider

# Teleop bridge for real arms (needs the `bridge` extra)
botmanifold bridge serve ...           # also: teleop, upload, sessions, robots, pair, resume,
                                       # jog, control-take, confirm-calibration,
                                       # confirm-diagnostics, confirm-leader-web

Run any command with --help for its options.

Async usage

import asyncio
from botmanifold import AsyncBotManifoldClient

async def main() -> None:
    async with AsyncBotManifoldClient(api_key="bm_...") as client:
        report = await client.verify.run("my_policy.zip", scenario="messy_room")
        print(report.verdict)

asyncio.run(main())

API reference

Client

client = BotManifoldClient(
    api_key="...",      # or set BOTMANIFOLD_API_KEY
    base_url="...",     # optional, defaults to production; or BOTMANIFOLD_API_URL
    timeout=30,         # request timeout in seconds
)

The client exposes verify, training and pipeline.

client.verify

# Verify a policy file and wait for the result
report = client.verify.run(policy="policy.zip", scenario="messy_room", num_episodes=5, timeout=300)

# Or verify a running policy server
report = client.verify.run(policy_url="http://localhost:8765", scenario="messy_room")

if report.is_safe:
    print("Policy is safe")

# Non-blocking
report = client.verify.run("policy.zip", scenario="messy_room", wait=False)
final = client.verify.wait(report.job_id)

# Poll an existing job
status = client.verify.status(job_id)

client.training

Training runs, checkpoints and managed jobs: list_runs, get_run, list_checkpoints, get_convergence_status, submit_job, get_job, list_jobs, cancel_job, get_job_logs, set_gpu_provider, and the reporting calls report_metrics, report_gpu, register_checkpoint. Reporting needs BOTMANIFOLD_TRAINING_API_KEY. The Training Monitor service these talk to is not deployed in staging or production.

client.pipeline

Dataset management: list_datasets, get_dataset_quality, list_episodes, exclude_episodes.

Hardware

bundles = client.get("/api/hardware/bundles")
for b in bundles["bundles"]:
    print(f"{b['name']} - ${b['price_cents'] / 100:,.2f}")

See examples/hardware_quickstart.py.

Teleop bridge

botmanifold.bridge is the local agent that drives an arm (SO-100, myCobot 280), records demonstration episodes as LeRobot datasets, uploads them, and talks to the Studio Teleop panel over WebSocket (directly or through services/teleop_relay). It also hosts the myCobot diagnostics checks. The setup guides are in docs/guides/.

Environment variables

Development

# From the repository root (a plain `uv sync` removes this package)
uv sync --all-packages --all-groups --all-extras

uv run pytest sdk/python/tests -q
uv run ruff check sdk/python/botmanifold

License

Proprietary - see LICENSE file.