Metadata-Version: 2.4
Name: robotbase-kit
Version: 0.3.0
Summary: The batteries-included developer-experience layer for agent-driven robotics.
Author-email: Tom Newton <tominator172@gmail.com>
License-Expression: MIT
Project-URL: Homepage, https://github.com/tomnewtoneng/robotbase
Project-URL: Repository, https://github.com/tomnewtoneng/robotbase
Project-URL: Issues, https://github.com/tomnewtoneng/robotbase/issues
Keywords: robotics,ros2,gazebo,simulation,mcp,agents,declarative,testing
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Operating System :: POSIX :: Linux
Classifier: Topic :: Scientific/Engineering
Classifier: Topic :: Software Development :: Testing
Requires-Python: >=3.12
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: pydantic>=2.6
Requires-Dist: pyyaml>=6.0
Requires-Dist: mcp<2,>=1.2
Requires-Dist: mcap>=1.0
Provides-Extra: dev
Requires-Dist: pytest>=8.0; extra == "dev"
Provides-Extra: sim-mujoco
Requires-Dist: mujoco>=3.0; extra == "sim-mujoco"
Provides-Extra: sim-rl
Requires-Dist: mujoco>=3.0; extra == "sim-rl"
Requires-Dist: gymnasium>=1.0; extra == "sim-rl"
Provides-Extra: bench-agent
Requires-Dist: claude-agent-sdk>=0.2; extra == "bench-agent"
Provides-Extra: studio
Requires-Dist: fastapi>=0.110; extra == "studio"
Requires-Dist: uvicorn>=0.27; extra == "studio"
Requires-Dist: jinja2>=3.1; extra == "studio"
Dynamic: license-file

