Metadata-Version: 2.4
Name: realbench-robotics
Version: 0.2.5
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
Requires-Dist: mujoco>=3.0
Provides-Extra: dev
Requires-Dist: pytest; extra == "dev"
Requires-Dist: httpx; extra == "dev"
Provides-Extra: ros2
Provides-Extra: lerobot
Dynamic: license-file

# RealBench

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

## Install

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

Needs Python 3.10 or newer (`python3 --version`). The import package and CLI remain `realbench`. `pip install realbench-robotics[ros2]` does not install `rclpy`; that comes from your ROS2 distro.

Run `realbench` in the same shell where you sourced `/opt/ros/<distro>/setup.bash`. Match `ROS_DOMAIN_ID` to the robot.

## ROS2 warning

A positions-only ROS2 connection **cannot reach READY**. Faults and actuator state stay unverifiable, and the run quarantines by design.

This is the command that can reach READY once the graph infers diagnostics and the controller manager (or you pass them):

```bash
realbench check --source ros2
```

Run `realbench doctor --source ros2` first if anything is missing. Pass `--urdf` only when there is no latched `*/robot_description` on the graph.

`realbench check --source ros2` with no sensors or nodes declared exits 3
(usage error) and does not print a readiness verdict. Open the Components
tab and save, or run `realbench capture-components`.

## Quickstart

```bash
realbench analyze --urdf robot.urdf
realbench doctor --source ros2
realbench capture-home --source ros2 --repo .
realbench check --source ros2
```

`--urdf` accepts a URDF or MJCF file and is optional on `doctor`/`check`/`serve` when `*/robot_description` is latched. `analyze` needs only the model. `doctor` diagnoses setup and never produces a readiness verdict. `capture-home` writes `<repo>/.realbench/home.json` when the robot has a home pose. Continuous-joint robots skip home. `check` and `cycle` look for that file when `--home` is omitted.

## Serve

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

`cd` first to the directory where `.realbench/` should be written. It prints `ROS_DOMAIN_ID=<n>` and a URL. The default bind is `127.0.0.1` (this machine only); `--host 0.0.0.0` is required to open the URL from a laptop. The printed address may not be the one your laptop can route to — use the robot's LAN IP and port.

No `--urdf`. The model is read from the latched `*/robot_description` topic
(TRANSIENT_LOCAL `std_msgs/String`). Joint states, diagnostics, and
controller manager are inferred from the graph, including namespaced
paths such as `/JK3/platform/joint_states`. Continuous-joint robots skip
home pose.

Until at least one sensor or node is declared, the stored verdict is
**SETUP INCOMPLETE**, not QUARANTINE. The Components tab pre-ticks
discoverable sensors and nodes so save is one click. Wait a few seconds
after save for the next evaluation. Saving a LaserScan
or Imu also writes a default `value_field` and plausible range so those
checks evaluate (PASS or FAIL), not NOT_APPLICABLE.

A failing diagnostic, sensor, or node can be marked a known issue with a
required note. Acknowledged rows stay recorded and visible; they do not
drive `classify()` until the reason string changes.

Host wall-clock is stored next to robot time. If they disagree by more
than 5 seconds, `check_clock_sane` fails at HEALTH and the UI shows both
clocks.

`check_state_stream_fresh` uses 3× the observed `joint_states` period and
3× the recorder sample interval, floored at 2.0s.

Recording continues if you close the browser tab. Ctrl-C stops serve.
Recording is saved in `.realbench/records.db`. Nothing is lost. To hand it over, run `realbench export`.

## Export

Do not copy `.realbench/` while serve is running. The recording database
is WAL-mode; a folder copy drops the `-wal` file.

History lives in `<repo>/.realbench/records.db` (serve recorder). One-shot
`/api/check` History also writes `runs.db`; `realbench export` includes it
as `<stem>-runs.db` when present. Settings in the UI has the same Export
recording button.

```bash
realbench export
realbench export --out capture.db --repo .
```

SQLite's backup API writes one consistent file, prints path and size, and
only reports success if `integrity_check` passes. Safe while serve is up.
Open the `.db` in DB Browser for SQLite (or sqlite3).

## Exit codes

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

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

## CI

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

## Read-only

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

## Known limits

- Reset execution is stubbed.
- Plausible-but-varying sensor nonsense is not caught; frozen and stopped sensors are.
- The ROS2 path is validated against a Dockerised Humble Jackal, not physical hardware.
