Metadata-Version: 2.4
Name: realbench-robotics
Version: 0.1.1
Summary: Fail-closed robot readiness checks for integration-test reset cycles
Author-email: Raghavan Madabushi <raghavanmadabushi10@gmail.com>
License-Expression: MIT
Project-URL: Homepage, https://pypi.org/project/realbench-robotics/
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Topic :: Scientific/Engineering
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: yourdfpy>=0.0.56
Requires-Dist: numpy>=1.24
Requires-Dist: rich>=13
Requires-Dist: typer>=0.12
Requires-Dist: fastapi>=0.110
Requires-Dist: uvicorn[standard]>=0.27
Requires-Dist: python-multipart>=0.0.9
Requires-Dist: defusedxml>=0.7.1
Provides-Extra: dev
Requires-Dist: pytest; extra == "dev"
Requires-Dist: httpx; extra == "dev"
Provides-Extra: mjcf
Requires-Dist: mujoco; extra == "mjcf"
Provides-Extra: ros2
Provides-Extra: ros1
Dynamic: license-file

# RealBench

Fail-closed readiness checks that answer one question: **is this robot verifiably
ready for the next run?**

Every check returns PASS, FAIL, UNVERIFIABLE, or NOT_APPLICABLE — and
UNVERIFIABLE never yields READY. If RealBench cannot see something, it says so
instead of assuming the best. That is what makes it safe to gate a run on.

Read-only. It never commands motion, never writes firmware, never modifies your
robot.

## Install

```bash
pip install realbench-robotics
```

Install into the same Python that can already import `rclpy` — normally the
system Python you use for ROS. A virtualenv must be created with
`--system-site-packages`, or RealBench installs fine and then reports
"ROS 2 not found".

## Run

With your ROS 2 environment sourced and the robot stack up:

```bash
realbench serve --source ros2 --host 0.0.0.0 --no-browser
```

It prints a URL. Open it from any machine on the network.

**No configuration.** RealBench reads your robot model from
`/robot_description`, and infers your joint states, diagnostics and controller
manager from the ROS graph. Namespaced robots are handled — a ClearPath robot
under `/JK3` resolves `/JK3/platform/joint_states` and `/JK3/diagnostics` on its
own. No files, no flags, no config.

In the browser, open **Components**, tick the sensors and nodes you care about,
and save. That is the only setup step. After that it records continuously,
whether or not the page is open.

## What it catches

- A sensor or node that **stops** mid-run — named, with the second it happened
- A sensor that is alive but **frozen** — still publishing, identical payload
- A joint that **disappears** from `/joint_states`
- **Loss of contact** with the robot, with history preserved on screen

The important one: **the record survives the restart that fixes it.** A fault
that heals itself on reboot still leaves a timestamped trace.

## What it does not catch

- **Anything at boot.** RealBench needs the ROS graph to exist before it can see
  anything. If DDS never comes up, it is blind by the same mechanism that broke
  the robot.
- **A sensor publishing plausible-looking nonsense.** It catches stopped and
  frozen, not wrong-but-varying.
- **Pose, on robots with only continuous joints.** A differential-drive base has
  no home pose to verify, so both pose checks correctly report not-applicable.

## CLI

```bash
realbench doctor  --source ros2      # diagnose setup; never returns a verdict
realbench check   --source ros2      # one readiness verdict, then exit
realbench analyze --urdf robot.urdf  # inspect a model, no robot needed
```

`--urdf` accepts URDF or MJCF. Pass `--urdf` to `check` only if your robot does
not publish `/robot_description`.

## Exit codes

| Code | Meaning |
|------|---------|
| 0 | READY |
| 1 | NOT_READY_RECOVERABLE (pose can be reset) |
| 2 | QUARANTINE (liveness or health failed, or was unverifiable) |
| 3 | Could not run (missing model, home, or source) |

`doctor` uses 0 (no blocking setup problems), 1 (problems that would block a
useful verdict), and 3 (could not run).

## Gating a test run

```bash
realbench check --source ros2 || { echo "robot not ready, aborting"; exit 1; }
```

## Requirements

Python 3.10+, ROS 2 (validated on Humble). `rclpy` comes from your ROS
installation, not from pip.

## Status and known limits

Early. Honest about it:

- Validated against a Dockerised ROS 2 Humble robot, **not physical hardware**.
  First real-robot pilots are in progress.
- Reset execution is stubbed. RealBench reports readiness; it does not yet
  restore it.
- **ROS 1 support is experimental.** `--source ros1` exists and is unit-tested,
  but has not yet been validated against a live ROS 1 master. Treat it as a
  preview. Note that ROS 1 Noetic reached end-of-life in May 2025.

If RealBench flags something while your robot is genuinely healthy, that is the
bug I most want to hear about — a false alarm is worse than a miss.

## License

MIT