![robotbase — describe your robot, world, and scenarios in YAML; compile to a running headless ROS 2 + Gazebo sim; get pass/fail evidence.](https://raw.githubusercontent.com/tomnewtoneng/robotbase/main/assets/robotbase-header.png)

**Declarative robotics.** Describe a robot, its sensors, its world, and the behaviours you want to
verify in YAML — Robotbase compiles that into a running, **headless** ROS 2 + Gazebo simulation and
gives you machine-readable evidence. Local-first and open-core: no cloud, no accounts in the core.

## What it is

Robotbase is the *layer over ROS 2*, not a replacement for it — think Terraform over cloud APIs.
What your YAML compiles down to is a **real, standard ROS 2 graph** (nodes, topics, TF,
`ros2_control`) running on top of Gazebo; Robotbase just means you stop hand-writing the URDF, launch
files, and bridges. Because the runtime is genuine ROS 2, a passing scenario means something, and you
can drop in your own ROS 2 code — or, later, a real robot — underneath the same specs.

It's all YAML: `robot.yaml` (the robot + its sensors), `world.yaml` (the world), and one or more
**scenario** files under `simulation/scenarios/*.yaml`. A scenario is the test — its `assertions:`
block declares what "working" means:

```yaml
# simulation/scenarios/drive-forward.yaml
assertions:
  - {type: robot_moved_minimum_distance, minimum_distance_metres: 1.0}
  - {type: required_topic_messages, topic: /scan, minimum_count: 5}
```

Robotbase compiles all of it into a complete ROS 2 + Gazebo project (URDF, world SDF, launch,
ROS↔gz bridges, control config) and runs it headless in Docker. You never hand-write the XML —
the way you never click through a cloud console with Terraform.

## How it works

```text
edit robot.yaml / world.yaml / a scenario  →  robotbase up  →  robotbase test
                       ▲                                              │
                       └────────── read the structured result / episode ──────────┘
```

**Prerequisites:** Linux with Docker and Python **3.12** (Python 3.11 and below can't install it).
**On Windows or macOS, use WSL2 Ubuntu 24.04 + Docker Desktop** — that's the supported path. The
runtime is ROS 2 Jazzy + Gazebo Harmonic in Docker.

```bash
pip install robotbase-kit

robotbase create my-bot        # scaffold a project (differential-drive by default)
cd my-bot
robotbase up                   # start the container + build (first run builds the image)
robotbase test drive-forward   # run a scenario; prints a structured pass/fail result
```

Every run is an objective result (metrics + assertions) plus a recorded **MCAP episode**
(Foxglove/Rerun-openable). Every action is a verb with a structured result, so a human and a coding
agent drive it the same way.

### Build your own robot and world

The scaffold is only a starting point — the robot, its sensors, the world, and the tests are all
yours to edit. Author declaratively and let the tool keep you honest:

```bash
robotbase schema      # the full robot.yaml / world.yaml / scenario authoring reference
# …edit robot.yaml and world.yaml…
robotbase validate    # static physics checks (mass, inertia, joint limits) before you launch
robotbase explain     # which links / joints / topics each line of your spec produced
robotbase describe    # structured ground truth for the robot, world, and scenarios
robotbase up          # recompile the specs, (re)build, and run
```

Define what "working" means as scenarios — each is a `simulation/scenarios/*.yaml` whose
`assertions:` block *is* the test:

```bash
robotbase scenario add reach-the-shelf
robotbase test reach-the-shelf
```

### Bring your own policy

Instead of a ROS controller, you can drive a scenario with a plain Python policy — ideal for
evaluating a trained one. Write a `Policy` with `act(obs) -> action` (`robotbase policy new`
scaffolds it), point a scenario at it with `{type: run_policy, module: policy}`, and get the same
objective evidence. `robotbase describe` reports the exact observation/action keys for your robot.

### Statistical evaluation

`robotbase eval <scenario> --trials N` runs a scenario over N randomized trials and reports a
**success-rate with a 95% confidence interval** (Wilson score) plus per-metric distributions —
persisted as a shareable `report.json` + `report.md`. It evaluates a ROS controller or a brought
policy identically. When a scenario isn't randomized it says so instead of printing a meaningless
interval.

### Studio (a local control panel)

`pip install robotbase-kit[studio]` then `robotbase studio` opens a localhost web app: see your
robot, world, and scenarios; run a scenario or an eval and watch it live; open the 3D in Foxglove;
and read the structured results and eval reports — all a thin client over the same CLI/runtime.

### Start from a template or an existing URDF

```bash
robotbase templates                                # list the built-in templates
robotbase create my-arm --template arm             # differential-drive | camera-bot | arm | drone
robotbase create my-bot --from-urdf my_robot.urdf  # import an existing URDF verbatim
```

Each `create` gives you a minimal, working robot that passes one smoke-test scenario — a starting
point to build on. Want worked, unsolved challenges to practise on (or to test a coding agent)? See
[`examples/challenges/`](examples/challenges/).

## The knowledge layer (built for agents)

Robotbase is meant to be *operated by a coding agent*, so the tool teaches the agent how to use it —
there are no external docs to keep in sync.

- **One surface, CLI + MCP.** The full `robotbase` CLI is mirrored by a **19-tool MCP server**
  (`describe`, `explain`, `validate`, `build`, `test`, `diagnose`, `episode …`). A human types the
  commands; an agent calls the tools — same verbs, same structured results.
- **A built-in authoring reference.** `robotbase schema` (and the `authoring_schema` MCP tool)
  returns the full `robot.yaml` / `world.yaml` / scenario format — every field, the sensor/archetype
  vocabulary, the **assertion types**, and the common mistakes — as prose or JSON Schema. It's
  generated from the code, so it can't drift from what the compiler actually accepts.
- **Ground truth, not files to parse.** `describe` / `explain` / `validate` and the `episode` query
  verbs hand back structured facts about the compiled robot, world, topics, and recorded runs.
- **Every project is agent-ready.** `robotbase create` drops an `AGENTS.md` (project-specific
  instructions) and a `.mcp.json` into the new project.

**Setup for the MCP server: none** beyond `pip install robotbase-kit` — it ships in the core install. An
MCP-aware agent (e.g. Claude Code) opened in a project picks up the bundled `.mcp.json`
automatically. To run it by hand:

```bash
ROBOTBASE_PROJECT_DIR=. python -m robotbase.mcp_server   # stdio; ROBOTBASE_GUI=foxglove to watch runs
```

## Why it exists

Standing up ROS 2 + Gazebo by hand is a tax paid in opaque C++ tracebacks and terminal scraping —
and it's especially brutal for a coding agent. Robotbase removes it and replaces it with what agents
are good at:

- **Declarative, not fiddly.** A few lines of YAML; the compiler owns every sim gotcha (collision
  lumping, bridge wiring, inertia, control config) and, when the spec is wrong, returns an error that
  *names the field* instead of a crash.
- **Structured state, not log-scraping.** `describe` / `explain` / `validate` and the episode query
  verbs hand back ground truth, not console output to parse.
- **Evidence, not vibes.** A scenario is an objective pass/fail; you can't *claim* a robot works and
  be believed — you make the assertions pass. That closes the gap the project exists to close:
  **a coding agent can write robot code; on its own it can't tell whether the robot actually works.**

*Benchmark data — coding agents with vs. without Robotbase — coming soon.*

## Status

**Alpha, proven end-to-end.** The full local loop works — create → author the specs → build →
run → read the evidence — across four robot templates (differential-drive, camera-bot, arm, drone),
a growing scenario/assertion/metric vocabulary, MCAP episode recording + query, auto-diagnosis, a
domain-randomized eval layer, bring-your-own-policy evaluation (drive a scenario with a Python
policy via `run_policy`), and a proven sim-agnostic runner (Gazebo + an in-process MuJoCo backend).
Local-first, MIT-licensed.

## License

MIT — see [LICENSE](LICENSE).
