HANDOFF.md

> **30k candidate:** default checkpoint is
> `checkpoints/29999`. L40 and physical-robot acceptance
> are still pending. Do not publish or treat as frozen.

# StreamPI Piper-X Real6 Deployment Handoff

## 1. Release identity

| Item | Value |
|---|---|
| Release | `StreamPI-PiperX-Real6` |
| Configuration | `pi05_stream3_piper_x_real_6tasks` |
| Checkpoint | `checkpoints/20000` |
| Dataset asset | `real_piper_x_6tasks` |
| Model | StreamPI based on π0.5 |
| History horizon | 3 observations |
| History interval | 5 dataset frames |
| Prediction horizon | 10 actions |
| Execution length | 5 actions per inference |
| State dimension | 14 |
| Action dimension | 14 |

State and action order:

```text
left_joint_1 ... left_joint_6,
left_gripper,
right_joint_1 ... right_joint_6,
right_gripper
```

Camera order:

```text
cam_high
cam_left_wrist
cam_right_wrist
```

## 2. Action semantics

Training uses delta actions for the 12 arm joints.

The 14-dimensional action layout is:

```text
6 left-arm joints,
1 left gripper,
6 right-arm joints,
1 right gripper
```

The arm-joint dimensions use delta-action training semantics. The two gripper
dimensions remain absolute gripper commands.

During inference, `AbsoluteActions` converts the arm-joint predictions back to
absolute joint positions. The policy server therefore returns:

```ini
action_type=absolute_joint_position
```

The robot client must not apply an additional delta-to-absolute conversion.

## 3. Environment installation

Install the server environment:

```bash
cd /path/to/StreamPI-PiperX-Real6
bash scripts/setup_server_env.sh
```

Optionally install an independent client environment:

```bash
cd /path/to/StreamPI-PiperX-Real6
bash scripts/setup_client_env.sh
```

An existing compatible Python interpreter may instead be selected explicitly:

```bash
export OPENPI_PYTHON=/path/to/python
```

## 4. Release verification

```bash
cd /path/to/StreamPI-PiperX-Real6

export OPENPI_PYTHON=/path/to/python
bash scripts/verify_release.sh
```

Expected final markers include:

```text
CHECKPOINT_STRUCTURE_OK
CONFIG_REGISTRATION_OK
DELTA_TO_ABSOLUTE_TRANSFORM_OK
SERVER_CLIENT_PROTOCOL_OK
RELEASE_VERIFY_OK
```

## 5. Synthetic loopback test

The loopback test starts a local policy server and sends synthetic camera
images and robot states. It does not connect to robot hardware.

```bash
cd /path/to/StreamPI-PiperX-Real6

export OPENPI_PYTHON=/path/to/python
export LOOPBACK_GPU=0
export LOOPBACK_PORT=18080
export LOOPBACK_MAX_LATENCY_SECONDS=2.0

bash scripts/test_loopback.sh
```

Expected markers:

```text
POLICY_WARMUP_OK
SMOKE_CLIENT_OK
LOOPBACK_TEST_OK
```

The script should stop its policy-server subprocess automatically when it
exits.

## 6. Start the deployment server

```bash
cd /path/to/StreamPI-PiperX-Real6

export OPENPI_PYTHON=/path/to/python
export POLICY_GPU=0
export POLICY_HOST=0.0.0.0
export POLICY_PORT=8000

bash scripts/start_policy_server.sh
```

WebSocket endpoint:

```text
ws://SERVER_IP:8000
```

Only one robot/policy session should use each server process.

## 7. Warm-up before connecting hardware

The first inference calls for history lengths 1, 2 and 3 may trigger separate
JAX compilation. Complete all warm-up requests before enabling robot torque.

With the policy server already running:

```bash
cd /path/to/StreamPI-PiperX-Real6

export OPENPI_PYTHON=/path/to/python
export POLICY_HOST=127.0.0.1
export POLICY_PORT=8000
export WARMUP_STEPS=3

bash scripts/warmup_policy.sh
```

The warm-up client uses synthetic inputs and does not access robot hardware.

## 8. Client integration

Reference adapter:

```text
deployment/piperx_client.py
```

The robot-side integration must:

1. Supply all three camera observations using the documented names.
2. Supply a 14-dimensional measured state in the documented order.
3. Execute only the returned `execute_actions`, normally 5 actions.
4. Feed the latest measured robot state into the next policy request.
5. Call `reset_episode()` before every new episode.
6. Keep one WebSocket connection for one robot episode.
7. Never reuse observation history from the preceding episode.

Do not execute all 10 predicted actions and then make the next request as
though only 5 actions had been executed. The training and deployment contract
is predict 10, execute 5, and then replan.

## 9. Required robot-side safety

The policy server does not implement complete hardware safety. The robot
controller must independently enforce:

- joint-position limits;
- joint-velocity and joint-acceleration limits;
- command timeout and watchdog;
- communication-loss handling;
- collision and workspace limits;
- emergency stop;
- torque-disable recovery;
- gripper-command bounds;
- gripper-command rate limiting.

The synthetic loopback observed small arm-joint chunk-boundary gaps but larger
gripper-command changes. Gripper limiting must remain enabled during both
dry-run and real-robot evaluation.

## 10. Known non-fatal logs

On an NVIDIA machine, JAX may print unsuccessful backend probes such as:

```text
Unable to initialize backend 'rocm'
Unable to initialize backend 'tpu'
```

These messages do not indicate CUDA inference failure.

Orbax may also report that it cannot read the optional
`EXPERIMENTAL_ORBAX_USE_DISTRIBUTED_PROCESS_ID` flag. The checkpoint is
considered valid when restoration completes and the verifier produces:

```text
RELEASE_VERIFY_OK
```

## 11. Acceptance scope

Completed:

- checkpoint structure verification;
- configuration registration verification;
- delta-to-absolute action-semantics verification;
- WebSocket server/client protocol verification;
- three-frame streaming-history verification;
- episode-reset verification;
- warmed L40S synthetic-loopback verification.

Pending:

- zero-torque robot communication test;
- low-speed dry-run;
- per-task real-robot success-rate evaluation;
- final robot safety acceptance.