62 lines
3.4 KiB
Markdown
62 lines
3.4 KiB
Markdown
# Research bundle schema v1
|
|
|
|
An export is an immutable directory:
|
|
|
|
```text
|
|
policy.onnx deterministic actor, with trained observation normalization
|
|
contract.json observation/action ordering, affine transforms, simulation PD settings
|
|
reference.json one raw observation and its expected unclipped policy action
|
|
evaluation.json fixed-protocol rollout evidence bound to the checkpoint/source hashes
|
|
experiment.json original experiment
|
|
agent.json runner architecture/configuration
|
|
provenance.json source/assets/runtime versions and hashes
|
|
manifest.json SHA-256 of every payload file, checkpoint hash, ONNX parity results
|
|
```
|
|
|
|
The bundle contains no robot meshes, checkpoint pickle, board executable or motor transport.
|
|
It is portable for **CPU ONNX inference**, not a self-contained simulation environment. Replay
|
|
still needs the recorded task code, asset checkout and compatible mjlab environment.
|
|
|
|
## Consumer contract
|
|
|
|
`PolicyRuntime(Path(bundle)).predict(observation)` accepts a finite float32 `[1, observation_size]`
|
|
array. Observation terms must be concatenated in the exact `start:stop` order. Read each term's
|
|
function identity in `contract.json`; implementation semantics are in the recorded sources.
|
|
|
|
For current flat tasks, terms are base linear/angular velocity from the configured IMU sensors,
|
|
projected gravity, joint position relative to default, joint velocity relative to default,
|
|
previous clipped raw action, and `(vx, vy, yaw_rate)` commands. Sensor frame/site and filtering
|
|
matter; a base estimator cannot be substituted without validating parity. Joint observation
|
|
ordering is explicitly separate from action ordering. Units are SI; angles in radians.
|
|
|
|
Normalization is inside ONNX. Do **not** normalize twice. On reset, previous action is zero.
|
|
During inference:
|
|
|
|
```text
|
|
raw_action = policy(observation)
|
|
clipped_action = clip(raw_action, -raw_clip, raw_clip)
|
|
joint_target_rad = offset + scale * clipped_action
|
|
```
|
|
|
|
The consumer returns all three arrays and does not send them anywhere. Host PD/control frequency
|
|
must match the recorded policy/physics timestep semantics. Simulation gain and torque data are
|
|
metadata, not a certified motor configuration. Joint-limit clamping is not silently added to
|
|
inference because it would change training semantics; a physical safety controller must be
|
|
separately designed, validated and may refuse the policy.
|
|
|
|
## Export checks and limits
|
|
|
|
Export requires a completed local run and matching evaluation report. It tests ONNX checker
|
|
validity and action parity at 16 actual rollout observations (`atol=1e-5`, `rtol=1e-4`), then
|
|
writes file hashes. `verify-bundle --inference` checks integrity and one saved reference.
|
|
|
|
This detects common swapped-joint/normalizer/version mistakes, but is not a complete behavioral
|
|
proof. The current exporter requires MLP, one joint-position action group, no per-joint action
|
|
clip, one position actuator per joint and batch size one. It does not generate a robot driver.
|
|
|
|
A report can show poor tracking and many falls and still be packaged for research. All bundles
|
|
are `hardware_approved: false`. There is no release-quality gate or hardware approval command.
|
|
Before physical deployment, implement and validate bus index mapping, estimator/calibration,
|
|
IMU frame, latency, torque/position bounds, thermal limits, watchdog, controlled startup/shutdown,
|
|
E-stop and supervised sim-to-real tests. Require explicit operator authorization for actual motion.
|