Metadata-Version: 2.4
Name: realbench-robotics
Version: 0.2.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
Requires-Dist: mujoco>=3.0
Provides-Extra: dev
Requires-Dist: pytest; extra == "dev"
Requires-Dist: httpx; extra == "dev"
Provides-Extra: ros2
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
```

The import package and CLI remain `realbench`. `pip install realbench-robotics[ros2]` does not install `rclpy`; that comes from your ROS2 distro.

## 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:

```bash
realbench check --urdf robot.urdf --source ros2 \
  --ros2-topic /joint_states \
  --diagnostics-topic /diagnostics \
  --controller-manager /controller_manager
```

Run `realbench doctor --urdf robot.urdf --source ros2` first if anything is missing.

`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 --urdf robot.urdf --source ros2
realbench capture-home --urdf robot.urdf --source ros2 --repo .
realbench check --urdf robot.urdf --source ros2 \
  --diagnostics-topic /diagnostics \
  --controller-manager /controller_manager
```

`--urdf` accepts a URDF or MJCF file. `analyze` needs only the model. `doctor` diagnoses setup and never produces a readiness verdict. `capture-home` writes `<repo>/.realbench/home.json`. `check` and `cycle` look for that file when `--home` is omitted.

## Serve

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

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. 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.

## 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`. There is no separate
`runs.db` on the serve path.

```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.

## 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 --urdf robot.urdf --source ros2 --diagnostics-topic /diagnostics --controller-manager /controller_manager || { 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.
- Sensor and firmware checks are not implemented.
- The ROS2 path is validated against a Dockerised Jazzy node, not physical hardware.
