feat(upgrade): adding new robots, teleoperators and sensors to the third party packages list

Co-authored-by: Steven Palma <imstevenpmwork@ieee.org>

.dockerignore

@@ -22,6 +22,10 @@ outputs
 rl
 media
 
+# Local virtualenvs (the image provides its own)
+.venv
+venv
+
 
 # Logging
 logs

.github/workflows/benchmark_tests.yml

@@ -167,9 +167,9 @@ jobs:
 
       # ── LIBERO TRAIN+EVAL SMOKE ──────────────────────────────────────────────
       # Train SmolVLA for 1 step (batch_size=1, dataset episode 0 only) then
-      # immediately runs eval inside the training loop (eval_freq=1, 1 episode).
+      # immediately runs eval inside the training loop (env_eval_freq=1, 1 episode).
       # Tests the full train→eval-within-training pipeline end-to-end.
-      - name: Run Libero train+eval smoke (1 step, eval_freq=1)
+      - name: Run Libero train+eval smoke (1 step, env_eval_freq=1)
         if: env.HF_USER_TOKEN != ''
         run: |
           docker run --name libero-train-smoke --gpus all \
@@ -196,7 +196,7 @@ jobs:
                 --output_dir=/tmp/train-smoke \
                 --steps=1 \
                 --batch_size=1 \
-                --eval_freq=1 \
+                --env_eval_freq=1 \
                 --eval.n_episodes=1 \
                 --eval.batch_size=1 \
                 --eval.use_async_envs=false \

.github/workflows/documentation.yml

@@ -55,7 +55,7 @@ jobs:
       github.repository == 'huggingface/lerobot'
     permissions:
       contents: read
-    uses: huggingface/doc-builder/.github/workflows/build_main_documentation.yml@2430c1ec91d04667414e2fa31ecfc36c153ea391  # main
+    uses: huggingface/doc-builder/.github/workflows/build_main_documentation.yml@e60a538eea9817ab312196d0d233604b01697265  # main
     with:
       commit_sha: ${{ github.sha }}
       package: lerobot
@@ -78,7 +78,7 @@ jobs:
     permissions:
       contents: read
       pull-requests: write
-    uses: huggingface/doc-builder/.github/workflows/build_pr_documentation.yml@2430c1ec91d04667414e2fa31ecfc36c153ea391  # main
+    uses: huggingface/doc-builder/.github/workflows/build_pr_documentation.yml@e60a538eea9817ab312196d0d233604b01697265  # main
     with:
       commit_sha: ${{ github.event.pull_request.head.sha }}
       pr_number: ${{ github.event.number }}

.pre-commit-config.yaml

@@ -65,6 +65,9 @@ repos:
         name: Format Markdown with Prettier
         types_or: [markdown, mdx]
         args: [--prose-wrap=preserve]
+        # Jinja2 model-card templates use a .md extension but contain {% ... %} /
+        # {{ ... }} tags that prettier's Markdown formatter mangles (e.g. table loops).
+        exclude: ^src/lerobot/templates/.*\.md$
 
   ##### Security #####
   - repo: https://github.com/gitleaks/gitleaks

AGENT_GUIDE.md

@@ -138,7 +138,7 @@ lerobot-replay --robot.type=so101_follower --robot.port=<FOLLOWER_PORT> --robot.
   --dataset.repo_id=${HF_USER}/my_task --dataset.episode=0
 ```
 
-**4.9 Train** (default: ACT — fastest, lowest memory). Apple silicon: `--policy.device=mps`. See §6/§7 for policy and duration.
+**4.9 Train** (default: ACT — fastest, lowest memory). Apple silicon: `--policy.device=mps`. No local GPU? Add `--job.target=<flavor>` (e.g. `a10g-small`, list them with `hf jobs hardware`) to run on Hugging Face Jobs instead. See §6/§7 for policy and duration.
 
 ```bash
 lerobot-train \

Makefile

@@ -58,7 +58,7 @@ test-act-ete-train:
 		--dataset.episodes="[0]" \
 		--batch_size=2 \
 		--steps=4 \
-		--eval_freq=2 \
+		--env_eval_freq=2 \
 		--eval.n_episodes=1 \
 		--eval.batch_size=1 \
 		--save_freq=2 \
@@ -96,7 +96,7 @@ test-diffusion-ete-train:
 		--dataset.episodes="[0]" \
 		--batch_size=2 \
 		--steps=2 \
-		--eval_freq=2 \
+		--env_eval_freq=2 \
 		--eval.n_episodes=1 \
 		--eval.batch_size=1 \
 		--save_checkpoint=true \
@@ -126,7 +126,7 @@ test-tdmpc-ete-train:
 		--dataset.episodes="[0]" \
 		--batch_size=2 \
 		--steps=2 \
-		--eval_freq=2 \
+		--env_eval_freq=2 \
 		--eval.n_episodes=1 \
 		--eval.batch_size=1 \
 		--save_checkpoint=true \
@@ -161,7 +161,7 @@ test-smolvla-ete-train:
 		--dataset.episodes="[0]" \
 		--batch_size=2 \
 		--steps=4 \
-		--eval_freq=2 \
+		--env_eval_freq=2 \
 		--eval.n_episodes=1 \
 		--eval.batch_size=1 \
 		--save_freq=2 \
@@ -178,3 +178,9 @@ test-smolvla-ete-eval:
 		--env.episode_length=5 \
 		--eval.n_episodes=1 \
 		--eval.batch_size=1
+
+# E2E annotation pipeline smoke test against a tiny in-memory fixture
+# dataset. Opt-in (not part of `make test-end-to-end`) and uses a stub VLM
+# backend, so it does not require a real model checkpoint or GPU.
+annotation-e2e:
+	uv run python -m tests.annotations.run_e2e_smoke

README.md

@@ -87,7 +87,7 @@ Learn more about it in the [LeRobotDataset Documentation](https://huggingface.co
 
 ## SoTA Models
 
-LeRobot implements state-of-the-art policies in pure PyTorch, covering Imitation Learning, Reinforcement Learning, and Vision-Language-Action (VLA) models, with more coming soon. It also provides you with the tools to instrument and inspect your training process.
+LeRobot implements state-of-the-art policies in pure PyTorch, covering Imitation Learning, Reinforcement Learning, Vision-Language-Action (VLA) models, World Models, and Reward Models, with more coming soon. It also provides you with the tools to instrument and inspect your training process.
 
 <p align="center">
   <img alt="Gr00t Architecture" src="./media/readme/VLA_architecture.jpg" width="640px">
@@ -97,17 +97,17 @@ Training a policy is as simple as running a script configuration:
 
 ```bash
 lerobot-train \
-  --policy=act \
+  --policy.type=act \
   --dataset.repo_id=lerobot/aloha_mobile_cabinet
 ```
 
-| Category                   | Models                                                                                                                                                                                                                                                                                                                                                     |
-| -------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| **Imitation Learning**     | [ACT](./docs/source/policy_act_README.md), [Diffusion](./docs/source/policy_diffusion_README.md), [VQ-BeT](./docs/source/policy_vqbet_README.md), [Multitask DiT Policy](./docs/source/policy_multi_task_dit_README.md)                                                                                                                                    |
-| **Reinforcement Learning** | [HIL-SERL](./docs/source/hilserl.mdx), [TDMPC](./docs/source/policy_tdmpc_README.md) & QC-FQL (coming soon)                                                                                                                                                                                                                                                |
-| **VLAs Models**            | [Pi0](./docs/source/pi0.mdx), [Pi0Fast](./docs/source/pi0fast.mdx), [Pi0.5](./docs/source/pi05.mdx), [GR00T N1.5](./docs/source/policy_groot_README.md), [SmolVLA](./docs/source/policy_smolvla_README.md), [XVLA](./docs/source/xvla.mdx), [EO-1](./docs/source/eo1.mdx), [MolmoAct2](./docs/source/molmoact2.mdx), [WALL-OSS](./docs/source/walloss.mdx) |
-| **World Models**           | [VLA-JEPA](./docs/source/vla_jepa.mdx) (more coming soon)                                                                                                                                                                                                                                                                                                  |
-| **Reward Models**          | [SARM](./docs/source/sarm.mdx), [TOPReward](./docs/source/topreward.mdx), [Robometer](./docs/source/robometer.mdx)                                                                                                                                                                                                                                         |
+| Category                   | Models                                                                                                                                                                                                                                                                                                                                                                                     |
+| -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| **Imitation Learning**     | [ACT](./docs/source/policy_act_README.md), [Diffusion](./docs/source/policy_diffusion_README.md), [VQ-BeT](./docs/source/policy_vqbet_README.md), [Multitask DiT Policy](./docs/source/policy_multi_task_dit_README.md)                                                                                                                                                                    |
+| **Reinforcement Learning** | [HIL-SERL](./docs/source/hilserl.mdx), [TDMPC](./docs/source/policy_tdmpc_README.md) & QC-FQL (coming soon)                                                                                                                                                                                                                                                                                |
+| **VLAs Models**            | [Pi0](./docs/source/pi0.mdx), [Pi0Fast](./docs/source/pi0fast.mdx), [Pi0.5](./docs/source/pi05.mdx), [GR00T N1.7](./docs/source/policy_groot_README.md), [SmolVLA](./docs/source/policy_smolvla_README.md), [XVLA](./docs/source/xvla.mdx), [EO-1](./docs/source/eo1.mdx), [MolmoAct2](./docs/source/molmoact2.mdx), [WALL-OSS](./docs/source/walloss.mdx), [EVO1](./docs/source/evo1.mdx) |
+| **World Models**           | [VLA-JEPA](./docs/source/vla_jepa.mdx), [LingBot-VA](./docs/source/lingbot_va.mdx), [FastWAM](./docs/source/fastwam.mdx)                                                                                                                                                                                                                                                                   |
+| **Reward Models**          | [SARM](./docs/source/sarm.mdx), [TOPReward](./docs/source/topreward.mdx), [Robometer](./docs/source/robometer.mdx)                                                                                                                                                                                                                                                                         |
 
 Similarly to the hardware, you can easily implement your own policy & leverage LeRobot's data collection, training, and visualization tools, and share your model to the HF Hub
 
@@ -136,6 +136,7 @@ Learn how to implement your own simulation environment or benchmark and distribu
 - **[X](https://x.com/LeRobotHF):** Follow us on X to stay up-to-date with the latest developments.
 - **[Robot Learning Tutorial](https://huggingface.co/spaces/lerobot/robot-learning-tutorial):** A free, hands-on course to learn robot learning using LeRobot.
 - **[T-Shirt Folding Experiment](https://huggingface.co/spaces/lerobot/robot-folding):** An end-to-end demonstration of folding t-shirts with LeRobot.
+- **[LeLab](https://github.com/huggingface/leLab):** A web interface for LeRobot — teleoperate, calibrate, record datasets, replay, and train your SO arm from the browser, no CLI required.
 
 ## Citation
 

async_proposal1.md

@@ -1,417 +0,0 @@
-# Decoupled VLA Inference & Edge Control: System Design Proposal
-
-## 1. Executive Summary
-
-This document proposes a production-grade system for decoupling GPU-bound VLA (Vision-Language-Action) policy inference from high-frequency, CPU-bound robot control in LeRobot. The system adopts a **Model-as-a-Service (MaaS)** paradigm using **Zenoh** as the sole transport protocol, enabling multiple edge devices to be served by centralized GPU servers with minimal latency and high reliability.
-
-An initial prototype exists in `src/lerobot/async_inference/` (gRPC-based, single-client). This proposal defines the target architecture, identifies gaps between the prototype and production requirements, documents known bugs, and establishes the design for the new system.
-
----
-
-## 2. Motivation
-
-LeRobot's standard control loop runs policy inference and robot I/O in the same process. This works for lightweight policies on local GPUs, but breaks down when:
-
-- **The policy is too large for edge hardware** (e.g., Pi0 at ~3B parameters requires a dedicated GPU).
-- **Multiple robots need the same policy** (redundant GPU allocation per robot).
-- **Inference latency exceeds the control deadline** (e.g., 200ms inference on a 33ms control loop at 30 FPS).
-
-Decoupling inference from control solves all three: the edge device runs a tight I/O loop on a CPU, while a GPU server handles inference for one or more clients.
-
----
-
-## 3. Core Architectural Principles
-
-### 3.1 Model-as-a-Service (MaaS)
-
-Servers initialize models **once at startup** from a configuration manifest. Edge devices do **not** trigger dynamic model loading — they route to pre-warmed servers and validate compatibility via a status endpoint.
-
-### 3.2 Multi-Tenant & Stateless Inference
-
-A single GPU server handles multiple edge devices executing the same task. The server is stateless per inference call — `predict_action_chunk()` is a pure function with no side effects on the model. Client isolation is achieved through per-client observation slots and Zenoh key-expression routing.
-
-> **Invariant**: `predict_action_chunk()` must remain a pure function (no mutation of `self`) for all supported policies. This is what enables safe multi-tenant sharing of a single model instance. This invariant must be documented and tested.
-
-### 3.3 Zenoh as primary Transport
-
-The system uses Zenoh's pub/sub model, replacing the current gRPC implementation. Zenoh provides:
-
-- **Hierarchical key expressions** for routing (natural fit for the cluster/experiment/model/task topology).
-- **Built-in discovery** (no external service discovery needed).
-- **Non-blocking publish** for observations (fire-and-forget with best-effort QoS).
-- **Reliable delivery** configurable per-topic (required for action chunks).
-- **Shared-memory transport** for same-machine deployments (zero-copy) (if available).
-
-### 3.4 Local Edge CPU
-
-Edge devices rely on standard CPUs for sensor polling, image compression, payload serialization, motor control, and data logging. No edge-GPU dependency.
-
----
-
-## 4. System Topology
-
-![alt text](MaaS_async_inference_diagram.png)
-
-- **Cluster**: A set of GPU machines. Identified by `cluster_uuid`.
-- **Experiment**: A logical grouping of servers and clients. Identified by `experiment_tag`.
-- **Server**: One model + one task, pre-warmed. Serves N clients for that model/task combination.
-- **Client**: One robot, one task. Publishes observations, subscribes to actions.
-
-The number of clients a single server can handle is a **user decision** based on model inference time and acceptable latency.
-
----
-
-## 5. Component Specifications
-
-### 5.1 The Edge Device (Client)
-
-**Responsibilities:**
-
-1. **Observation capture**: Read sensors (cameras, motors) at the control loop frequency.
-2. **Image compression**: JPEG-encode RGB images before transmission.
-3. **Observation publishing**: Non-blocking Zenoh put to the observation topic.
-4. **Action subscription**: Zenoh callback receives action chunks, deposits into local buffer.
-5. **Action execution**: Pop actions from buffer, send to robot at control frequency.
-6. **Action blending**: When a new action chunk overlaps with the current buffer, blend via configurable aggregation function (weighted average, latest-only, etc.).
-7. **Latency compensation**: Calculate one-way latency from RTT, discard expired initial steps of incoming action chunks.
-8. **Fail-safe**: If action buffer empties, logs a warning.
-9. **Data logging**: Record raw observations and executed actions to local `LeRobotDataset` storage for deferred upload.
-
-**Threading model:**
-
-- **Control loop thread** (main): Capture observation → deposit in outbox → pop action from buffer → send to robot → sleep to maintain frequency.
-- **Zenoh action callback** (Zenoh-managed): Receives action chunks, processes RTT, trims stale steps, deposits into action buffer.
-- **Observation publisher thread**: Drains the outbox, compresses images, serializes, publishes via Zenoh.
-
-> **Design note**: The current prototype blocks on `send_observation` inside the control loop (BUG-1, see Section 9). The new design decouples observation publishing from the control loop entirely, using a separate thread and Zenoh's non-blocking put.
-
-### 5.2 The Inference Server (GPU Pod)
-
-**Responsibilities:**
-
-1. **Model pre-warming**: Load model and processor pipelines at startup from config manifest (including expected clients & policy parameters).
-2. **Status publishing**: Expose model capabilities (policy type, expected camera names, resolutions, action dimensions) via Zenoh queryable.
-3. **Observation subscription**: Subscribe to observation topics for all clients of this model/task. Maintain per-client observation slots (newest-only semantics).
-4. **Inference**: Single inference thread processes observations sequentially (round-robin across clients). Calls `policy.predict_action_chunk()`.
-5. **Action publishing**: Publish action chunks to per-client action topics with reliable QoS.
-
-> **Thread safety**: PyTorch's `model.forward()` is not guaranteed thread-safe. Inference will be sequential, latency is mostly about the capabilities of the server to serve multiple requests.
-
----
-
-## 6. Zenoh Routing & Key Expressions
-
-### 6.1 Key Expression Schema
-
-```
-[cluster_uuid] / [experiment_tag] / [model_id] / [model_version] / [application_tag] / [client_uuid] / [topic]
-```
-
-**Example key expressions:**
-
-| Key Expression                                   | Direction         | Purpose                            |
-| ------------------------------------------------ | ----------------- | ---------------------------------- |
-| `jupiter/fabio2/pi0/v1/cookie/robot_a4b9/obs`    | Client → Server   | Observation payload                |
-| `jupiter/fabio2/pi0/v1/cookie/robot_a4b9/action` | Server → Client   | Action chunk                       |
-| `jupiter/fabio2/pi0/v1/cookie/*/obs`             | Server subscribes | All observations for pi0/v1/cookie |
-| `jupiter/fabio2/pi0/v1/cookie/status`            | Server publishes  | Model capabilities (queryable)     |
-
-### 6.2 QoS Configuration
-
-| Topic    | Reliability | Rationale                                                            |
-| -------- | ----------- | -------------------------------------------------------------------- |
-| `obs`    | Best-effort | Dropping stale observations is expected behavior.                    |
-| `action` | Reliable    | Every action chunk must be delivered; loss causes action starvation. |
-| `status` | Reliable    | Client needs accurate capability info before starting.               |
-
-### 6.3 Discovery Flow
-
-0. Server goes up with the static configuration.
-1. Client constructs its target key prefix: `cluster/experiment/model/version/task/`.
-2. Client queries `cluster/experiment/model/version/task/status` (Zenoh queryable).
-3. Server responds with its capabilities (expected camera names, image resolutions, action dimensions, model metadata).
-4. Client validates its own configuration against server capabilities.
-5. On match: client starts publishing observations and subscribing to actions.
-6. On mismatch: client logs an error and refuses to start.
-
-No dynamic client discovery for now.
-
----
-
-## 7. Message Schema
-
-### 7.1 Observation Payload (Client → Server)
-
-| Field         | Type               | Purpose                                                     |
-| ------------- | ------------------ | ----------------------------------------------------------- |
-| `seq_id`      | `uint64`           | Incrementing ID for causality tracking and RTT computation. |
-| `client_uuid` | `string`           | Identifies the sending client.                              |
-| `state`       | `bytes`            | Proprioceptive state vector (`numpy.tobytes()`).            |
-| `images`      | `dict[str, bytes]` | JPEG-compressed camera images, keyed by camera name.        |
-| `task`        | `string`           | Natural-language task instruction (for VLA conditioning).   |
-
-### 7.2 Action Payload (Server → Client)
-
-| Field                | Type      | Purpose                                                         |
-| -------------------- | --------- | --------------------------------------------------------------- |
-| `response_to_seq_id` | `uint64`  | Echoes the observation `seq_id` this action corresponds to.     |
-| `inference_time_ms`  | `float32` | Server-side compute duration (for edge RTT math).               |
-| `actions`            | `bytes`   | Action chunk as numpy array bytes (`(chunk_size, action_dim)`). |
-
-### 7.3 Status Payload (Server, Queryable)
-
-| Field                   | Type                | Purpose                                    |
-| ----------------------- | ------------------- | ------------------------------------------ |
-| `model_id`              | `string`            | Policy identifier (e.g., `pi0`).           |
-| `model_version`         | `string`            | Model version or checkpoint path.          |
-| `expected_cameras`      | `dict[str, (H, W)]` | Expected camera names and shapes.          |
-| `action_dim`            | `int`               | Dimensionality of the action space.        |
-| `max_actions_per_chunk` | `int`               | Maximum chunk size the model supports.     |
-| `observation_features`  | `dict`              | Full feature specification for validation. |
-
-### 7.4 Serialization Format
-
-**MessagePack** for all structured metadata (compact, fast, cross-language). Image payloads are raw JPEG bytes embedded in the MessagePack structure. State vectors use `numpy.tobytes()` with shape/dtype metadata for zero-copy reconstruction.
-
-**No pickle.** The current prototype uses `pickle.dumps`/`pickle.loads` throughout, which allows arbitrary code execution. This is replaced entirely.
-
----
-
-## 8. Latency Compensation
-
-### 8.1 RTT Calculation
-
-The edge device tracks in-flight observations:
-
-```python
-in_flight: dict[int, float] = {}  # seq_id -> time.perf_counter() at send
-
-# On send:
-in_flight[seq_id] = time.perf_counter()
-
-# On receive action chunk:
-rtt = time.perf_counter() - in_flight[response_to_seq_id]
-# delete older keys than the one received
-```
-
-> **Important**: Delete only the exact `response_to_seq_id` key from `in_flight`, not all keys `<= response_to_seq_id`. With Zenoh's best-effort transport, messages can arrive out of order. Clearing earlier keys would make their RTT unmeasurable.
-
-### 8.2 Stale Action Trimming
-
-When an action chunk arrives, the edge calculates how many initial steps have already expired:
-
-```python
-expired_steps = int(rtt / environment_dt)
-valid_actions = action_chunk[expired_steps:]
-```
-
-The valid actions are then blended into the action buffer using the configured aggregation function.
-
-### 8.3 Edge Cases
-
-| Scenario                               | Behavior                                                                               |
-| -------------------------------------- | -------------------------------------------------------------------------------------- |
-| **First observation** (no RTT history) | Apply all action steps without trimming.                                               |
-| **Dropped observations**               | Server infers on next received observation. No special handling needed.                |
-| **Dropped action chunks**              | Edge continues executing current buffer. If buffer empties, warn & hold last position. |
-| **Server crash**                       | Edge exhausts buffer, holds position, warns & re-validates via status query.           |
-
-> **Assumption**: All currently supported robots are position-controlled (SO100, SO101, OMX). For velocity-controlled robots, the fail-safe must send zero-velocity instead of holding position. This should be configurable per-robot.
-
----
-
-## 9. Known Bugs in Current Prototype
-
-These issues exist in `src/lerobot/async_inference/` and must be addressed in the new implementation.
-
-### BUG-1: `send_observation` Blocks the Control Loop (Critical)
-
-**Location**: `robot_client.py:207`
-
-`self.stub.SendObservations(observation_iterator)` is a synchronous gRPC call inside the 33ms control loop. For multi-camera observations (several MB after pickle), this consumes 10-20ms on the network, leaving no headroom for sensor capture and motor commands. The robot stutters.
-
-**Resolution in new design**: Observation publishing is moved to a dedicated thread. Zenoh's `session.put()` is non-blocking by default. The control loop only deposits observations into a local outbox.
-
-### BUG-2: Race Condition in Action Queue Aggregation (Correctness)
-
-**Location**: `robot_client.py:236-267`
-
-The lock on `self.action_queue` is acquired to read `internal_queue = self.action_queue.queue` (a reference to the internal deque), then **released** at line 238. The aggregation logic iterates over this reference outside the lock. Meanwhile, the control loop thread can `get_nowait()` from the same queue, mutating the deque during iteration. At line 267, the entire queue is replaced, but actions popped between 238-267 are silently lost.
-
-**Fix**: Either hold the lock for the entire aggregation, or `list(self.action_queue.queue)` to copy contents before releasing.
-
-### BUG-3: No RPC Deadlines (Reliability)
-
-**Location**: `robot_client.py:278`
-
-`GetActions` blocks indefinitely if the server hangs (GPU OOM, deadlock). The retry policy handles `UNAVAILABLE` but not a hung connection.
-
-**Resolution in new design**: The polling `GetActions` pattern is replaced by Zenoh subscription callbacks. The client needs a watchdog timer or check when action queue is empty: if no actions are received for `T` seconds, trigger re-validation via the status service.
-
-### BUG-4: Similarity Check Ignores Images (Correctness for VLAs)
-
-**Location**: `helpers.py:280-297`
-
-`observations_similar()` + `must_go` is a workaround for current architecure limitations to avoid filling up the server queue the first seconds of the task & the robot remaining idle.
-
-**Resolution in new design**: the server always processes the latest observation per client in its inference loop, and doesn't need similarity gating at all. The client can always push.
-
----
-
-## 10. Gaps Between Prototype and Target Architecture
-
-### 10.1 Critical (Must Address)
-
-| #   | Gap                       | Current State                                                                                                                                                   | Target State                                                                                                                              |
-| --- | ------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
-| G1  | **Single-client server**  | One `observation_queue(maxsize=1)`, one `last_processed_obs`, one `_predicted_timesteps`. `_reset_server()` flushes all state on any new connection.            | Per-client state (`ClientState` dataclass) keyed by `client_uuid`. Zenoh key-expression routing provides client isolation.                |
-| G2  | **Dynamic model loading** | Client sends `RemotePolicyConfig` → server calls `from_pretrained()` on demand.                                                                                 | Server loads models at startup from config manifest. `SendPolicyInstructions` RPC eliminated. Client validates via status query.          |
-| G3  | **gRPC transport**        | Entire `transport/` directory: proto definitions, generated stubs, chunking utils. 4 RPCs: `Ready`, `SendPolicyInstructions`, `SendObservations`, `GetActions`. | Zenoh pub/sub. Client publishes obs, subscribes to actions. Server subscribes to obs, publishes actions. Dispatching via key expressions. |
-| G4  | **Pickle serialization**  | `pickle.dumps`/`pickle.loads` throughout (arbitrary code execution risk, `# nosec` suppression).                                                                | MessagePack for structured metadata + raw JPEG bytes for images + `numpy.tobytes()` for state vectors.                                    |
-
-### 10.2 Important
-
-| #   | Gap                              | Current State                                                                                                                                                                  | Target State                                                                                                                           |
-| --- | -------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------- |
-| G5  | **No RTT/latency compensation**  | No `seq_id`, no `response_to_seq_id`, no `inference_time_ms`. Timestamps use `time.time()` (unreliable across machines).                                                       | Edge-local `perf_counter` + echoed `seq_id` + server inference duration. Stale action step trimming.                                   |
-| G6  | **No hierarchical routing**      | Direct gRPC channel to `host:port`.                                                                                                                                            | Zenoh key expressions: `cluster/experiment/model/version/task/client/topic`.                                                           |
-| G7  | **No data logging**              | `control_loop` has access to obs and actions but doesn't persist them.                                                                                                         | Edge records via `LeRobotDataset` (`build_dataset_frame` + `dataset.add_frame`).                                                       |
-| G8  | **No authentication**            | `grpc.insecure_channel`.                                                                                                                                                       | Zenoh TLS + access control lists on key expressions.                                                                                   |
-| G9  | **ProcessorPipeline divergence** | Server reimplements observation prep in `helpers.py` (custom `resize_robot_observation_image` with `F.interpolate` bilinear). Diverges from standard `RobotProcessorPipeline`. | Use the standard `RobotProcessorPipeline` + `build_dataset_frame` to ensure behavioral equivalence between record and async inference. |
-
-### 10.3 Nice-to-Have
-
-| #   | Gap                                   | Current State                                                                                             | Target State                                                                                                                              |
-| --- | ------------------------------------- | --------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
-| G11 | **No status/discovery service**       | Bare `Ready()` ping.                                                                                      | Zenoh queryable at `cluster/exp/model/version/task/status`.                                                                               |
-| G12 | **No monitoring**                     | `FPSTracker` + `logging.debug`.                                                                           | Structured metrics via Zenoh telemetry topics. Wildcard subscriptions for centralized monitoring.                                         |
-| G13 | **No entry points**                   | Module-level `__main__`.                                                                                  | `lerobot-policy-server` and `lerobot-robot-client` console scripts in `pyproject.toml`.                                                   |
-| G14 | **Ratio-based observation threshold** | `chunk_size_threshold` (0-1 ratio of queue fill). Scales oddly with different `actions_per_chunk` values. | Absolute time threshold: `buffer_time_s` calibrated to observed RTT. Send observation when `queue_size * environment_dt < buffer_time_s`. |
-
----
-
-## 11. Design Decisions & Rationale
-
-### 11.1 Why Zenoh Over gRPC
-
-| Aspect                    | Zenoh                                                                      | gRPC                                                                               |
-| ------------------------- | -------------------------------------------------------------------------- | ---------------------------------------------------------------------------------- |
-| Communication model       | Pub/sub — natural fit for "client publishes obs, server publishes actions" | Request/response — requires polling (`GetActions` loop) or bidirectional streaming |
-| Multi-tenant routing      | Hierarchical key expressions provide built-in per-client topic isolation   | Requires manual per-client channel/stream management                               |
-| Discovery                 | Built-in discovery                                                         | Requires external service (mDNS, Consul, etc.)                                     |
-| Observation publishing    | Non-blocking put (fire-and-forget) — resolves BUG-1 automatically          | Synchronous stream-unary call — blocks the control loop                            |
-| Same-machine optimization | Shared-memory transport (zero-copy)                                        | Loopback TCP                                                                       |
-| Telemetry                 | Wildcard subscriptions (`+/+/+/+/+/metrics`)                               | Requires separate monitoring infrastructure                                        |
-
-**Tradeoffs of going Zenoh-only:**
-
-- Smaller community, less tooling for monitoring/tracing vs. gRPC's mature ecosystem.
-- No built-in schema enforcement (Zenoh sends raw bytes) — serialization correctness is entirely on us.
-- Default QoS is best-effort (like UDP). Must explicitly configure reliable delivery for action chunks.
-- `zenoh-python` bindings are less battle-tested than `grpcio`. Needs integration testing under network stress.
-
-### 11.2 Why Single Inference Thread (Not Batching)
-
-True GPU batching across clients requires collecting observations from multiple clients and running a single forward pass. This is difficult because:
-
-- Clients send observations at different times — waiting to batch adds latency.
-- Different clients may have slightly different image resolutions.
-- Error in one client's observation shouldn't affect others.
-
-**Decision**: Start with sequential processing (single inference thread, round-robin across clients). Profile GPU utilization.
-
-### 11.4 Why MessagePack (Not Protobuf, Not FlatBuffers)
-
-- **Protobuf**: Strong schema enforcement but heavier toolchain (proto compilation, generated code). Since we're dropping gRPC, the protobuf dependency becomes unnecessary overhead.
-- **MessagePack**: Fast, compact, schema-less (enforced by application), excellent Python support (`msgpack` package), good for nested dicts with mixed types. Natural fit for observation/action payloads.
-
-Images are embedded as raw JPEG bytes within the MessagePack structure. State vectors use `numpy.tobytes()` with shape/dtype metadata for zero-copy reconstruction.
-
-### 11.5 Action Aggregation Strategy
-
-When a new action chunk overlaps with the existing buffer, the overlapping timesteps must be blended. The current prototype supports configurable aggregation functions:
-
-| Function           | Formula                 | Character                                  |
-| ------------------ | ----------------------- | ------------------------------------------ |
-| `weighted_average` | `0.3 * old + 0.7 * new` | Smooth transitions, favors new predictions |
-| `latest_only`      | `new`                   | Most responsive, can cause discontinuities |
-| `average`          | `0.5 * old + 0.5 * new` | Equal weight                               |
-| `conservative`     | `0.7 * old + 0.3 * new` | Smooth, slow to adapt                      |
-
-Ultimately, this should be the user's decision. Default to `weighted_average`. The goal of async is not to do temporal ensembling, but to provide a solution when we want to decouple inference and execution.
-
----
-
-## 12. Configuration
-
-### 12.1 Server Configuration (Manifest)
-
-Servers are configured via a YAML manifest that declares which models to pre-warm & clients to serve:
-
-```yaml
-cluster_uuid: jupiter
-experiment_tag: fabio2
-server:
-  - model_id: pi0
-    model_version: v1
-    pretrained_path: lerobot/pi0-cookie-v1
-    application_tag: cookie
-    device: cuda:0
-    fps: 30
-    endpoint: tcp/192.168.1.50:7447
-clients:
-  - client_uuid: cookie-worker-4269
-```
-
-### 12.2 Client Configuration
-
-Clients are configured via draccus dataclass (CLI-compatible):
-
-```python
-@dataclass
-class AsyncClientConfig:
-    # Zenoh routing
-    cluster_uuid: str
-    experiment_tag: str
-    model_id: str
-    model_version: str
-    application_tag: str
-    client_uuid: str
-    endpoint: str
-
-    # Robot
-    robot: RobotConfig
-
-    # Control
-    fps: int = 30
-    actions_per_chunk: int = 50
-    aggregate_fn_name: str = "weighted_average"
-    jpeg_quality: int = 90
-
-    # Fail-safe
-    max_empty_cycles_before_warning: int = 10
-
-    # Datset recording
-    dataset_repo_id: str | None = None  # None = no logging
-
-    # Task
-    task: str = ""
-```
-
----
-
-## 14. Data Logging Integration
-
-The client records observations and executed actions into a local `LeRobotDataset` for deferred upload to the training dataset:
-
-```python
-# In control_loop, after executing an action:
-if self.dataset is not None:
-    frame = build_dataset_frame(
-        self.dataset.features,
-        processed_observation,
-        prefix=OBS_STR,
-    )
-    frame["action"] = executed_action_tensor
-    self.dataset.add_frame(frame)
-```

async_proposal2.md

@@ -1,498 +0,0 @@
-# Decoupled VLA Inference & Edge Control v2: Async Network Inference for `lerobot-rollout`
-
-> **Status**: supersedes the v1 proposal in full. v1 was written against the standalone `src/lerobot/async_inference/` prototype, before `lerobot-rollout` existed. This revision re-grounds the design in the current codebase, keeps v1's decisions that survived contact with it (marked **KEPT** throughout), reverses the ones that didn't, and adds the safety, multi-tenancy, and operations specifications v1 lacked.
-
-## 1. Executive Summary
-
-This document specifies a production-grade system for decoupling GPU-bound policy inference from high-frequency robot control, targeting power users running **hundreds of robots** against centralized GPU clusters. The system keeps v1's **Model-as-a-Service (MaaS)** paradigm and **Zenoh** transport, but changes the integration architecture fundamentally:
-
-- **The client is not a standalone CLI.** It is `--inference.type=remote`, a new `InferenceEngine` backend inside `lerobot-rollout` (`src/lerobot/rollout/inference/`). Every rollout strategy (base, sentry, highlight, dagger, episodic) gets network inference for free — including dataset recording, DAgger pause/resume, Rerun visualization, and safe teardown.
-- **The client is weightless.** No policy weights, no policy processors on the edge. `--policy.path` resolves to a config-only `PreTrainedConfig` (no weight download) used for pre-flight validation and action ordering.
-- **The server is stateless per request.** All RTC chunk state (leftover prefixes, latency tracking, delay computation) lives client-side in the existing `ActionQueue`/`LatencyTracker` machinery — the client ships prefixes + a delay hint with each observation. A server crash loses zero control state; reconnects and horizontal scaling are trivial.
-- **Multi-tenancy is engineered, not assumed.** The real hazards are stateful processor pipelines and episode-scoped policy state — not `predict_action_chunk` purity (which holds for ACT/Pi0/Pi0.5/SmolVLA but _not_ diffusion). The server uses per-session processor instances, a chunk-stateless allowlist, and an exclusive serving mode for policies that need it.
-- **The legacy module dies.** `src/lerobot/async_inference/` (~1,900 lines, pickle-over-gRPC, single-client, four confirmed bugs) is deleted in the same PR that lands the new backend. No deprecation cycle: the module is experimental, its CLI undocumented in the main flow, and every config field has a mapped successor (§13.4).
-
----
-
-## 2. Motivation (unchanged from v1) — **KEPT**
-
-LeRobot's standard control loop runs policy inference and robot I/O in the same process. This breaks down when:
-
-- **The policy is too large for edge hardware** (Pi0-class models need a dedicated GPU).
-- **Multiple robots need the same policy** (redundant GPU allocation per robot).
-- **Inference latency exceeds the control deadline** (e.g. 150 ms inference on a 33 ms control tick).
-
-Decoupling solves all three: the edge runs a tight CPU loop; a GPU server performs inference for N clients.
-
-What changed since v1: the _local_ version of this decoupling already shipped. `RTCInferenceEngine` (`src/lerobot/rollout/inference/rtc.py`) runs inference in a background thread against a thread-safe `ActionQueue` with latency-aware chunk merging. **The network system is that same architecture with the thread boundary replaced by a network boundary.** This is the design's central simplification: reuse, don't reinvent.
-
----
-
-## 3. Gap Analysis: v1 Proposal vs. Modern Codebase
-
-| Topic                                     | v1 assumed                                                      | Modern reality                                                                                                 | Verdict                                 |
-| ----------------------------------------- | --------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------- | --------------------------------------- |
-| Client architecture                       | Standalone robot-client CLI (§5.1 of v1)                        | `InferenceEngine` ABC seam in `lerobot-rollout` (`rollout/inference/base.py`); strategies are backend-agnostic | **Superseded** — backend, not CLI       |
-| Chunk blending                            | Configurable aggregation zoo (`weighted_average`, …)            | `ActionQueue` replace-with-delay-trim (RTC) / append (non-RTC) (`policies/rtc/action_queue.py:147-217`)        | **Superseded** — drop blending entirely |
-| Latency compensation                      | Hand-rolled RTT trim (`expired_steps = int(rtt/dt)`, v1 §8.2)   | `ActionQueue.merge(..., real_delay, idx_before)` + `LatencyTracker` already do this, validated                 | **Superseded**                          |
-| Multi-tenancy invariant                   | "`predict_action_chunk()` pure ⇒ safe to share"                 | Processor state + episode-scoped policy state are the real hazards (§7)                                        | **Incomplete** — fixed in §8.3          |
-| Data logging                              | Client-side `build_dataset_frame` + `add_frame` sketch (v1 §14) | Recording strategies (sentry/episodic/dagger) already log obs + executed actions                               | **Superseded** — free via rollout       |
-| MaaS pre-warm, no dynamic loading         | ✓                                                               | Still right; legacy `SendPolicyInstructions` is a pickle/RCE + capacity-planning disaster                      | **KEPT**                                |
-| JPEG observation compression              | ✓                                                               | Still right (§10.1)                                                                                            | **KEPT**                                |
-| Status/capability validation before start | ✓ (Zenoh queryable)                                             | Still right; extended into a hard sync-safety contract (§8.4)                                                  | **KEPT, extended**                      |
-| Time-based send threshold (v1 G14)        | ✓                                                               | Adopted as `buffer_time_s`                                                                                     | **KEPT**                                |
-| Zenoh pub/sub data plane                  | ✓                                                               | Confirmed; QoS corrected (§6.3), control plane moved to queryables, liveliness added                           | **KEPT, hardened**                      |
-| MessagePack serialization                 | ✓                                                               | Endorsed (zenoh's `ext` serializer cannot encode numpy); must be version-gated (§10.4)                         | **KEPT, with schema discipline**        |
-| QoS table (v1 §6.2)                       | "obs best-effort, actions reliable"                             | Conflates transport reliability with congestion control; BLOCK on actions is dangerous                         | **Revised** (§6.3)                      |
-| Bugs BUG-1…BUG-4, gaps G1…G14             | Listed as work items                                            | Every one resolved _structurally_ by this design (§13.5 mapping)                                               | **Resolved by design**                  |
-
----
-
-## 4. Critical Pushbacks on v1
-
-Each pushback: claim → evidence → consequence for this design.
-
-**P1 — A standalone client duplicates `lerobot-rollout`.**
-v1 §5.1 assigns the client: observation capture, action execution at frequency, fail-safe, data logging. Every one of those is already owned by rollout strategies and `send_next_action` (`rollout/strategies/core.py:269-304`), which tolerates `None` actions, runs the interpolator, and routes through the canonical robot processors. A standalone client re-implements loop timing, recording, DAgger UX, Rerun, and teardown safety — and then drifts. _Consequence_: the client is `RemoteInferenceEngine`, registered as `--inference.type=remote` next to `sync` and `rtc`.
-
-**P2 — The aggregation-function zoo fabricates actions no policy predicted.**
-`0.3*old + 0.7*new` produces hybrid actions that exist in no policy's output distribution; the logged action becomes unexplainable (bad for the reproducibility story) and the implementation hosted a real lock-release race (BUG-2, `async_inference/robot_client.py:236-267`). RTC's prefix-conditioned chunk generation is the principled mechanism for smooth chunk transitions; plain append covers non-RTC chunking. _Consequence_: `ActionQueue` replace/append are the only two merge semantics. The zoo is deleted.
-
-**P3 — "predict_action_chunk pure ⇒ multi-tenant safe" is incomplete.**
-Verified in-tree: (a) `RelativeActionsProcessorStep` caches `_last_state` at preprocess (`processor/relative_action_processor.py:131`) and the postprocessor reads it back (`:189`) — a shared pipeline across clients is a race; (b) `DiffusionPolicy.predict_action_chunk` reads `self._queues`, which only `select_action` populates (`policies/diffusion/modeling_diffusion.py:90-108`) — it is **not** chunk-stateless; (c) SAC/SARM have no `predict_action_chunk` at all. _Consequence_: per-session processor instances (mandatory), a chunk-stateless allowlist, `serving_mode: exclusive` for diffusion-family, refusal at startup for SAC/SARM, and `policy.reset()` is **never** called in shared mode (§8.3).
-
-**P4 — v1 re-derives latency compensation that already exists, on top of broken clocks.**
-v1 §8 specifies an in-flight RTT dict and manual stale-step trimming. `ActionQueue.merge(original, processed, real_delay, idx_before)` already trims `real_delay` stale steps and cross-validates against actions consumed in flight (`action_queue.py:219-246`). Worse, the legacy code compares wall clocks across machines (`robot_client.py:420` stamps `time.time()` "to compare timestamps across client and server"; `policy_server.py:178` compares it) — NTP skew is the same order as the latencies being measured. _Consequence_: the **monotonic iron rule** (§11): instants never cross machines; client timestamps are opaque echoed tokens; servers report only durations. `delay_steps = ceil((rtt + inference)/dt)` is computed client-side from client-local `perf_counter` samples and shipped per request.
-
-**P5 — One-in-flight per client is a correctness requirement, not a tuning choice.**
-At send time the client snapshots `idx_before = queue.get_action_index()` and the leftover prefixes; `merge` validates against them. Two in-flight requests carry conflicting snapshots — the second merge corrupts both RTC replace mode and append mode. The local RTC thread is also strictly one-inference-at-a-time; one-in-flight preserves exact parity. _Consequence_: the worker publishes one observation, waits for its chunk (or timeout), then sends the next. v1 §8.1's out-of-order in-flight dict is dead weight; a late chunk is accepted only if it answers the _latest_ outstanding `seq_id`, otherwise dropped.
-
-**P6 — v1's QoS table conflates transport reliability with congestion behavior.**
-"Reliable delivery for actions" sounds right but the dangerous knob is congestion control: a publisher configured `BLOCK` on the action topic can stall the **server's** publish path on one robot's dead uplink (Zenoh blocks up to `wait_before_close`, then may close the transport). A dropped action chunk is _recoverable by design_ — the client's queue keeps the robot moving and the next chunk replaces it. _Consequence_ (§6.3): actions = `reliability=RELIABLE` (hop-level) + `congestion_control=DROP` + `express=True` + `priority=INTERACTIVE_HIGH`; observations = `DROP` + `DATA`. If WAN loss proves material, upgrade the action topic to Zenoh Advanced Pub/Sub (cache + recovery, zenoh ≥ 1.5) rather than BLOCK.
-
-**P7 — Schema-less MessagePack invites silent version drift across a 300-robot fleet.**
-msgpack stays (zenoh's `ext` serializer cannot encode numpy/dataclasses, and the team's choice stands), but naked msgpack dicts across heterogeneous fleet versions fail at runtime, on the robot. _Consequence_ (§10.4): a packed little-endian **attachment header** (`schema_version`, `seq_id`, `episode_id`, `client_mono_ns` — the rmw_zenoh pattern) so routing/correlation never deserializes the body; `schema_version` negotiated at the session handshake; additive-only evolution; golden codec tests. Protobuf-over-ZBytes is the documented fallback if drift bites in practice.
-
-**P8 — "Deterministic rollout reproducibility" is unattainable on real robots.**
-No seed controls hardware, sensor noise, or network jitter; RTC's latency-driven trimming is inherently timing-dependent. _Consequence_: the contract is **fully logged + replayable** (§12): recording strategies already persist observations and executed actions; the remote engine adds `(session_id, seq_id, episode_id)` provenance so client datasets join server audit logs mechanically.
-
-**P9 — v1 has no safety specification.**
-"Log a warning when the buffer empties" is not a fail-safe for a 300-robot fleet. _Consequence_ (§9): a staleness bound (`max_action_age_s` — never execute an action older than X relative to its source observation), an explicit fallback ladder (`hold` / `repeat_last` / `zero` — zero-command required for future velocity-controlled robots), and a DEAD state that triggers the existing strategy shutdown path (return-to-initial-pose, disconnect) via the same `shutdown_event` mechanism RTC uses (`rtc.py:359-360`).
-
-**P10 — Capacity must be formula-driven, not "a user decision".**
-v1 §4 says clients-per-server "is a user decision". With `t` = server time per request, `r` = per-client request rate, `H` = RTC execution horizon, `dt` = control period:
-`N_max = min( 0.8 / (r·t),  (H·dt/2 − RTT_net) / t )`
-→ ACT @ 20 ms, 1 Hz: ~40 clients/GPU. Pi0 @ 150 ms, 1 Hz: ~5 clients/GPU. 300 robots on Pi0 ≈ 60 GPU pods. _Consequence_: the manifest carries `max_sessions`; the server rejects session opens beyond it (with current load in the reply) so clients retry another replica. Micro-batching is deferred — blocked on a real API issue (`predict_action_chunk` takes a _scalar_ `inference_delay`; batched clients have different delays) — behind a `Scheduler` seam so it can land later without redesign (§8.5).
-
-**P11 — Discovery ≠ multicast.**
-Zenoh's multicast scouting does not cross WAN, NAT, or most k8s CNIs. _Consequence_: multicast scouting disabled; clients use static `connect.endpoints` (DNS name of the router) + gossip; presence and liveness come from Zenoh **liveliness tokens** (§6.4), not discovery. "Discovery" for a robot fleet is configuration.
-
----
-
-## 5. System Topology
-
-![MaaS topology](MaaS_async_inference_diagram.png)
-_(Diagram unchanged from v1 — the topology survives; transport/QoS/session details in it are superseded by §6.)_
-
-- **Router tier**: one or more `zenohd` routers (k8s Deployment + Service, TLS on 7447). Robots **dial out** to the router (NAT-friendly: labs only need outbound 7447/443). GPU servers join as peers via cluster DNS.
-- **Server**: one process = one `(model_repo, revision, dtype, device)` on one GPU, pre-warmed from a YAML manifest (**KEPT** from v1, amended: `pin_task: bool` — VLA prompts may vary per session unless pinned).
-- **Client**: one robot running `lerobot-rollout --inference.type=remote`. Weightless: config-only policy metadata.
-- **Identity**: `client_uuid` per robot; `session_id` per connection epoch; both in every log line on both sides.
-
----
-
-## 6. Zenoh Design
-
-All Zenoh claims below were verified against zenoh / zenoh-python 1.x (eclipse-zenoh 1.9.0). Pin: `eclipse-zenoh>=1.9,<2.0`; keep `zenohd` on the same minor as the Python binding. Wheels cover manylinux x86_64/aarch64/armv7l/armv6l + macOS — Raspberry Pi edge clients are covered.
-
-### 6.1 Key-expression schema
-
-```
-@lerobot/<model_id>/<revision>/<task_slug>/<client_uuid>/obs       client → server
-@lerobot/<model_id>/<revision>/<task_slug>/<client_uuid>/action    server → client
-@lerobot/<model_id>/<revision>/<task_slug>/status                  queryable (capabilities)
-@lerobot/<model_id>/<revision>/<task_slug>/session                 queryable (open/validate)
-@lerobot/<model_id>/<revision>/<task_slug>/<client_uuid>/reset     queryable (episode boundary)
-@lerobot/<model_id>/<revision>/<task_slug>/<client_uuid>/alive     liveliness token (client)
-@lerobot/<model_id>/<revision>/<task_slug>/server/alive            liveliness token (server)
-```
-
-Rules (hard, enforced by a `sanitize_keyexpr()` helper):
-
-- Root at the **verbatim chunk** `@lerobot` — verbatim chunks are only matched by identical chunks, so third-party `**` subscribers on a shared router can never scrape the tree.
-- Sanitize every user-supplied segment (model ids, task strings, uuids): non-empty, no `* $ ? # /`, no leading/trailing/double `/`. A task string containing `/` must be slugified before it becomes a key chunk.
-- Server subscribes with a **single-depth** wildcard (`.../*/obs`) — never `**` (it would also match `status`, `alive`, …).
-- v1's `cluster/experiment` prefix segments are dropped from the key schema; they return as free-form `tags` metadata in the session handshake (telemetry/labeling, not routing). Routing topology belongs to deployment (which router you dial), not to key depth.
-
-### 6.2 Data plane vs. control plane (the rmw_zenoh split)
-
-- **Data plane = pub/sub** (KEPT from v1): observations up, action chunks down, correlated by `seq_id` in **attachments** (§10.4). Pub/sub rather than query-per-inference because: a timed-out query's late reply is _dropped by the transport_ (wasted inference), whereas a late pub/sub chunk is still mergeable if it answers the latest outstanding seq; and pub/sub leaves room for server-initiated messages (drain notices). The one-in-flight discipline (P5) is enforced in the client worker, not by the transport.
-- **Control plane = queryables** (request/reply with explicit timeouts; the pattern rmw*zenoh uses for ROS 2 services): `status` (pre-flight capability fetch, 2 s timeout), `session` (open/validate → ack with capabilities + `session_id`), `reset` (episode boundary — \_acknowledged*, so episodic strategies know the server-side episode state is clean). Always pass an explicit `timeout` to `session.get()` — the config default is 10 s, far too long for our watchdogs.
-- **Episode ordering**: under one-in-flight there is no obs/reset race window in the data plane, but as belt-and-braces the first observation of each episode also carries `episode_start=True` + the new `episode_id` in its header.
-
-### 6.3 QoS (revised from v1 §6.2 — see P6)
-
-| Topic              | reliability | congestion_control     | express  | priority         | Why                                                                                                                                                                                                                                              |
-| ------------------ | ----------- | ---------------------- | -------- | ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
-| `obs`              | default     | **DROP**               | false    | DATA             | Intentional drop already happened at the client's one-slot holder; if the uplink stalls, dropping a frame protects the control loop.                                                                                                             |
-| `action`           | RELIABLE    | **DROP** (never BLOCK) | **true** | INTERACTIVE_HIGH | Hop-level reliability over TCP; express skips batching for the small (4–50 KB) latency-critical payload; DROP so one dead robot uplink can never stall the server's publish path. Chunk loss is recoverable: the client buffer rides through it. |
-| control queryables | RELIABLE    | default                | —        | —                | Correctness over latency; explicit timeouts bound them.                                                                                                                                                                                          |
-
-Upgrade path if WAN chunk loss proves material: `AdvancedPublisher`/`AdvancedSubscriber` (zenoh ≥ 1.5) with a small cache + heartbeat-based recovery **on the action topic only**. Hop-by-hop RELIABLE is not end-to-end reliability — Zenoh has no broker persistence; a disconnected subscriber's data is gone. The design assumes this (client state machine, §9).
-
-### 6.4 Liveliness (presence + watchdogs)
-
-- Client declares a liveliness token on `.../<client_uuid>/alive`. The server liveliness-subscribes with `history=True`: token appear → ensure session state; token drop → GC the session (mailbox, processor instances) after a grace period.
-- Server declares `.../server/alive`. The client liveliness-subscribes: on drop → treat as RECONNECTING (§9), hold/fallback per config, re-run the `status`/`session` handshake when the token reappears.
-- Tune the transport lease down from its default so ungraceful-death detection is seconds, not tens of seconds (verify the default in the pinned version; it is config `transport/link/tx/lease`).
-- Liveliness cannot detect a _hung-but-connected_ server. The client's per-request timeout (`request_timeout_s`) is the authoritative watchdog — this is the structural fix for legacy BUG-3 (no deadlines on `GetActions`).
-
-### 6.5 Threading constraints (zenoh-python facts that shape both processes)
-
-- **No asyncio API** in zenoh-python — both client and server are thread-based. This matches the existing RTC engine pattern exactly.
-- Each callback-based subscriber spawns a dedicated Python thread; **blocking Zenoh calls inside callbacks are disallowed**. Callbacks must be deposit-only (write a slot, set an event, return).
-- Channel handlers (`FifoChannel`, `RingChannel`) are Rust-side; `try_recv()` polls without spawning Python threads. `RingChannel(1)` is native latest-only semantics.
-- No zero-copy path for our payloads (SHM API is `@_unstable` and same-host-only; `ZBytes` copy behavior undocumented). At ~200 KB × a few Hz per robot, one memcpy is irrelevant.
-
-### 6.6 Router deployment
-
-- `zenohd` official image as a k8s Deployment (1–N replicas; routers mesh and reroute around failures) behind a `LoadBalancer`/`NodePort` Service exposing TLS 7447. No official Helm chart exists — roll-your-own manifests.
-- `scouting.multicast.enabled: false`; `scouting.gossip.enabled: true`; clients/servers use static `connect.endpoints`.
-- **Auth**: mTLS per robot (`transport.link.tls` with `enable_mtls`) + router **ACL** keyed on `cert_common_names`: a robot's cert may only `put` to `@lerobot/**/<its-uuid>/obs` and receive on `.../<its-uuid>/action`. Caveat (flagged): ACL config reloads require a router restart — plan cert/ACL changes as rolling router restarts.
-- Security review input: the third-party Zenoh protocol security analysis (Census Labs, 2025) should be read before exposing 7447 publicly.
-
----
-
-## 7. The Statelessness Boundary (the load-bearing section)
-
-**Where the network cut goes.** The local RTC pipeline is:
-
-```
-obs (robot-processed dict)
-  → build_dataset_frame(hw_features, obs, "observation")        CLIENT  (cheap, hardware-coupled)
-─────────────────────────── network ───────────────────────────
-  → prepare_observation_for_inference(...)                      SERVER  (policy-coupled, heavy)
-  → per-session preprocessor(...)                               SERVER  (stateful within the request)
-  → policy.predict_action_chunk(obs, inference_delay, prefix)   SERVER  (pure for allowlisted policies)
-  → per-session postprocessor(...)                              SERVER  (reads state cached at preprocess)
-─────────────────────────── network ───────────────────────────
-  → ActionQueue.merge(original, processed, real_delay, idx_before)   CLIENT
-```
-
-Three consequences:
-
-1. **The server needs no cross-request state.** `RelativeActionsProcessorStep` writes `_last_state` at preprocess and the postprocessor reads it back _within the same request_. Per-session pipeline instances + one-request-at-a-time-per-session give correctness with zero persistent state.
-2. **RTC state stays client-side**, exactly where `RTCInferenceEngine` already keeps it. Each request ships: `inference_delay_steps = ceil(L_max/dt)` (from the client `LatencyTracker`, whose samples are full network-inclusive cycle times — RTT compensation falls out for free), `prefix_model = queue.get_left_over()[:H]`, and `prefix_robot = queue.get_processed_left_over()[:H]` (needed for server-side relative-prefix re-anchoring, mirroring `rtc.py:287-305`). The response returns **both** the model-space and robot-space chunks because `merge` needs both. ≤ `execution_horizon × action_dim` float32 each — a few hundred bytes.
-3. **G9 dies structurally.** No bespoke client resize (`F.interpolate` in legacy `helpers.py`), no client-side normalization. Clients ship native camera resolution; the server's canonical processor path does everything — serve-time preprocessing is byte-identical to train-time.
-
-**What the server _does_ hold** (and what it means):
-
-- Per-session processor instances (cheap; normalization stat tensors shared read-only).
-- Per-session episode counter + stats. Episode reset = reset the session's pipelines, clear its mailbox. **`policy.reset()` is never called in shared mode** — it is global to the shared policy instance and unnecessary for chunk-pure policies (ACT's ensembler and Pi0/SmolVLA's queues live in `select_action`, not `predict_action_chunk` — verified).
-- Policies that are _not_ chunk-pure get `serving_mode: exclusive` (§8.3).
-
----
-
-## 8. The Inference Server: `lerobot-policy-server`
-
-New package `src/lerobot/policy_server/`; console script `lerobot-policy-server --manifest manifest.yaml`.
-
-### 8.1 Process model — **KEPT** from v1, amended
-
-One process = one model+task on one GPU, loaded and warmed at startup (`warmup_inferences` dummy forwards; covers torch.compile). Multi-GPU nodes run N processes (`CUDA_VISIBLE_DEVICES` pinning). Dynamic model loading (`SendPolicyInstructions`) is **rejected**: pickle/RCE surface, arbitrary-download surface, and it destroys capacity planning. Amendment: `pin_task: false` (default) lets VLA clients set the task per session; `pin_task: true` rejects mismatched tasks at session open.
-
-### 8.2 Concurrency (pure threads — no asyncio in zenoh-python)
-
-```
-zenoh subscriber (.../*/obs)          inference worker (1 thread, owns GPU)
-  deposit-only callback:                loop:
-  slots[client_uuid] = sample   ──►       pick next session with pending obs (RR ring)
-  (per-client latest-only)                decode JPEG → per-session preprocess
-                                          predict_action_chunk(delay, prefix)
-control queryables (status/session/      per-session postprocess → encode
-  reset): validate, mutate session        publisher.put(.../<uuid>/action)
-  registry, reply                       (publishing from the worker thread is fine)
-```
-
-- **Per-client latest-only mailbox**: a wildcard subscriber with a deposit-only callback writing per-client slots (scales to dynamic fleets), or — when the manifest enumerates clients — one `RingChannel(1)` subscriber per client polled via `try_recv()`. Either way: newest observation wins; a superseded request is counted (`superseded_seqs` in the next response) so drops are visible. This deletes legacy BUG-4 (`observations_similar` + `must_go`) by construction — the **client** decides when to request; the server never second-guesses observation content.
-- **Single inference worker**: torch releases the GIL inside `forward`, callbacks stay responsive. Strict round-robin over sessions with pending observations: each gets exactly one inference per cycle; starvation is structurally impossible. Overload degrades into longer cycle times → larger (but correct) client `delay_steps` → eventually the client staleness bound trips and the robot holds — safe by construction.
-
-### 8.3 Chunk-stateless allowlist and serving modes
-
-At startup the server classifies the loaded policy:
-
-| Class           | Policies (verified)                                                                              | Mode                                                                                                                                                    |
-| --------------- | ------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| chunk-stateless | ACT, Pi0, Pi0.5, SmolVLA (and any policy whose `predict_action_chunk` touches no instance state) | `shared`: N sessions, per-session pipelines, `policy.reset()` never called                                                                              |
-| chunk-stateful  | Diffusion family (`predict_action_chunk` reads `select_action`-fed `self._queues`)               | `exclusive`: `max_sessions=1` enforced; episode reset additionally calls `policy.reset()`; second session open → rejected with a self-explanatory error |
-| no chunk API    | SAC, SARM                                                                                        | refused at startup                                                                                                                                      |
-
-Implemented as a registry in `policy_server/validation.py`; the cleaner follow-up is a `supports_stateless_chunking` class attribute on `PreTrainedPolicy` (needs a pass over policy families — roadmap §14).
-
-### 8.4 Session open & capability validation (fail fast, fail loud)
-
-`session` queryable payload: `client_uuid`, `policy_type`, `fps`, feature summary (post-rename observation feature names + shapes, ordered action keys), `schema_version`, RTC intent, `tags`. Checks:
-
-| Check                      | Rule                                                            | On mismatch                                                                        |
-| -------------------------- | --------------------------------------------------------------- | ---------------------------------------------------------------------------------- |
-| Action names **and order** | must equal server's `action_feature_names` exactly              | **hard reject** — this is the sync-safety contract mapping chunk columns to motors |
-| Camera names               | client set must cover `policy.config.input_features` image keys | hard reject                                                                        |
-| Resolution                 | any H×W accepted (server resizes canonically)                   | warn if aspect ratio differs from training                                         |
-| State dim                  | flattened dim must match                                        | hard reject                                                                        |
-| `schema_version`           | client within server's supported range                          | hard reject                                                                        |
-| fps                        | vs. manifest `trained_fps`                                      | warn (reject only when `strict_fps: true`)                                         |
-| Task                       | when `pin_task: true`, must equal `default_task`                | reject                                                                             |
-| RTC                        | client RTC requires policy RTC kwargs support                   | downgrade to append mode + warning                                                 |
-| Capacity                   | `active_sessions < max_sessions`                                | reject with current load → client retries another replica                          |
-
-Reply: `session_id`, model info (repo, revision — consider a checkpoint hash, §15), `action_feature_names`, `chunk_size`, `trained_fps`, `supports_rtc`, `serving_mode`, `warmed_up`, `schema_version`, warnings. **rename_map is applied client-side** so the wire format is canonical policy-feature keys across heterogeneous robots (also a prerequisite for future batching).
-
-### 8.5 Scheduler seam (micro-batching later, not in v1)
-
-The worker calls a `Scheduler.select(ready: list[Session]) -> list[Session]`; v1 ships `RoundRobin` (`return ready[:1]`). Cross-session batching is blocked on the policy API (`inference_delay` is scalar; batched clients have different delays/prefixes) — when that lands, a `MicroBatch` scheduler groups same-shape sessions. The seam costs nothing now and prevents a redesign later.
-
-### 8.6 Manifest
-
-```yaml
-model:
-  {
-    repo_or_path: lerobot/pi0_towels,
-    revision: main,
-    dtype: bfloat16,
-    device: cuda,
-  }
-default_task: "fold the towel"
-pin_task: false
-serving_mode: shared # forced to exclusive for chunk-stateful policies
-max_sessions: 5 # from the §P10 formula: Pi0 @150ms, 1 Hz refresh
-warmup_inferences: 2
-strict_fps: false
-zenoh:
-  connect_endpoints: ["tls/router.gpu-cluster.internal:7447"]
-  tls:
-    {
-      connect_certificate: ...,
-      connect_private_key: ...,
-      root_ca_certificate: ...,
-    }
-health_port: 9100 # HTTP health + Prometheus metrics
-debug: { capture_dir: null, capture_max: 256 }
-```
-
-Draccus dataclass in `policy_server/manifest.py`; YAML via `--manifest`, individual overrides via CLI.
-
----
-
-## 9. The Edge Client: `RemoteInferenceEngine`
-
-New file `src/lerobot/rollout/inference/remote.py`, registered `@InferenceEngineConfig.register_subclass("remote")`.
-
-### 9.1 Threading model
-
-| Thread                           | Role                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
-| -------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| Main (strategy loop)             | `notify_observation(obs)` → lock-protected latest-only slot (identical to `rtc.py` `_obs_holder`). `get_action()` → `ActionQueue.get()` + staleness check. **Never any I/O.** Structurally fixes legacy BUG-1 (blocking send inside the 33 ms loop).                                                                                                                                                                                                        |
-| Network worker (1 daemon thread) | Cycle: wait until `queue_remaining·dt ≤ buffer_time_s` and active → snapshot `idx_before`, prefixes, `delay_steps = ceil(L_max/dt)` → encode (JPEG q=`jpeg_quality`) → `publisher.put(obs, attachment=header)` → await chunk on the action subscriber channel (timeout `request_timeout_s`) → `merge(original, processed, ceil(L/dt), idx_before)` → `latency_tracker.add(L)`. Owns the state machine, reconnects, and control queries. One-in-flight (P5). |
-| Zenoh action subscriber          | `FifoChannel(2)` handler drained by the worker (no Python callback thread on the hot path); liveliness subscriber callback is deposit-only (sets an event).                                                                                                                                                                                                                                                                                                 |
-
-Reused unchanged: `ActionQueue` (`policies/rtc/action_queue.py`), `LatencyTracker`, `ActionInterpolator` (lives in strategies — `interpolation_multiplier` works with remote for free). Deleted concepts: aggregation zoo, `observations_similar`, `must_go`, `TimedObservation`/`TimedAction` pickles.
-
-### 9.2 Fail-safe state machine
-
-```
-              ok                              no chunk for degraded_after_s
- CONNECTING ─────► STREAMING ───────────────────────────────► DEGRADED
-   │ ▲               ▲   │ queue empty OR max_action_age_s hit     │
-   │ │ backoff,      │   └───────────────────────────────────► STALLED ◄──┘
-   │ │ re-handshake  │ first successful merge                      │
-   │ └─ RECONNECTING ◄── timeout streak / server liveliness drop ◄─┘
-   │        │ offline > max_offline_s, capability/schema mismatch, auth failure
-   └──────► DEAD  (failed=True → shutdown_event → strategy teardown: return-to-initial-pose)
-```
-
-- **DEGRADED**: requests failing but the queue still holds actions — the robot keeps executing; chunks _are_ the fault-tolerance buffer (1–3 s of coverage makes blips and clean server drains invisible).
-- **STALLED**: queue empty or staleness bound hit → apply `fallback`: `hold` (`get_action` → `None`; `send_next_action` already tolerates it), `repeat_last`, or `zero` (required for velocity-controlled robots, where "send nothing" means "keep last velocity").
-- **Staleness bound** (sync safety): every merge records `(chunk_start_index, t_send)`; `get_action` refuses any action whose source observation is older than `max_action_age_s` (default 3.0 s ≈ 90 steps @ 30 fps). Bounds open-loop execution after a network stall.
-- **DEAD**: only after `max_offline_s` (default 60 s) or a hard contract violation (capability/schema mismatch on reconnect — e.g. the server restarted with a different model; never execute wrong-model chunks). Uses the exact mechanism RTC uses (`failed=True` + global `shutdown_event`) so existing teardown runs unchanged.
-- **Watchdog layering**: per-request timeout (hung server — the BUG-3 fix) → server liveliness token (dead server/router) → staleness bound (the robot-side invariant that holds regardless of why data stopped).
-- **Pause/resume (DAgger)**: `pause()` stops the worker publishing (slot keeps refreshing, ignored); queue intact — parity with `RTCInferenceEngine.pause`. DAgger's existing `interpolator.reset(); engine.reset(); engine.resume()` sequence works unchanged.
-- **`reset()` (episode boundary)**: clear `ActionQueue` + staleness bookkeeping, bump `episode_id`, fire the acked `reset` query (1 s timeout, failure logged — the server has nothing it _must_ do thanks to per-request statelessness), flag `episode_start` on the next observation. `LatencyTracker` intentionally survives reset (latency is episode-invariant; parity with local RTC).
-- **`ready`** = session opened ∧ capabilities validated ∧ server `warmed_up`. First-chunk gating is implicit (`get_action` → `None` until the first merge).
-
-### 9.3 Weightless client — exact integration changes
-
-- `rollout/context.py`: `PolicyContext.{policy, preprocessor, postprocessor}` become `| None`. For remote configs, skip step 1 (weight load / PEFT / `.to(device)` / torch.compile / `init_rtc_processor`) and step 6 (`make_pre_post_processors`). Verified safe: strategies only consume `ctx.policy.inference`. Keep steps 2–5 (robot processors, hardware, features, dataset) — they are robot-derived. Keep the visual pre-flight check (`context.py:309-324`): `--policy.path` already loads config-only (`rollout/configs.py:324-328`, no weight download) and failing before dialing the server is free. `use_torch_compile` / explicit `--device` → warn-and-ignore for remote.
-- `rollout/inference/factory.py`: signature loosens to `policy: PreTrainedPolicy | None` (+ `policy_config: PreTrainedConfig`); `sync`/`rtc` branches guard `policy is None`; the `remote` branch lazy-imports (`eclipse-zenoh` stays an optional extra).
-- The authoritative validation moves to session open (§8.4); the local check becomes a fast-fail convenience.
-
-### 9.4 Config
-
-```python
-@InferenceEngineConfig.register_subclass("remote")
-@dataclass
-class RemoteInferenceConfig(InferenceEngineConfig):
-    connect_endpoint: str = "tls/localhost:7447"   # zenoh router endpoint
-    tls_cert: str | None = None; tls_key: str | None = None; tls_ca: str | None = None
-    client_uuid: str = ""                # "" → uuid4 at start()
-    jpeg_quality: int = 90               # 0 = raw (LAN/debug)
-    buffer_time_s: float = 0.5           # send next obs when queue playback ≤ this (v1 G14) — KEPT
-    max_action_age_s: float = 3.0        # staleness bound (safety)
-    degraded_after_s: float = 1.0
-    request_timeout_s: float = 5.0
-    reconnect_initial_backoff_s: float = 0.5
-    reconnect_max_backoff_s: float = 10.0
-    max_offline_s: float = 60.0
-    fallback: FallbackBehavior = FallbackBehavior.HOLD   # hold | repeat_last | zero
-    rtc: RTCConfig = field(default_factory=RTCConfig)    # enabled → replace mode; horizon caps prefix
-    tags: dict[str, str] = field(default_factory=dict)   # ex-cluster/experiment labels
-```
-
-```bash
-# Remote RTC + sentry recording (the reproducibility path)
-lerobot-rollout \
-    --strategy.type=sentry \
-    --policy.path=lerobot/pi0_towels \                 # config-only: no weights downloaded
-    --inference.type=remote \
-    --inference.connect_endpoint=tls/router.gpu-cluster.internal:7447 \
-    --inference.rtc.execution_horizon=10 \
-    --robot.type=so100_follower --robot.port=/dev/ttyACM0 \
-    --robot.cameras="{front: {type: opencv, index_or_path: 0, width: 640, height: 480, fps: 30}}" \
-    --dataset.repo_id=user/rollout_fleet_a --dataset.single_task="fold the towel"
-```
-
----
-
-## 10. Wire Schema
-
-### 10.1 Payload anatomy & rates — **KEPT** (JPEG) with numbers
-
-Upstream per request: joints (24–128 B) + JPEG frames (480p q90 ≈ 40–90 KB each; 720p ≈ 110–230 KB) + RTC prefixes (≤ a few KB) → 60–450 KB depending on cameras. Downstream: `2 × chunk_size × action_dim × 4 B` + metadata → 3–50 KB. Effective request rate is self-clocked by `buffer_time_s` to ~1–4 Hz per robot (not the 30 Hz control rate). 300 robots ≈ 0.3–10 Mbps each — the wire is never the bottleneck; bandwidth budgeting is about camera count/resolution, and each GPU pod only ever sees its own ≤ `max_sessions` clients. Zenoh fragments >64 KiB payloads transparently; multi-MB messages are fine.
-
-### 10.2 Attachment header (fixed-layout, packed little-endian — parsed without touching the body)
-
-| Field            | Type | Notes                                                          |
-| ---------------- | ---- | -------------------------------------------------------------- |
-| `schema_version` | u16  | negotiated at session open                                     |
-| `msg_type`       | u8   | OBS / CHUNK / EVENT                                            |
-| `seq_id`         | u64  | per-session monotonic; echoed in the chunk                     |
-| `episode_id`     | u32  | bumped by `reset()`                                            |
-| `client_mono_ns` | i64  | client `monotonic_ns()`; **opaque to the server, echoed back** |
-| `session_epoch`  | u32  | bumped per (re)connect; stale-epoch chunks dropped             |
-
-### 10.3 msgpack bodies
-
-**ObservationMsg** (client → server): `state: {names_ref, data: f32 LE bytes}`, `images: {name: {codec: jpeg|raw, bytes, (h,w,c) if raw}}`, `task: str`, `inference_delay_steps: int`, `prefix_model: tensor?`, `prefix_robot: tensor?` (tensors = raw LE bytes + dtype + shape), `episode_start: bool`.
-**ActionChunkMsg** (server → client): `seq_id_echo`, `client_mono_ns_echo`, `chunk_model: tensor`, `chunk_robot: tensor`, `queue_wait_ms: f32`, `inference_ms: f32`, `superseded_seqs: u32`, `server_load: f32`.
-**Status / SessionOpen / SessionAck / ResetMsg**: as specified in §8.4.
-
-### 10.4 Schema discipline (P7)
-
-`schema_version` gates at handshake; evolution is additive-only (new optional msgpack keys; unknown keys ignored); attachment layout changes require a version bump; golden codec round-trip tests (tensor exactness, JPEG RGB-channel-order regression — a silent BGR swap poisons every VLA in the fleet) are part of the test suite. **No pickle anywhere** — KEPT from v1 and now structural: nothing in the schema can carry code.
-
----
-
-## 11. Latency Budget & the Clock Iron Rule
-
-| Stage                          | LAN             | WAN (50 ms RTT) |
-| ------------------------------ | --------------- | --------------- |
-| JPEG encode ×3 (edge CPU)      | 2–9 ms          | 2–9 ms          |
-| Serialize                      | <1 ms           | <1 ms           |
-| Uplink (tx + ½RTT)             | ~2 ms           | ~54 ms          |
-| Server queue wait              | 0 → 1×inference | 0 → 1×inference |
-| Decode + canonical preprocess  | 4–10 ms         | 4–10 ms         |
-| **Inference**                  | **15–150 ms**   | **15–150 ms**   |
-| Postprocess + downlink + merge | ~2 ms           | ~27 ms          |
-| **Total (Pi0-class)**          | **~110–175 ms** | **~190–250 ms** |
-
-Inference is 60–85 % of end-to-end on LAN; the entire transport+serialization stack is <10 ms. WAN adds propagation + uplink bandwidth — identical under any transport. At 30 fps this lands `delay_steps` ≈ 4–8, comfortably inside RTC execution horizons: WAN degrades smoothness parameters, never correctness. _This table is the standing answer to transport-performance bikeshedding._
-
-**Clock iron rule** (P4): wall-clock instants never cross machines. Client stamps `monotonic_ns`, the server echoes it opaquely; `RTT = now − echo`. The server reports only **durations** (`queue_wait_ms`, `inference_ms`) measured on its own monotonic clock; `network_time = RTT − queue_wait − inference` for diagnostics. The schema has no field in which a foreign wall-clock instant can be compared — the legacy `time.time()` bug is unrepresentable.
-
----
-
-## 12. Reproducibility & Audit (P8)
-
-The contract is **fully logged + replayable**, not "deterministic":
-
-- **Client = source of truth.** Recording strategies already persist observations + executed actions to `LeRobotDataset`. The remote engine logs, per executed action, the `(session_id, seq_id, episode_id)` of its source chunk plus the echoed `queue_wait_ms`/`inference_ms` (dataset-extras columns are a follow-up; client logs in v1).
-- **Server audit line per request** (structured JSON): `{ts, session_id, client_uuid, seq_id, episode_id, queue_wait_ms, inference_ms, chunk_range, superseded_seqs, outcome}`.
-- **Optional bounded capture**: `debug.capture_dir` writes a ring of request/response pairs (safetensors) for byte-exact offline replay through the same server pipeline.
-- **Runbook — "robot #217 stuttered at 14:03"**: (1) Grafana `session_staleness{client="217"}` — spike ⇒ server side, flat ⇒ client/network. (2) Server side: audit lines — `queue_wait_ms` rising across _all_ sessions ⇒ overloaded replica (check `active_sessions` vs `max_sessions`); `superseded_seqs` streak on 217 only ⇒ that client over-requesting; `outcome=error` ⇒ adjacent stack trace. (3) Client side: state-machine transitions + reconnects in the client log; dataset rows show which seq's chunk was executing and where `None` ticks occurred. Every hop shares `(session_id, seq_id)` — the join is mechanical.
-
----
-
-## 13. Integration & Migration Plan
-
-### 13.1 New
-
-| Path                                                                                                | Content                                                                                                                                                                                                                     |
-| --------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `src/lerobot/policy_server/{__init__,schema,codec,manifest,session,scheduler,validation,server}.py` | wire schema constants, msgpack/attachment codecs, manifest dataclasses, `Session` + mailbox, `Scheduler` seam, capability rules + chunk-stateless registry, zenoh servicer + inference worker + drain + HTTP health/metrics |
-| `src/lerobot/rollout/inference/remote.py`                                                           | `RemoteInferenceEngine` (~600 lines; mirrors `rtc.py` structure)                                                                                                                                                            |
-| `src/lerobot/scripts/lerobot_policy_server.py` + `[project.scripts]` entry                          | thin `main()`                                                                                                                                                                                                               |
-| `docker/Dockerfile.policy-server`                                                                   | CUDA runtime base + uv; manifest via ConfigMap                                                                                                                                                                              |
-| `docs/source/remote_inference.mdx` (+ `_toctree.yml`)                                               | replaces `async.mdx`                                                                                                                                                                                                        |
-
-### 13.2 Modified
-
-`rollout/inference/factory.py` (config + Optional-typed signature + lazy import) · `rollout/context.py` (weightless branch) · `rollout/inference/__init__.py` · `scripts/lerobot_rollout.py` docstring · `pyproject.toml`: `[async]` extra becomes `eclipse-zenoh>=1.9,<2.0` + `msgpack` (grpcio/matplotlib leave it; grpcio remains under `[hilserl]`/`dev` for the RL stack).
-
-### 13.3 Removed — same landing PR
-
-`src/lerobot/async_inference/` · `tests/async_inference/` · `docs/source/async.mdx` + its `_toctree.yml` entry · the `AsyncInference` service + `Observation`/`Actions`/`PolicySetup` messages from `src/lerobot/transport/services.proto` (regenerate pb2; **`LearnerService` untouched** — `transport/` is shared with HIL-SERL (`src/lerobot/rl/`); the RL test suite gates this change).
-
-### 13.4 Legacy config → successor mapping
-
-| Legacy (`RobotClientConfig`/`PolicyServerConfig`) | Successor                                                  |
-| ------------------------------------------------- | ---------------------------------------------------------- |
-| `server_address`                                  | `--inference.connect_endpoint` (zenoh router)              |
-| `policy_type`, `pretrained_name_or_path`          | `--policy.path` (config-only) + server manifest            |
-| `chunk_size_threshold` (0–1 ratio)                | `--inference.buffer_time_s` (seconds)                      |
-| `actions_per_chunk`                               | server manifest (validated at session open)                |
-| `aggregate_fn_name` + `AGGREGATE_FUNCTIONS`       | **dropped** — `ActionQueue` replace/append                 |
-| `policy_device`, `client_device`                  | **dropped** — server concern / chunks arrive CPU f32       |
-| `debug_visualize_queue_size`                      | **dropped** — Rerun (`--display_data`) + engine stats      |
-| `PolicyServerConfig.{host,port}`                  | manifest `zenoh.connect_endpoints`                         |
-| `inference_latency`, `obs_queue_timeout`          | **dropped** — latency client-measured; no server obs queue |
-| `SendPolicyInstructions`                          | **dropped** — MaaS manifest + session validation           |
-| `observations_similar` / `must_go`                | **dropped** — latest-only slots + client send gate         |
-| pickle envelopes                                  | **dropped** — msgpack + attachment headers                 |
-
-### 13.5 Legacy bugs/gaps → structural resolution
-
-BUG-1 → worker thread owns all I/O. BUG-2 → aggregation deleted; `ActionQueue` is internally locked. BUG-3 → per-request timeout + liveliness. BUG-4 → client-side send gating; server newest-wins. G1 → per-session registry. G2 → manifest. G4 → msgpack+attachments. G5 → monotonic echo + `delay_steps`. G7 → recording strategies. G8 → mTLS + ACL. G9 → server-side canonical processors. G11 → `status` queryable. G12 → Prometheus + audit logs. G13 → `lerobot-policy-server` console script. G14 → `buffer_time_s`.
-
-### 13.6 Tests
-
-- **Unit**: codec round-trips (tensor exact; JPEG RGB-order regression), capability-validation matrix (§8.4 as parametrized cases), scheduler fairness + newest-wins supersession (mock policy with configurable sleep), manifest parsing, key-expr sanitization.
-- **Loopback integration** (CPU, fast CI): client+server in one process over zenoh peer-to-peer (or a localhost `zenohd` started by the fixture), tiny-ACT, fake 2-camera robot, N=8 concurrent sessions. The headline regression: two sessions with different joint states must not cross-contaminate `RelativeActionsProcessorStep` postprocessing — the test that proves the multi-tenancy claim.
-- **Chaos**: kill the server mid-episode → client returns `None`, never raises into the control loop, `failed` stays False within `max_offline_s`, resumes on restart; `docker kill zenohd` → liveliness flap → safe state → re-handshake (explicitly tests re-declaration behavior, flagged unverified upstream); SIGTERM drain → in-flight chunk completes, clients reconnect invisibly.
-- **Golden parity**: remote RTC vs local `RTCInferenceEngine` on identical observation sequences → byte-identical merged queues (the re-anchoring contract test). Gate for any real-robot remote-RTC use.
-
----
-
-## 14. Roadmap
-
-1. **PR1 — schema & codecs** (no torch deps): `policy_server/{schema,codec,manifest}.py`, key-expr sanitizer, golden codec tests.
-2. **PR2 — server core**: session registry, scheduler, validation/allowlist, inference worker with mock policy, loopback harness.
-3. **PR3 — client engine**: `RemoteInferenceEngine`, factory/context weightless integration, loopback integration + chaos + golden-parity tests.
-4. **PR4 — ops & docs**: Dockerfile, health/metrics, drain, ACL examples, `remote_inference.mdx`, rollout docstring.
-5. **Landing PR — legacy deletion**: remove `async_inference/` + tests + docs + proto service (RL suite gates), `[async]` extra swap.
-6. **Pre-release field validation**: one real robot on a lossy network (watchdog default tuning); JPEG q90 vs raw A/B on one policy (train/serve shift).
-7. **Future**: micro-batching (needs per-sample `inference_delay` across policy families), client-side downscale-to-policy-resolution (config-only shapes make it possible), Advanced Pub/Sub on the action topic, per-robot quotas, dataset provenance columns, `supports_stateless_chunking` attribute upstreamed to policy classes.
-
----
-
-## 15. Open Risks
-
-| Risk                                                                                                                                                                          | Mitigation / decision needed                                                                                                                                  |
-| ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| Re-anchoring parity (server-side relative-prefix re-anchor vs `rtc.py`)                                                                                                       | Golden parity test (§13.6) is a hard gate before robot use; likely failure mode is normalizer dtype/device drift                                              |
-| First-chunk over-trim when idle: `merge` trims `ceil(L/dt)` even when nothing was consumed (queue empty at episode start) — wasteful at network latencies (600 ms ⇒ 18 steps) | Proposed clamp `real_delay = min(real_delay, last_index - idx_before)` touches the shared `ActionQueue` used by local RTC — needs sign-off + regression tests |
-| JPEG train/serve distribution shift                                                                                                                                           | Unmeasured; A/B before locking q90 default (roadmap §14.6)                                                                                                    |
-| Watchdog defaults untuned (`request_timeout_s=5`, `degraded_after_s=1`, `max_action_age_s=3`)                                                                                 | Field validation on wired and Wi-Fi; consider named profiles                                                                                                  |
-| Capability check can pass while semantics differ (different finetune, different normalization stats, identical feature names)                                                 | Add checkpoint hash/revision pinning to SessionAck — decide in PR2                                                                                            |
-| zenoh-python long-session maturity: re-declaration after router restart partially verified; SHM unstable; no asyncio                                                          | Chaos tests own this; thread-based design avoids the asyncio gap entirely                                                                                     |
-| Router ACL reload requires restart                                                                                                                                            | Operational runbook: cert/ACL changes = rolling router restart                                                                                                |
-| `fallback=zero` has no consumer until velocity actions land in rollout (only `.pos` features routed today)                                                                    | Validate the enum against robot capabilities when velocity support lands                                                                                      |
-| Per-client mailbox memory under fleet-scale wildcard subscription                                                                                                             | One decoded-obs slot per client is small; add an LRU GC tied to liveliness drops                                                                              |

docker/Dockerfile.policy-server

@@ -1,82 +0,0 @@
-# Copyright 2026 The HuggingFace Inc. team. All rights reserved.
-#
-# Licensed under the Apache License, Version 2.0 (the "License");
-# you may not use this file except in compliance with the License.
-# You may obtain a copy of the License at
-#
-#     http://www.apache.org/licenses/LICENSE-2.0
-#
-# Unless required by applicable law or agreed to in writing, software
-# distributed under the License is distributed on an "AS IS" BASIS,
-# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
-# See the License for the specific language governing permissions and
-# limitations under the License.
-
-# This Dockerfile builds a GPU inference pod for `lerobot-policy-server`
-# (remote inference over Zenoh). It starts from an NVIDIA CUDA base image;
-# the cu128 PyTorch wheels bundle their own CUDA runtime (driver floor 570.86,
-# see pyproject.toml [tool.uv]).
-
-# docker build -f docker/Dockerfile.policy-server -t lerobot-policy-server .
-# docker run --gpus all -v ./server.yaml:/etc/lerobot/server.yaml lerobot-policy-server
-#
-# Extra policy-family dependencies (e.g. pi0/smolvla need transformers) can be
-# added at build time:
-#   docker build -f docker/Dockerfile.policy-server \
-#       --build-arg LEROBOT_EXTRAS="async pi0" -t lerobot-policy-server .
-
-# Configure the base image (same CUDA family as Dockerfile.internal)
-ARG CUDA_VERSION=12.8.1
-ARG OS_VERSION=24.04
-FROM nvidia/cuda:${CUDA_VERSION}-base-ubuntu${OS_VERSION}
-
-# Define Python version and lerobot extras arguments
-ARG PYTHON_VERSION=3.12
-ARG LEROBOT_EXTRAS="async"
-
-# Configure environment variables
-ENV DEBIAN_FRONTEND=noninteractive \
-    PATH=/lerobot/.venv/bin:$PATH
-
-# Install system dependencies and uv (as root).
-# Kept lean: no hardware/teleop libraries — this image only serves policies.
-RUN apt-get update && apt-get install -y --no-install-recommends \
-    git curl ca-certificates libglib2.0-0 ffmpeg \
-    && curl -LsSf https://astral.sh/uv/install.sh | sh \
-    && mv /root/.local/bin/uv /usr/local/bin/uv \
-    && useradd --create-home --shell /bin/bash user_lerobot \
-    && apt-get clean && rm -rf /var/lib/apt/lists/*
-
-# Create application directory and set permissions
-WORKDIR /lerobot
-RUN chown -R user_lerobot:user_lerobot /lerobot
-
-# Switch to the non-root user
-USER user_lerobot
-
-# Model checkpoints are cached under HF_HOME — mount it as a volume
-# (or a PVC in Kubernetes) so warm restarts skip the Hub download.
-ENV HOME=/home/user_lerobot \
-    HF_HOME=/home/user_lerobot/.cache/huggingface \
-    HF_LEROBOT_HOME=/home/user_lerobot/.cache/huggingface/lerobot \
-    TORCH_HOME=/home/user_lerobot/.cache/torch \
-    TRITON_CACHE_DIR=/home/user_lerobot/.cache/triton
-
-# Create the virtual environment (Python provisioned by uv)
-RUN uv venv --python ${PYTHON_VERSION}
-
-# Install lerobot from the build context with the async extra
-# (eclipse-zenoh + msgpack — see pyproject.toml [project.optional-dependencies])
-COPY --chown=user_lerobot:user_lerobot setup.py pyproject.toml uv.lock README.md MANIFEST.in ./
-COPY --chown=user_lerobot:user_lerobot src/ src/
-
-RUN uv sync --locked --no-cache $(printf -- '--extra %s ' ${LEROBOT_EXTRAS})
-
-# HTTP health + Prometheus metrics (manifest `health_port`, 0 disables)
-EXPOSE 9100
-
-# The manifest is typically mounted as a ConfigMap (Kubernetes) or a bind
-# mount (docker run -v) at /etc/lerobot/server.yaml; any field can also be
-# overridden on the command line, e.g. --model.repo_or_path=lerobot/pi0_towels
-ENTRYPOINT ["lerobot-policy-server"]
-CMD ["--manifest", "/etc/lerobot/server.yaml"]

docs/source/_toctree.yml

@@ -45,6 +45,8 @@
     title: Language Columns and Recipes
   - local: tools
     title: Tools
+  - local: annotation_pipeline
+    title: Annotation Pipeline
   - local: video_encoding_parameters
     title: Video encoding parameters
   - local: streaming_video_encoding
@@ -67,8 +69,14 @@
     title: VLA-JEPA
   - local: eo1
     title: EO-1
+  - local: lingbot_va
+    title: LingBot-VA
+  - local: fastwam
+    title: FastWAM
+  - local: evo1
+    title: EVO1
   - local: groot
-    title: NVIDIA GR00T N1.5
+    title: NVIDIA GR00T
   - local: xvla
     title: X-VLA
   - local: multi_task_dit
@@ -87,8 +95,8 @@
 - sections:
   - local: inference
     title: Policy Deployment (lerobot-rollout)
-  - local: remote_inference
-    title: Remote Inference (lerobot-policy-server)
+  - local: async
+    title: Use Async Inference
   - local: rtc
     title: Real-Time Chunking (RTC)
   title: "Inference"
@@ -157,14 +165,24 @@
     title: OpenArm
   - local: rebot_b601
     title: reBot B601-DM
+  - local: third_party_robots
+<<<<<<< Updated upstream
+    title: Third-Party Robots Packages
+=======
+    title: Third-Party Robots & Teleoperators
+>>>>>>> Stashed changes
   title: "Robots"
 - sections:
   - local: phone_teleop
     title: Phone
+  - local: isaac_teleop
+    title: Isaac Teleop
   title: "Teleoperators"
 - sections:
   - local: cameras
     title: Cameras
+  - local: third_party_sensors
+    title: Third-Party Cameras & Sensors
   title: "Sensors"
 - sections:
   - local: notebooks

docs/source/annotation_pipeline.mdx

@@ -0,0 +1,291 @@
+# Annotation Pipeline
+
+`lerobot-annotate` watches each episode's video with a vision-language
+model (VLM) and writes natural-language annotations back into your
+dataset. It fills the two language columns from the
+[Language Columns and Recipes](./language_and_recipes) page —
+`language_persistent` and `language_events` — straight into
+`data/chunk-*/file-*.parquet`.
+
+In short: point it at a LeRobot dataset, and it adds subtasks, plans,
+memory, interjections, speech, and visual Q&A that a policy can be
+trained on.
+
+## How it fits together
+
+```text
+  your dataset                  lerobot-annotate
+  (LeRobot v3.1)
+        │
+        ▼
+  ┌─────────────────────────────────────────────────────┐
+  │                    read episodes                     │
+  └──────────────────────────┬──────────────────────────┘
+                             │
+        ┌────────────────────┼────────────────────┐
+        ▼                    ▼                     ▼
+  ┌──────────┐      ┌───────────────┐        ┌──────────┐       one shared Qwen-VL
+  │   plan   │      │ interjections │        │   vqa    │  ◀──   server (vLLM, OpenAI
+  └────┬─────┘      └───────┬───────┘        └────┬─────┘        API) drives all three
+       └────────────────────┼─────────────────────┘
+                            │   each module stages raw JSONL
+                            ▼   into .annotate_staging/
+                  ┌─────────────────┐
+                  │    validator    │  ◀──  checks everything
+                  └────────┬────────┘
+                           ▼
+                  ┌─────────────────┐
+                  │     writer      │
+                  └────────┬────────┘
+                           ▼
+              data/chunk-*/file-*.parquet
+              (+ meta/info.json tools)
+```
+
+Three modules (`plan`, `interjections`, `vqa`) all talk to **one** shared
+VLM. Each module stages its output to disk, a validator checks it, and a
+single writer rewrites the dataset shards in place.
+
+## What the pipeline produces
+
+Each module emits a few kinds of annotation ("styles"), routed to one of
+the two language columns:
+
+| Style / atom                                | Column                | Module          |
+| ------------------------------------------- | --------------------- | --------------- |
+| `subtask` (Pi0.7-style "how, not what")     | `language_persistent` | `plan`          |
+| `plan` (initial + refresh on interjection)  | `language_persistent` | `plan`          |
+| `memory` (MEM-style compression)            | `language_persistent` | `plan`          |
+| `task_aug` (rephrasings of the task)        | `language_persistent` | `plan`          |
+| `interjection`                              | `language_events`     | `interjections` |
+| speech tool-call atom (`style=null`, `say`) | `language_events`     | `interjections` |
+| `vqa` (user / assistant pair)               | `language_events`     | `vqa`           |
+
+### How subtasks are generated
+
+The `plan` module doesn't ask the VLM for subtasks in one shot. Instead
+it uses a two-step **describe → segment** flow:
+
+1. **Describe** — the VLM narrates only what it actually sees in the
+   chosen camera (no guessing about the task).
+2. **Segment** — that description is fed back in, and the VLM splits the
+   episode into consecutive atomic subtasks.
+
+Both passes see the episode as **timestamped contact sheets** — frames
+sampled at `frames_per_second` (0.5s by default) and packed into JPEG
+grids with each frame's time burned into its corner, so the VLM cites
+exact boundary times directly. This is far cheaper in vision tokens than
+one image per frame, so the sampling can stay dense; episodes longer than
+`max_frames_per_prompt` are split into windows at the same density and
+merged. Both prompts also carry a causal **event-boundary** definition (a
+new event starts when an object becomes held / is released / reaches a new
+location / a lid changes state / contents move) to sharpen where cuts land.
+
+The resulting spans are then stitched into a gap-free, full-episode
+cover, so **every frame has exactly one active subtask**. See
+[`run_hf_job.py`](https://github.com/huggingface/lerobot/blob/main/examples/annotations/run_hf_job.py)
+for the production settings (single camera, timestamped contact sheets,
+auto-windowed subtask generation).
+
+### Tools
+
+The writer does **not** add a `tools` column to the parquet. The tool
+catalog lives in `meta/info.json["tools"]` instead (see [Tools](./tools)).
+After every run, the pipeline makes sure the canonical `say` schema is in
+that list, keeping any tools you declared beforehand.
+
+Want to add your own tool? Edit `meta/info.json["tools"]` directly — the
+pipeline preserves whatever is already there. That makes the tool visible
+to the chat template, so the model can learn to _generate_ the call. The
+runtime layer that actually _executes_ a generated call (the `Tool`
+protocol / `TOOL_REGISTRY` under `src/lerobot/tools/`) is not part of
+this PR — the [Tools](./tools) doc marks those pieces as
+not-yet-implemented.
+
+## Running on Hugging Face Jobs
+
+Annotation runs on [Hugging Face Jobs](https://huggingface.co/docs/hub/en/jobs).
+The repo ships a launcher script you copy and tweak for your dataset:
+
+```bash
+HF_TOKEN=hf_... uv run python examples/annotations/run_hf_job.py
+```
+
+[`run_hf_job.py`](https://github.com/huggingface/lerobot/blob/main/examples/annotations/run_hf_job.py)
+starts a single-GPU `h200` job (bump it to `h200x4` for big datasets)
+that:
+
+1. installs `lerobot` (from `main`) plus the annotation extras,
+2. boots one vLLM server per GPU (using the `vllm/vllm-openai` image) and
+   drives it over the OpenAI-compatible API,
+3. runs the `plan` / `interjections` / `vqa` modules across the dataset
+   with `lerobot-annotate`,
+4. with `--push_to_hub=true`, uploads the result to `--new_repo_id` (or
+   back to `--repo_id` in place if you leave that unset).
+
+To use a different dataset, model, or hub repo, edit the `CMD` block in
+the script. Every flag there maps directly to a `lerobot-annotate` flag
+(run `lerobot-annotate --help` for the full list).
+
+## Key options
+
+These are the flags you'll reach for most often. Run
+`lerobot-annotate --help` for everything else; the defaults are tuned for
+short manipulation episodes.
+
+### Dataset in / out
+
+| Flag              | Default | What it does                                                            |
+| ----------------- | ------- | ----------------------------------------------------------------------- |
+| `--repo_id`       | —       | Hub dataset to annotate (downloaded if `--root` unset).                 |
+| `--root`          | —       | Annotate a local dataset directory instead.                             |
+| `--new_repo_id`   | —       | Push the result to a new repo (leaves the source repo untouched).       |
+| `--push_to_hub`   | `false` | Upload after annotating (to `--new_repo_id`, else back to `--repo_id`). |
+| `--only_episodes` | all     | Annotate just these episode indices (handy for a test run).             |
+| `--seed`          | `1729`  | Seeds the RNGs that pick interjection timestamps + VQA question types.  |
+
+### Which modules run
+
+Every module is on by default and can be toggled independently (set to
+`false` to skip it, e.g. to iterate on one module at a time):
+
+| Flag                      | Default | Turns off                           |
+| ------------------------- | ------- | ----------------------------------- |
+| `--plan.enabled`          | `true`  | subtasks + plan + memory + task_aug |
+| `--interjections.enabled` | `true`  | interjections + speech atoms        |
+| `--vqa.enabled`           | `true`  | the VQA pairs                       |
+
+### The VLM (`--vlm.*`)
+
+| Flag                       | Default            | What it does                                                                        |
+| -------------------------- | ------------------ | ----------------------------------------------------------------------------------- |
+| `--vlm.model_id`           | `Qwen/Qwen3.6-27B` | The model to serve and prompt.                                                      |
+| `--vlm.camera_key`         | first `images.*`   | Which camera every prompt is grounded on.                                           |
+| `--vlm.serve_command`      | auto               | The exact `vllm serve …` command (set TP size, GPU memory, `--max-model-len` here). |
+| `--vlm.parallel_servers`   | `1`                | Independent servers for round-robin routing (one per GPU).                          |
+| `--vlm.num_gpus`           | `0`                | GPUs per server (`0` = one each).                                                   |
+| `--vlm.client_concurrency` | `16`               | In-flight requests across all servers.                                              |
+| `--vlm.max_new_tokens`     | `512`              | Generation cap per call.                                                            |
+| `--vlm.temperature`        | `0.2`              | Sampling temperature.                                                               |
+
+### Subtasks / plan / memory (`--plan.*`)
+
+| Flag                            | Default    | What it does                                                                                                              |
+| ------------------------------- | ---------- | ------------------------------------------------------------------------------------------------------------------------- |
+| `--plan.frames_per_second`      | `2.0`      | Frame sampling rate for the contact sheets (`2.0` = one frame every 0.5s).                                                |
+| `--plan.max_frames_per_prompt`  | `60`       | Frame budget per VLM call. Episodes whose sampling exceeds this are auto-windowed at the same density, then stitched.     |
+| `--plan.contact_sheet_columns`  | `5`        | Columns per contact-sheet grid (`contact_sheet_frames_per_sheet` tiles, time row-major).                                  |
+| `--plan.plan_max_steps`         | `8`        | Upper bound on subtasks per episode.                                                                                      |
+| `--plan.subtask_describe_first` | `true`     | Run the describe→segment grounding pass (best subtask quality; +1 call/episode).                                          |
+| `--plan.emit_plan`              | `true`     | Emit the numbered `plan` rows (`false` = subtasks + memory only).                                                         |
+| `--plan.emit_memory`            | `true`     | Emit the `memory` rows (`false` = subtasks + plan only); symmetric to `emit_plan`.                                        |
+| `--plan.n_task_rephrasings`     | `10`       | How many `task_aug` rephrasings to emit (`0` disables).                                                                   |
+| `--plan.derive_task_from_video` | `if_short` | Use the dataset task as-is (`off`), only when it's missing/short (`if_short`), or always re-derive from video (`always`). |
+
+### Interjections + VQA
+
+| Flag                                            | Default | What it does                                               |
+| ----------------------------------------------- | ------- | ---------------------------------------------------------- |
+| `--interjections.max_interjections_per_episode` | `3`     | Cap on interjection/speech pairs per episode.              |
+| `--vqa.vqa_emission_hz`                         | `1.0`   | How often VQA pairs are emitted.                           |
+| `--vqa.restrict_to_default_camera`              | `false` | Ground VQA only on `--vlm.camera_key` (else every camera). |
+| `--executor.episode_parallelism`                | `16`    | Episodes processed concurrently within each phase.         |
+
+## Contributing new modules
+
+The pipeline is built to grow, and **contributions are very welcome** —
+a brand-new module (say, trajectory traces or affordances), a new prompt
+template, a smarter grounding flow, or quality fixes to the existing
+`plan` / `interjections` / `vqa` modules.
+
+Every module lives under
+`src/lerobot/annotations/steerable_pipeline/modules/`, shares the VLM
+client and the keyframe cache, writes its raw output to the staging
+tree, and plugs into the executor as its own phase. Got an idea? Open an
+issue or PR on [the repo](https://github.com/huggingface/lerobot).
+
+## How recipes consume the output
+
+The annotations are meant to be read by recipes (see
+[Language Columns and Recipes](./language_and_recipes)). Typically:
+
+- low-level / high-level / memory-update branches read
+  `subtask` / `plan` / `memory` from `language_persistent`.
+- an interjection-response branch reads `interjection` events plus the
+  paired speech atom (merged into one assistant turn via `tool_calls_from`)
+  and the matching `plan` refresh at the same timestamp.
+- a VQA branch reads the `(vqa, user)` and `(vqa, assistant)` pairs from
+  `language_events`.
+
+## Why state and events are split
+
+Two ideas shape the design:
+
+1. **Persistent state vs. exact events.** Persistent rows (`subtask`,
+   `plan`, `memory`) apply to the whole episode and answer "what's true
+   right now?". Event rows (`interjection`, `vqa`, speech) appear only on
+   the one frame whose timestamp matches. Timestamps are copied straight
+   from the source parquet — never recomputed in floating point.
+2. **One VLM pass.** All three modules share a single VLM client (the
+   OpenAI-compatible client talking to the job's vLLM server), so you pay
+   for one model load per dataset, not three.
+
+## Re-running a single module
+
+Each module stages its raw output to
+`<root>/.annotate_staging/episode_{N:06d}/<module>.jsonl`. This makes
+prompt iteration cheap: re-running one module overwrites only its own
+JSONL, then the writer recomposes the final parquet. Disable modules you
+don't want with `--plan.enabled=false` (and likewise
+`--interjections.enabled` / `--vqa.enabled`) to test one at a time.
+
+## What the validator checks
+
+Before the writer runs, `StagingValidator` confirms:
+
+- every event row lands exactly on a real frame timestamp;
+- no speech / interjection pairs are left orphaned;
+- `plan` is refreshed at every interjection timestamp;
+- `memory` rows fall on subtask boundaries (a warning, not an error);
+- each VQA assistant `content` is valid JSON in one of the
+  bbox / keypoint / count / attribute / spatial shapes;
+- every row goes to the column chosen by `column_for_style(style)`.
+
+Any error aborts the writer. Pass `--skip_validation=true` to override
+while debugging.
+
+## Where each module's ideas come from
+
+- **`plan` — subtasks.** Hi Robot ([Shi 2025](https://arxiv.org/abs/2502.19417))
+  for atom granularity ("pick up one piece of lettuce", "place bowl to
+  box"); Pi0.7 ([Physical Intelligence 2025](https://pi.website/pi07))
+  for "how, not what" detail.
+- **`plan` — memory.** MEM ([Torne 2026](https://arxiv.org/abs/2603.03596)):
+  keep only the minimal relevant information — preserve outcomes, drop
+  specific attributes.
+- **`interjections`.** Hi Robot's scenario taxonomy: negative task,
+  situated correction, specific constraint, preference. Speech is a
+  tool-call-only atom
+  (`tool_calls=[{type:function, function:{name:"say", arguments:{text:...}}}]`).
+- **`vqa`.** ECoT ([Zawalski 2024](https://arxiv.org/abs/2407.08693)) for
+  grounded features (pixel bounding boxes `[x_min, y_min, x_max, y_max]`,
+  keypoints) and Steerable VLA Policies
+  ([Zhao 2025](https://arxiv.org/abs/2509.07626)) for multi-abstraction
+  grounding. Pi0.7 also grounds answers across abstraction levels.
+
+When improving a module, tweak its prompt template in
+`src/lerobot/annotations/steerable_pipeline/prompts/` rather than
+rewriting from scratch.
+
+## Roughly how much it costs
+
+Per episode, the pipeline makes about `max_steps` plan calls,
+`max_interjections_per_episode` interjection calls, and
+`vqa_emission_hz × episode_seconds` VQA calls. With the defaults (8
+subtasks, 1 interjection, 1 Hz × 3 pairs) on a 30-second episode, that's
+~50 VLM calls.
+
+Storage stays small: `language_persistent` is at most tens of KB per
+episode (parquet dictionary-encodes the one entry that repeats across
+frames), and `language_events` is empty on most frames — its size scales
+with the number of emissions, not `num_frames × num_emissions`.

docs/source/async.mdx

@@ -0,0 +1,313 @@
+# Asynchronous Inference
+
+With our [SmolVLA](https://huggingface.co/papers/2506.01844) we introduced a new way to run inference on real-world robots, **decoupling action prediction from action execution**.
+In this tutorial, we'll show how to use asynchronous inference (_async inference_) using a finetuned version of SmolVLA, and all the policies supported by LeRobot.
+**Try async inference with all the policies** supported by LeRobot!
+
+**What you'll learn:**
+
+1. Why asynchronous inference matters and how it compares to, more traditional, sequential inference.
+2. How to spin-up a `PolicyServer` and connect a `RobotClient` from the same machine, and even over the network.
+3. How to tune key parameters (`actions_per_chunk`, `chunk_size_threshold`) for your robot and policy.
+
+If you get stuck, hop into our [Discord community](https://discord.gg/s3KuuzsPFb)!
+
+In a nutshell: with _async inference_, your robot keeps acting while the policy server is already busy computing the next chunk of actions---eliminating "wait-for-inference" lags and unlocking smoother, more reactive behaviours.
+This is fundamentally different from synchronous inference (sync), where the robot stays idle while the policy computes the next chunk of actions.
+
+---
+
+## Getting started with async inference
+
+You can read more information on asynchronous inference in our [blogpost](https://huggingface.co/blog/async-robot-inference). This guide is designed to help you quickly set up and run asynchronous inference in your environment.
+
+First, install `lerobot` with the `async` tag, to install the extra dependencies required to run async inference.
+
+```shell
+pip install -e ".[async]"
+```
+
+Then, spin up a policy server (in one terminal, or in a separate machine) specifying the host address and port for the client to connect to.
+You can spin up a policy server running:
+
+```shell
+python -m lerobot.async_inference.policy_server \
+     --host=127.0.0.1 \
+     --port=8080
+```
+
+This will start a policy server listening on `127.0.0.1:8080` (`localhost`, port 8080). At this stage, the policy server is empty, as all information related to which policy to run and with which parameters are specified during the first handshake with the client. Spin up a client with:
+
+```shell
+python -m lerobot.async_inference.robot_client \
+    --server_address=127.0.0.1:8080 \ # SERVER: the host address and port of the policy server
+    --robot.type=so100_follower \ # ROBOT: your robot type
+    --robot.port=/dev/tty.usbmodem585A0076841 \ # ROBOT: your robot port
+    --robot.id=follower_so100 \ # ROBOT: your robot id, to load calibration file
+    --robot.cameras="{ laptop: {type: opencv, index_or_path: 0, width: 1920, height: 1080, fps: 30}, phone: {type: opencv, index_or_path: 0, width: 1920, height: 1080, fps: 30}}" \ # POLICY: the cameras used to acquire frames, with keys matching the keys expected by the policy
+    --task="dummy" \ # POLICY: The task to run the policy on (`Fold my t-shirt`). Not necessarily defined for all policies, such as `act`
+    --policy_type=your_policy_type \ # POLICY: the type of policy to run (smolvla, act, etc)
+    --pretrained_name_or_path=user/model \ # POLICY: the model name/path on server to the checkpoint to run (e.g., lerobot/smolvla_base)
+    --policy_device=mps \ # POLICY: the device to run the policy on, on the server (cuda, mps, xpu, cpu)
+    --actions_per_chunk=50 \ # POLICY: the number of actions to output at once
+    --chunk_size_threshold=0.5 \ # CLIENT: the threshold for the chunk size before sending a new observation to the server
+    --aggregate_fn_name=weighted_average \ # CLIENT: the function to aggregate actions on overlapping portions
+    --debug_visualize_queue_size=True # CLIENT: whether to visualize the queue size at runtime
+```
+
+In summary, you need to specify instructions for:
+
+- `SERVER`: the address and port of the policy server
+- `ROBOT`: the type of robot to connect to, the port to connect to, and the local `id` of the robot
+- `POLICY`: the type of policy to run, and the model name/path on server to the checkpoint to run. You also need to specify which device should the sever be using, and how many actions to output at once (capped at the policy max actions value).
+- `CLIENT`: the threshold for the chunk size before sending a new observation to the server, and the function to aggregate actions on overlapping portions. Optionally, you can also visualize the queue size at runtime, to help you tune the `CLIENT` parameters.
+
+Importantly,
+
+- `actions_per_chunk` and `chunk_size_threshold` are key parameters to tune for your setup.
+- `aggregate_fn_name` is the function to aggregate actions on overlapping portions. You can either add a new one to a registry of functions, or add your own in `robot_client.py` (see [here](NOTE:addlinktoLOC))
+- `debug_visualize_queue_size` is a useful tool to tune the `CLIENT` parameters.
+
+## Done! You should see your robot moving around by now 😉
+
+## Async vs. synchronous inference
+
+Synchronous inference relies on interleaving action chunk prediction and action execution. This inherently results in _idle frames_, frames where the robot awaits idle the policy's output: a new action chunk.
+In turn, inference is plagued by evident real-time lags, where the robot simply stops acting due to the lack of available actions.
+With robotics models increasing in size, this problem risks becoming only more severe.
+
+<p align="center">
+  <img
+    src="https://huggingface.co/datasets/huggingface/documentation-images/resolve/main/async-inference/sync.png"
+    width="80%"
+  ></img>
+</p>
+<p align="center">
+  <i>Synchronous inference</i> makes the robot idle while the policy is
+  computing the next chunk of actions.
+</p>
+
+To overcome this, we design async inference, a paradigm where action planning and execution are decoupled, resulting in (1) higher adaptability and, most importantly, (2) no idle frames.
+Crucially, with async inference, the next action chunk is computed _before_ the current one is exhausted, resulting in no idleness.
+Higher adaptability is ensured by aggregating the different action chunks on overlapping portions, obtaining an up-to-date plan and a tighter control loop.
+
+<p align="center">
+  <img
+    src="https://huggingface.co/datasets/huggingface/documentation-images/resolve/main/async-inference/async.png"
+    width="80%"
+  ></img>
+</p>
+<p align="center">
+  <i>Asynchronous inference</i> results in no idleness because the next chunk is
+  computed before the current chunk is exhausted.
+</p>
+
+---
+
+## Start the Policy Server
+
+Policy servers are wrappers around a `PreTrainedPolicy` interfacing them with observations coming from a robot client.
+Policy servers are initialized as empty containers which are populated with the requested policy specified in the initial handshake between the robot client and the policy server.
+As such, spinning up a policy server is as easy as specifying the host address and port. If you're running the policy server on the same machine as the robot client, you can use `localhost` as the host address.
+
+<hfoptions id="start_policy_server">
+<hfoption id="Command">
+```bash
+python -m lerobot.async_inference.policy_server \
+     --host=127.0.0.1 \
+     --port=8080
+```
+</hfoption>
+<hfoption id="API example">
+
+<!-- prettier-ignore-start -->
+```python
+from lerobot.async_inference.configs import PolicyServerConfig
+from lerobot.async_inference.policy_server import serve
+
+config = PolicyServerConfig(
+    host="localhost",
+    port=8080,
+)
+serve(config)
+```
+<!-- prettier-ignore-end -->
+
+</hfoption>
+</hfoptions>
+
+This listens on `localhost:8080` for an incoming connection from the associated`RobotClient`, which will communicate which policy to run during the first client-server handshake.
+
+---
+
+## Launch the Robot Client
+
+`RobotClient` is a wrapper around a `Robot` instance, which `RobotClient` connects to the (possibly remote) `PolicyServer`.
+The `RobotClient` streams observations to the `PolicyServer`, and receives action chunks obtained running inference on the server (which we assume to have better computational resources than the robot controller).
+
+<hfoptions id="start_robot_client">
+<hfoption id="Command">
+```bash
+python -m lerobot.async_inference.robot_client \
+    --server_address=127.0.0.1:8080 \ # SERVER: the host address and port of the policy server
+    --robot.type=so100_follower \ # ROBOT: your robot type
+    --robot.port=/dev/tty.usbmodem585A0076841 \ # ROBOT: your robot port
+    --robot.id=follower_so100 \ # ROBOT: your robot id, to load calibration file
+    --robot.cameras="{ laptop: {type: opencv, index_or_path: 0, width: 1920, height: 1080, fps: 30}, phone: {type: opencv, index_or_path: 0, width: 1920, height: 1080, fps: 30}}" \ # POLICY: the cameras used to acquire frames, with keys matching the keys expected by the policy
+    --task="dummy" \ # POLICY: The task to run the policy on (`Fold my t-shirt`). Not necessarily defined for all policies, such as `act`
+    --policy_type=your_policy_type \ # POLICY: the type of policy to run (smolvla, act, etc)
+    --pretrained_name_or_path=user/model \ # POLICY: the model name/path on server to the checkpoint to run (e.g., lerobot/smolvla_base)
+    --policy_device=mps \ # POLICY: the device to run the policy on, on the server
+    --actions_per_chunk=50 \ # POLICY: the number of actions to output at once
+    --chunk_size_threshold=0.5 \ # CLIENT: the threshold for the chunk size before sending a new observation to the server
+    --aggregate_fn_name=weighted_average \ # CLIENT: the function to aggregate actions on overlapping portions
+    --debug_visualize_queue_size=True # CLIENT: whether to visualize the queue size at runtime
+```
+</hfoption>
+<hfoption id="API example">
+
+<!-- prettier-ignore-start -->
+```python
+import threading
+from lerobot.robots.so_follower import SO100FollowerConfig
+from lerobot.cameras.opencv import OpenCVCameraConfig
+from lerobot.async_inference.configs import RobotClientConfig
+from lerobot.async_inference.robot_client import RobotClient
+from lerobot.async_inference.helpers import visualize_action_queue_size
+
+# 1. Create the robot instance
+"""Check out the cameras available in your setup by running `python lerobot/find_cameras.py`"""
+# these cameras must match the ones expected by the policy
+# check the config.json on the Hub for the policy you are using
+camera_cfg = {
+    "top": OpenCVCameraConfig(index_or_path=0, width=640, height=480, fps=30),
+    "side": OpenCVCameraConfig(index_or_path=1, width=640, height=480, fps=30)
+}
+
+robot_cfg = SO100FollowerConfig(
+  port="/dev/tty.usbmodem585A0076841",
+  id="follower_so100",
+  cameras=camera_cfg
+)
+
+# 3. Create client configuration
+client_cfg = RobotClientConfig(
+    robot=robot_cfg,
+    server_address="localhost:8080",
+    policy_device="mps",
+    client_device="cpu",
+    policy_type="smolvla",
+    pretrained_name_or_path="<user>/smolvla_async",
+    chunk_size_threshold=0.5,
+    actions_per_chunk=50,  # make sure this is less than the max actions of the policy
+)
+
+# 4. Create and start client
+client = RobotClient(client_cfg)
+
+# 5. Specify the task
+task = "Don't do anything, stay still"
+
+if client.start():
+    # Start action receiver thread
+    action_receiver_thread = threading.Thread(target=client.receive_actions, daemon=True)
+    action_receiver_thread.start()
+
+    try:
+        # Run the control loop
+        client.control_loop(task)
+    except KeyboardInterrupt:
+        client.stop()
+        action_receiver_thread.join()
+        # (Optionally) plot the action queue size
+        visualize_action_queue_size(client.action_queue_size)
+```
+<!-- prettier-ignore-end -->
+
+</hfoption>
+</hfoptions>
+
+The following two parameters are key in every setup:
+
+<table>
+  <thead>
+    <tr>
+      <th>Hyperparameter</th>
+      <th>Default</th>
+      <th>What it does</th>
+    </tr>
+  </thead>
+  <tbody>
+    <tr>
+      <td>
+        <code>actions_per_chunk</code>
+      </td>
+      <td>50</td>
+      <td>
+        How many actions the policy outputs at once. Typical values: 10-50.
+      </td>
+    </tr>
+    <tr>
+      <td>
+        <code>chunk_size_threshold</code>
+      </td>
+      <td>0.7</td>
+      <td>
+        When the queue is ≤ 50% full, the client sends a fresh observation.
+        Value in [0, 1].
+      </td>
+    </tr>
+  </tbody>
+</table>
+
+<Tip>
+  Different values of `actions_per_chunk` and `chunk_size_threshold` do result
+  in different behaviours.
+</Tip>
+
+On the one hand, increasing the value of `actions_per_chunk` will result in reducing the likelihood of ending up with no actions to execute, as more actions will be available when the new chunk is computed.
+However, larger values of `actions_per_chunk` might also result in less precise actions, due to the compounding errors consequent to predicting actions over longer timespans.
+
+On the other hand, increasing the value of `chunk_size_threshold` will result in sending out to the `PolicyServer` observations for inference more often, resulting in a larger number of updates action chunks, overlapping on significant portions. This results in high adaptability, in the limit predicting one action chunk for each observation, which is in turn only marginally consumed while a new one is produced.
+This option does also put more pressure on the inference pipeline, as a consequence of the many requests. Conversely, values of `chunk_size_threshold` close to 0.0 collapse to the synchronous edge case, whereby new observations are only sent out whenever the current chunk is exhausted.
+
+We found the default values of `actions_per_chunk` and `chunk_size_threshold` to work well in the experiments we developed for the [SmolVLA paper](https://huggingface.co/papers/2506.01844), but recommend experimenting with different values to find the best fit for your setup.
+
+### Tuning async inference for your setup
+
+1. **Choose your computational resources carefully.** [PI0](https://huggingface.co/lerobot/pi0) occupies 14GB of memory at inference time, while [SmolVLA](https://huggingface.co/lerobot/smolvla_base) requires only ~2GB. You should identify the best computational resource for your use case keeping in mind smaller policies require less computational resources. The combination of policy and device used (CPU-intensive, using MPS, or the number of CUDA cores on a given NVIDIA GPU) directly impacts the average inference latency you should expect.
+2. **Adjust your `fps` based on inference latency.** While the server generates a new action chunk, the client is not idle and is stepping through its current action queue. If the two processes happen at fundamentally different speeds, the client might end up with an empty queue. As such, you should reduce your fps if you consistently run out of actions in queue.
+3. **Adjust `chunk_size_threshold`**.
+   - Values closer to `0.0` result in almost sequential behavior. Values closer to `1.0` → send observation every step (more bandwidth, relies on good world-model).
+   - We found values around 0.5-0.6 to work well. If you want to tweak this, spin up a `RobotClient` setting the `--debug_visualize_queue_size` to `True`. This will plot the action queue size evolution at runtime, and you can use it to find the value of `chunk_size_threshold` that works best for your setup.
+
+<p align="center">
+  <img
+    src="https://huggingface.co/datasets/huggingface/documentation-images/resolve/main/async-inference/queues.png"
+    width="80%"
+  ></img>
+</p>
+<p align="center">
+  <i>
+    The action queue size is plotted at runtime when the
+    `--debug_visualize_queue_size` flag is passed, for various levels of
+    `chunk_size_threshold` (`g` in the SmolVLA paper).
+  </i>
+</p>
+
+---
+
+## Conclusion
+
+Asynchronous inference represents a significant advancement in real-time robotics control, addressing the fundamental challenge of inference latency that has long plagued robotics applications. Through this tutorial, you've learned how to implement a complete async inference pipeline that eliminates idle frames and enables smoother, more reactive robot behaviors.
+
+**Key Takeaways:**
+
+- **Paradigm Shift**: Async inference decouples action prediction from execution, allowing robots to continue acting while new action chunks are computed in parallel
+- **Performance Benefits**: Eliminates "wait-for-inference" lags that are inherent in synchronous approaches, becoming increasingly important as policy models grow larger
+- **Flexible Architecture**: The server-client design enables distributed computing, where inference can run on powerful remote hardware while maintaining real-time robot control
+- **Tunable Parameters**: Success depends on properly configuring `actions_per_chunk` and `chunk_size_threshold` for your specific hardware, policy, and task requirements
+- **Universal Compatibility**: Works with all LeRobot-supported policies, from lightweight ACT models to vision-language models like SmolVLA
+
+Start experimenting with the default parameters, monitor your action queue sizes, and iteratively refine your setup to achieve optimal performance for your specific use case.
+If you want to discuss this further, hop into our [Discord community](https://discord.gg/s3KuuzsPFb), or open an issue on our [GitHub repository](https://github.com/huggingface/lerobot/issues).

docs/source/bring_your_own_policies.mdx

@@ -295,11 +295,12 @@ The file names are load-bearing: the factory does lazy imports by name, and the
 
 ### Wiring
 
-Three places need to know about your policy. All by name.
+Four places need to know about your policy. All by name.
 
 1. **`policies/__init__.py`** — re-export `MyPolicyConfig` and add it to `__all__`. **Don't** re-export the modeling class; it loads lazily through the factory (so `import lerobot` stays fast).
 2. **`factory.py:get_policy_class`** — add a branch returning `MyPolicy` from a lazy import.
 3. **`factory.py:make_policy_config`** and **`factory.py:make_pre_post_processors`** — same idea, two more branches.
+4. **`templates/lerobot_modelcard_template.md` and the root `README.md`** — the template is what `push_model_to_hub` renders into the model card of every checkpoint trained with your policy: add a one-line description of your policy in the `model_name` branches, map it in `policy_docs` so cards link to your MDX guide, and optionally add an architecture image to `diagrams`. Then add your policy to the models table in the root `README.md`, under the right category, linking to your doc page.
 
 Mirror an existing policy that's structurally similar to yours; the diff is small.
 
@@ -371,6 +372,8 @@ The general expectations are in [`CONTRIBUTING.md`](https://github.com/huggingfa
 - [ ] Optional deps live behind a `[project.optional-dependencies]` extra and the `TYPE_CHECKING + require_package` guard.
 - [ ] `tests/policies/` updated; backward-compat artifact committed & policy-specific tests.
 - [ ] `src/lerobot/policies/<name>/README.md` symlinked into `docs/source/policy_<name>_README.md`; user-facing `docs/source/<name>.mdx` written and added to `_toctree.yml`.
+- [ ] `templates/lerobot_modelcard_template.md` has a description entry and a `policy_docs` link for your policy.
+- [ ] The models table in the root `README.md` lists your policy in the right category, linking to your doc page.
 - [ ] At least one reproducible benchmark eval in the policy MDX with a published checkpoint (sim benchmark, or real-robot dataset + checkpoint).
 
 The fastest way to get a clean PR is to copy the directory of the existing policy closest to yours, rename, and replace contents method by method. Don't wait until everything is polished — open a draft PR early and iterate with us; reviewers would much rather give feedback on a half-finished branch than a fully-merged one.

docs/source/cameras.mdx

@@ -157,6 +157,14 @@ finally:
 </hfoption>
 </hfoptions>
 
+### Working with depth
+
+The Intel RealSense and Reachy 2 cameras can capture both color and depth in lockstep. Calling `read()` returns the **color** frame as `(H, W, 3)` `uint8`. Calling `read_depth()` returns the **depth map** as `(H, W, 1)` `uint16`, where each pixel value is the distance from the sensor expressed in **millimetres**. A pixel value of `0` typically means "no measurement available" (out-of-range, occluded, or low-confidence).
+
+During recording, the control loop peeks the freshest buffered frames non-blockingly via `read_latest()` (color) and `read_latest_depth()` (depth), adding the depth map as a sibling feature (e.g. `front_depth` next to `front`).
+
+For how depth streams are stored and encoded when recording a dataset, see the [Depth streams](./video_encoding_parameters#depth-streams) section of the video encoding guide.
+
 ## Use your phone's camera
 
 <hfoptions id="use phone">

docs/source/cheat-sheet.mdx

@@ -89,6 +89,36 @@ Control the data recording flow using keyboard shortcuts:
 - Press **Left Arrow (`←`)**: Delete current episode and retry.
 - Press **Escape (`ESC`)**: Stop, encode videos, and upload.
 
+### Recording depth
+
+Intel RealSense cameras (`type: intelrealsense`) record a depth stream when you set `use_depth: true`. Depth is quantized to 12-bit codes and stored as its own video.
+
+```bash
+lerobot-record \
+    ... \
+    --robot.cameras="{ head: {type: intelrealsense, serial_number_or_name: \"0123456789\", width: 640, height: 480, fps: 30, use_depth: true} }" \
+    --dataset.repo_id=${HF_USER}/so101_depth_test \
+    --dataset.single_task="put the red brick in a bowl" \
+    --dataset.depth_encoder.depth_min=0.01 \
+    --dataset.depth_encoder.depth_max=10.0 \
+    --dataset.depth_encoder.shift=0.0 \
+    --dataset.depth_encoder.use_log=true
+```
+
+### Video encoding parameters
+
+RGB and depth streams are encoded independently via the `--dataset.rgb_encoder.*` and `--dataset.depth_encoder.*` keys.
+
+```bash
+lerobot-record \
+    ... \
+    --dataset.rgb_encoder.vcodec=h264 \
+    --dataset.rgb_encoder.pix_fmt=yuv420p \
+    --dataset.rgb_encoder.crf=23 \
+    --dataset.depth_encoder.vcodec=hevc \
+    --dataset.depth_encoder.extra_options='{"x265-params": "lossless=1"}'
+```
+
 ### Training
 
 Depending on your hardware training the policy might take a few hours. That's how you train simple `ACT` policy:
@@ -120,6 +150,14 @@ lerobot-train \
     --steps=20000
 ```
 
+No local GPU? Add `--job.target=<flavor>` (e.g. `a10g-small`) to either command and `lerobot-train` runs it on [Hugging Face Jobs](https://huggingface.co/docs/hub/jobs) instead — it uploads a local-only dataset for you and pushes the trained model. List flavors with `hf jobs hardware`.
+
+To resume, point `--config_path` at a checkpoint and add `--resume=true`. It accepts a local path or a Hub repo id (the latest checkpoint is fetched), and works locally or on a job by adding `--job.target=<flavor>`:
+
+```bash
+lerobot-train --config_path=${HF_USER}/policy_test --resume=true --job.target=a10g-small
+```
+
 ### Inference
 
 Inference means running the trained policy/model on a robot. For that we use `lerobot-rollout`. You will need to provide a path to your policy. It can be a local path or a path to Hugging Face for example "lerobot/folding_latest". Your cameras configuration needs to match what was used when collecting the dataset. Duration is in seconds if unspecified, it will run forever.

docs/source/earthrover_mini_plus.mdx

@@ -194,7 +194,7 @@ lerobot-record \
     --dataset.single_task="Navigate around obstacles" \
     --dataset.streaming_encoding=true \
     --dataset.encoder_threads=2 \
-    # --dataset.camera_encoder.vcodec=auto \
+    # --dataset.rgb_encoder.vcodec=auto \
     --display_data=true
 ```
 

docs/source/envhub_isaaclab_arena.mdx

@@ -193,7 +193,7 @@ To learn more about training policies with LeRobot, please refer to the training
 
 - [SmolVLA](./smolvla)
 - [Pi0.5](./pi05)
-- [GR00T N1.5](./groot)
+- [GR00T N1.7](./groot)
 
 Sample IsaacLab Arena datasets are available on HuggingFace Hub for experimentation:
 

docs/source/evo1.mdx

@@ -0,0 +1,191 @@
+# EVO1
+
+EVO1 is a Vision-Language-Action policy for robot control built around an InternVL3 backbone and a continuous flow-matching action head. This LeRobot integration exposes EVO1 as a standard policy type so it can be trained and evaluated with the usual LeRobot dataset, checkpoint, and processor APIs.
+
+## Model Overview
+
+The policy embeds one or more camera images and the language task prompt with InternVL3, pads robot state/action vectors to fixed maximum dimensions, and predicts future action chunks with a flow-matching action head. During inference, the policy samples an action chunk and returns `n_action_steps` actions from that chunk before sampling again.
+
+### What the LeRobot Integration Covers
+
+- Standard `policy.type=evo1` configuration through LeRobot
+- InternVL3 image/text embedding with optional FlashAttention fallback
+- Stage-based finetuning controls for action-head-only and VLM finetuning runs
+- Continuous flow-matching action prediction
+- Checkpoint save/load through LeRobot policy APIs
+- Training with `lerobot-train` and evaluation with standard policy inference APIs
+
+The broader EVO1 project may include additional training scripts and dataset tooling. This page focuses on the LeRobot robot-control policy path.
+
+## Installation Requirements
+
+1. Install LeRobot by following the [Installation Guide](./installation).
+2. Install EVO1 dependencies:
+
+   ```bash
+   pip install -e ".[evo1]"
+   ```
+
+   For LIBERO evaluation, install the LIBERO extra as well:
+
+   ```bash
+   pip install -e ".[evo1,libero]"
+   ```
+
+3. Install a `flash-attn` wheel only if it is compatible with your Python, PyTorch, CUDA, and GPU stack. EVO1 falls back to standard attention when `flash_attn` is not available.
+
+EVO1 uses the native Hugging Face `transformers` InternVL implementation, so `policy.vlm_model_name` must point to a natively converted checkpoint such as `OpenGVLab/InternVL3-1B-hf` (note the `-hf` suffix). The first run may download the configured VLM checkpoint unless `policy.vlm_model_name` points to a local model directory.
+
+## Data Requirements
+
+EVO1 expects a LeRobot dataset with:
+
+- One to `policy.max_views` visual observations, for example `observation.images.image`
+- `observation.state`
+- `action`
+- A language task instruction in the dataset `task` field, or another field configured with `policy.task_field`
+
+State and action vectors are padded to `policy.max_state_dim` and `policy.max_action_dim`. Predictions are cropped back to the dataset action dimension before being returned.
+
+## Usage
+
+To use EVO1 in a LeRobot configuration, specify:
+
+```python
+policy.type=evo1
+```
+
+By default, a new EVO1 policy initializes its VLM from:
+
+```python
+policy.vlm_model_name=OpenGVLab/InternVL3-1B-hf
+```
+
+Once a LeRobot-format EVO1 checkpoint is available, load it with:
+
+```python
+policy.path=your-org/your-evo1-checkpoint
+```
+
+## Training
+
+### Stage 1
+
+Stage 1 freezes the VLM and trains the action head:
+
+```bash
+lerobot-train \
+  --dataset.repo_id=your_org/your_dataset \
+  --policy.type=evo1 \
+  --policy.training_stage=stage1 \
+  --policy.vlm_model_name=OpenGVLab/InternVL3-1B-hf \
+  --policy.device=cuda \
+  --policy.chunk_size=50 \
+  --policy.n_action_steps=50 \
+  --policy.max_state_dim=24 \
+  --policy.max_action_dim=24 \
+  --policy.optimizer_lr=1e-5 \
+  --batch_size=4 \
+  --steps=5000 \
+  --output_dir=./outputs/evo1_stage1
+```
+
+### Stage 2
+
+Stage 2 finetunes the VLM branches and action head. A common workflow starts from a Stage 1 checkpoint:
+
+```bash
+lerobot-train \
+  --dataset.repo_id=your_org/your_dataset \
+  --policy.path=./outputs/evo1_stage1/checkpoints/005000/pretrained_model \
+  --policy.training_stage=stage2 \
+  --policy.vlm_model_name=OpenGVLab/InternVL3-1B-hf \
+  --policy.device=cuda \
+  --policy.chunk_size=50 \
+  --policy.n_action_steps=50 \
+  --policy.max_state_dim=24 \
+  --policy.max_action_dim=24 \
+  --policy.optimizer_lr=1e-5 \
+  --batch_size=4 \
+  --steps=80000 \
+  --output_dir=./outputs/evo1_stage2
+```
+
+By default, `policy.training_stage` reapplies the finetuning defaults for that stage. This is important when
+starting Stage 2 from a Stage 1 checkpoint, because the Stage 1 checkpoint config stores the VLM finetuning
+flags as disabled. These stage defaults take precedence over saved or manually supplied `policy.finetune_*`
+flags unless `policy.apply_training_stage_defaults=false`, so set that flag only when manually controlling
+every finetuning flag.
+
+### Key Training Parameters
+
+| Parameter                                     | Default                     | Description                                                       |
+| --------------------------------------------- | --------------------------- | ----------------------------------------------------------------- |
+| `policy.vlm_model_name`                       | `OpenGVLab/InternVL3-1B-hf` | Natively converted InternVL3 checkpoint or local model directory  |
+| `policy.training_stage`                       | `stage1`                    | `stage1` trains the action head; `stage2` finetunes VLM branches  |
+| `policy.apply_training_stage_defaults`        | `true`                      | Reapplies stage finetuning defaults after loading a checkpoint    |
+| `policy.vlm_num_layers`                       | `14`                        | Number of InternVL3 language layers kept for the policy           |
+| `policy.vlm_dtype`                            | `bfloat16`                  | Requested VLM dtype                                               |
+| `policy.use_flash_attn`                       | `true`                      | Requests FlashAttention when installed; otherwise falls back      |
+| `policy.enable_gradient_checkpointing`        | `true`                      | Enables checkpointing on supported InternVL3 modules              |
+| `policy.gradient_checkpointing_use_reentrant` | `false`                     | Reentrant setting passed to gradient checkpointing when supported |
+| `policy.chunk_size`                           | `50`                        | Number of future actions predicted per chunk                      |
+| `policy.n_action_steps`                       | `50`                        | Number of actions consumed from a sampled chunk                   |
+| `policy.max_state_dim`                        | `24`                        | State padding dimension                                           |
+| `policy.max_action_dim`                       | `24`                        | Action padding dimension                                          |
+| `policy.postprocess_action_dim`               | `null`                      | Optional action dimension returned after EVO1 postprocessing      |
+| `policy.binarize_gripper`                     | `false`                     | Binarizes the postprocessed gripper channel for LIBERO-style eval |
+| `policy.task_field`                           | `task`                      | Batch field used as the language prompt                           |
+
+## Inference
+
+Try it out with a trained EVO1 checkpoint:
+
+```bash
+lerobot-rollout \
+  --policy.path=your-org/your-evo1-checkpoint \
+  --inference.type=rtc \ # optional
+  ...
+```
+
+## Results
+
+### LIBERO Evaluation
+
+> [!NOTE]
+> Benchmark results for a `lerobot`-hosted LIBERO checkpoint trained with this implementation
+> will be added once training completes.
+
+The official EVO1 LIBERO rollout protocol uses the raw LIBERO camera feature names
+(`observation.images.agentview_image` and `observation.images.robot0_eye_in_hand_image`), replans every
+14 actions, and binarizes the gripper command before stepping the simulator. The EVO1 policy postprocessor
+can crop the padded 24D action back to the 7D LIBERO action space and apply that gripper binarization. To
+evaluate a LIBERO checkpoint under the same one-episode-per-task setting, keep the raw camera names instead
+of the default `image`/`image2` mapping and set the LIBERO action postprocessing flags:
+
+```bash
+lerobot-eval \
+  --policy.path=your-org/your-evo1-libero-checkpoint \
+  --policy.vlm_model_name=OpenGVLab/InternVL3-1B-hf \
+  --policy.device=cuda \
+  --policy.use_flash_attn=true \
+  --policy.n_action_steps=14 \
+  --policy.postprocess_action_dim=7 \
+  --policy.binarize_gripper=true \
+  --env.type=libero \
+  --env.task=libero_object \
+  --env.camera_name_mapping="{agentview_image: agentview_image, robot0_eye_in_hand_image: robot0_eye_in_hand_image}" \
+  --env.observation_height=448 \
+  --env.observation_width=448 \
+  --eval.batch_size=1 \
+  --eval.n_episodes=1
+```
+
+## References
+
+- [EVO1 repository](https://github.com/MINT-SJTU/Evo-1)
+- [InternVL3-1B-hf](https://huggingface.co/OpenGVLab/InternVL3-1B-hf)
+
+## License
+
+This LeRobot integration follows the Apache 2.0 License used by LeRobot. Check the upstream EVO1 and InternVL3 model pages for the licenses of released checkpoints and data.

docs/source/fastwam.mdx

@@ -0,0 +1,167 @@
+# FastWAM
+
+FastWAM is a World Action Model policy for robot control. The LeRobot integration exposes FastWAM through the standard policy API so it can be configured with `policy.type=fastwam`, trained with `lerobot-train`, and loaded through the LeRobot pretrained policy interface.
+
+## Model Overview
+
+FastWAM keeps video modeling during training, but uses direct action prediction at inference time instead of iteratively generating future observations. This LeRobot policy wraps the FastWAM action model, adapts LeRobot batches to FastWAM training samples, and provides the standard processor pipeline for normalization and action postprocessing.
+
+The implementation initializes the visual world-model components from `Wan-AI/Wan2.2-TI2V-5B` by default and predicts action chunks with shape `[batch, action_horizon, action_dim]`.
+
+### What the LeRobot Integration Covers
+
+- Standard `policy.type=fastwam` configuration through LeRobot
+- Image, state, action, and language-task batch adaptation
+- Action chunk inference through `select_action` and `predict_action_chunk`
+- Checkpoint save/load through the LeRobot policy APIs
+- Configurable LIBERO gripper action postprocessing
+
+## Installation Requirements
+
+Install LeRobot from source, then install FastWAM dependencies:
+
+```bash
+pip install -e ".[fastwam]"
+```
+
+This installs the FastWAM policy extra from `pyproject.toml`: `transformers`,
+`diffusers`, `ftfy`, and `regex`, plus LeRobot's base dependencies.
+
+For LIBERO evaluation, install the benchmark dependencies too:
+
+```bash
+pip install -e ".[fastwam,libero]"
+```
+
+This installs both extras. In addition to the FastWAM dependencies above, the
+`libero` extra installs LeRobot dataset dependencies, `hf-libero` on Linux, and
+`scipy`.
+
+FastWAM uses the Wan2.2 TI2V backbone. The default model id is:
+
+```python
+policy.model_id=Wan-AI/Wan2.2-TI2V-5B
+```
+
+## Data Requirements
+
+FastWAM expects a LeRobot dataset with:
+
+- one or more visual observations whose widths concatenate to `policy.image_size[1]`
+- `observation.state` when `policy.proprio_dim` is not `None`
+- `action`
+- a language task instruction through the dataset task field, or precomputed `context` and `context_mask` tensors
+
+The default visual setup is one image feature named `observation.images.image` with shape `(3, 224, 448)`. If the dataset uses two cameras, configure `policy.input_features` so their heights match `224` and their widths sum to `448`.
+
+## Usage
+
+Create a new FastWAM policy with:
+
+```bash
+lerobot-train \
+  --dataset.repo_id=your-org/your-dataset \
+  --policy.type=fastwam \
+  --policy.action_dim=7 \
+  --policy.proprio_dim=8 \
+  --policy.action_horizon=32 \
+  --policy.n_action_steps=10 \
+  --policy.image_size='[224,448]' \
+  --output_dir=./outputs/fastwam_training \
+  --job_name=fastwam_training \
+  --steps=300000 \
+  --batch_size=8 \
+  --policy.device=cuda
+```
+
+Evaluate an existing LeRobot-format checkpoint on LIBERO-10 with:
+
+```bash
+lerobot-eval \
+  --policy.path=ZibinDong/fastwam_libero_uncond_2cam224 \
+  --policy.device=cuda \
+  --policy.torch_dtype=float32 \
+  --policy.n_action_steps=10 \
+  --env.type=libero \
+  --env.task=libero_10 \
+  --env.observation_height=224 \
+  --env.observation_width=224 \
+  --eval.batch_size=1 \
+  --eval.n_episodes=50 \
+  --seed=0 \
+  --env.episode_length=600
+```
+
+For `libero_goal`, `libero_spatial`, and `libero_object`, use
+`--env.episode_length=300`.
+
+For real-robot rollout, use the same checkpoint path:
+
+```bash
+lerobot-rollout \
+  --robot.type=so101_follower \
+  --robot.port=/dev/ttyACM0 \
+  --policy.path=your-org/fastwam-real-robot
+```
+
+## Configuration Notes
+
+### Image Features
+
+`policy.image_size` is the size of the concatenated FastWAM image tensor as `(height, width)`. Each configured image feature must have shape `(3, height, camera_width)`, and all camera widths must sum to the configured width.
+
+### Action Chunking
+
+`policy.action_horizon` controls the number of future actions supervised during training and predicted during inference. `policy.n_action_steps` controls how many actions are consumed before the policy predicts a fresh chunk. `policy.n_action_steps` must be less than or equal to `policy.action_horizon`.
+
+### Wan Components
+
+FastWAM loads the Wan VAE, video DiT, text encoder, and tokenizer from the configured Wan model directory or Hugging Face Hub model id. LeRobot-format FastWAM checkpoints saved by `save_pretrained` also copy the local Wan component files needed by `from_pretrained`.
+
+### Attention Backend
+
+FastWAM's DiT uses PyTorch's `scaled_dot_product_attention` (SDPA) for all attention. It does **not** use FlashAttention: its Mixture-of-Transformers (MoT) routing needs arbitrary boolean `[query, key]` attention masks, which the FlashAttention varlen API cannot express. Installing the `flash-attn` package therefore has no effect on the FastWAM path. (Note that SDPA itself may still select PyTorch's own flash / memory-efficient / math kernel internally — this is unrelated to the `flash-attn` package.)
+
+### LIBERO Action Toggle
+
+FastWAM LIBERO checkpoints use `policy.toggle_action_dimensions=[-1]` by
+default to match the gripper action convention used by the original FastWAM
+evaluation pipeline:
+
+```bash
+--policy.toggle_action_dimensions='[-1]'
+```
+
+## Results
+
+Evaluated on LIBERO with [`ZibinDong/fastwam_libero_uncond_2cam224`](https://huggingface.co/ZibinDong/fastwam_libero_uncond_2cam224):
+
+| Suite          | Success rate | n_episodes |
+| -------------- | -----------: | ---------: |
+| libero_spatial |        97.6% |        500 |
+| libero_object  |        99.0% |        500 |
+| libero_goal    |        95.0% |        500 |
+| libero_10      |        94.0% |        500 |
+| **average**    |    **96.4%** |       2000 |
+
+Reproduce: `lerobot-eval --policy.path=ZibinDong/fastwam_libero_uncond_2cam224 --policy.device=cuda --policy.torch_dtype=float32 --policy.n_action_steps=10 --env.type=libero --env.task=libero_spatial --env.observation_height=256 --env.observation_width=256 --eval.batch_size=1 --eval.n_episodes=50 --seed=0 --env.episode_length=300` (1x H20 140 GB).
+
+## References
+
+- [Fast-WAM paper](https://arxiv.org/abs/2603.16666)
+- [Fast-WAM project page](https://yuantianyuan01.github.io/FastWAM/)
+- [Fast-WAM code](https://github.com/yuantianyuan01/FastWAM)
+- [Released upstream checkpoints](https://huggingface.co/yuanty/fastwam)
+- [Wan2.2 TI2V 5B](https://huggingface.co/Wan-AI/Wan2.2-TI2V-5B)
+
+## Citation
+
+```bibtex
+@article{yuan2026fastwam,
+  title = {Fast-WAM: Do World Action Models Need Test-time Future Imagination?},
+  author = {Tianyuan Yuan and Zibin Dong and Yicheng Liu and Hang Zhao},
+  journal = {arXiv preprint arXiv:2603.16666},
+  year = {2026},
+  url = {https://arxiv.org/abs/2603.16666}
+}
+```

docs/source/groot.mdx

@@ -1,16 +1,19 @@
-# GR00T N1.5 Policy
+# GR00T Policy
 
-GR00T N1.5 is an open foundation model from NVIDIA designed for generalized humanoid robot reasoning and skills. It is a cross-embodiment model that accepts multimodal input, including language and images, to perform manipulation tasks in diverse environments.
+GR00T is an NVIDIA foundation model family for generalized humanoid robot reasoning and skills. It is a cross-embodiment policy that accepts multimodal input, including language, images, and proprioception, to perform manipulation tasks in diverse environments.
 
-This document outlines the specifics of its integration and usage within the LeRobot framework.
+LeRobot integrates GR00T N1.7 through the `groot` policy type.
+
+> [!WARNING]
+> **Breaking change:** GR00T N1.5 support was removed from LeRobot, and current releases support GR00T N1.7 only. N1.5 checkpoints and configs are rejected with a migration note. To keep using an N1.5 checkpoint, pin the last release that supports it: `pip install 'lerobot==0.5.1'`. To use the current release, migrate to GR00T N1.7 (base model [`nvidia/GR00T-N1.7-3B`](https://huggingface.co/nvidia/GR00T-N1.7-3B)).
 
 ## Model Overview
 
-NVIDIA Isaac GR00T N1.5 is an upgraded version of the GR00T N1 foundation model. It is built to improve generalization and language-following abilities for humanoid robots.
+GR00T N1.7 uses a Cosmos-Reason2/Qwen3-VL backbone and provides checkpoints for SimplerEnv, DROID, and LIBERO.
 
-Developers and researchers can post-train GR00T N1.5 with their own real or synthetic data to adapt it for specific humanoid robots or tasks.
+Developers and researchers can post-train GR00T with their own real or synthetic data to adapt it for specific humanoid robots or tasks.
 
-GR00T N1.5 (specifically the GR00T-N1.5-3B model) is built using pre-trained vision and language encoders. It utilizes a flow matching action transformer to model a chunk of actions, conditioned on vision, language, and proprioception.
+GR00T uses pre-trained vision and language encoders with a flow matching action transformer to model a chunk of actions conditioned on vision, language, and proprioception.
 
 <img
   src="https://huggingface.co/datasets/huggingface/documentation-images/resolve/main/lerobot/lerobot-groot-paper1%20(1).png"
@@ -28,33 +31,24 @@ This approach allows the model to be highly adaptable through post-training for
 
 ## Installation Requirements
 
-As of today, GR00T N1.5 requires flash attention for it's internal working.
-
-We are working on making this optional, but in the meantime that means that we require an extra installation step and it can only be used in CUDA enabled devices.
-
-1. Following the Environment Setup of our [Installation Guide](./installation). **Attention** don't install `lerobot` in this step.
-2. Install [Flash Attention](https://github.com/Dao-AILab/flash-attention) by running:
+GR00T is intended for NVIDIA GPU-accelerated systems. Install LeRobot with the GR00T extra:
 
 ```bash
-# Check https://pytorch.org/get-started/locally/ for your system
-pip install "torch>=2.2.1,<2.8.0" "torchvision>=0.21.0,<0.23.0" # --index-url https://download.pytorch.org/whl/cu1XX
-pip install ninja "packaging>=24.2,<26.0" # flash attention dependencies
-pip install "flash-attn>=2.5.9,<3.0.0" --no-build-isolation
-python -c "import flash_attn; print(f'Flash Attention {flash_attn.__version__} imported successfully')"
+pip install "lerobot[groot]"
 ```
 
-3. Install LeRobot by running:
+For a source checkout:
 
 ```bash
-pip install lerobot[groot]
+pip install -e ".[groot]"
 ```
 
 ## Usage
 
-To use GR00T in your LeRobot configuration, specify the policy type as:
+To use GR00T N1.7:
 
-```python
-policy.type=groot
+```bash
+--policy.type=groot
 ```
 
 ## Training
@@ -63,72 +57,171 @@ policy.type=groot
 
 Here's a complete training command for finetuning the base GR00T model on your own dataset:
 
+This command is using the `new_embodiment` flag, which is used for the SO-101 robot, [read more about how GR00T handles different embodiments.](https://github.com/NVIDIA/Isaac-GR00T/blob/main/getting_started/policy.md#--embodiment-tag).
+
 ```bash
-# Using a multi-GPU setup
-accelerate launch \
-  --multi_gpu \
-  --num_processes=$NUM_GPUS \
-  $(which lerobot-train) \
-  --output_dir=$OUTPUT_DIR \
-  --save_checkpoint=true \
-  --batch_size=$BATCH_SIZE \
-  --steps=$NUM_STEPS \
-  --save_freq=$SAVE_FREQ \
-  --log_freq=$LOG_FREQ \
-  --policy.push_to_hub=true \
+# install extra deps for training
+pip install "lerobot[training]"
+
+hf auth login
+wandb login
+
+export DATASET_NAME=your_data_set
+export HF_USER=your_hf_username
+export DATASET=$HF_USER/$DATASET_NAME
+export REPO_ID="${DATASET}_GR00T17" #this is the model that will be uploaded to huggingface
+export OUTPUT_DIR=outputs/train/$REPO_ID
+
+lerobot-train \
+  --dataset.repo_id=$DATASET \
+  --dataset.image_transforms.enable=true \
   --policy.type=groot \
+  --policy.device=cuda \
+  --policy.base_model_path=nvidia/GR00T-N1.7-3B \
+  --policy.embodiment_tag=new_embodiment \
+  --policy.chunk_size=16 \
+  --policy.n_action_steps=16 \
+  --policy.use_relative_actions=true \
+  --policy.relative_exclude_joints='["gripper"]' \
+  --policy.use_bf16=true \
+  --policy.push_to_hub=true \
   --policy.repo_id=$REPO_ID \
-  --policy.tune_diffusion_model=false \
-  --dataset.repo_id=$DATASET_ID \
+  --seed=42 \
+  --batch_size=64 \
+  --steps=20000 \
+  --save_checkpoint=true \
+  --save_freq=5000 \
+  --use_policy_training_preset=true \
+  --env_eval_freq=0 \
+  --eval_steps=0 \
+  --log_freq=10 \
+  --output_dir=$OUTPUT_DIR \
+  --job_name=$DATASET \
   --wandb.enable=true \
-  --wandb.disable_artifact=true \
-  --job_name=$JOB_NAME
+  --wandb.disable_artifact=true
+
 ```
 
 ## Performance Results
 
-### Libero Benchmark Results
+### LIBERO Benchmark Results
 
 > [!NOTE]
-> Follow our instructions for Libero usage: [Libero](./libero)
+> Follow the [LIBERO](./libero) setup instructions before running `lerobot-eval`.
 
-GR00T has demonstrated strong performance on the Libero benchmark suite. To compare and test its LeRobot implementation, we finetuned the GR00T N1.5 model for 30k steps on the Libero dataset and compared the results to the GR00T reference results.
+GR00T N1.7 has demonstrated strong performance on the LIBERO benchmark suite. To reproduce LeRobot results, follow the instructions in the [LIBERO](./libero) section.
 
-| Benchmark          | LeRobot Implementation | GR00T Reference |
-| ------------------ | ---------------------- | --------------- |
-| **Libero Spatial** | 82.0%                  | 92.0%           |
-| **Libero Object**  | 99.0%                  | 92.0%           |
-| **Libero Long**    | 82.0%                  | 76.0%           |
-| **Average**        | 87.0%                  | 87.0%           |
+### Train on LIBERO
 
-These results demonstrate GR00T's strong generalization capabilities across diverse robotic manipulation tasks. To reproduce these results, you can follow the instructions in the [Libero](https://huggingface.co/docs/lerobot/libero) section.
+Example training command for a LIBERO suite (here `libero_spatial`):
+
+```bash
+IMAGE_TRANSFORMS='{
+  "brightness": {"weight": 1.0, "type": "ColorJitter", "kwargs": {"brightness": [0.7, 1.3]}},
+  "contrast":   {"weight": 1.0, "type": "ColorJitter", "kwargs": {"contrast":   [0.6, 1.4]}},
+  "saturation": {"weight": 1.0, "type": "ColorJitter", "kwargs": {"saturation": [0.5, 1.5]}},
+  "hue":        {"weight": 1.0, "type": "ColorJitter", "kwargs": {"hue":        [-0.08, 0.08]}}
+}'
+
+lerobot-train \
+  --dataset.repo_id=IPEC-COMMUNITY/libero_spatial_no_noops_1.0.0_lerobot \
+  --dataset.root=/datasets/libero_spatial \
+  --dataset.revision=main \
+  --dataset.video_backend=pyav \
+  --dataset.image_transforms.enable=true \
+  --dataset.image_transforms.max_num_transforms=4 \
+  --dataset.image_transforms.tfs="$IMAGE_TRANSFORMS" \
+  --policy.type=groot \
+  --policy.base_model_path=nvidia/GR00T-N1.7-3B \
+  --policy.embodiment_tag=libero_sim \
+  --policy.push_to_hub=false \
+  --policy.use_relative_actions=false \
+  --policy.max_steps=20000 \
+  --batch_size=320 \
+  --steps=20000 \
+  --save_freq=2000 \
+  --env_eval_freq=0 \
+  --eval_steps=0 \
+  --log_freq=10 \
+  --wandb.enable=true \
+  --wandb.project=lerobot \
+  --wandb.mode=online \
+  --wandb.disable_artifact=true \
+  --num_workers=4 \
+  --prefetch_factor=2 \
+  --persistent_workers=true \
+  --output_dir=$OUTPUT_DIR \
+  --job_name=$JOB_NAME
+```
+
+This will follow the recipe found [here](https://github.com/NVIDIA/Isaac-GR00T/blob/main/examples/LIBERO/README.md).
+
+### GR00T N1.7 LIBERO Results
+
+Preliminary LeRobot integration results (GR00T-LeRobot, `eval.n_episodes >= 50` per suite):
+
+| Suite            | Success rate | Checkpoint                                                                                                    |
+| ---------------- | -----------: | ------------------------------------------------------------------------------------------------------------- |
+| LIBERO Spatial   |          95% | [nvidia/gr00t17-lerobot-libero_spatial-640](https://huggingface.co/nvidia/gr00t17-lerobot-libero_spatial-640) |
+| LIBERO Object    |         100% | [nvidia/gr00t17-lerobot-libero_object-640](https://huggingface.co/nvidia/gr00t17-lerobot-libero_object-640)   |
+| LIBERO Goal      |          98% | [nvidia/gr00t17-lerobot-libero_goal-640](https://huggingface.co/nvidia/gr00t17-lerobot-libero_goal-640)       |
+| LIBERO 10 (Long) |          93% | [nvidia/gr00t17-lerobot-libero_10-640](https://huggingface.co/nvidia/gr00t17-lerobot-libero_10-640)           |
+| **Average**      |    **96.5%** |                                                                                                               |
+
+```bash
+export MODEL_ID=your_trained_model_on_huggingface
+
+lerobot-eval \
+  --policy.type=groot \
+  --policy.base_model_path=$MODEL_ID \
+  --policy.embodiment_tag=libero_sim \
+  --env.type=libero \
+  --env.task=libero_spatial \
+  --eval.n_episodes=50
+```
+
+Use `eval.n_episodes >= 50` per suite when reporting success rates.
 
 ### Evaluate in your hardware setup
 
 Once you have trained your model using your parameters you can run inference in your downstream task. Follow the instructions in [Policy Deployment (lerobot-rollout)](./inference). For example:
 
 ```bash
-lerobot-rollout\
-  --strategy.type=sentry \
-  --strategy.upload_every_n_episodes=5 \
-  --robot.type=bi_so_follower \
-  --robot.left_arm_port=/dev/ttyACM1 \
-  --robot.right_arm_port=/dev/ttyACM0 \
-  --robot.id=bimanual_follower \
-  --robot.cameras='{ right: {"type": "opencv", "index_or_path": 0, "width": 640, "height": 480, "fps": 30},
-    left: {"type": "opencv", "index_or_path": 2, "width": 640, "height": 480, "fps": 30},
-    top: {"type": "opencv", "index_or_path": 4, "width": 640, "height": 480, "fps": 30},
-  }' \
+# install extra deps for roullout and real hardware
+pip install "lerobot[feetech,viz]"
+
+export MODEL_ID=your_trained_model_on_huggingface
+
+# make sure that camera index matches your setup!
+# find index using `uv run lerobot-find-cameras opencv`
+WRIST_CAM='wrist: {type: opencv, index_or_path: 2, width: 640, height: 480, fps: 30, fourcc: "MJPG"}'
+FRONT_CAM='front: {type: opencv, index_or_path: 0, width: 640, height: 480, fps: 30, fourcc: "MJPG"}'
+export ROBOT_CAMERAS="{ $WRIST_CAM, $FRONT_CAM }"
+export ROBOT_ID=follower_robot
+export ROBOT_PORT=/dev/ttyACM0
+
+uv run lerobot-rollout \
+  --strategy.type=base \
+  --policy.path=$MODEL_ID \
+  --policy.base_model_path=nvidia/GR00T-N1.7-3B \
+  --policy.n_action_steps=8 \
+  --robot.type=so101_follower \
+  --robot.port=$ROBOT_PORT \
+  --robot.id=$ROBOT_ID \
+  --robot.cameras="$ROBOT_CAMERAS" \
+  --task="place the vial in the rack" \
+  --duration=60 \
+  --device=cuda \
   --display_data=true \
-  --dataset.repo_id=<user>/eval_groot-bimanual  \
-  --dataset.single_task="Grab and handover the red cube to the other arm" \
-  --dataset.streaming_encoding=true \
-  --dataset.encoder_threads=2 \
-  # --dataset.camera_encoder.vcodec=auto \
-  --policy.path=<user>/groot-bimanual \ # your trained model
-  --duration=600
+  --inference.type=rtc \
+  --inference.rtc.enabled=True \ # set to False if it causes inference instability
+  --inference.rtc.execution_horizon=8 \
+  --inference.queue_threshold=0
 ```
 
+> [!NOTE]
+> Value of `inference.queue_threshold` should not exceed 5 to ensure stable inference.
+
 ## License
 
-This model follows NVIDIA's proprietary license, consistent with the original [GR00T repository](https://github.com/NVIDIA/Isaac-GR00T). Future versions (starting from N1.7) will follow **Apache 2.0 License**.
+GR00T N1.7 is released under the [NVIDIA Open Model License Agreement](https://www.nvidia.com/en-us/agreements/enterprise-software/nvidia-open-model-license/).

docs/source/hardware_guide.mdx

@@ -82,17 +82,18 @@ VRAM is the first filter. Within a tier, pick by budget and availability — the
 
 ### Hugging Face Jobs
 
-[Hugging Face Jobs](https://huggingface.co/docs/hub/jobs) lets you run training on managed HF infrastructure, billed by the second. The repo publishes a ready-to-use image: **`huggingface/lerobot-gpu:latest`**, rebuilt **every night at 02:00 UTC from `main`** ([`docker_publish.yml`](https://github.com/huggingface/lerobot/blob/main/.github/workflows/docker_publish.yml)) — so it tracks the current state of the repo, not a tagged release.
+[Hugging Face Jobs](https://huggingface.co/docs/hub/jobs) lets you run training on managed HF infrastructure, billed by the second, without owning a GPU. `lerobot-train` submits and streams the job for you — just add `--job.target=<flavor>` to a normal training command:
 
 ```bash
-hf jobs run --flavor a10g-large huggingface/lerobot-gpu:latest \
-  bash -c "nvidia-smi && lerobot-train \
-    --policy.type=act --dataset.repo_id=<USER>/<DATASET> \
-    --policy.repo_id=<USER>/act_<task> --batch_size=8 --steps=50000"
+lerobot-train \
+  --policy.type=act --dataset.repo_id=<USER>/<DATASET> \
+  --policy.repo_id=<USER>/act_<task> \
+  --job.target=a10g-large
 ```
 
 Notes:
 
-- The leading `nvidia-smi` is a quick sanity check that CUDA is visible inside the container — useful to fail fast if the flavor or driver mismatched.
-- The default Job timeout is 30 minutes; pass `--timeout 4h` (or longer) for real training.
-- `--flavor` maps onto the table above: `t4-small`/`t4-medium` (T4, ACT only), `l4x1`/`l4x4` (L4 24 GB), `a10g-small/large/largex2/largex4` (A10G 24 GB scaled out), `a100-large` (A100). For the current full catalogue + pricing see [https://huggingface.co/docs/hub/jobs](https://huggingface.co/docs/hub/jobs).
+- Run `hf auth login` once before submitting, the job runs under your token.
+- `--job.target` maps onto the table above: `t4-small`/`t4-medium` (T4, ACT only), `l4x1`/`l4x4` (L4 24 GB), `a10g-small/large/largex2/largex4` (A10G 24 GB scaled out), `a100-large` (A100). List the current catalogue with pricing via `hf jobs hardware`, or see [https://huggingface.co/docs/hub/jobs](https://huggingface.co/docs/hub/jobs).
+- The job defaults to a `2d` (48h) timeout. Override it with `--job.timeout=4h` (or any other valid duration string) to shorten or extend the timeout. The job automatically stops when the command completes.
+- For the full walkthrough — dataset upload, checkpoint streaming, resuming a run on a job — see the [imitation-learning training guide](./il_robots#train-using-hugging-face-jobs).

docs/source/hil_data_collection.mdx

@@ -57,11 +57,11 @@ The `lerobot-rollout --strategy.type=dagger` mode requires **teleoperators with
 
 **Compatible teleoperators:**
 
-- `openarm_mini` - OpenArm Mini
+- `bi_openarm_mini` - Bimanual OpenArm Mini
 - `so_leader` - SO100 / SO101 leader arm
 
 > [!IMPORTANT]
-> The provided commands default to `bi_openarm_follower` + `openarm_mini`.
+> The provided commands default to `bi_openarm_follower` + `bi_openarm_mini`.
 > `so_follower` + `so_leader` configs are also registered and can be used via CLI flags.
 
 ---
@@ -104,9 +104,9 @@ lerobot-rollout --strategy.type=dagger \
     --robot.right_arm_config.port=can0 \
     --robot.right_arm_config.side=right \
     --robot.cameras='{left_wrist: {type: opencv, index_or_path: "/dev/video0", width: 1280, height: 720, fps: 30}, right_wrist: {type: opencv, index_or_path: "/dev/video4", width: 1280, height: 720, fps: 30}, base: {type: opencv, index_or_path: "/dev/video2", width: 640, height: 480, fps: 30}}' \
-    --teleop.type=openarm_mini \
-    --teleop.port_left=/dev/ttyACM0 \
-    --teleop.port_right=/dev/ttyACM1 \
+    --teleop.type=bi_openarm_mini \
+    --teleop.left_arm_config.port=/dev/ttyACM0 \
+    --teleop.right_arm_config.port=/dev/ttyACM1 \
     --policy.path=outputs/pretrain/checkpoints/last/pretrained_model \
     --dataset.repo_id=your-username/rollout_hil_dataset \
     --dataset.single_task="Fold the T-shirt properly" \
@@ -131,9 +131,9 @@ lerobot-rollout --strategy.type=dagger \
     --robot.right_arm_config.port=can0 \
     --robot.right_arm_config.side=right \
     --robot.cameras='{left_wrist: {type: opencv, index_or_path: "/dev/video0", width: 1280, height: 720, fps: 30}, right_wrist: {type: opencv, index_or_path: "/dev/video4", width: 1280, height: 720, fps: 30}, base: {type: opencv, index_or_path: "/dev/video2", width: 640, height: 480, fps: 30}}' \
-    --teleop.type=openarm_mini \
-    --teleop.port_left=/dev/ttyACM0 \
-    --teleop.port_right=/dev/ttyACM1 \
+    --teleop.type=bi_openarm_mini \
+    --teleop.left_arm_config.port=/dev/ttyACM0 \
+    --teleop.right_arm_config.port=/dev/ttyACM1 \
     --policy.path=outputs/pretrain/checkpoints/last/pretrained_model \
     --dataset.repo_id=your-username/rollout_hil_rtc_dataset \
     --dataset.single_task="Fold the T-shirt properly" \

docs/source/hilserl.mdx

@@ -719,7 +719,7 @@ Example configuration for training the [reward classifier](https://huggingface.c
   "num_workers": 4,
   "steps": 5000,
   "log_freq": 10,
-  "eval_freq": 1000,
+  "env_eval_freq": 1000,
   "save_freq": 1000,
   "save_checkpoint": true,
   "seed": 2,

docs/source/hope_jr.mdx

@@ -232,7 +232,7 @@ lerobot-record \
     --dataset.private=true \
     --dataset.streaming_encoding=true \
     --dataset.encoder_threads=2 \
-    # --dataset.camera_encoder.vcodec=auto \
+    # --dataset.rgb_encoder.vcodec=auto \
     --display_data=true
 ```
 
@@ -278,6 +278,6 @@ lerobot-record \
   --dataset.num_episodes=10 \
   --dataset.streaming_encoding=true \
   --dataset.encoder_threads=2 \
-  # --dataset.camera_encoder.vcodec=auto \
+  # --dataset.rgb_encoder.vcodec=auto \
   --policy.path=outputs/train/hopejr_hand/checkpoints/last/pretrained_model
 ```

docs/source/il_robots.mdx

@@ -126,7 +126,7 @@ import time
 from lerobot.teleoperators.so_leader import SO101Leader, SO101LeaderConfig
 from lerobot.robots.so_follower import SO101Follower, SO101FollowerConfig
 from lerobot.cameras.opencv import OpenCVCameraConfig
-from lerobot.utils.visualization_utils import init_rerun, log_rerun_data, shutdown_rerun
+from lerobot.utils.visualization_utils import init_visualization, log_visualization_data, shutdown_visualization
 
 robot_config = SO101FollowerConfig(
     port="/dev/tty.usbmodem5AB90687491",
@@ -142,7 +142,7 @@ teleop_config = SO101LeaderConfig(
     id="my_leader_arm",
 )
 
-init_rerun(session_name="teleoperation")
+init_visualization("rerun", session_name="teleoperation")  # pass "foxglove" to stream to Foxglove instead
 
 robot = SO101Follower(robot_config)
 teleop_device = SO101Leader(teleop_config)
@@ -158,7 +158,7 @@ while True:
     observation = robot.get_observation()
     action = teleop_device.get_action()
     robot.send_action(action)
-    log_rerun_data(observation=observation, action=action)
+    log_visualization_data("rerun", observation=observation, action=action)
 
     elapsed_time = time.perf_counter() - start_time
     sleep_time = TIME_PER_FRAME - elapsed_time
@@ -207,7 +207,7 @@ lerobot-record \
     --dataset.num_episodes=5 \
     --dataset.single_task="Grab the black cube" \
     --dataset.streaming_encoding=true \
-    # --dataset.camera_encoder.vcodec=auto \
+    # --dataset.rgb_encoder.vcodec=auto \
     --dataset.encoder_threads=2
 ```
 </hfoption>
@@ -223,7 +223,7 @@ from lerobot.teleoperators.so_leader.config_so_leader import SO101LeaderConfig
 from lerobot.teleoperators.so_leader.so_leader import SO101Leader
 from lerobot.common.control_utils import init_keyboard_listener
 from lerobot.utils.utils import log_say
-from lerobot.utils.visualization_utils import init_rerun
+from lerobot.utils.visualization_utils import init_visualization
 from lerobot.scripts.lerobot_record import record_loop
 from lerobot.processor import make_default_processors
 
@@ -270,7 +270,7 @@ def main():
 
     # Initialize the keyboard listener and rerun visualization
     _, events = init_keyboard_listener()
-    init_rerun(session_name="recording")
+    init_visualization("rerun", session_name="recording")
 
     # Connect the robot and teleoperator
     robot.connect()
@@ -390,9 +390,17 @@ Set the flow of data recording using command-line arguments:
 
 Control the data recording flow using keyboard shortcuts:
 
-- Press **Right Arrow (`→`)**: Early stop the current episode or reset time and move to the next.
-- Press **Left Arrow (`←`)**: Cancel the current episode and re-record it.
-- Press **Escape (`ESC`)**: Immediately stop the session, encode videos, and upload the dataset.
+- Press **Right Arrow (`→`)** or **`n`**: Early stop the current episode or reset time and move to the next.
+- Press **Left Arrow (`←`)** or **`r`**: Cancel the current episode and re-record it.
+- Press **Escape (`ESC`)** or **`q`**: Immediately stop the session, encode videos, and upload the dataset.
+
+<Tip>
+
+These control-flow shortcuts work on **X11, Wayland, and headless/SSH** sessions. When a global keyboard backend isn't available (Wayland, a headless machine, or macOS without Accessibility permission), `lerobot-record` automatically reads the same keys from the terminal — launch it from an interactive terminal and keep it focused. You can also use the letter equivalents **`n`** (next, same as `→`), **`r`** (re-record, same as `←`) and **`q`** (quit, same as `ESC`). No `$DISPLAY` setup is required.
+
+This applies to the recording control flow only. Keyboard **teleoperation** (driving the robot with the keyboard) still needs a global key backend, so it works only on an X11 session, a Windows desktop, or macOS with Accessibility/Input Monitoring granted — not on Wayland or headless sessions.
+
+</Tip>
 
 #### Tips for gathering data
 
@@ -406,7 +414,7 @@ If you want to dive deeper into this important topic, you can check out the [blo
 
 #### Troubleshooting:
 
-- On Linux, if the left and right arrow keys and escape key don't have any effect during data recording, make sure you've set the `$DISPLAY` environment variable. See [pynput limitations](https://pynput.readthedocs.io/en/latest/limitations.html#linux).
+- On Linux, the recording control-flow keys (arrow keys, Escape) work on X11, Wayland, and headless/SSH sessions as long as `lerobot-record` runs in an interactive terminal — no `$DISPLAY` setup is needed. If the keys have no effect, make sure you are in an interactive (TTY) terminal, not a piped/non-TTY session, and that it is focused; the letter equivalents `n` / `r` / `q` also work. Keyboard _teleoperation_ (as opposed to the recording control flow) still requires a global key backend — an X11 session, a Windows desktop, or macOS with Accessibility/Input Monitoring granted — and is unavailable on Wayland or headless machines. See [pynput limitations](https://pynput.readthedocs.io/en/latest/limitations.html#linux).
 
 ## Visualize a dataset
 
@@ -506,6 +514,12 @@ lerobot-train \
   --resume=true
 ```
 
+`--config_path` also accepts a **Hub repo id**: if a run pushed its checkpoints to the Hub (with `--save_checkpoint_to_hub=true`), you can resume straight from the repo — its latest checkpoint is downloaded and training continues, restoring the optimizer, scheduler, step counter and data order:
+
+```bash
+lerobot-train --config_path=${HF_USER}/my_policy --resume=true
+```
+
 If you do not want to push your model to the hub after training use `--policy.push_to_hub=false`.
 
 Additionally you can provide extra `tags` or specify a `license` for your model or make the model repo `private` by adding this: `--policy.private=true --policy.tags=\[ppo,rl\] --policy.license=mit`
@@ -518,78 +532,48 @@ If your local computer doesn't have a powerful GPU you could utilize Google Cola
 
 Hugging Face jobs let's you easily select hardware and run the training in the cloud. So if you don't have a powerful GPU or you need more VRAM or just want to train a model much faster use HF Jobs! It's pay as you go and you simply pay for each second of use, you can see the pricing and additional information [here](https://huggingface.co/docs/hub/jobs).
 
-To run the training use this command:
+`lerobot-train` runs locally by default. To run on a HuggingFace GPU, pass `--job.target` with a hardware flavor name:
 
-<hfoptions id="train_with_hf_jobs">
-<hfoption id="Command">
 ```bash
-hf jobs run \
-  --flavor a10g-small \
-  --timeout 4h \
-  --secrets HF_TOKEN \
-  huggingface/lerobot-gpu:latest \
-  -- \
-  python -m lerobot.scripts.lerobot_train \
-    --dataset.repo_id=username/dataset \
-    --policy.type=act \
-    --steps=5000 \
-    --batch_size=16 \
-    --policy.device=cuda \
-    --policy.repo_id=username/your_policy \
-    --log_freq=100
+lerobot-train \
+  --dataset.repo_id=${HF_USER}/so101_test \
+  --policy.type=act \
+  --policy.repo_id=${HF_USER}/my_policy \
+  --job.target=a10g-small
 ```
-</hfoption>
-<hfoption id="API example">
 
-<!-- prettier-ignore-start -->
-```python
-from huggingface_hub import run_job, get_token
+List available flavors and pricing with `hf jobs hardware`. The run streams its logs to your terminal; press Ctrl-C to detach (the job keeps running in the cloud). Re-attach or cancel with:
 
-run_name = "act_so101_hf_jobs"
-dataset_id = "username/dataset"
-user_hub_id = "username"
-
-command_args = [
-    "python", "-m", "lerobot.scripts.lerobot_train",
-    "--dataset.repo_id", dataset_id,
-    "--policy.type", "act",
-    "--steps", "5000",
-    "--batch_size", "16",
-    "--num_workers", "4",
-    "--policy.device", "cuda",
-    "--log_freq", "100",
-    "--save_freq", "1000",
-    "--save_checkpoint", "true",
-    "--wandb.enable", "false",
-    "--policy.repo_id", f"{user_hub_id}/{run_name}"
-]
-
-print(f"Submitting job '{run_name}' to Hugging Face Infrastructure...")
-
-job_info = run_job(
-    image="huggingface/lerobot-gpu:latest",
-    command=command_args,
-    flavor="a10g-small",
-    timeout="4h",
-    secrets={"HF_TOKEN": get_token()}
-)
-
-print("\n🚀 Job successfully launched!")
-print(f"🔹 Job ID: {job_info.id}")
-print(f"🔗 Live UI Dashboard & Logs: {job_info.url}")
+```bash
+hf jobs logs <job-id>
+hf jobs cancel <job-id>
 ```
-<!-- prettier-ignore-end -->
 
-</hfoption>
-</hfoptions>
+If your dataset exists only locally (not yet on the Hub), it is automatically pushed to a **private** Hub repo so the job can download it by `repo_id` (nothing is made public). The trained model is pushed to the model repo at the end of the run. To also push every intermediate checkpoint to the Hub as it is saved (so you can monitor progress mid-run), add `--save_checkpoint_to_hub=true` — this requires a runtime image that includes this feature.
 
-You can modify the `--flavor` to use different hardware, for example: `t4-small`, `a100-large`, `h200`. Use `hf jobs hardware` to see the full list with pricing.
-Depending on the model you want to train and the hardware you selected you can also modify the `--batch_size` and `--number_of_workers`.
-For longer training sessions increase the timeout.
+Every job (and any dataset pushed by the run) is tagged `lerobot` so it's easy to find on the Hub. Add your own with `--job.tags '["my-tag"]'`.
 
-Once the training is started you can go to [Jobs](https://huggingface.co/settings/jobs) and see if your jobs is running as well as all the outputs. Sometimes it takes a few minutes to schedule your job so be patient.
+By default the job is capped at `2d` (48h) of wall-clock. Override it with an HF Jobs duration string, e.g. `--job.timeout=4h` to fail faster or `--job.timeout=7d` for a longer run.
 
-After training the model will be pushed to hub and you can use it as any other model with LeRobot.
+> **Note:** the model repo is created up front (it holds the staged training config the job runs from). If a run fails before the model is pushed, that repo is left on the Hub so you can inspect it — it is not deleted automatically, so repeated failures can leave empty repos behind. Remove one with `hf repo delete <repo-id>`.
+
+**Prerequisites:** run `hf auth login` before submitting. For Weights & Biases integration, run `wandb login` or set `WANDB_API_KEY` on your machine — the key is forwarded to the job automatically.
+
+**Resuming on a job.** Adding `--job.target` to a resume command runs the resume in the cloud — the same command works locally or remotely. The checkpoint repo is the source of truth, and new checkpoints continue the lineage in the same repo:
+
+```bash
+# resume a Hub run on a job (its checkpoints are already on the Hub)
+lerobot-train --config_path=${HF_USER}/my_policy --resume=true --job.target=a10g-small
+
+# resume a LOCAL run on a job — the checkpoint is uploaded to a private Hub repo first,
+# then the job resumes from it (a local-only dataset is uploaded the same way)
+lerobot-train \
+  --config_path=outputs/train/act_so101_test/checkpoints/last/pretrained_model/train_config.json \
+  --resume=true \
+  --job.target=a10g-small
+```
+
+Job settings come from the current command, so override `--job.target`, `--job.timeout`, etc. as needed; for the resumed run to itself be resumable later, keep `--save_checkpoint_to_hub=true`.
 
 #### Upload policy checkpoints
 
@@ -612,6 +596,8 @@ hf upload ${HF_USER}/act_so101_test${CKPT} \
 
 Use `lerobot-rollout` to deploy a trained policy on your robot. You can choose different strategies depending on your needs:
 
+The examples below load the model from `--policy.path`. To pin a specific pushed version — useful once `--save_checkpoint_to_hub=true` has committed several checkpoints — add `--policy.pretrained_revision` with a commit hash, branch, or tag. Each pushed checkpoint is tagged with its step (e.g. `--policy.pretrained_revision=010000`), so you can recover a checkpoint by step without looking up its commit sha.
+
 <hfoptions id="eval">
 <hfoption id="Base mode (no recording)">
 ```bash

docs/source/inference.mdx

@@ -117,7 +117,7 @@ lerobot-rollout \
     --strategy.num_episodes=20 \
     --policy.path=outputs/pretrain/checkpoints/last/pretrained_model \
     --robot.type=bi_openarm_follower \
-    --teleop.type=openarm_mini \
+    --teleop.type=bi_openarm_mini \
     --dataset.repo_id=${HF_USER}/rollout_hil_data \
     --dataset.single_task="Fold the T-shirt"
 ```

docs/source/isaac_teleop.mdx

@@ -0,0 +1,397 @@
+# Isaac Teleop
+
+Control your robot with NVIDIA [Isaac Teleop](https://github.com/NVIDIA/IsaacTeleop), a
+multi-modal teleoperation framework. Isaac Teleop drives a single `TeleopSession` from a range
+of input devices — XR (VR) controllers, hand tracking, full-body tracking, Manus gloves, foot
+pedals, and more.
+
+In LeRobot, Isaac Teleop ships as a self-contained example under
+[`examples/isaac_teleop_to_so101/`](https://github.com/huggingface/lerobot/tree/main/examples/isaac_teleop_to_so101).
+Each Isaac Teleop input device is its own `Teleoperator` subclass in the example's
+`isaac_teleop` package, sharing one session lifecycle (see `IsaacTeleopTeleoperator`). The
+devices available today are the **XR controller** (`XRController`) and a back-drivable
+**SO-101 leader arm** (`SO101LeaderArm`); Manus gloves and hand/full-body tracking are the
+natural next devices. This guide focuses on the XR controller; the SO-101 leader is summarized
+under [Run the example](#step-3-run-the-example).
+
+**In this guide you'll learn:**
+
+- How an Isaac Teleop device drives a robot end‑effector (EE) target
+- How the _clutch_ (squeeze/grip on the XR controller) engages teleoperation without jerking the arm
+- How to run the SO‑101 teleoperation example and tune motion / gripper / IK
+
+## Installation
+
+The example lives in the LeRobot repository (it is not part of the `lerobot` pip package), so
+clone the repo and install from source. The canonical, always-up-to-date install and usage
+reference is the example's
+[`README.md`](https://github.com/huggingface/lerobot/tree/main/examples/isaac_teleop_to_so101/README.md);
+in short:
+
+```bash
+git clone https://github.com/huggingface/lerobot.git
+cd lerobot
+uv pip install -e ".[feetech,kinematics,dataset]" "huggingface_hub>=1.5"
+uv pip install "isaacteleop[cloudxr,retargeters-lite]~=1.3.131" "scipy>=1.14"
+```
+
+`isaacteleop` is published on public PyPI (Linux only). The `cloudxr` extra brings the CloudXR
+runtime bindings; `retargeters-lite` is the scipy-based retargeter path that resolves on both
+x86_64 and ARM (on aarch64 — e.g. a DGX Spark — the full `retargeters` extra does not resolve
+because of its `dex-retargeting`/`nlopt` pins, which is why it is not the default here). On
+x86_64 you can additionally install the full retargeter stack:
+
+```bash
+uv pip install "isaacteleop[retargeters]~=1.3.131"
+```
+
+### Set up CloudXR and connect a headset
+
+Isaac Teleop streams the headset to your machine over **NVIDIA CloudXR**, which provides the
+OpenXR runtime the session connects to. By default LeTeleop **auto-launches the CloudXR runtime
+for you** when you call `teleop_device.connect()` — you no longer have to run `python -m
+isaacteleop.cloudxr` and `source cloudxr.env` in a separate shell. All you need is a supported
+headset connected and the CloudXR firewall ports open. Follow the Isaac Teleop
+[Quick Start](https://nvidia.github.io/IsaacTeleop/main/getting_started/quick_start.html) for the
+headset-pairing and firewall details.
+
+**First run (EULA).** The very first launch must accept the NVIDIA CloudXR EULA. The auto-launch
+prompts for it **on stdin**, so on a headless machine it will hang waiting for input. Bootstrap
+the EULA once, interactively, with:
+
+```bash
+python -m isaacteleop.cloudxr --accept-eula   # one-time: accept the CloudXR EULA
+```
+
+After that, `connect()` launches the runtime non-interactively. The launch **blocks for ~30s**
+while the runtime comes up.
+
+**Configuration.** Two fields on `IsaacTeleopConfig` (shared by every device) control this:
+
+- `auto_launch_cloudxr` (default `True`) — whether `connect()` starts the runtime. Set `False`
+  when CloudXR is already running externally.
+- `cloudxr_env_file` (default `None`) — an optional CloudXR device-profile `.env` selecting the
+  headset transport (e.g. an Apple Vision Pro profile). This is launcher **input**; it is not the
+  `~/.cloudxr/run/cloudxr.env` **output** file the old manual flow told you to `source`. `None`
+  keeps the default auto-WebRTC profile — though the SO-101 example overrides it to the
+  `default.env` shipped next to `teleoperate.py` unless you pass `--teleop.cloudxr_env_file`.
+
+**Opting out.** To skip the auto-launch (CloudXR already running), either set
+`auto_launch_cloudxr=False` or export:
+
+```bash
+export LEROBOT_CLOUDXR_SKIP_AUTOLAUNCH=1
+```
+
+The **env var takes precedence over the config field**: if `LEROBOT_CLOUDXR_SKIP_AUTOLAUNCH=1` is
+set, the auto-launch is skipped even when `auto_launch_cloudxr=True`. This variable is
+**independent** of Isaac Lab's `ISAACLAB_CXR_SKIP_AUTOLAUNCH` — setting one does not affect the
+other.
+
+**One teleoperator per process.** The CloudXR runtime configures the environment process-wide (a
+singleton), so run a single Isaac Teleop teleoperator per process.
+
+**Shutting down.** Always call `teleop_device.disconnect()` on exit — including on Ctrl-C. Wrap
+your teleoperation loop in `try/finally` and call `disconnect()` in the `finally`. This tears down
+the OpenXR session **before** the CloudXR runtime, which is the required order; the launcher's
+`atexit` hook only reaps the runtime and does not run the session's `__exit__`, so without an
+explicit `disconnect()` an interrupted run shuts down in the wrong order.
+
+```python
+teleop_device.connect()
+try:
+    while True:
+        action = teleop_device.get_action()
+        # ... drive the robot ...
+finally:
+    teleop_device.disconnect()
+```
+
+See [System Requirements](https://nvidia.github.io/IsaacTeleop/main/references/requirements.html)
+for supported OS / GPU / CloudXR versions and headsets.
+
+## How it works
+
+The XR controller is one Isaac Teleop **input** device. `XRController` is a deliberately thin
+reader: it exposes the **raw** controller grip pose — already statically rebased into the robot
+base frame — plus the squeeze and trigger analog values. It has **no** retargeters and **no**
+clutch logic of its own. The clutch (engage latch + delta rebasing onto the EE) and the gripper
+mapping live downstream in the example loop, which then feeds LeRobot's existing closed‑loop
+Cartesian IK pipeline — the same one the phone teleoperator uses. The device‑specific pieces are
+`XRController`, the loop's `Clutch`, and `MapXRControllerActionToRobotAction`; everything downstream
+(`EEBoundsAndSafety`, `InverseKinematicsEEToJoints`) is shared, and a future device (e.g. Manus
+gloves) would swap in its own `teleop_<device>.py` + processor while reusing the rest.
+
+`XRController._build_pipeline` wires Isaac Teleop's `ControllersSource` — statically rebased into
+the robot base frame by the native `ControllerTransform` (`base_T_anchor`) — and exposes the
+transformed controller stream verbatim. `get_action()` reads the grip pose, squeeze, and trigger
+straight off it; the session is always stepped `RUNNING` (there is no clutch retargeter to gate).
+
+The `Clutch` class (in `examples/isaac_teleop_to_so101/isaac_teleop/clutch.py`, driven by the
+loop in `common.py`) mirrors Isaac Teleop's `SO101ClutchRetargeter`, but lives in-loop so the
+device can stay a thin reader:
+
+- It latches its engage origin on the squeeze **engage edge** (the frame the squeeze first crosses
+  `clutch_threshold`) and rebases both position and orientation around it, so engaging does not
+  teleport the arm. `Clutch.rebase` returns the absolute base-frame target as a `(pos, quat)`
+  pair, which the loop concatenates into the 7D `ee_pose` fed to the processor.
+- The analog trigger becomes a gripper `closedness` in `[0, 1]` (0 = open, 1 = closed),
+  proportional to the trigger pull, which `MapXRControllerActionToRobotAction` maps to a jaw target.
+
+See the Isaac Teleop
+[Retargeting interface](https://nvidia.github.io/IsaacTeleop/main/references/retargeting/index.html)
+and [architecture overview](https://nvidia.github.io/IsaacTeleop/main/overview/architecture.html)
+for how source nodes and retargeters compose.
+
+```text
+  VR controller (OpenXR)
+        │
+        ▼
+  XRController.get_action()          ── raw base-frame grip_pos / grip_quat + squeeze + trigger
+        │                                (TeleopSession always stepped RUNNING; clutch lives downstream)
+        ▼
+  Clutch.rebase(grip_pos, grip_quat) ── engage-relative delta applied to the EE home (pos + orient)
+        │  ee_pose (7) / closedness       → absolute ee_pose; closedness = trigger
+        ▼
+  MapXRControllerActionToRobotAction ── absolute ee.x/y/z; ee.w* = orientation rotvec target;
+        │  ee.x/y/z / ee.w* / ee.gripper_pos   ee.gripper_pos = (1 - closedness) * 100
+        ▼
+  EEBoundsAndSafety                ── workspace clip + per-frame step clamp (clamp+warn)
+        │
+        ▼
+  InverseKinematicsEEToJoints      ── closed-loop Placo IK; position + soft-orientation
+        │  (orientation_weight=0.01)   (passes ee.gripper_pos → gripper.pos)
+        ▼
+  SO-101 follower joint targets
+```
+
+### The clutch: owned by the example loop
+
+Unlike the phone pipeline (which splits the clutch across `MapPhoneActionToRobotAction` and
+`EEReferenceAndDelta`), the XR clutch lives entirely in the example loop's `Clutch` class. It emits
+an **absolute** EE pose, so there is no `EEReferenceAndDelta` stage and no delta accumulation in the
+processor — `MapXRControllerActionToRobotAction` is a pure, stateless per‑frame mapping.
+
+The clutch latches its engage origin on the squeeze **engage edge** (the moment the squeeze crosses
+`clutch_threshold`) and drives the EE from the motion _relative_ to that origin, so the arm does not
+teleport on engage. On **every** engage — startup and mid‑task re‑clutch alike — the home
+_position_ is latched from forward kinematics on the arm's **measured joints**, so the home equals
+where the arm physically is even if it moved while disengaged, and the engage is jump‑free. The
+home _orientation_ keeps the last commanded rotation: the 5‑DOF arm tracks orientation only
+softly, so latching the measured wrist orientation would inject its tracking offset into the
+command on every re‑clutch.
+
+## Controls
+
+- **Squeeze / grip** — the **clutch** (deadman). Hold it past `clutch_threshold` to engage
+  teleoperation; release to pause. Each engage re‑captures the origin, so you can reposition
+  your hand while paused and re‑engage without the arm jumping (index/clutch style).
+- **Trigger** — the **gripper**, controlled **analog**. The jaw tracks the trigger
+  proportionally — a half‑pressed trigger leaves the jaw half‑closed — via a closedness in
+  `[0, 1]` (0 = open, 1 = closed) that maps to an absolute gripper joint target.
+- **Controller orientation** — the **wrist**. The clutch rebases the controller orientation
+  (engage‑relative, base‑frame) into a soft IK orientation target the wrist tracks alongside
+  position. On the 5‑DOF SO‑101 the wrist follows the hand only partially by design — see
+  `orientation_weight` below.
+
+## Get started
+
+### Step 1: Create the teleoperator
+
+```python
+# Run from the repo root so the `examples` package is importable.
+from examples.isaac_teleop_to_so101.isaac_teleop import XRController, XRControllerConfig
+
+teleop_config = XRControllerConfig(
+    hand_side="right",      # "left" or "right" controller
+    clutch_threshold=0.5,   # squeeze value above which the clutch engages
+)
+teleop_device = XRController(teleop_config)
+```
+
+`XRController.get_action()` returns the **raw** base‑frame controller pose, not a clutch‑rebased
+target: `grip_pos` (3,) `[x, y, z]` [m] and `grip_quat` (4,) `[qx, qy, qz, qw]` in the robot base
+frame, plus scalar `squeeze` and `trigger` analog values in `[0, 1]`. The example loop's `Clutch`
+turns these into the absolute `ee_pose`, and the squeeze is thresholded by the loop against
+`clutch_threshold` to engage.
+
+### Step 2: Connect
+
+Calling `teleop_device.connect()` first auto-launches the CloudXR runtime (unless you opted out —
+see [Set up CloudXR and connect a headset](#set-up-cloudxr-and-connect-a-headset); this blocks for
+~30s and on the first run prompts for the EULA on stdin), then starts the Isaac Teleop
+[`TeleopSession`](https://nvidia.github.io/IsaacTeleop/main/getting_started/teleop_session.html)
+(opens the OpenXR session and discovers the controllers). XR controllers are self‑calibrating, so
+there is no manual calibration step — the clutch handles re‑centering each time you engage. Pair
+`connect()` with a `try/finally` that calls `disconnect()` so the session tears down before the
+runtime on exit/Ctrl-C.
+
+### Step 3: Run the example
+
+The example assumes you configured your robot (SO‑101 follower) and set the correct serial port.
+
+The **robot URDF and its meshes are fetched automatically** on first run: the XR device downloads
+the SO-101 URDF from the
+[`lerobot/robot-urdfs` Hugging Face bucket](https://huggingface.co/buckets/lerobot/robot-urdfs/tree/so101)
+into the LeRobot cache (`HF_LEROBOT_HOME/robot-urdfs/so101/`) and reuses it after, so there is no
+separate download step :
+
+```bash
+python -m examples.isaac_teleop_to_so101.teleoperate --robot.type=so101_follower --robot.port=/dev/ttyACM0 \
+    --robot.id=so101_follower_arm --teleop.type=xr_controller
+```
+
+The CLI is `lerobot-teleoperate`-style (draccus): `--robot.*` configures the SO-101 follower and
+`--teleop.type` selects the Isaac input device (`xr_controller` | `so101_leader`), with
+`--teleop.*` its device knobs. `--teleop.type=xr_controller` runs the XR-controller path described
+above. The startup safety contract: by default it slews all joints to a default reset pose over
+`--reset_duration` seconds (`--reset_to_origin=false` keeps the arm where it is), then seeds the
+clutch home from the arm's measured pose so the first engage is jump-free; the follower is
+commanded only while the clutch is engaged.
+
+**Customizing the reset pose.** The reset pose ships as a built-in default (a comfortable mid-range
+pose) and works out of the box — you do **not** need to record anything. To tailor it to your setup,
+back-drive the arm to the pose you want and run
+`python -m examples.isaac_teleop_to_so101.override_reset_pose --id <robot.id>`; it writes the
+current joints to a per-arm file in the LeRobot cache
+(`HF_LEROBOT_HOME/reset_poses/<robot.name>/<robot.id>.json`, keyed like calibration), which then takes
+priority over the built-in default on the next run. Because it lives in the user-local cache (not
+the repo), your override stays on your machine, and both `teleoperate` and `record` honor it
+when launched with the same `--robot.id`.
+
+The other device, `--teleop.type=so101_leader`, mirrors the follower 1:1 from a back-drivable
+SO-101 _leader arm_ whose joints are streamed by Isaac Teleop's native `so101_leader` plugin (no
+clutch, no IK — the leader and follower share the SO-101 kinematics).
+
+The `so101_leader_plugin` binary is a C++ plugin that is **not** part of the `isaacteleop` pip
+package — you build it from the Isaac Teleop source tree. Follow
+[Build Isaac Teleop from source](https://nvidia.github.io/IsaacTeleop/main/getting_started/build_from_source/index.html)
+(in short, from your Isaac Teleop checkout: `cmake -B build && cmake --build build --parallel &&
+cmake --install build`); the build installs the plugins under `<IsaacTeleop>/install/plugins/`, so
+the binary lands at `install/plugins/so101_leader/so101_leader_plugin` — the `--launch_plugin` path
+below. See the plugin's own `README.md` (next to the binary) for its serial/calibration details.
+
+Point `--teleop.port` at the physical leader's serial port and `--launch_plugin` at that plugin
+binary to have the script spawn it after CloudXR is up:
+
+```bash
+python -m examples.isaac_teleop_to_so101.teleoperate --robot.type=so101_follower --robot.port=/dev/ttyACM0 \
+    --robot.id=so101_follower_arm --teleop.type=so101_leader \
+    --teleop.port=/dev/ttyACM1 --teleop.id=so101_leader_arm \
+    --launch_plugin=/code/Teleop/install/plugins/so101_leader/so101_leader_plugin
+```
+
+(Note `so101_leader` here is the _Isaac_ leader, resolved against the Isaac Teleop device
+registry, distinct from `lerobot-teleoperate`'s serial `so101_leader`.) When a `--teleop.port` is
+set, the plugin's tick→radian calibration is inferred from `--teleop.id` and passed to the plugin
+as its third positional arg — the LeRobot-format JSON at
+`HF_LEROBOT_CALIBRATION/teleoperators/so_leader/<id>.json`, the same file the serial SO-101 leader
+uses (`lerobot-calibrate --teleop.type=so101_leader --teleop.id=<id>`). If it is missing the script
+warns and the plugin uses built-in defaults. Run `python -m examples.isaac_teleop_to_so101.teleoperate --help` for all flags. Its
+startup safety contract: by default the follower is
+slewed to the leader's first reading over `--align_duration` seconds (`--align=false` to skip) so
+the arm does not snap when the mirror begins, and while the leader stream is stale the follower is
+held at its measured pose.
+
+The URDF fetch uses `huggingface_hub` (already a LeRobot dependency) against the public
+`lerobot/robot-urdfs` bucket, so it needs no login. It is cached under
+`HF_LEROBOT_HOME/robot-urdfs/so101/`; delete that folder to force a re‑download.
+
+Then, in your headset: squeeze and hold the grip to engage, move the controller to drive the
+arm, twist/tilt it to orient the wrist, and press the trigger to close the gripper
+(proportionally — release to open).
+
+To record a dataset (not just teleoperate), use `record.py` in the same folder. It dispatches on
+`--teleop.type` (`xr_controller` | `so101_leader`) exactly like `teleoperate.py`, so either device
+can drive the follower, and it saves the commanded joints to a LeRobot dataset (`lerobot-record`-style
+`--dataset.*` flags). See its module docstring for the full CLI and the keyboard recording shortcuts.
+
+## Important pipeline steps and options
+
+The clutch already produces an absolute base‑frame pose, so the processor side is a thin
+**absolute‑pose** path — there is no frame remap, no delta accumulation, and no
+`EEReferenceAndDelta` stage.
+
+- `MapXRControllerActionToRobotAction` is a stateless per‑frame mapping from the device output to
+  the IK input contract. It writes the absolute base‑frame position, encodes the absolute
+  orientation as a rotvec target, and inverts the closedness into a motor gripper target:
+
+  ```python
+  action["ee.x"], action["ee.y"], action["ee.z"] = ee_pose[:3]   # absolute, base frame [m]
+  action["ee.wx"], action["ee.wy"], action["ee.wz"] = orient_rotvec  # orientation target (rotvec)
+  action["ee.gripper_pos"] = (1 - closedness) * 100   # motor units; SO-101 calibrates 100 = open
+  ```
+
+  The gripper polarity (`100 = open, 0 = closed`) is a hardware‑calibration convention in the source — flip it there if the jaw opens when it should close.
+
+- `EEBoundsAndSafety` clamps the EE to a workspace and rate‑limits per‑frame jumps. The clutch's
+  no‑teleport keeps frames small, so `max_ee_step_m` mostly catches transient controller tracking
+  glitches. The z floor is `0.0` (the table plane) so a stray target cannot drive the EE below the
+  table; x/y stay at the loose `[-1, 1]` m box. Set `raise_on_jump=False` so an over‑limit frame is
+  **clamped and warned** instead of raising — a crash mid‑loop would leave the arm uncontrolled:
+
+  ```python
+  EEBoundsAndSafety(
+      end_effector_bounds={"min": [-1.0, -1.0, 0.0], "max": [1.0, 1.0, 1.0]},
+      max_ee_step_m=0.10,
+      raise_on_jump=False,
+  )
+  ```
+
+- `InverseKinematicsEEToJoints(initial_guess_current_joints=False, orientation_weight=0.01)` solves
+  closed‑loop Placo IK. SO‑101 is a 5‑DOF arm, so the IK is position‑dominant; the small
+  `orientation_weight` lets it softly track the orientation target carried in `ee.w*` so the wrist
+  follows the hand, while the under‑determined roll stays partial by design. There is **no**
+  `GripperVelocityToJoint`: the absolute `ee.gripper_pos` is passed straight to `gripper.pos`.
+  `initial_guess_current_joints=False` warm‑starts each solve from the **previous IK solution**
+  rather than re‑seeding from the measured joints, so the joint trajectory stays continuous
+  frame‑to‑frame. Tune `orientation_weight` on hardware — too high fights position tracking, too
+  low ignores the orientation command.
+
+The example also gates safety at the loop level: after the startup reset slew (on by default —
+pass `--reset_to_origin=false` to keep the arm where it is), it commands the robot **only while
+the clutch is engaged**, and re‑sends the measured joints while disengaged, so releasing the
+clutch freezes the arm in place.
+
+See the [Processors for Robots and Teleoperators](./processors_robots_teleop) guide for more on
+adapting the pipeline to other robots.
+
+## Troubleshooting
+
+- **`ModuleNotFoundError: isaacteleop`** — the `isaacteleop` package is not installed in the
+  active environment. Re-run the install command at the top of this guide:
+  `uv pip install "isaacteleop[cloudxr,retargeters-lite]~=1.3.131"`.
+- **No controllers found** — make sure the CloudXR runtime is running, the firewall ports are
+  whitelisted, and the headset is connected (see
+  [Set up CloudXR and connect a headset](#set-up-cloudxr-and-connect-a-headset) and the Isaac
+  Teleop [Quick Start](https://nvidia.github.io/IsaacTeleop/main/getting_started/quick_start.html)).
+- **CloudXR auto-launch failed** — `connect()` raises a `RuntimeError` if the runtime does not
+  come up within its startup timeout. Check the launcher logs under `~/.cloudxr/logs`. Common
+  causes: the EULA was never accepted (run `python -m isaacteleop.cloudxr --accept-eula` once,
+  interactively — the auto-launch prompts on stdin and hangs headless), or the runtime is already
+  running externally (set `LEROBOT_CLOUDXR_SKIP_AUTOLAUNCH=1` or `auto_launch_cloudxr=False` to
+  skip the auto-launch).
+- **Arm does not move** — the clutch is a deadman: you must hold the squeeze/grip past
+  `clutch_threshold`. Lower the threshold if your controller's squeeze is reported softly.
+- **Motion feels misaligned** — confirm the headset/play space orientation. The controller stream
+  is rebased into the robot base frame by the `base_T_anchor` transform on `XRControllerConfig`
+  (default: standard OpenXR → robot axis convention); adjust it if your anchor frame differs.
+
+## Learn more
+
+NVIDIA Isaac Teleop documentation ([docs home](https://nvidia.github.io/IsaacTeleop/),
+[GitHub](https://github.com/NVIDIA/IsaacTeleop)):
+
+- [Quick Start](https://nvidia.github.io/IsaacTeleop/main/getting_started/quick_start.html) —
+  install, run the CloudXR server, connect a headset, run a teleop example.
+- [TeleopSession](https://nvidia.github.io/IsaacTeleop/main/getting_started/teleop_session.html) —
+  the session API `XRController` wraps.
+- [Retargeting interface](https://nvidia.github.io/IsaacTeleop/main/references/retargeting/index.html)
+  and [architecture overview](https://nvidia.github.io/IsaacTeleop/main/overview/architecture.html) —
+  how source nodes and retargeters compose into a pipeline.
+- [Build from source](https://nvidia.github.io/IsaacTeleop/main/getting_started/build_from_source/index.html) —
+  build `isaacteleop` (and its C++ plugins, including the `so101_leader` plugin used above) from a
+  local checkout.
+- [System Requirements](https://nvidia.github.io/IsaacTeleop/main/references/requirements.html) and
+  the [CloudXR SDK docs](https://docs.nvidia.com/cloudxr-sdk) — supported platforms, GPUs,
+  CloudXR/OpenXR runtime versions, and headsets.

docs/source/lekiwi.mdx

@@ -319,7 +319,7 @@ If you want to dive deeper into this important topic, you can check out the [blo
 
 #### Troubleshooting:
 
-- On Linux, if the left and right arrow keys and escape key don't have any effect during data recording, make sure you've set the `$DISPLAY` environment variable. See [pynput limitations](https://pynput.readthedocs.io/en/latest/limitations.html#linux).
+- On Linux, the recording control-flow keys (arrow keys, Escape) work on X11, Wayland, and headless/SSH sessions as long as you run the recording from an interactive terminal (keep it focused) — no `$DISPLAY` setup is needed; the letter equivalents `n` / `r` / `q` also work. Note that **keyboard teleoperation of the LeKiwi base** is different: it relies on a global key backend and therefore works only on an X11 session, a Windows desktop, or macOS with Accessibility/Input Monitoring granted — not on Wayland or headless machines. See [pynput limitations](https://pynput.readthedocs.io/en/latest/limitations.html#linux).
 
 ## Replay an episode
 

docs/source/lerobot-dataset-v3.mdx

@@ -44,7 +44,7 @@ lerobot-record \
   --dataset.num_episodes=5 \
   --dataset.single_task="Grab the black cube" \
   --dataset.streaming_encoding=true \
-  # --dataset.camera_encoder.vcodec=auto \
+  # --dataset.rgb_encoder.vcodec=auto \
   --dataset.encoder_threads=2
 ```
 

docs/source/libero.mdx

@@ -143,7 +143,7 @@ lerobot-train \
   --batch_size=4 \
   --eval.batch_size=1 \
   --eval.n_episodes=1 \
-  --eval_freq=1000
+  --env_eval_freq=1000
 ```
 
 ## Reproducing published results

docs/source/libero_plus.mdx

@@ -173,7 +173,7 @@ lerobot-train \
     --batch_size=4 \
     --eval.batch_size=1 \
     --eval.n_episodes=1 \
-    --eval_freq=1000
+    --env_eval_freq=1000
 ```
 
 ## Relationship to LIBERO

docs/source/lingbot_va.mdx

@@ -0,0 +1,187 @@
+# LingBot-VA
+
+LingBot-VA is an **autoregressive video-action world-model policy** built on the **Wan2.2**
+video-diffusion stack. It interleaves, in one autoregressive sequence, the prediction of
+future **video latents** and **robot actions** ("VA" = Video-Action). The LeRobot
+integration wires LingBot-VA into the standard training, evaluation and processor
+interfaces.
+
+## Model Overview
+
+LingBot-VA is a **dual-stream "mixture-of-transformers"**: a video/latent stream
+(`patch_embedding_mlp → blocks → proj_out`) and an action stream
+(`action_embedder → blocks → action_proj_out`) share the same 30 transformer blocks and
+text conditioning.
+
+| Component                | Class                   | Role                                                        |
+| ------------------------ | ----------------------- | ----------------------------------------------------------- |
+| DiT backbone (trainable) | `WanTransformer3DModel` | ~5B-param dual-stream transformer.                          |
+| VAE (frozen)             | `AutoencoderKLWan`      | Wan2.2 VAE, `z_dim=48`. Lazy-pulled from the source repo.   |
+| Text encoder (frozen)    | `UMT5EncoderModel`      | UMT5-XXL, `d_model=4096`. Lazy-pulled from the source repo. |
+
+At inference the policy runs an autoregressive loop per chunk: it denoises the video-latent
+stream (CFG, ~20 steps) and the action stream (~50 steps) with two independent
+flow-matching schedulers, maintaining a KV cache across chunks. Real observed keyframes are
+fed back into the KV cache as the chunk is executed (closed-loop world modeling).
+
+### What the LeRobot Integration Covers
+
+- Standard `policy.type=lingbot_va` configuration through LeRobot.
+- Ready-to-use LeRobot-format checkpoints on the Hub (converted from the released upstream ones).
+- Autoregressive dual-stream inference behind the standard `select_action` interface
+  (single-environment eval, `--eval.batch_size=1`).
+- Opt-in saving of the policy's **predicted (imagined) videos** during eval / training.
+- Evaluation with `lerobot-eval` on LIBERO and RoboTwin.
+- Training / fine-tuning via the dual-stream flow-matching loss (`policy.forward`), see below.
+
+## Installation
+
+1. Install LeRobot by following the [Installation Guide](./installation).
+2. Install the LingBot-VA extra:
+
+```bash
+pip install -e ".[lingbot_va]"
+```
+
+## Checkpoints
+
+The released upstream checkpoints have been converted to LeRobot format and pushed to the Hub:
+
+| Variant                | LeRobot checkpoint               |
+| ---------------------- | -------------------------------- |
+| LIBERO-Long post-train | `lerobot/lingbot_va_libero_long` |
+| RoboTwin post-train    | `lerobot/lingbot_va_robotwin`    |
+| Pretrained base        | `lerobot/lingbot_va_base`        |
+
+Only the trainable ~5B transformer is stored in the LeRobot
+`model.safetensors`. The frozen VAE + UMT5 + tokenizer (~20 GB) are pulled from
+`config.wan_pretrained_path` at load time (defaults to the source `robbyant/*` repo). The
+UMT5-XXL text encoder runs on CPU by default (`config.text_encoder_device`) so the 5B
+transformer + VAE fit on a single 24–32 GB GPU.
+
+## Evaluation (LIBERO)
+
+```bash
+lerobot-eval \
+    --policy.path=lerobot/lingbot_va_libero_long \
+    --policy.device=cuda \
+    --env.type=libero --env.task=libero_10 \
+    --env.observation_height=128 --env.observation_width=128 \
+    --eval.n_episodes=50 --eval.batch_size=1 \
+    --output_dir=outputs/eval/lingbot_va_libero
+```
+
+LingBot-VA's streaming inference (KV cache + observed-keyframe feedback) is implemented for
+single-environment eval; use `--eval.batch_size=1`.
+
+## Evaluation (RoboTwin)
+
+RoboTwin 2.0 needs the SAPIEN + CuRobo simulator stack. You can use the benchmark Docker image
+(`docker/Dockerfile.benchmark.robotwin`, which also needs `warp-lang==1.3.1` and CuRobo built
+with the GPU's compute capability in `TORCH_CUDA_ARCH_LIST`). RoboTwin uses **end-effector-pose
+control**, so run with `--env.action_mode=ee`: the policy predicts per-arm `xyz+quaternion+gripper`
+deltas (`robotwin_tshape` latent layout) that are composed onto the episode's initial eef pose and
+executed via CuRobo IK.
+
+```bash
+lerobot-eval \
+    --policy.path=lerobot/lingbot_va_robotwin \
+    --policy.device=cuda \
+    --env.type=robotwin --env.task=beat_block_hammer --env.action_mode=ee \
+    --eval.n_episodes=10 --eval.batch_size=1 \
+    --output_dir=outputs/eval/lingbot_va_robotwin
+```
+
+### Saving predicted (imagined) videos
+
+Set `--policy.save_predicted_video=true` to additionally VAE-decode the predicted video
+latents and write `pred_episode_*.mp4` next to the env-rendered `eval_episode_*.mp4` videos.
+The same flag works for the periodic eval during `lerobot-train`.
+
+## Training / fine-tuning
+
+`LingBotVAPolicy.forward(batch)` implements the dual-stream **flow-matching** loss
+(`latent_loss + action_loss`, timestep-weighted, action-masked) from the paper: it VAE-encodes
+the camera clips into video latents, UMT5-encodes the task, noises both streams, runs the
+transformer's block-causal training pass and returns `(loss, metrics)`. Optimizer preset is AdamW
+with a linear-warmup-then-constant schedule (matching upstream).
+
+Requirements:
+
+- The block-causal masks use PyTorch **flex-attention**, so build the policy with
+  `--policy.attn_mode=flex` for training (the default `torch` SDPA is inference-only).
+- The full 5B DiT does not fit a single 24–32 GB GPU under AdamW; fine-tune with **LoRA**
+  (`--policy.use_peft=true`) and/or optimizer offload. `get_optim_params` returns only the
+  trainable (e.g. adapter) parameters; the VAE + UMT5 text encoder stay frozen.
+
+```bash
+lerobot-train \
+  --policy.path=lerobot/lingbot_va_libero_long --policy.attn_mode=flex \
+  --policy.use_peft=true \
+  --dataset.repo_id=<your LeRobot-format dataset> \
+  --batch_size=1 --steps=... --output_dir=outputs/train/lingbot_va
+```
+
+The dataset must provide camera clips (a temporal window per camera, VAE-encoded to
+`frame_chunk_size` latent frames) and `frame_chunk_size * action_per_frame` action steps per item.
+
+## Data format (action channels & camera order)
+
+LingBot-VA is an **end-effector (Cartesian) pose** policy, it predicts EEF poses + gripper, not
+joint positions. Actions live in a fixed multi-embodiment **30-dim** layout; map your robot's
+action dimensions into these channels and pad the rest with `0` (`used_action_channel_ids` selects
+the channels a given checkpoint actually uses):
+
+| channels | meaning                                               |
+| -------- | ----------------------------------------------------- |
+| 0–6      | Left-arm end-effector pose                            |
+| 7–13     | Right-arm end-effector pose                           |
+| 14–20    | Left-arm joints (unused by the released checkpoints)  |
+| 21–27    | Right-arm joints (unused by the released checkpoints) |
+| 28       | Left gripper                                          |
+| 29       | Right gripper                                         |
+
+- **LIBERO** uses channels `0–6`: a 6-DoF EEF delta (xyz + rotation) + gripper (single arm).
+- **RoboTwin** uses channels `[0–6, 28, 7–13, 29]`: left EEF (xyz + quaternion) + left gripper +
+  right EEF + right gripper (16 dims). The env converts these poses to joint trajectories via
+  CuRobo IK — joints are never predicted.
+
+Joint-space datasets (or a different EEF convention) must be remapped into this schema before
+fine-tuning these checkpoints.
+
+**Camera order is fixed and order-sensitive**, per-camera latents are concatenated spatially in
+`obs_cam_keys` order, so the physical camera→slot mapping must match training:
+
+| benchmark | `obs_cam_keys` (in order)                                                                             | `camera_layout`                                                     |
+| --------- | ----------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------- |
+| LIBERO    | `observation.images.image` (agentview / 3rd-person), `observation.images.image2` (eye-in-hand wrist)  | `width_concat` (latents concatenated on width)                      |
+| RoboTwin  | `observation.images.head_camera`, `observation.images.left_camera`, `observation.images.right_camera` | `robotwin_tshape` (full-res head below, two half-res wrists on top) |
+
+The first camera is the exterior/head view and the rest are wrist views.
+
+## Inference Hyperparameters (LIBERO)
+
+| Key                                    | Value                                                                             |
+| -------------------------------------- | --------------------------------------------------------------------------------- |
+| height × width                         | 128 × 128                                                                         |
+| cameras                                | `observation.images.image` (agentview), `observation.images.image2` (eye-in-hand) |
+| action channels used                   | 0–6 (7-DoF arm + gripper)                                                         |
+| action_per_frame / frame_chunk_size    | 4 / 4                                                                             |
+| attn_window                            | 30                                                                                |
+| video / action denoising steps         | 20 / 50                                                                           |
+| guidance_scale / action_guidance_scale | 5 / 1                                                                             |
+| snr_shift / action_snr_shift           | 5.0 / 0.05                                                                        |
+
+These are the defaults of `LingBotVAConfig`; override any of them via `--policy.<name>=...`.
+
+## Notes
+
+- **Attention backend:** inference uses the `torch` SDPA backend (always available). The
+  `flashattn` and `flex` backends are optional; `flex` is only needed for training.
+- **Model size:** the DiT is ~5B params and the frozen VAE+UMT5 add ~20 GB; inference needs
+  roughly 18–24 GB of VRAM.
+
+## License
+
+LingBot-VA is released under Apache-2.0. See the
+[upstream repository](https://github.com/Robbyant/lingbot-va).

docs/source/metaworld.mdx

@@ -120,11 +120,11 @@ lerobot-train \
   --batch_size=4 \
   --eval.batch_size=1 \
   --eval.n_episodes=1 \
-  --eval_freq=1000
+  --env_eval_freq=1000
 ```
 
 ## Practical tips
 
 - Use the one-hot task conditioning for multi-task training (MT10/MT50 conventions) so policies have explicit task context.
 - Inspect the dataset task descriptions and the `info["is_success"]` keys when writing post-processing or logging so your success metrics line up with the benchmark.
-- Adjust `batch_size`, `steps`, and `eval_freq` to match your compute budget.
+- Adjust `batch_size`, `steps`, and `env_eval_freq` to match your compute budget.

docs/source/molmoact2.mdx

@@ -17,7 +17,7 @@ the paper, see [allenai/molmoact2](https://github.com/allenai/molmoact2).
 Install LeRobot with the MolmoAct2 optional dependencies:
 
 ```bash
-pip install -e ".[molmoact2]"
+uv sync --locked --extra molmoact2
 ```
 
 To run the models in this repository, you need an NVIDIA GPU. The measurements
@@ -46,8 +46,8 @@ The repo has been tested with Ubuntu 22.04.
 
 To use MolmoAct2 in a LeRobot training config, set:
 
-```python
-policy.type=molmoact2
+```bash
+--policy.type=molmoact2
 ```
 
 ## Training
@@ -103,7 +103,7 @@ accelerate launch \
   --batch_size=32 \
   --num_workers=4 \
   --log_freq=20 \
-  --eval_freq=-1 \
+  --env_eval_freq=-1 \
   --save_checkpoint=true \
   --save_freq=2000
 ```
@@ -142,7 +142,7 @@ accelerate launch \
   --batch_size=32 \
   --num_workers=4 \
   --log_freq=20 \
-  --eval_freq=-1 \
+  --env_eval_freq=-1 \
   --save_checkpoint=true \
   --save_freq=2000
 ```
@@ -386,6 +386,68 @@ These results demonstrate MolmoAct2's strong performance across diverse robotic
 manipulation tasks. To reproduce them, follow the instructions in the LIBERO
 evaluation section.
 
+## Hardware Deployment (lerobot-rollout)
+
+LeRobot-format checkpoints are available on the Hub for direct use with
+`lerobot-rollout`. Each checkpoint uses specific camera names that must
+match your robot's camera configuration.
+
+### Camera naming convention
+
+Each checkpoint expects specific `observation.images.*` keys.
+If your robot cameras have different names, use `--rename_map` to map them:
+
+| Checkpoint                    | Camera keys            | Description              |
+| ----------------------------- | ---------------------- | ------------------------ |
+| MolmoAct2-LIBERO-LeRobot      | `image`, `wrist_image` | LIBERO sim cameras       |
+| MolmoAct2-BimanualYAM-LeRobot | `top`, `left`, `right` | YAM 3-camera setup       |
+| MolmoAct2-DROID-LeRobot       | `cam0`, `cam1`         | External + wrist         |
+| MolmoAct2-SO100_101-LeRobot   | `cam0`, `cam1`         | Primary + secondary view |
+
+Example with an SO-100 robot using top and side cameras:
+
+```bash
+lerobot-rollout \
+  --policy.path=lerobot/MolmoAct2-SO100_101-LeRobot \
+  --rename_map='{"observation.images.top": "observation.images.cam0", "observation.images.side": "observation.images.cam1"}' \
+  --robot.type=so100_follower \
+  --robot.port=/dev/ttyACM0 \
+  --robot.cameras='{
+      top: {type: opencv, index_or_path: 0, width: 640, height: 480, fps: 30},
+      side: {type: opencv, index_or_path: 2, width: 640, height: 480, fps: 30}
+  }' \
+  --task="pick up the red cube" --duration=30
+```
+
+To use a wrist camera instead, just change the rename mapping:
+
+```bash
+--rename_map='{"observation.images.top": "observation.images.cam0", "observation.images.wrist": "observation.images.cam1"}'
+```
+
+### Joint frame transform (SO-100/101 zero-shot)
+
+<Tip warning={true}>
+The MolmoAct2-SO100_101 checkpoint was trained on data that uses a different
+joint calibration convention than LeRobot >= 0.5.0. Without a frame
+correction, the arm may move in the wrong direction.
+
+This affects both **zero-shot deployment** and **fine-tuning** from the
+original checkpoint. The pretrained weights expect the old convention, so
+all joint data (observations and actions) must be transformed to match.
+
+The converted LeRobot checkpoint (`lerobot/MolmoAct2-SO100_101-LeRobot`)
+already includes this correction in its processor pipeline. If you convert
+or fine-tune the checkpoint yourself, set the following in the policy config (`configuration_molmoact2.py`):
+
+- `joint_signs`: `[1, -1, 1, 1, 1, 1]` (flips shoulder_lift direction)
+- `joint_offsets`: `[0, 90, 90, 0, 0, 0]` (shifts shoulder_lift and elbow_flex by 90°)
+
+See the [backward compatibility guide](./backwardcomp) for details on the
+calibration change.
+
+</Tip>
+
 ## Differences From the Original Implementation
 
 This LeRobot port is intended to match MolmoAct2 behavior while using LeRobot's

docs/source/multi_gpu_training.mdx

@@ -95,7 +95,7 @@ If you want to scale your hyperparameters when using multiple GPUs, you should d
 accelerate launch --num_processes=2 $(which lerobot-train) \
   --optimizer.lr=2e-4 \
   --dataset.repo_id=lerobot/pusht \
-  --policy=act
+  --policy.type=act
 ```
 
 **Training Steps Scaling:**
@@ -110,9 +110,64 @@ accelerate launch --num_processes=2 $(which lerobot-train) \
   --batch_size=8 \
   --steps=50000 \
   --dataset.repo_id=lerobot/pusht \
-  --policy=act
+  --policy.type=act
 ```
 
+## Training Large Models with FSDP
+
+DDP replicates the full model on every GPU, so a model that doesn't fit on one GPU won't fit under
+DDP either. For large models, use **FSDP** (Fully Sharded Data Parallel), which shards parameters,
+gradients, and optimizer state across GPUs. See the [accelerate FSDP guide](https://huggingface.co/docs/accelerate/usage_guides/fsdp) for background.
+
+An example on how to launch LeRobot training with FSDP across 4 GPUs (1 machine):
+
+```bash
+accelerate launch --config_file fsdp.yaml --num_processes=4 $(which lerobot-train) \
+  --dataset.repo_id=${HF_USER}/my_dataset \
+  --policy.type=<your_policy> \
+  --output_dir=outputs/train/my_policy_fsdp
+```
+
+A minimal `fsdp.yaml` (FSDP1; shards params/grads/optimizer — ZeRO-3-equivalent):
+
+```yaml
+compute_environment: LOCAL_MACHINE
+distributed_type: FSDP
+mixed_precision: bf16
+num_machines: 1
+num_processes: 4
+fsdp_config:
+  fsdp_version: 1
+  fsdp_sharding_strategy: FULL_SHARD # params + grads + optimizer (ZeRO-3)
+  fsdp_auto_wrap_policy: TRANSFORMER_BASED_WRAP
+  fsdp_transformer_layer_cls_to_wrap: <YourTransformerBlock> # repeated block class to shard
+  fsdp_use_orig_params: true # required: optimizer is built pre-prepare
+  fsdp_state_dict_type: FULL_STATE_DICT
+```
+
+Set `fsdp_transformer_layer_cls_to_wrap` to your model's repeated transformer-block class so each
+block is sharded as its own unit. `fsdp_use_orig_params: true` is required because LeRobot builds the
+optimizer before `accelerator.prepare()`.
+
+### FSDP checkpoints
+
+LeRobot gathers the full state dict across all ranks and the main process writes it as a single
+`model.safetensors`, loadable as usual with `Policy.from_pretrained(...)`. Two things to look out for:
+
+- **Checkpoints store fp32 weights.** Under mixed precision (`bf16`/`fp16`) FSDP keeps an fp32 master
+  copy, and the checkpoint saves it (~2× the bf16 size on disk) so training can resume consistently
+  with the fp32 optimizer state; `from_pretrained` casts back to the policy dtype on load. FSDP-specific
+  caveat: an fp32 checkpoint is materialized in full precision on the target device _before_ casting,
+  so loading it for inference on a tight GPU can OOM even when the bf16 model would fit — load on CPU
+  first, or cast `model.safetensors` to the deployment dtype offline.
+- The sharded optimizer state is gathered into a full (world-size-independent) state dict and saved
+  alongside the model in the same `optimizer_state.safetensors` / `optimizer_param_groups.json`
+  format as single-GPU training, so **resume-from-checkpoint is supported** with `--resume=true`.
+  Resume reshards both the model and the optimizer state to the _current_ FSDP topology, so you can
+  resume an FSDP checkpoint on a different number of GPUs. Note that the data sampler is only
+  sample-exact when the world size and batch size match the original run (a warning is logged
+  otherwise); the optimizer/model state itself is unaffected.
+
 ## Notes
 
 - The `--policy.use_amp` flag in `lerobot-train` is only used when **not** running with accelerate. When using accelerate, mixed precision is controlled by accelerate's configuration.

docs/source/multi_task_dit.mdx

@@ -314,7 +314,7 @@ lerobot-train \
   --steps=30000 \
   --save_freq=1000 \
   --log_freq=100 \
-  --eval_freq=1000 \
+  --env_eval_freq=1000 \
   --policy.type=multi_task_dit \
   --policy.device=cuda \
   --policy.horizon=32 \

docs/source/pi0fast.mdx

@@ -96,7 +96,7 @@ lerobot-train \
     --policy.type=pi0_fast \
     --output_dir=./outputs/pi0fast_training \
     --job_name=pi0fast_training \
-    --policy.pretrained_path=lerobot/pi0_fast_base \
+    --policy.pretrained_path=lerobot/pi0fast-base \
     --policy.dtype=bfloat16 \
     --policy.gradient_checkpointing=true \
     --policy.chunk_size=10 \
@@ -187,7 +187,7 @@ lerobot-train \
   --dataset.repo_id=lerobot/libero \
   --output_dir=outputs/libero_pi0fast \
   --job_name=libero_pi0fast \
-  --policy.path=lerobot/pi0fast_base \
+  --policy.path=lerobot/pi0fast-base \
   --policy.dtype=bfloat16 \
   --steps=100000 \
   --save_freq=20000 \

docs/source/policy_evo1_README.md

@@ -0,0 +1,18 @@
+# EVO1
+
+EVO1 is a Vision-Language-Action policy for robot control. The LeRobot
+integration uses an InternVL3 vision-language backbone with a flow-matching
+action head, and supports staged training through the standard LeRobot policy
+APIs.
+
+The upstream EVO1 project is available at
+[MINT-SJTU/Evo-1](https://github.com/MINT-SJTU/Evo-1).
+
+```bibtex
+@misc{evo1,
+  title = {EVO1},
+  author = {{MINT-SJTU}},
+  year = {2025},
+  howpublished = {\url{https://github.com/MINT-SJTU/Evo-1}},
+}
+```

docs/source/policy_fastwam_README.md

@@ -0,0 +1,56 @@
+## Research Paper
+
+Paper: https://arxiv.org/abs/2603.16666
+
+## Repository
+
+Code: https://github.com/yuantianyuan01/FastWAM
+
+Project page: https://yuantianyuan01.github.io/FastWAM/
+
+## Citation
+
+```bibtex
+@article{yuan2026fastwam,
+  title = {Fast-WAM: Do World Action Models Need Test-time Future Imagination?},
+  author = {Tianyuan Yuan and Zibin Dong and Yicheng Liu and Hang Zhao},
+  journal = {arXiv preprint arXiv:2603.16666},
+  year = {2026},
+  url = {https://arxiv.org/abs/2603.16666}
+}
+```
+
+## Additional Resources
+
+Base video model: https://huggingface.co/Wan-AI/Wan2.2-TI2V-5B
+
+Released upstream checkpoints: https://huggingface.co/yuanty/fastwam
+
+## Results
+
+Evaluated on LIBERO with [`ZibinDong/fastwam_libero_uncond_2cam224`](https://huggingface.co/ZibinDong/fastwam_libero_uncond_2cam224):
+
+| Suite          | Success rate | n_episodes |
+| -------------- | -----------: | ---------: |
+| libero_spatial |        97.6% |        500 |
+| libero_object  |        99.0% |        500 |
+| libero_goal    |        95.0% |        500 |
+| libero_10      |        94.0% |        500 |
+| **average**    |    **96.4%** |       2000 |
+
+Reproduce: `lerobot-eval --policy.path=ZibinDong/fastwam_libero_uncond_2cam224 --policy.device=cuda --policy.torch_dtype=float32 --policy.n_action_steps=10 --env.type=libero --env.task=libero_spatial --env.observation_height=256 --env.observation_width=256 --eval.batch_size=1 --eval.n_episodes=50 --seed=0 --env.episode_length=300`.
+
+For LIBERO-10, use `--env.task=libero_10 --env.episode_length=600`:
+
+```bash
+lerobot-eval \
+    --policy.path=ZibinDong/fastwam_libero_uncond_2cam224 \
+    --policy.device=cuda \
+    --policy.torch_dtype=float32 \
+    --policy.n_action_steps=10 \
+    --env.type=libero \
+    --env.task=libero_10 --env.observation_height=256 --env.observation_width=256 \
+    --eval.batch_size=1 \
+    --eval.n_episodes=50 \
+    --seed=0 --env.episode_length=600
+```

docs/source/policy_groot_README.md

@@ -1,6 +1,13 @@
 ## Research Paper
 
-Paper: https://research.nvidia.com/labs/gear/gr00t-n1_5/
+GR00T N1 technical report (covers the GR00T N1.x family, including N1.7): https://arxiv.org/abs/2503.14734
+
+GR00T N1.7 model card: https://huggingface.co/nvidia/GR00T-N1.7-3B
+
+GR00T N1.5 research page (earlier version): https://research.nvidia.com/labs/gear/gr00t-n1_5/
+
+> GR00T N1.5 support was removed from LeRobot; the last release supporting it is `lerobot==0.5.1`.
+> Current releases support GR00T N1.7 only.
 
 ## Repository
 
@@ -24,4 +31,108 @@ Code: https://github.com/NVIDIA/Isaac-GR00T
 
 Blog: https://developer.nvidia.com/isaac/gr00t
 
-Hugging Face Model: https://huggingface.co/nvidia/GR00T-N1.5-3B
+Hugging Face Models:
+
+- GR00T N1.7: https://huggingface.co/nvidia/GR00T-N1.7-3B
+- GR00T N1.7 LIBERO checkpoints: https://huggingface.co/nvidia/GR00T-N1.7-LIBERO
+
+<details>
+<summary><b>Original-vs-LeRobot parity test</b></summary>
+
+## Original-vs-LeRobot parity test
+
+`tests/policies/groot/test_groot_vs_original.py` verifies this LeRobot
+reimplementation of GR00T N1.7 (Qwen3-VL backbone + flow-matching action head)
+against NVIDIA's original `gr00t` package with two comparisons, each parametrized
+over every embodiment tag present in the checkpoint:
+
+1. **Model parity** — given byte-identical pre-processed inputs and the same
+   flow-matching seed (recorded in each artifact), both implementations must produce
+   the **same raw model output** (`get_action(...)["action_pred"]`, the normalized
+   flow-matching prediction). Output shapes must match exactly; any action-horizon
+   or action-dim mismatch fails the test.
+2. **Preprocessor parity** — given the identical raw observations (per-camera
+   frames, state vectors, language instruction), LeRobot's own preprocessor pipeline
+   (real Qwen3-VL chat template / tokenizer / image packing + checkpoint-driven
+   state normalization, no mocks) must produce the **same collated model inputs**
+   (`input_ids`, `attention_mask`, `pixel_values`, `image_grid_thw`, `state`,
+   `embodiment_id`) as the original package's processor.
+
+### Why two environments
+
+The original `gr00t` package pins `transformers==4.57.3` (Python 3.10); this
+integration requires `transformers>=5.x` (Qwen3-VL). Under 5.x, `PretrainedConfig`
+is itself a defaulted dataclass, so the original config dataclasses fail to import
+(`non-default argument follows default argument`). The two implementations therefore
+**cannot be imported in the same Python process**.
+
+So the test uses a **producer / consumer** split across two venvs:
+
+1. **Producer** — `tests/policies/groot/utils/dump_original_n1_7.py`, run in the _original_
+   gr00t venv. For each embodiment it builds dummy inputs generically from the
+   checkpoint metadata (state dims from `statistics.json`; camera/language keys from
+   the processor modality configs), runs the original model, and saves to one `.npz`
+   per tag: the raw observations (`raw::` keys), the exact collated inputs
+   (`in::` keys), the seed, and the raw `action_pred`.
+2. **Consumer** — the pytest above, run in the _LeRobot_ venv. It discovers every
+   `.npz`; the model-parity case replays the byte-identical collated inputs through
+   the LeRobot model with the recorded seed and asserts the outputs match, and the
+   preprocessor-parity case replays the raw observations through LeRobot's full
+   preprocessor pipeline and asserts the collated tensors match.
+
+> Artifacts generated by older versions of the dump script contain no `raw::`
+> fields; the preprocessor-parity case then **skips** with a regeneration hint.
+> Re-run the producer to refresh them.
+
+### Fairness controls
+
+- **Same pre-processed inputs (model parity)** — the original processor's `input_ids`,
+  `pixel_values`, `image_grid_thw`, `attention_mask`, `state`, `embodiment_id` are
+  fed verbatim to the LeRobot model (no re-tokenization / re-normalization), so the
+  model comparison isolates the model. LeRobot's own tokenization / image packing is
+  covered separately by the preprocessor-parity case, which compares its output
+  against those same collated tensors from identical raw observations.
+- **Same precision + attention kernel** — both sides run **fp32 + SDPA**. The
+  original defaults to `use_flash_attention=True` (flash_attention_2 + bf16); the
+  producer forces SDPA + fp32. (With the defaults the gap is ~3e-2 — pure
+  kernel/rounding noise, not an implementation difference.)
+- **Same flow-matching seed** — fixed right before sampling on both sides; the
+  producer records it in each artifact (`--seed`, default 42) and the consumer
+  replays the recorded value.
+
+### How to run
+
+```bash
+# Resolve a local checkpoint (GR00T-N1.7-LIBERO / libero_10)
+CKPT=$(python - <<'PY'
+import os
+from huggingface_hub import snapshot_download
+print(os.path.join(snapshot_download("nvidia/GR00T-N1.7-LIBERO",
+      allow_patterns=["libero_10/*"]), "libero_10"))
+PY
+)
+
+# 1) Produce the original-side artifacts for all embodiments (original gr00t venv, CUDA)
+CUDA_VISIBLE_DEVICES=0 /path/to/Isaac-GR00T/.venv-original/bin/python \
+    tests/policies/groot/utils/dump_original_n1_7.py \
+    --ckpt "$CKPT" --out-dir tests/policies/groot/artifacts --device cuda --seed 42
+
+# 2) Run the parity test (LeRobot venv) — one parametrized case per embodiment
+CUDA_VISIBLE_DEVICES=0 GROOT_PARITY_DEVICE=cuda \
+    uv run pytest tests/policies/groot/test_groot_vs_original.py -v -s
+```
+
+The `.npz` artifacts are local-only (gitignored, ~6–10 MB each) and are regenerated by
+the producer; they are never committed. The tests **skip** (do not fail) on CI or
+when the checkpoint / artifacts are absent.
+
+#### Env knobs (all optional)
+
+| Var                                       | Default                          | Purpose                               |
+| ----------------------------------------- | -------------------------------- | ------------------------------------- |
+| `GROOT_N1_7_PARITY_DIR`                   | `tests/policies/groot/artifacts` | directory of per-tag `.npz` artifacts |
+| `GROOT_N1_7_LIBERO_CKPT`                  | auto (HF cache)                  | override checkpoint dir               |
+| `GROOT_PARITY_DEVICE`                     | `cuda` if available              | `cpu` or `cuda`                       |
+| `GROOT_PARITY_ATOL` / `GROOT_PARITY_RTOL` | `1e-3`                           | comparison tolerance                  |
+
+</details>

docs/source/reachy2.mdx

@@ -161,7 +161,7 @@ lerobot-record \
     --dataset.private=true \
     --dataset.streaming_encoding=true \
     --dataset.encoder_threads=2 \
-    # --dataset.camera_encoder.vcodec=auto \
+    # --dataset.rgb_encoder.vcodec=auto \
     --display_data=true
 ```
 
@@ -203,7 +203,7 @@ lerobot-record \
     --dataset.private=true \
     --dataset.streaming_encoding=true \
     --dataset.encoder_threads=2 \
-    # --dataset.camera_encoder.vcodec=auto \
+    # --dataset.rgb_encoder.vcodec=auto \
     --display_data=true
 ```
 

docs/source/remote_inference.mdx

@@ -1,250 +0,0 @@
-# Remote Inference (lerobot-policy-server)
-
-Remote inference decouples GPU policy inference from robot control. A `lerobot-policy-server` process runs the policy on a GPU machine; the robot runs `lerobot-rollout --inference.type=remote` as a **weightless edge client** — no policy weights, no GPU, no policy processors on the robot. One GPU server can serve several robots at once, and the remote backend works with every rollout strategy (`base`, `sentry`, `highlight`, `dagger`, `episodic`).
-
-Use remote inference when:
-
-- The policy is too large or too slow for the machine attached to the robot (e.g. Pi0/Pi0.5 on a Raspberry Pi or laptop edge).
-- You want one GPU to serve a fleet of robots running the same policy.
-- You want to update or restart the inference side without touching the robots.
-
-<Tip>
-
-Remote inference requires the `async` extra on **both** sides: `pip install 'lerobot[async]'` (installs `eclipse-zenoh` and `msgpack`). The server additionally needs the extras of the policy it serves (e.g. `lerobot[pi]`, `lerobot[smolvla]`).
-
-</Tip>
-
-## Architecture
-
-```
- robot (edge, weightless)                              GPU machine
-┌───────────────────────────┐                  ┌────────────────────────────┐
-│ lerobot-rollout           │                  │ lerobot-policy-server      │
-│  --inference.type=remote  │     zenoh        │  one process = one         │
-│                           │     router       │  (model, revision, GPU)    │
-│  control loop @ fps       │   ┌────────┐     │                            │
-│   └─ pops local action ◄──┼───┤ zenohd ├─────┼─► inference worker thread  │
-│      buffer (chunks)      │   └────────┘     │   (round-robin over        │
-│                           │   observations ► │    client sessions)        │
-│  network worker thread ───┼──► ◄ action      │                            │
-│   (publishes obs, merges  │      chunks      │  stateless per request     │
-│    chunks into buffer)    │                  │                            │
-└───────────────────────────┘                  └────────────────────────────┘
-```
-
-The client keeps a local **action buffer** filled with chunks of future actions, so the control loop never blocks on the network: short network blips are absorbed by the buffer and the robot keeps moving. The client self-clocks — it requests a new chunk whenever the buffer holds less than `--inference.buffer_time_s` seconds of playback.
-
-The server is **stateless per request**: clients ship their RTC prefixes and a delay hint with every observation, so a server crash or restart loses zero control state and reconnects are trivial. In production both robots and servers _dial out_ to a `zenohd` router (NAT-friendly: nothing on the robot network needs an open inbound port).
-
-## Quickstart on a LAN (peer mode, no router)
-
-For a quick test on one network you can skip the router: the server listens directly and the robot connects to it.
-
-On the GPU machine:
-
-```bash
-lerobot-policy-server \
-    --model.repo_or_path=${HF_USER}/my_pi0_policy \
-    --default_task="pick up the cube" \
-    --zenoh.mode=peer \
-    --zenoh.listen_endpoints='["tcp/0.0.0.0:7447"]'
-```
-
-Wait for `Policy server up: ...` (the model is downloaded, loaded, and warmed up first).
-
-On the robot machine (replace `192.168.1.42` with the GPU machine's IP):
-
-```bash
-lerobot-rollout \
-    --strategy.type=base \
-    --policy.path=${HF_USER}/my_pi0_policy \
-    --inference.type=remote \
-    --inference.zenoh_mode=peer \
-    --inference.connect_endpoint=tcp/192.168.1.42:7447 \
-    --robot.type=so100_follower \
-    --robot.port=/dev/ttyACM0 \
-    --robot.cameras="{ front: {type: opencv, index_or_path: 0, width: 640, height: 480, fps: 30}}" \
-    --task="pick up the cube" \
-    --duration=60
-```
-
-`--policy.path` on the client resolves to a config-only download (no weights): it is used for pre-flight validation and action ordering, and doubles as the default service address. The client's `--policy.path` and `--task` must match the server's `--model.repo_or_path` and `--default_task` — that pair is the namespace the service is published under (see [Troubleshooting](#troubleshooting)).
-
-## Production deployment (router)
-
-In production, run a [zenoh router](https://zenoh.io/docs/getting-started/installation/) (`zenohd`) somewhere both sides can reach, and have robots and servers dial out to it:
-
-```bash
-zenohd  # listens on tcp/0.0.0.0:7447 by default
-```
-
-Configure the server with a YAML manifest:
-
-```yaml
-# server.yaml
-model:
-  repo_or_path: lerobot/pi0_towels
-  revision: main
-  dtype: bfloat16 # optional cast after load
-  device: cuda
-default_task: "fold the towel"
-serving_mode: auto # shared for verified chunk-stateless policies, exclusive otherwise
-max_sessions: 5
-warmup_inferences: 2
-trained_fps: 30.0
-rtc:
-  enabled: true
-  execution_horizon: 10
-  max_guidance_weight: 10.0
-health_port: 9100 # /healthz + /metrics; 0 disables
-zenoh:
-  mode: client
-  connect_endpoints: ["tcp/router.gpu-cluster.internal:7447"]
-```
-
-```bash
-lerobot-policy-server --manifest server.yaml
-```
-
-Everything in the manifest can also be set directly on the CLI (`--model.repo_or_path=...`, `--max_sessions=...`, etc.). One process serves exactly one `(model, revision, dtype, device)` — to serve two models, or one model on two GPUs, run two processes. Dynamic model loading is deliberately unsupported: pre-warmed processes keep capacity planning honest.
-
-On the robot, only the endpoint changes (the default `--inference.zenoh_mode=client` is already router mode):
-
-```bash
-lerobot-rollout \
-    --strategy.type=base \
-    --policy.path=lerobot/pi0_towels \
-    --inference.type=remote \
-    --inference.connect_endpoint=tcp/router.gpu-cluster.internal:7447 \
-    --robot.type=so100_follower \
-    --robot.port=/dev/ttyACM0 \
-    --robot.cameras="{ front: {type: opencv, index_or_path: 0, width: 640, height: 480, fps: 30}}" \
-    --task="fold the towel" \
-    --duration=600
-```
-
-### TLS / mTLS
-
-For traffic that leaves a trusted network, terminate TLS at the router and give both sides client certificates (all three PEM paths are required together):
-
-```yaml
-# server.yaml (zenoh section)
-zenoh:
-  mode: client
-  connect_endpoints: ["tls/router.gpu-cluster.internal:7447"]
-  tls_root_ca_certificate: /etc/lerobot/ca.pem
-  tls_connect_certificate: /etc/lerobot/server.pem
-  tls_connect_private_key: /etc/lerobot/server.key
-```
-
-On the robot the equivalent flags are `--inference.tls_ca`, `--inference.tls_cert`, and `--inference.tls_key`, with `--inference.connect_endpoint=tls/...`.
-
-<Tip>
-
-Multicast scouting is always disabled: discovery is configuration, not protocol magic. If nothing connects, check the endpoints — there is no fallback discovery mechanism.
-
-</Tip>
-
-## RTC over the network
-
-The remote engine reuses the [Real-Time Chunking](./rtc) machinery: the client keeps the chunk leftover and latency tracking locally and ships an action prefix plus a delay hint with every observation; the server runs prefix-conditioned chunk generation. This gives the same smooth chunk-to-chunk transitions as local RTC, with network latency folded into the delay computation.
-
-RTC is enabled by default on both sides (`rtc.enabled: true`). Tune it from the client:
-
-```bash
-lerobot-rollout \
-    ... \
-    --inference.type=remote \
-    --inference.rtc.execution_horizon=10 \
-    --inference.rtc.max_guidance_weight=10.0
-```
-
-If the server or its policy does not support RTC (only `pi0`, `pi05`, and `smolvla` are RTC-capable, and the server manifest must have `rtc.enabled: true`), the session is **downgraded to plain chunk-append** and the client logs:
-
-```
-RTC downgraded to chunk-append (server does not support RTC)
-```
-
-The robot still runs — chunks are simply appended to the buffer without prefix blending, which can produce visible seams between chunks on slow policies.
-
-## Fail-safe behavior
-
-The client runs a fail-safe state machine (`CONNECTING → STREAMING → DEGRADED → STALLED → RECONNECTING → DEAD`). A bad initial deployment fails fast: `lerobot-rollout` aborts before the robot moves if the handshake or validation fails. Once streaming, faults degrade in stages:
-
-| Condition                                          | Behavior                                                                                                                                |
-| -------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------- |
-| Short network blip / late chunk                    | The robot rides its action buffer; state goes `DEGRADED` after `--inference.degraded_after_s` (default 1.0 s) without a fresh chunk     |
-| Buffered actions older than `max_action_age_s`     | Stale actions are dropped (never executed); default `--inference.max_action_age_s=3.0`                                                  |
-| Buffer runs dry (`STALLED`)                        | Fallback per `--inference.fallback`: `hold` (default — robot holds its last commanded position), `repeat_last`, or `zero`               |
-| Server liveliness lost / repeated request timeouts | `RECONNECTING`: re-handshake with exponential backoff (`reconnect_initial_backoff_s=0.5` doubling up to `reconnect_max_backoff_s=10.0`) |
-| Reconnected server runs a different model/revision | Hard refusal (`DEAD`) — the client never executes wrong-model chunks                                                                    |
-| Offline longer than `max_offline_s` (default 60 s) | `DEAD`: the engine signals the rollout's shutdown event for a clean stop                                                                |
-
-<Tip warning={true}>
-
-`--inference.fallback=zero` is required for velocity-controlled robots: for them "send nothing" means "keep the last velocity", so an explicit zero command is the only safe stop. For position-controlled arms the default `hold` is safe.
-
-</Tip>
-
-Server restarts are equally graceful: on SIGTERM the server drops its liveliness token first (clients ride their buffers through the drain), finishes the in-flight inference, and exits. Clients reconnect when the replacement comes up.
-
-## Serving multiple robots
-
-`max_sessions` caps concurrent clients per server process. A single inference worker thread serializes GPU access and round-robins over sessions with a pending observation; per-client newest-wins mailboxes mean overload degrades into longer cycle times (larger but correct client-side delays), never into queue buildup.
-
-A rough capacity estimate, keeping ~20% headroom:
-
-```
-N_robots ≈ 0.8 / (rate × inference_time)
-```
-
-where `rate` is each robot's chunk-request rate in Hz (how often the client's buffer dips below `buffer_time_s`) and `inference_time` is the server's seconds per chunk. For example, at 100 ms per chunk and ~2 chunk requests per second per robot: `N ≈ 0.8 / (2 × 0.1) = 4` robots.
-
-The actual serving mode is classified per policy family, never inferred:
-
-- **shared** — verified chunk-stateless policies (`act`, `pi0`, `pi05`, and `smolvla` with `n_obs_steps=1`) serve up to `max_sessions` clients from one policy instance.
-- **exclusive** — stateful families (diffusion-family policies, `smolvla` with observation history, and any unverified policy) are forced to `max_sessions=1`. Run one server process per robot for these.
-
-`serving_mode: auto` (the default) resolves this automatically; you may force `exclusive`, but `shared` can never override a stateful classification.
-
-## Observability
-
-With `health_port` set (default 9100), the server exposes:
-
-- `GET /healthz` — `200 ok` while the inference worker is alive, `503` otherwise. Wire this to your orchestrator's liveness probe.
-- `GET /metrics` — Prometheus text format: `lerobot_policy_server_requests_total`, `errors_total`, `superseded_total`, `dropped_unknown_client_total`, `sessions_opened_total`, `sessions_closed_total`, `active_sessions`, `server_load`.
-
-Every inference request also emits one structured audit line on the `lerobot.policy_server.audit` logger:
-
-```json
-{
-  "session_id": "9f2c...",
-  "client_uuid": "robot-07",
-  "seq_id": 412,
-  "episode_id": 3,
-  "queue_wait_ms": 1.8,
-  "inference_ms": 93.2,
-  "superseded": 0,
-  "outcome": "ok"
-}
-```
-
-`(session_id, seq_id)` correlates a server-side audit line with the client's request. Set a stable `--inference.client_uuid` per robot (instead of the default fresh UUID per run) for fleet-wide log correlation, and use `--inference.tags` to forward free-form labels in the handshake.
-
-## Troubleshooting
-
-**`No policy server answered status query at '@lerobot/...'`**
-
-The client found no server under the key it dialed. Either the endpoint is wrong (check `--inference.connect_endpoint`, the router, and firewalls), or the **service namespace** does not match. The namespace is the `(model_id, revision, task)` triple: on the client it comes from `--inference.service_model_id` (default: `--policy.path`), `--inference.service_revision` (default: `main`), and `--inference.service_task` (default: the rollout `--task`); on the server from `model.repo_or_path`, `model.revision`, and `service_name` (default: a slug of `default_task`). A robot task string that differs from the server's `default_task` is the most common cause — fix the task, or pin the namespace explicitly with `--inference.service_task` on the client / `service_name` in the manifest.
-
-**`Action name/order mismatch between server policy and this robot`**
-
-The hard sync-safety contract: chunk columns map to motors **by order**, so the robot's ordered action keys must exactly equal the policy's `action_feature_names`. This fires when the robot type, motor naming, or rename map differs from the training setup. Use the same robot type (and rename map) the policy was trained with.
-
-**`RTC requested but this server/policy does not support it — downgrading to chunk-append`**
-
-Informational, not fatal. Enable RTC in the server manifest (`rtc.enabled: true`) and make sure the policy family is RTC-capable (`pi0`, `pi05`, `smolvla`). Otherwise, expect chunk-append behavior (see [RTC over the network](#rtc-over-the-network)).
-
-**`server full: N/N sessions active`**
-
-The session-open was rejected at capacity. Raise `max_sessions` (shared mode only), or point the robot at another server replica — the rejection includes the current load so orchestration can retry elsewhere.

docs/source/robocasa.mdx

@@ -166,7 +166,7 @@ lerobot-train \
   --output_dir=./outputs/smolvla_robocasa_CloseFridge \
   --steps=100000 \
   --batch_size=4 \
-  --eval_freq=5000 \
+  --env_eval_freq=5000 \
   --eval.batch_size=1 \
   --eval.n_episodes=5 \
   --save_freq=10000

docs/source/rtc.mdx

@@ -151,18 +151,18 @@ lerobot-rollout \
     --device=cuda
 ```
 
-## How It Relates to Remote Inference
+## How It Differs from the Async Inference in LeRobot
 
-Both RTC and [remote inference](./remote_inference) improve real-time robot control, but they solve different problems.
+Both RTC and [async inference](./async) improve real-time robot control, but they solve different problems.
 
-| Aspect        | Remote Inference                                                         | RTC                                                 |
-| ------------- | ------------------------------------------------------------------------ | --------------------------------------------------- |
-| **Problem**   | The policy is too large (or too slow) for the edge machine               | Discontinuities between action chunks               |
-| **Solution**  | Run inference on a GPU server; the robot executes buffered action chunks | Guide new chunks to continue smoothly from previous |
-| **Benefit**   | Weightless edge clients, one GPU serves many robots                      | Smooth transitions, natural motion                  |
-| **Best Used** | Large models with high inference latency, robot fleets                   | Flow-matching based policies                        |
+| Aspect        | Async Inference                                                            | RTC                                                 |
+| ------------- | -------------------------------------------------------------------------- | --------------------------------------------------- |
+| **Problem**   | Idle frames while waiting for inference                                    | Discontinuities between action chunks               |
+| **Solution**  | Decouple prediction from execution                                         | Guide new chunks to continue smoothly from previous |
+| **Benefit**   | No waiting, continuous action                                              | Smooth transitions, natural motion                  |
+| **Best Used** | Async inference is best used with large models with high inference latency | Flow-matching based policies                        |
 
-**Use both together** (`--inference.type=remote` with `--inference.rtc.execution_horizon=...`) for maximum smoothness and reactivity: the remote engine reuses RTC's chunk-merging machinery client-side while the server runs prefix-conditioned chunk generation.
+**Use both together** for maximum smoothness and reactivity!
 
 ## Advanced: Debug Tracking
 

docs/source/so101.mdx

@@ -122,7 +122,7 @@ The video below shows the sequence of steps for setting the motor ids.
 
 #### Follower
 
-Connect the usb cable from your computer and the power supply to the follower arm's controller board. Then, run the following command or run the API example with the port you got from the previous step. You'll also need to give your leader arm a name with the `id` parameter.
+Connect the usb cable from your computer and the power supply to the follower arm's controller board. Then, run the following command or run the API example with the port you got from the previous step. You'll also need to give your follower arm a name with the `id` parameter.
 
 <hfoptions id="setup_motors">
 <hfoption id="Command">

docs/source/streaming_video_encoding.mdx

@@ -17,7 +17,7 @@ This makes `save_episode()` near-instant (the video is already encoded by the ti
 | Parameter               | CLI Flag                          | Type          | Default       | Description                                                       |
 | ----------------------- | --------------------------------- | ------------- | ------------- | ----------------------------------------------------------------- |
 | `streaming_encoding`    | `--dataset.streaming_encoding`    | `bool`        | `True`        | Enable real-time encoding during capture                          |
-| `vcodec`                | `--dataset.camera_encoder.vcodec` | `str`         | `"libsvtav1"` | Video codec. `"auto"` detects best HW encoder                     |
+| `vcodec`                | `--dataset.rgb_encoder.vcodec`    | `str`         | `"libsvtav1"` | Video codec. `"auto"` detects best HW encoder                     |
 | `encoder_threads`       | `--dataset.encoder_threads`       | `int \| None` | `None` (auto) | Threads per encoder instance. `None` will leave the vcoded decide |
 | `encoder_queue_maxsize` | `--dataset.encoder_queue_maxsize` | `int`         | `30`          | Max buffered frames per camera (~1s at 30fps). Consumes RAM       |
 
@@ -82,15 +82,15 @@ Use HW encoding when:
 
 ### Available HW Encoders
 
-| Encoder             | Platform      | Hardware                                                                                         | CLI Value                                           |
-| ------------------- | ------------- | ------------------------------------------------------------------------------------------------ | --------------------------------------------------- |
-| `h264_videotoolbox` | macOS         | Apple Silicon / Intel                                                                            | `--dataset.camera_encoder.vcodec=h264_videotoolbox` |
-| `hevc_videotoolbox` | macOS         | Apple Silicon / Intel                                                                            | `--dataset.camera_encoder.vcodec=hevc_videotoolbox` |
-| `h264_nvenc`        | Linux/Windows | NVIDIA GPU                                                                                       | `--dataset.camera_encoder.vcodec=h264_nvenc`        |
-| `hevc_nvenc`        | Linux/Windows | NVIDIA GPU                                                                                       | `--dataset.camera_encoder.vcodec=hevc_nvenc`        |
-| `h264_vaapi`        | Linux         | Intel/AMD GPU                                                                                    | `--dataset.camera_encoder.vcodec=h264_vaapi`        |
-| `h264_qsv`          | Linux/Windows | Intel Quick Sync                                                                                 | `--dataset.camera_encoder.vcodec=h264_qsv`          |
-| `auto`              | Any           | Probes the system for available HW encoders. Falls back to `libsvtav1` if no HW encoder is found | `--dataset.camera_encoder.vcodec=auto`              |
+| Encoder             | Platform      | Hardware                                                                                         | CLI Value                                        |
+| ------------------- | ------------- | ------------------------------------------------------------------------------------------------ | ------------------------------------------------ |
+| `h264_videotoolbox` | macOS         | Apple Silicon / Intel                                                                            | `--dataset.rgb_encoder.vcodec=h264_videotoolbox` |
+| `hevc_videotoolbox` | macOS         | Apple Silicon / Intel                                                                            | `--dataset.rgb_encoder.vcodec=hevc_videotoolbox` |
+| `h264_nvenc`        | Linux/Windows | NVIDIA GPU                                                                                       | `--dataset.rgb_encoder.vcodec=h264_nvenc`        |
+| `hevc_nvenc`        | Linux/Windows | NVIDIA GPU                                                                                       | `--dataset.rgb_encoder.vcodec=hevc_nvenc`        |
+| `h264_vaapi`        | Linux         | Intel/AMD GPU                                                                                    | `--dataset.rgb_encoder.vcodec=h264_vaapi`        |
+| `h264_qsv`          | Linux/Windows | Intel Quick Sync                                                                                 | `--dataset.rgb_encoder.vcodec=h264_qsv`          |
+| `auto`              | Any           | Probes the system for available HW encoders. Falls back to `libsvtav1` if no HW encoder is found | `--dataset.rgb_encoder.vcodec=auto`              |
 
 > [!NOTE]
 > In order to use the HW accelerated encoders you might need to upgrade your GPU drivers.
@@ -100,15 +100,15 @@ Use HW encoding when:
 
 ## 5. Troubleshooting
 
-| Symptom                                                            | Likely Cause                                 | Fix                                                                                                                                                                                                                                                                                                 |
-| ------------------------------------------------------------------ | -------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| System freezes or choppy robot movement or Rerun visualization lag | CPU starved (100% load usage)                | Close other apps, reduce encoding throughput, lower `encoder_threads`, use `h264`, use `display_data=False`. If the CPU continues to be at 100% then it might be insufficient for your setup, consider `--dataset.streaming_encoding=false` or HW encoding (`--dataset.camera_encoder.vcodec=auto`) |
-| "Encoder queue full" warnings or dropped frames in dataset         | Encoder can't keep up (Queue overflow)       | If CPU is not at 100%: Increase `encoder_threads`, increase `encoder_queue_maxsize` or use HW encoding (`--dataset.camera_encoder.vcodec=auto`).                                                                                                                                                    |
-| High RAM usage                                                     | Queue filling faster than encoding           | `encoder_threads` too low or CPU insufficient. Reduce `encoder_queue_maxsize` or use HW encoding                                                                                                                                                                                                    |
-| Large video files                                                  | Using HW encoder or H.264                    | Expected trade-off. Switch to `libsvtav1` if CPU allows                                                                                                                                                                                                                                             |
-| `save_episode()` still slow                                        | `streaming_encoding` is `False`              | Set `--dataset.streaming_encoding=true`                                                                                                                                                                                                                                                             |
-| Encoder thread crash                                               | Codec not available or invalid settings      | Check `vcodec` is installed, try `--dataset.camera_encoder.vcodec=auto`                                                                                                                                                                                                                             |
-| Recorded dataset is missing frames                                 | CPU/GPU starvation or occasional load spikes | If ~5% of frames are missing, your system is likely overloaded — follow the recommendations above. If fewer frames are missing (~2%), they are probably due to occasional transient load spikes (often at startup) and can be considered expected.                                                  |
+| Symptom                                                            | Likely Cause                                 | Fix                                                                                                                                                                                                                                                                                              |
+| ------------------------------------------------------------------ | -------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| System freezes or choppy robot movement or Rerun visualization lag | CPU starved (100% load usage)                | Close other apps, reduce encoding throughput, lower `encoder_threads`, use `h264`, use `display_data=False`. If the CPU continues to be at 100% then it might be insufficient for your setup, consider `--dataset.streaming_encoding=false` or HW encoding (`--dataset.rgb_encoder.vcodec=auto`) |
+| "Encoder queue full" warnings or dropped frames in dataset         | Encoder can't keep up (Queue overflow)       | If CPU is not at 100%: Increase `encoder_threads`, increase `encoder_queue_maxsize` or use HW encoding (`--dataset.rgb_encoder.vcodec=auto`).                                                                                                                                                    |
+| High RAM usage                                                     | Queue filling faster than encoding           | `encoder_threads` too low or CPU insufficient. Reduce `encoder_queue_maxsize` or use HW encoding                                                                                                                                                                                                 |
+| Large video files                                                  | Using HW encoder or H.264                    | Expected trade-off. Switch to `libsvtav1` if CPU allows                                                                                                                                                                                                                                          |
+| `save_episode()` still slow                                        | `streaming_encoding` is `False`              | Set `--dataset.streaming_encoding=true`                                                                                                                                                                                                                                                          |
+| Encoder thread crash                                               | Codec not available or invalid settings      | Check `vcodec` is installed, try `--dataset.rgb_encoder.vcodec=auto`                                                                                                                                                                                                                             |
+| Recorded dataset is missing frames                                 | CPU/GPU starvation or occasional load spikes | If ~5% of frames are missing, your system is likely overloaded — follow the recommendations above. If fewer frames are missing (~2%), they are probably due to occasional transient load spikes (often at startup) and can be considered expected.                                               |
 
 ## 6. Recommended Configurations
 
@@ -146,7 +146,7 @@ On very constrained systems, streaming encoding may compete too heavily with the
 # 2camsx 640x480x3 @30fps: Requires some tuning.
 
 # Use H.264, disable streaming, consider batching encoding
-lerobot-record --dataset.camera_encoder.vcodec=h264 --dataset.streaming_encoding=false ...
+lerobot-record --dataset.rgb_encoder.vcodec=h264 --dataset.streaming_encoding=false ...
 ```
 
 ## 7. Closing note

docs/source/third_party_robots.mdx

@@ -0,0 +1,171 @@
+# Third-Party Robots & Teleoperators
+
+The LeRobot ecosystem extends far beyond its officially supported hardware. Thanks to LeRobot's plugin architecture, the community has built integrations for a wide range of robot arms and teleoperation devices — from industrial manipulators to affordable hobbyist platforms, VR headsets, haptic devices, and full arm-plus-leader kits. This page showcases community-maintained integrations you can use for teleoperation, data collection, and policy deployment.
+
+<Tip>
+These projects are developed and maintained by third parties. Please refer to each repository for installation instructions, hardware requirements, and support.
+</Tip>
+
+## Industrial & Collaborative Arms
+
+**[lerobot-robot-xarm](https://github.com/SpesRobotics/lerobot-robot-xarm)** — by SpesRobotics
+
+xArm integration for LeRobot, bringing UFACTORY's popular collaborative arm series into the LeRobot workflow.
+
+**[lerobot_trossen](https://github.com/TrossenRobotics/lerobot_trossen)** — by Trossen Robotics
+
+Official hardware integrations from Trossen Robotics, makers of the WidowX and ALOHA-style arms widely used in robot learning research.
+
+**[lerobot_lebai](https://github.com/lebai-robotics/lerobot_lebai)** — by Lebai Robotics
+
+Integration for Lebai collaborative robot arms, bringing them into the LeRobot teleoperation and recording workflow.
+
+**[LeFranX](https://github.com/wengmister/LeFranX)** — by wengmister
+
+LeRobot extension for the Franka robot paired with the XHand dexterous hand. An instantiation of the LeVR framework, combining a research-grade arm with VR-based teleoperation.
+
+**[UR5e-LeRobot](https://github.com/yechen056/UR5e-LeRobot)** — by yechen056
+
+LeRobot extension for the Universal Robots UR5e, with both single-arm and bimanual support.
+
+**[lerobot_ur5e_auto](https://github.com/scy-v/lerobot_ur5e_auto)** — by scy-v
+
+Automated data collection for a mobile UR5e platform, built on LeRobot — great for scaling up dataset creation with minimal human supervision.
+
+**[lerobot_ur5e_gello](https://github.com/F-Fer/lerobot_ur5e_gello)** — by F-Fer
+
+Custom LeRobot plugins for a UR5e follower and GELLO leader arm, with ready-to-use scripts for data collection and VLA policy inference.
+
+## Research & Learning Platforms
+
+**[lerobot-arx5](https://github.com/villekuosmanen/lerobot-arx5)** — by villekuosmanen
+
+An ARX5 robot arm plugin for LeRobot, integrating this compact, learning-friendly manipulator into the ecosystem.
+
+**[lerobot_robot_piper (AgRobotics Research)](https://github.com/AgRoboticsResearch/lerobot_robot_piper)** — by AgRoboticsResearch
+
+Integration of the AgileX Piper arm with LeRobot, developed in the context of agricultural robotics research.
+
+**[lerobot_robot_piper (WeGo Robotics)](https://github.com/WeGo-Robotics/lerobot_robot_piper)** — by WeGo-Robotics
+
+Multi-arm teleoperation plugin for the AgileX Piper robot, integrating with LeRobot for data collection and policy deployment.
+
+## Affordable & Hobbyist Arms
+
+**[fashionstar-lerobot-robot-cello](https://github.com/servodevelop/fashionstar-lerobot-robot-cello)** — by servodevelop
+
+LeRobot integration for the FashionStar Cello robot arm.
+
+**[fashionstar-lerobot-robot-viola](https://github.com/servodevelop/fashionstar-lerobot-robot-viola)** — by servodevelop
+
+LeRobot integration for the FashionStar Viola robot arm — a sibling to the Cello integration above.
+
+**[lerobot-robot-seeed-b601](https://github.com/Seeed-Projects/lerobot-robot-seeed-b601)** — by Seeed Studio
+
+Integration for Seeed Studio's reBot Arm B601, enabling the low-cost B601 to be used as a follower arm within LeRobot.
+
+## Multi-Device & Specialized Integrations
+
+**[lerobot-robot-ugo-pro](https://github.com/ugo-plus/lerobot-robot-ugo-pro)** — by ugo (ugo-plus)
+
+ugo Pro integration for LeRobot, bringing this service robot platform into the LeRobot ecosystem.
+
+**[lerobot_robot_lekiwi_pincopen](https://github.com/zuoxingdong/lerobot_robot_lekiwi_pincopen)** — by zuoxingdong
+
+A drop-in plugin that lets unmodified LeRobot drive a LeKiwi mobile manipulator built with STS3250 servos on the main arm joints and a PincOpen gripper, with tunable servo parameters exposed as config fields — no source edits required.
+
+**[lerobot_robot_ros2_zenoh](https://github.com/ROBOTIS-GIT/lerobot_robot_ros2_zenoh)** — by ROBOTIS
+
+A ROS 2 (Zenoh-based) robot integration for LeRobot, letting you drive ROS 2 robots through the LeRobot interface.
+
+**[lerobot-robot-dummy](https://github.com/KillingJacky/lerobot-robot-dummy)** — by KillingJacky
+
+A virtual follower arm for debugging: it drives no hardware and instead prints the actions it receives (with an optional silent mode), handy for testing leaders and pipelines. Defaults to Seeed B601 joint names, with configurable motor names for other leaders.
+
+## Teleoperators
+
+**[lerobot-teleoperator-teleop](https://github.com/SpesRobotics/lerobot-teleoperator-teleop)** — by SpesRobotics
+
+Phone and VR teleoperation integration for LeRobot, one of the community plugins referenced in the official Bring Your Own Hardware guide.
+
+**[lerobot-teleoperator-spacemouse](https://github.com/Jas000n/lerobot-teleoperator-spacemouse)** — by Jas000n
+
+Turns a 3Dconnexion SpaceMouse into a 6-DoF teleoperator, with built-in inverse kinematics for SO-101/SO-ARM followers, a direct end-effector mode, axis remapping, and custom-URDF profiles.
+
+**[vr-teleop-kit](https://github.com/Dream-Machines-Robotics/vr-teleop-kit)** — by Dream-Machines-Robotics
+
+An open-source VR teleoperation kit that drives robot arms from a Meta Quest (WebXR) headset via differential inverse kinematics, exposed as a drop-in LeRobot `Teleoperator` (single-arm and bimanual).
+
+**[lerobot-teleoperator-pico4](https://github.com/xensedyl/lerobot-teleoperator-pico4)** — by xensedyl
+
+Teleoperation plugin driving LeRobot from a PICO 4 VR headset, with a companion [hand-tracking variant](https://github.com/xensedyl/lerobot-teleoperator-pico4-hand).
+
+**[lerobot_teleoperator_yamactiveleader](https://github.com/uynitsuj/lerobot_teleoperator_yamactiveleader)** — by uynitsuj
+
+Active YAM teleop leader device integration for LeRobot.
+
+**[lerobot_teleoperator_omy](https://github.com/charlie8612/lerobot_teleoperator_omy)** — by charlie8612
+
+LeRobot teleoperator plugin for the ROBOTIS OMY-L100 6-DoF leader arm (no ROS 2 required).
+
+**[lerobot-teleoperator-deltas-gamepad](https://github.com/jpizarrom/lerobot-teleoperator-deltas-gamepad)** — by jpizarrom
+
+Teleoperate LeRobot with a standard gamepad, sending incremental (delta) end-effector commands.
+
+**[lerobot_teleoperator_inverse3](https://github.com/chohh7391/lerobot_teleoperator_inverse3)** — by chohh7391
+
+Teleoperator plugin for the Haply Inverse3 haptic device.
+
+**[lerobot_teleoperator_omega7](https://github.com/hzhz112/lerobot_teleoperator_omega7)** — by hzhz112
+
+Teleoperator plugin for the Force Dimension omega.7 haptic device.
+
+**[lerobot-teleoperator-arx5](https://pypi.org/project/lerobot-teleoperator-arx5/)** — by villekuosmanen
+
+ARX5 leader/teleoperator plugin — the leader counterpart to the ARX5 robot plugin listed above, from the same author.
+
+**[lerobot-teleoperator-seeed-b601](https://github.com/Seeed-Projects/lerobot-teleoperator-seeed-b601)** — by Seeed Studio
+
+Leader-arm teleoperator for the Seeed reBot Arm B601 (Damiao CAN motors), pairing with the B601 follower listed above.
+
+**[lerobot-teleoperator-rebot-arm-102](https://pypi.org/project/lerobot-teleoperator-rebot-arm-102/)** — by Seeed Studio
+
+reBot Arm 102 leader arm (FashionStar UART servos) designed to teleoperate the Seeed reBot B601 follower.
+
+**[lerobot-teleoperator-pipermate](https://pypi.org/project/lerobot-teleoperator-pipermate/)** — by Welt-liu
+
+PiperMate leader teleoperator (FashionStar UART servos) for the AgileX Piper arm.
+
+**[lerobot-teleoperator-livekit](https://pypi.org/project/lerobot-teleoperator-livekit/)** — by binhpham_lk
+
+Robot-side teleoperator that receives commands over a LiveKit Portal (WebRTC), enabling remote teleoperation across the network.
+
+## Robots + Teleoperators
+
+**[Nextis-AIRA-3D](https://github.com/robertorobotics/Nextis-AIRA-3D)** — by robertorobotics
+
+An open-source, 3D-printable 7-DoF arm that ships as a LeRobot plugin (not a fork), registering both a robot (`aira_follower`) and its Dynamixel leader teleoperator (`aira_leader`) for teleoperation, recording, and training.
+
+**[lerobot_yam](https://github.com/pravsels/lerobot_yam)** — by pravsels
+
+A plugin suite for the YAM arm shipping both a follower robot (`yam_follower`, CAN-driven) and a GELLO leader teleoperator (`yam_leader`), plus shared utilities — installable together or component-by-component (e.g. follower-only for policy inference).
+
+**[leros2](https://github.com/ngres/leros2)** — by ngres
+
+Maps ROS 2 topics and actions to LeRobot robots and teleoperators, bridging existing ROS 2 hardware into the LeRobot interface on both the robot and teleoperator sides.
+
+**[lerobot_robot_bi_so101_follower](https://github.com/SIGRobotics-UIUC/lerobot_robot_bi_so101_follower)** — by SIGRobotics-UIUC
+
+A bimanual (dual-arm) SO-101 setup: a follower robot package paired with its [bi-so101 leader teleoperator](https://pypi.org/project/lerobot-teleoperator-bi-so101-leader/) for dual-arm manipulation.
+
+**[trlc-dk1](https://github.com/robot-learning-co/trlc-dk1)** — by The Robot Learning Company
+
+An open-source dev kit for AI-native robotics. The repo ships a `lerobot_robot_trlc_dk1` plugin (auto-detected via LeRobot's plugin conventions despite the repo name) registering single-arm `dk1_follower`/`dk1_leader` and bimanual `bi_dk1_follower`/`bi_dk1_leader` types.
+
+**[hex_lerobot_drivers](https://github.com/hexfellow/hex_lerobot_drivers)** — by hexfellow
+
+A full suite of drop-in plugins for HEXFELLOW devices, published individually on PyPI: Hex Arm robots (`hex_arm`, `hex_arm_double`, and a `hex_arm_sim` MuJoCo variant), matching leader teleoperators (`hello`, `hex_arm`, and their double-arm versions), and cameras (see the [Cameras & Sensors](./third_party_sensors) page).
+
+## Contributing
+
+Built your own LeRobot hardware integration? The plugin system makes it straightforward to add new robots and teleoperators — check out the [Bring Your Own Hardware](./integrate_hardware) guide to get started, and share your project with the community!

docs/source/third_party_sensors.mdx

@@ -0,0 +1,25 @@
+# Third-Party Cameras & Sensors
+
+Beyond the cameras natively supported by LeRobot (OpenCV, Intel RealSense, ZMQ, Reachy 2), the community has published drop-in camera plugins using the `lerobot_camera_` package convention. Because LeRobot auto-discovers any installed package prefixed with `lerobot_camera_` and registers its `CameraConfig` subclass, these work with unmodified LeRobot — just `pip install` and reference the new camera `type` from the CLI. This page collects community-maintained camera and sensor integrations.
+
+<Tip>
+These projects are developed and maintained by third parties. Please refer to each repository for installation instructions, hardware requirements, and support.
+</Tip>
+
+## Cameras & Vision Sensors
+
+**[lerobot-camera-xense](https://github.com/xensedyl/lerobot-camera-xense)** — by xensedyl
+
+A drop-in camera plugin (registers the `xense` camera type) for Xense vision-based tactile sensors via `xensesdk>=2.0.0`. Exposes rectified/difference images for the standard image observation path, plus richer outputs — depth, 2D markers, force fields, force resultants, and 3D mesh — with a per-sensor process backend for multi-sensor setups.
+
+**[hex_lerobot_drivers cameras](https://github.com/hexfellow/hex_lerobot_drivers)** — by hexfellow
+
+Part of HEXFELLOW's LeRobot plugin suite, providing two camera plugins published on PyPI: [`lerobot_camera_berxel`](https://pypi.org/project/lerobot-camera-berxel/) for Berxel (depth) cameras, and [`lerobot_camera_dummy`](https://pypi.org/project/lerobot-camera-dummy/), a simulated MuJoCo camera for the Hex Arm useful for teleoperation and recording without physical camera hardware. (The same repo also ships Hex Arm robots and leader teleoperators — see the [Robots & Teleoperators](./third_party_robots) page.)
+
+**[lerobot_camera_imageclient](https://github.com/CoNG-harvard/lerobot_camera_imageclient)** — by CoNG-harvard
+
+A LeRobot camera plugin that sources frames from an external image client, following the `lerobot_camera_` auto-discovery convention.
+
+## Contributing
+
+Built your own LeRobot camera or sensor integration? Package it as an installable `lerobot_camera_<name>` plugin and it will be auto-discovered by the LeRobot CLI — see the [Bring Your Own Hardware](./integrate_hardware) guide and the [Cameras](./cameras) reference to get started, then share your project with the community!

docs/source/using_dataset_tools.mdx

@@ -11,8 +11,9 @@ LeRobot provides several utilities for manipulating datasets:
 3. **Merge Datasets** - Combine multiple datasets into one. The datasets must have identical features, and episodes are concatenated in the order specified in `repo_ids`
 4. **Add Features** - Add new features to a dataset
 5. **Remove Features** - Remove features from a dataset
-6. **Convert to Video** - Convert image-based datasets to video format for efficient storage
-7. **Show the Info of Datasets** - Show the summary of datasets information such as number of episode etc.
+6. **Convert to Video** - Convert image-based datasets to video format for efficient storage (RGB and depth cameras are encoded with separate encoders)
+7. **Re-encode Videos** - Re-encode an existing video dataset's RGB and/or depth streams with new encoder settings
+8. **Show the Info of Datasets** - Show the summary of datasets information such as number of episode etc.
 
 The core implementation is in `lerobot.datasets.dataset_tools`.
 An example script detailing how to use the tools API is available in `examples/dataset/use_dataset_tools.py`.
@@ -117,10 +118,19 @@ lerobot-edit-dataset \
     --repo_id lerobot/pusht_image \
     --operation.type convert_image_to_video \
     --operation.output_dir outputs/pusht_video \
-    --operation.camera_encoder.vcodec libsvtav1 \
-    --operation.camera_encoder.pix_fmt yuv420p \
-    --operation.camera_encoder.g 2 \
-    --operation.camera_encoder.crf 30
+    --operation.rgb_encoder.vcodec libsvtav1 \
+    --operation.rgb_encoder.pix_fmt yuv420p \
+    --operation.rgb_encoder.g 2 \
+    --operation.rgb_encoder.crf 30
+
+# Convert a dataset that includes depth maps, customizing the depth encoder
+lerobot-edit-dataset \
+    --repo_id lerobot/pusht_image \
+    --operation.type convert_image_to_video \
+    --operation.output_dir outputs/pusht_video \
+    --operation.depth_encoder.depth_min 0.01 \
+    --operation.depth_encoder.depth_max 10.0 \
+    --operation.depth_encoder.use_log true
 
 # Convert only specific episodes
 lerobot-edit-dataset \
@@ -147,11 +157,42 @@ lerobot-edit-dataset \
 **Parameters:**
 
 - `output_dir`: Custom output directory (optional - by default uses `new_repo_id` or `{repo_id}_video`)
-- `camera_encoder`: Video encoder settings — all sub-fields accessible via `--operation.camera_encoder.<field>. See [Video Encoding Parameters](./video_encoding_parameters) for more details.
+- `rgb_encoder`: Video encoder settings applied to RGB cameras — all sub-fields accessible via `--operation.rgb_encoder.<field>`. See [Video Encoding Parameters](./video_encoding_parameters) for more details.
+- `depth_encoder`: Video encoder settings applied to depth-map cameras (e.g. from an Intel RealSense). In addition to the standard encoder fields it exposes the depth quantization knobs (`depth_min`, `depth_max`, `shift`, `use_log`), accessible via `--operation.depth_encoder.<field>`. These quantization settings are persisted to the dataset metadata so depth can be dequantized back to physical units on load. See the [Depth streams](./video_encoding_parameters#depth-streams) section for details.
 - `episode_indices`: List of specific episodes to convert (default: all episodes)
 - `num_workers`: Number of parallel workers for processing (default: 4)
 
-**Note:** The resulting dataset will be a proper LeRobotDataset with all cameras encoded as videos in the `videos/` directory, with parquet files containing only metadata (no raw image data). All episodes, stats, and tasks are preserved.
+**Note:** The resulting dataset will be a proper LeRobotDataset with all cameras encoded as videos in the `videos/` directory, with parquet files containing only metadata (no raw image data). Depth-map cameras are detected automatically and routed to the `depth_encoder`, while RGB cameras use the `rgb_encoder`. All episodes, stats, and tasks are preserved.
+
+#### Re-encode Videos
+
+Re-encode the videos of an existing video dataset with different encoder settings, without going back to raw frames. RGB videos use the `rgb_encoder` and depth videos use the `depth_encoder`. Provide only the encoder(s) you want to re-encode; the other stream type is left untouched.
+
+```bash
+# Re-encode all RGB videos with new settings (saves to lerobot/pusht_reencoded by default)
+lerobot-edit-dataset \
+    --repo_id lerobot/pusht \
+    --operation.type reencode_videos \
+    --operation.rgb_encoder.vcodec h264 \
+    --operation.rgb_encoder.pix_fmt yuv420p \
+    --operation.rgb_encoder.crf 23
+
+# Re-encode both RGB and depth videos in a dataset with depth maps
+lerobot-edit-dataset \
+    --repo_id lerobot/pusht_depth \
+    --operation.type reencode_videos \
+    --operation.rgb_encoder.vcodec h264 \
+    --operation.depth_encoder.crf 50
+```
+
+**Parameters:**
+
+- `rgb_encoder`: Encoder settings applied to every RGB video. Omit to skip re-encoding RGB videos.
+- `depth_encoder`: Encoder settings applied to every depth video. Omit to skip re-encoding depth videos.
+- `num_workers`: Number of parallel workers for processing.
+
+> [!NOTE]
+> When re-encoding depth videos, the existing depth quantization parameters (`depth_min`, `depth_max`, `shift`, `use_log`) and the `is_depth_map` flag are **preserved** — re-encoding only changes the codec/quality of the stored stream, not how depth is dequantized on load.
 
 ### Show the information of datasets
 
@@ -224,6 +265,8 @@ lerobot-dataset-viz \
 
 Once executed, the tool opens `rerun.io` and displays the camera streams, robot states, and actions for the selected episode.
 
+To use [Foxglove](https://foxglove.dev) instead of Rerun, install the extra add `--display-mode foxglove`. This starts a WebSocket server (connect the Foxglove app to `ws://127.0.0.1:8765`) that serves the episode as a seekable timeline you can play/pause and scrub.
+
 For advanced usage—including visualizing datasets stored on a remote server—run:
 
 ```bash

docs/source/video_encoding_parameters.mdx

@@ -2,16 +2,15 @@
 
 When video storage is enabled, LeRobot stores each camera stream as an **MP4** file instead of saving one image file per timestep. Video encoding compresses across time, which usually cuts dataset size and I/O compared to a pile of PNG, while keeping MP4 — a format every player and loader understands.
 
-Encoding frames into an MP4 is a full FFmpeg pipeline: choice of encoder, pixel format, GOP/keyframes, quality vs. speed, and optional extra encoder flags. Most of these knobs are user-tunable through `camera_encoder`, a nested `VideoEncoderConfig` (`lerobot.configs.video.VideoEncoderConfig`) passed through PyAV.
+Encoding frames into an MP4 is a full FFmpeg pipeline: choice of encoder, pixel format, GOP/keyframes, quality vs. speed, and optional extra encoder flags. Most of these knobs are user-tunable through `rgb_encoder`, a nested `RGBEncoderConfig` (`lerobot.configs.video.RGBEncoderConfig`) passed through PyAV.
 
-You can set these parameters from the CLI with `--dataset.camera_encoder.<field>` (e.g. with `lerobot-record` or `lerobot-rollout`). The same block applies to every camera video stream in that run.
+You can set these parameters from the CLI with `--dataset.rgb_encoder.<field>` (e.g. with `lerobot-record` or `lerobot-rollout`). The same block applies to every camera video stream in that run.
 
-<Tip>
-  Video storage must be on for `camera_encoder` to have any effect —
-  `use_videos=True` in Python APIs, or `--dataset.video=true` on the CLI (the
-  recording default). With video off, inputs stay as images and `camera_encoder`
-  is ignored.
-</Tip>
+> [!TIP]
+> Video storage must be on for `rgb_encoder` to have any effect —
+> `use_videos=True` in Python APIs, or `--dataset.video=true` on the CLI (the
+> recording default). With video off, inputs stay as images and `rgb_encoder` is
+> ignored.
 
 For details on **when** frames are written vs. encoded (streaming vs. post-episode), queues, and other top-level `--dataset.*` switches, see [Streaming Video Encoding](./streaming_video_encoding). For an encoding-parameter comparison and experiments, see the [video-benchmark Space](https://huggingface.co/spaces/lerobot/video-benchmark).
 
@@ -33,9 +32,9 @@ lerobot-record \
     --dataset.single_task="Grab the cube" \
     --dataset.streaming_encoding=true \
     --dataset.encoder_threads=2 \
-    --dataset.camera_encoder.vcodec=h264 \
-    --dataset.camera_encoder.preset=fast \
-    --dataset.camera_encoder.extra_options={"tune": "film", "profile:v": "high", "bf": 2} \
+    --dataset.rgb_encoder.vcodec=h264 \
+    --dataset.rgb_encoder.preset=fast \
+    --dataset.rgb_encoder.extra_options={"tune": "film", "profile:v": "high", "bf": 2} \
     --display_data=true
 ```
 
@@ -43,14 +42,12 @@ lerobot-record \
 
 ## Tuning parameters
 
-<Tip warning={true}>
-The defaults are tuned to balance **compression ratio**, **visual quality**, and **decoding/seek speed** for typical robotics datasets. Changing them can affect both recording (CPU load, frame drops) and training (decoding throughput, image quality).
+> [!WARNING]
+> The defaults are tuned to balance **compression ratio**, **visual quality**, and **decoding/seek speed** for typical robotics datasets. Changing them can affect both recording (CPU load, frame drops) and training (decoding throughput, image quality).
+>
+> Only override these parameters if you have a specific reason to, and measure the impact on your pipeline before relying on the new settings.
 
-Only override these parameters if you have a specific reason to, and measure the impact on your pipeline before relying on the new settings.
-
-</Tip>
-
-All flags below are prefixed with `--dataset.camera_encoder.` on the CLI.
+All flags below are prefixed with `--dataset.rgb_encoder.` on the CLI.
 
 | Parameter       | Type             | Default       | Description                                                                                                                                                                            |
 | --------------- | ---------------- | ------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
@@ -65,6 +62,144 @@ All flags below are prefixed with `--dataset.camera_encoder.` on the CLI.
 
 ---
 
+## Depth streams
+
+Depth maps (Intel RealSense, Reachy 2) are stored as their **own video streams** alongside the RGB streams. Raw depth (`uint16` millimetres or `float32` metres) can't survive an 8-bit codec, so LeRobot **quantizes** each map to a 12-bit code (`[0, 4095]`) — logarithmically by default, to match the `1/depth` error profile of depth sensors — then packs it into a high-bit-depth pixel format (`gray12le`) and encodes it with a 12-bit codec.
+
+<div style="margin:28px 0;padding:14px 0;">
+  <div style="margin:0 auto;display:flex;flex-wrap:wrap;justify-content:center;align-items:stretch;gap:6px;font-family:'Source Sans 3',ui-sans-serif,system-ui,sans-serif;font-size:14px;font-weight:600;color:#1B1B1D;">
+    <span style="display:flex;flex-direction:column;justify-content:center;align-items:center;text-align:center;gap:2px;background:#DBEAFE;color:#1D4ED8;border-radius:9px;padding:8px 12px;">
+      <span>Raw depth</span>
+      <span style="font-size:11px;font-weight:400;color:#3B6FD4;white-space:nowrap;">
+        uint16 mm
+        <br />
+        float32 m
+      </span>
+    </span>
+    <span style="display:flex;align-items:center;font-size:16px;color:#C3CBD9;">
+      →
+    </span>
+    <div style="border:2px dashed #C4B5FD;border-radius:13px;padding:18px 12px 12px;position:relative;display:flex;align-items:stretch;gap:6px;">
+      <span style="position:absolute;top:-10px;left:12px;background:#fff;padding:0 6px;font-size:11px;font-weight:700;color:#7E22CE;text-transform:uppercase;letter-spacing:0.5px;white-space:nowrap;">
+        Record time
+      </span>
+      <span style="display:flex;flex-direction:column;justify-content:center;align-items:center;text-align:center;gap:2px;background:#F3E8FF;color:#7E22CE;border-radius:9px;padding:8px 12px;">
+        <span>Clip</span>
+        <span style="font-size:11px;font-weight:400;color:#9061C2;white-space:nowrap;">
+          to [depth_min,
+          <br />
+          depth_max]
+        </span>
+      </span>
+      <span style="display:flex;align-items:center;font-size:16px;color:#C3CBD9;">
+        →
+      </span>
+      <span style="display:flex;flex-direction:column;justify-content:center;align-items:center;text-align:center;gap:2px;background:#F3E8FF;color:#7E22CE;border-radius:9px;padding:8px 12px;">
+        <span>Quantize</span>
+        <span style="font-size:11px;font-weight:400;color:#9061C2;white-space:nowrap;">
+          12-bit codes 0–4095
+          <br />
+          log (default) or linear
+        </span>
+      </span>
+      <span style="display:flex;align-items:center;font-size:16px;color:#C3CBD9;">
+        →
+      </span>
+      <span style="display:flex;flex-direction:column;justify-content:center;align-items:center;text-align:center;gap:2px;background:#F3E8FF;color:#7E22CE;border-radius:9px;padding:8px 12px;">
+        <span>Pack</span>
+        <span style="font-size:11px;font-weight:400;color:#9061C2;white-space:nowrap;">
+          into gray12le
+          <br />
+          plane
+        </span>
+      </span>
+      <span style="display:flex;align-items:center;font-size:16px;color:#C3CBD9;">
+        →
+      </span>
+      <span style="display:flex;flex-direction:column;justify-content:center;align-items:center;text-align:center;gap:2px;background:#F3E8FF;color:#7E22CE;border-radius:9px;padding:8px 12px;">
+        <span>Encode</span>
+        <span style="font-size:11px;font-weight:400;color:#9061C2;white-space:nowrap;">
+          HEVC
+          <br />
+          Main 12
+        </span>
+      </span>
+    </div>
+    <span style="display:flex;align-items:center;font-size:16px;color:#C3CBD9;">
+      →
+    </span>
+    <span style="display:flex;flex-direction:column;justify-content:center;align-items:center;text-align:center;gap:2px;background:#FEF3C7;color:#B45309;border-radius:9px;padding:8px 12px;">
+      <span>MP4</span>
+      <span style="font-size:11px;font-weight:400;color:#C77D18;white-space:nowrap;">
+        stored
+        <br />
+        stream
+      </span>
+    </span>
+    <span style="display:flex;align-items:center;font-size:16px;color:#34A06B;">
+      →
+    </span>
+    <div style="border:2px dashed #6EE7B7;border-radius:13px;padding:18px 12px 12px;position:relative;display:flex;align-items:center;gap:6px;">
+      <span style="position:absolute;top:-10px;left:12px;background:#fff;padding:0 6px;font-size:11px;font-weight:700;color:#047857;text-transform:uppercase;letter-spacing:0.5px;white-space:nowrap;">
+        Load time
+      </span>
+      <span style="display:flex;flex-direction:column;justify-content:center;align-items:center;text-align:center;gap:2px;background:#D1FAE5;color:#047857;border-radius:9px;padding:8px 12px;">
+        <span>Dequantize</span>
+        <span style="font-size:11px;font-weight:400;color:#059669;white-space:nowrap;">
+          to mm / m
+        </span>
+      </span>
+    </div>
+  </div>
+</div>
+
+Configure the depth pipeline through a parallel **`depth_encoder`** block (`DepthEncoderConfig`). It shares every `RGBEncoderConfig` field (`vcodec`, `pix_fmt`, `crf`, …) and adds four quantizer knobs, set via `--dataset.depth_encoder.<field>`:
+
+```bash
+lerobot-record \
+    ... \
+    --dataset.depth_encoder.vcodec=hevc \
+    --dataset.depth_encoder.depth_min=0.05 \
+    --dataset.depth_encoder.depth_max=5.0 \
+    --dataset.depth_encoder.use_log=true
+```
+
+| Parameter       | Type    | Default                         | Description                                                                                                                            |
+| --------------- | ------- | ------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- |
+| `vcodec`        | `str`   | `"hevc"`                        | HEVC Main 12 (a 12-bit-capable codec, MP4-compatible).                                                                                 |
+| `extra_options` | `dict`  | `{"x265-params": "lossless=1"}` | **Depth defaults to lossless** (exact round-trip); `crf` is ignored. Pass `extra_options={}` and set `crf` for a smaller lossy stream. |
+| `pix_fmt`       | `str`   | `"gray12le"`                    | Single-channel 12-bit pixel format used to carry the quantized codes.                                                                  |
+| `depth_min`     | `float` | `0.01`                          | Depth in metres mapped to quantum `0`. Values below are clipped on decode.                                                             |
+| `depth_max`     | `float` | `10.0`                          | Depth in metres mapped to quantum `4095`. Values above are clipped on decode.                                                          |
+| `shift`         | `float` | `3.5`                           | Pre-log offset (metres) used in logarithmic quantization for numerical stability near zero. Must satisfy `depth_min + shift > 0`.      |
+| `use_log`       | `bool`  | `True`                          | If `true`, quantize in log-space (recommended for typical depth sensors). Set to `false` for uniform/linear quantization.              |
+
+> [!TIP]
+> `depth_min`, `depth_max`, and `shift` are always interpreted in **metres**, regardless of the input depth's unit. Inputs are auto-detected: integer arrays (e.g. `uint16` millimetres straight from a RealSense) are treated as millimetres, floating arrays as metres.
+> Pick `depth_min` / `depth_max` to bracket the actual working range of your sensor — quanta outside that range saturate, which can crush detail at the boundaries.
+
+Depth features are flagged with `"is_depth_map": true` in `meta/info.json`, and their quantizer settings (`video.depth_min`, `video.depth_max`, `video.shift`, `video.use_log`) are persisted — which is what lets depth be **dequantized back to physical units** on load.
+
+### Output unit at load time
+
+`depth_encoder` is a **record-time** concern. The unit that depth maps are dequantized to on _load_ (e.g. during training) is set separately by the read-time flag `--dataset.depth_output_unit`:
+
+```bash
+lerobot-train \
+    --dataset.repo_id=<my_username>/<my_dataset_name> \
+    --dataset.depth_output_unit=m \
+    --policy.type=act
+```
+
+| Parameter           | Type  | Default | Description                                                                                  |
+| ------------------- | ----- | ------- | -------------------------------------------------------------------------------------------- |
+| `depth_output_unit` | `str` | `"mm"`  | Physical unit depth maps are dequantized to on load: `"mm"` (millimetres) or `"m"` (metres). |
+
+> [!TIP]
+> This is purely a decode-time presentation choice — it does **not** alter the stored video or its metadata, so the same dataset can be read as `mm` or `m` without re-encoding. It has no effect on datasets without depth cameras.
+
+---
+
 ## Persistence in dataset metadata
 
 After the first episode of a video stream is encoded, the encoder configuration is **persisted into the dataset metadata** (`meta/info.json`) under each video feature, alongside the values probed from the file itself. For a video feature `observation.images.<camera>`, the layout in `info.json` is:
@@ -82,7 +217,7 @@ After the first episode of a video stream is encoded, the encoder configuration
         "video.pix_fmt": "yuv420p",
         "video.fps": 30,
         "video.channels": 3,
-        "video.is_depth_map": false,
+        "is_depth_map": false,
         "video.g": 2,
         "video.crf": 30,
         "video.preset": "fast",
@@ -97,15 +232,16 @@ After the first episode of a video stream is encoded, the encoder configuration
 
 Two sources contribute to the `info` block:
 
-- **Stream-derived** (read back from the encoded MP4 with PyAV): `video.height`, `video.width`, `video.codec`, `video.pix_fmt`, `video.fps`, `video.channels`, `video.is_depth_map`, plus `audio.*` if an audio stream is present.
-- **Encoder-derived** (taken from `VideoEncoderConfig`): `video.g`, `video.crf`, `video.preset`, `video.fast_decode`, `video.video_backend`, `video.extra_options`.
+| Source              | Where it comes from                                   | Fields                                                                                                                  |
+| ------------------- | ----------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------- |
+| **Stream-derived**  | Read back from the encoded MP4 with PyAV.             | `video.height`, `video.width`, `video.codec`, `video.pix_fmt`, `video.fps`, `video.channels`, `is_depth_map`, `audio.*` |
+| **Encoder-derived** | Taken from `RGBEncoderConfig` / `DepthEncoderConfig`. | `video.g`, `video.crf`, `video.preset`, `video.fast_decode`, `video.video_backend`, `video.extra_options`               |
 
-<Tip>
-  This block is populated **once**, from the **first** episode. It assumes every
-  episode in the dataset was encoded with the same `camera_encoder`. Changing
-  encoder settings partway through a recording is not supported — the
-  `info.json` will only reflect the parameters used for the first episode.
-</Tip>
+> [!IMPORTANT]
+> This block is populated **once**, from the **first** episode. It assumes every
+> episode in the dataset was encoded with the same `rgb_encoder`. Changing
+> encoder settings partway through a recording is not supported — the
+> `info.json` will only reflect the parameters used for the first episode.
 
 ---
 
@@ -113,5 +249,7 @@ Two sources contribute to the `info` block:
 
 When aggregating datasets with `merge_datasets`, video files are concatenated as-is (no re-encoding), and encoder fields in `info.json` are merged per-key:
 
-- **Stream-derived fields must match** across sources: `video.codec`, `video.pix_fmt`, `video.height`, `video.width`, `video.fps`. Otherwise FFmpeg's concat demuxer fails.
-- **Encoder-tuning fields are merged loosely**: `video.g`, `video.crf`, `video.preset`, `video.fast_decode`, `video.extra_options`. If every source agrees, the value is kept; if not, it's set to `null` (or `{}` for `video.extra_options`) and a warning is logged.
+| Merge rule         | Fields                                                                             | Behaviour                                                                                                                                                 |
+| ------------------ | ---------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| **Must match**     | `video.codec`, `video.pix_fmt`, `video.height`, `video.width`, `video.fps`         | Stream-derived fields must match across sources, otherwise FFmpeg's concat demuxer fails.                                                                 |
+| **Merged loosely** | `video.g`, `video.crf`, `video.preset`, `video.fast_decode`, `video.extra_options` | Encoder-tuning fields. If every source agrees, the value is kept; if not, it's set to `null` (or `{}` for `video.extra_options`) and a warning is logged. |

docs/source/vlabench.mdx

@@ -165,7 +165,7 @@ lerobot-train \
   --output_dir=./outputs/smolvla_vlabench_primitive \
   --steps=100000 \
   --batch_size=4 \
-  --eval_freq=5000 \
+  --env_eval_freq=5000 \
   --eval.batch_size=1 \
   --eval.n_episodes=1 \
   --save_freq=10000

examples/annotations/run_hf_job.py

@@ -0,0 +1,77 @@
+#!/usr/bin/env python
+
+# Copyright 2026 The HuggingFace Inc. team. All rights reserved.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+"""Launch ``lerobot-annotate`` on a Hugging Face job (vllm + Qwen3.6-27B VLM).
+
+Spawns one single-GPU ``h200`` job that:
+
+  1. installs ``lerobot`` from ``main`` plus the annotation extras,
+  2. boots one vllm server with Qwen3.6-27B (dense VLM),
+  3. runs the plan / interjections / vqa modules across the dataset
+     in free-form mode (each episode generates its own subtasks +
+     memory),
+  4. uploads the annotated dataset to ``--new_repo_id`` (when set)
+     or back to ``--repo_id``.
+
+Usage:
+
+    HF_TOKEN=hf_... uv run python examples/annotations/run_hf_job.py
+
+Adjust ``CMD`` (dataset, model, hub repo) and ``flavor`` below for your
+run. For larger datasets, scale to ``h200x4`` and raise
+``--vlm.parallel_servers`` / ``--vlm.num_gpus`` to match.
+"""
+
+import os
+
+from huggingface_hub import get_token, run_job
+
+token = os.environ.get("HF_TOKEN") or get_token()
+if not token:
+    raise RuntimeError("No HF token. Run `huggingface-cli login` or `export HF_TOKEN=hf_...`")
+
+CMD = (
+    "apt-get update -qq && apt-get install -y -qq git ffmpeg && "
+    "pip install --no-deps "
+    "'lerobot @ git+https://github.com/huggingface/lerobot.git@main' && "
+    "pip install --upgrade-strategy only-if-needed "
+    "datasets pyarrow av jsonlines draccus gymnasium torchcodec mergedeep pyyaml-include toml typing-inspect "
+    "openai && "
+    "export VLLM_MEMORY_PROFILER_ESTIMATE_CUDAGRAPHS=0 && "
+    "export VLLM_VIDEO_BACKEND=pyav && "
+    "lerobot-annotate "
+    "--repo_id=pepijn223/robocasa_pretrain_human300_v4 "
+    "--new_repo_id=pepijn223/robocasa_pretrain_human300_v4_annotated "
+    "--push_to_hub=true "
+    "--vlm.backend=openai "
+    "--vlm.model_id=Qwen/Qwen3.6-27B "
+    "--vlm.num_gpus=1 "
+    '--vlm.serve_command="vllm serve Qwen/Qwen3.6-27B '
+    "--tensor-parallel-size 1 --max-model-len 32768 "
+    '--gpu-memory-utilization 0.8 --uvicorn-log-level warning --port {port}" '
+    "--vlm.serve_ready_timeout_s=1800 "
+    # Qwen3.6 ships with thinking on; annotation wants plain JSON answers.
+    "--vlm.chat_template_kwargs='{\"enable_thinking\": false}'"
+)
+
+job = run_job(
+    image="vllm/vllm-openai:latest",
+    command=["bash", "-c", CMD],
+    flavor="h200",
+    secrets={"HF_TOKEN": token},
+    timeout="2h",
+)
+print(f"Job URL: {job.url}")
+print(f"Job ID:  {job.id}")

examples/isaac_teleop_to_so101/README.md

@@ -0,0 +1,131 @@
+# Isaac Teleop → SO-101
+
+Teleoperate an SO-101/SO-100 follower arm — and record LeRobot datasets — with NVIDIA
+[Isaac Teleop](https://github.com/NVIDIA/IsaacTeleop). Two input devices ship today:
+
+- **XR (VR) controller** (`--teleop.type=xr_controller`) — the controller's grip pose drives the
+  end-effector through a squeeze-to-engage clutch and LeRobot's Cartesian IK pipeline; the analog
+  trigger drives the gripper.
+- **SO-101 leader arm** (`--teleop.type=so101_leader`) — a back-drivable leader arm mirrored 1:1
+  onto the follower via Isaac Teleop's native `so101_leader` plugin (no clutch, no IK).
+
+The full narrative guide (how the clutch works, CloudXR setup, headset pairing, tuning, and
+troubleshooting) is in the [LeRobot docs](https://huggingface.co/docs/lerobot/isaac_teleop)
+(source: `docs/source/isaac_teleop.mdx`). This README is the canonical install and usage
+reference.
+
+## Requirements
+
+- Linux workstation (see NVIDIA's
+  [system requirements](https://nvidia.github.io/IsaacTeleop/main/references/requirements.html)
+  for supported OS/GPU/headset combinations; `isaacteleop` publishes Linux wheels only).
+- An SO-101 (or SO-100) follower arm, calibrated with `lerobot-calibrate`.
+- For the XR device: a CloudXR-capable headset (e.g. Quest 3, Pico 4, Apple Vision Pro) on the
+  same network.
+- For the leader device: a second, back-drivable SO-101 leader arm and the `so101_leader` plugin
+  binary built from the Isaac Teleop source tree (see
+  [Build from source](https://nvidia.github.io/IsaacTeleop/main/getting_started/build_from_source/index.html)).
+
+## Installation
+
+This example lives in the LeRobot repository and is not part of the `lerobot` pip package, so
+work from a source checkout. From the repo root:
+
+```bash
+# LeRobot with the extras this example uses:
+#   feetech    - SO-101 serial motor bus
+#   kinematics - Placo IK solver (XR controller path)
+#   dataset    - dataset recording (record.py)
+# huggingface_hub >= 1.5 is needed by the automatic URDF fetch (Buckets API).
+uv pip install -e ".[feetech,kinematics,dataset]" "huggingface_hub>=1.5"
+
+# Isaac Teleop from public PyPI. `cloudxr` brings the CloudXR runtime bindings;
+# `retargeters-lite` is the scipy-based retargeter path that resolves on both
+# x86_64 and ARM (the full `retargeters` extra does not resolve on aarch64).
+uv pip install "isaacteleop[cloudxr,retargeters-lite]~=1.3.131" "scipy>=1.14"
+
+# Optional, x86_64 only: the full retargeter stack.
+uv pip install "isaacteleop[retargeters]~=1.3.131"
+```
+
+One-time CloudXR EULA (the auto-launch prompts on stdin and would hang on a headless machine):
+
+```bash
+python -m isaacteleop.cloudxr --accept-eula
+```
+
+## Usage
+
+Run everything from the repo root with `python -m` so the `examples` package resolves.
+
+### Teleoperate — XR controller
+
+```bash
+python -m examples.isaac_teleop_to_so101.teleoperate \
+    --robot.type=so101_follower \
+    --robot.port=/dev/ttyACM0 \
+    --robot.id=so101_follower_arm \
+    --teleop.type=xr_controller
+```
+
+On startup the script launches the CloudXR runtime (~30 s), prints the workstation IP to enter in
+the headset's CloudXR web client, waits for the controllers to stream, slews the arm to a reset
+pose (`--reset_to_origin=false` to skip), and then: **hold the squeeze/grip** to engage, move the
+controller to drive the arm, pull the trigger to close the gripper. Releasing the squeeze freezes
+the arm. The SO-101 URDF is fetched automatically from the `lerobot/robot-urdfs` Hugging Face
+bucket into the LeRobot cache on first run.
+
+To customize the reset pose: back-drive the arm to the pose you want, then
+
+```bash
+python -m examples.isaac_teleop_to_so101.override_reset_pose --port /dev/ttyACM0 --id so101_follower_arm
+```
+
+which writes it to `HF_LEROBOT_HOME/reset_poses/<robot.name>/<robot.id>.json`; runs with the same
+`--robot.id` use it automatically.
+
+### Teleoperate — SO-101 leader arm
+
+```bash
+python -m examples.isaac_teleop_to_so101.teleoperate \
+    --robot.type=so101_follower --robot.port=/dev/ttyACM0 --robot.id=so101_follower_arm \
+    --teleop.type=so101_leader --teleop.port=/dev/ttyACM1 --teleop.id=so101_leader_arm \
+    --launch_plugin=/path/to/IsaacTeleop/install/plugins/so101_leader/so101_leader_plugin
+```
+
+The follower is first slewed to the leader's pose over `--align_duration` seconds
+(`--align=false` to skip), then mirrors it 1:1. The plugin reuses the serial leader's calibration
+(`HF_LEROBOT_CALIBRATION/teleoperators/so_leader/<teleop.id>.json`).
+
+### Record a dataset
+
+`record.py` takes the same `--robot.*`/`--teleop.*`/loop flags plus `lerobot-record`-style
+`--dataset.*` flags:
+
+```bash
+python -m examples.isaac_teleop_to_so101.record \
+    --robot.type=so101_follower --robot.port=/dev/ttyACM0 --robot.id=so101_follower_arm \
+    --teleop.type=xr_controller \
+    --robot.cameras="{ front: {type: opencv, index_or_path: 0, width: 640, height: 480, fps: 30}}" \
+    --dataset.repo_id=<hf_user>/<dataset_name> \
+    --dataset.single_task="Pick up the cube" \
+    --dataset.num_episodes=3 --dataset.episode_time_s=20 --dataset.reset_time_s=5
+```
+
+Keyboard shortcuts (terminal-first, so they work over SSH): **Right/n** end episode early,
+**Left/r** re-record, **Esc/q** stop after the current episode.
+
+Run either script with `--help` for all flags.
+
+## Layout
+
+```
+isaac_teleop/            device library: session lifecycle (base.py), XRController,
+                         SO101LeaderArm, Clutch, configs, and the XR→IK processor step
+common.py                shared loop infra: device bundles, clutch/IK pipeline wiring,
+                         reset/align slews, URDF fetch, keyboard listener
+teleoperate.py           teleoperation CLI (device selected via --teleop.type)
+record.py                dataset-recording CLI (same device selection + --dataset.*)
+override_reset_pose.py   save the current joints as the per-arm reset pose
+default.env              CloudXR device-profile overrides passed to the launcher
+```

examples/isaac_teleop_to_so101/__init__.py

@@ -0,0 +1,17 @@
+#!/usr/bin/env python
+
+# Copyright 2026 NVIDIA Corporation and The HuggingFace Inc. team. All rights reserved.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""Isaac Teleop -> SO-101 example package."""

examples/isaac_teleop_to_so101/common.py

@@ -0,0 +1,650 @@
+#!/usr/bin/env python
+
+# Copyright 2026 NVIDIA Corporation and The HuggingFace Inc. team. All rights reserved.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""Shared device + control-loop infrastructure for the Isaac Teleop -> SO-101 examples.
+
+Consumed by ``teleoperate.py`` and ``record.py``, which both build a per-device
+:class:`Device` bundle and run the same loop: read -> (maybe command) -> hold-when-idle ->
+sleep. A :class:`Device` bundles three closures: ``compute(obs) -> RobotAction | None``
+(``None`` = hold at the measured pose while idle), ``startup``, and ``cleanup``. The devices:
+
+* ``xr_controller`` — a thin :class:`XRController` whose raw grip pose an in-loop
+  :class:`Clutch` turns into an EE target for LeRobot's Cartesian IK pipeline.
+* ``so101_leader`` — a back-drivable leader arm mirrored 1:1 into the follower.
+
+Requires the ``isaacteleop`` package and an OpenXR runtime (install instructions in this
+folder's ``README.md``). User-facing guide: ``docs/source/isaac_teleop.mdx``.
+"""
+
+import json
+import logging
+import socket
+import subprocess
+import sys
+import time
+from collections.abc import Callable
+from contextlib import suppress
+from dataclasses import dataclass
+from importlib.resources import files
+from pathlib import Path
+from typing import Protocol
+
+import numpy as np
+
+from lerobot.model.kinematics import RobotKinematics
+from lerobot.processor import (
+    RobotProcessorPipeline,
+    robot_action_observation_to_transition,
+    transition_to_robot_action,
+)
+from lerobot.robots import RobotConfig, make_robot_from_config
+from lerobot.robots.so_follower import SOFollowerConfig  # noqa: F401  (registers so101_follower)
+from lerobot.robots.so_follower.robot_kinematic_processor import (
+    EEBoundsAndSafety,
+    InverseKinematicsEEToJoints,
+)
+from lerobot.types import RobotAction, RobotObservation
+from lerobot.utils.constants import HF_LEROBOT_CALIBRATION, HF_LEROBOT_HOME, TELEOPERATORS
+from lerobot.utils.robot_utils import precise_sleep
+
+from .isaac_teleop import (
+    Clutch,
+    IsaacTeleopConfig,
+    MapXRControllerActionToRobotAction,
+    SO101LeaderArm,
+    SO101LeaderArmConfig,
+    XRController,
+)
+
+# Fixed rate [Hz] for the teleoperate loop and the pre-loop slews / connect-wait poll sleeps.
+FPS = 30
+
+# CloudXR device-profile env file passed to the launcher (see default.env in this package).
+CLOUDXR_ENV_FILE = str(files(__package__) / "default.env")
+
+
+class LoopConfig(Protocol):
+    """Structural type for the loop/launch knobs ``build_device`` and the ``setup_*`` read.
+
+    Both ``TeleoperateConfig`` and ``RecordConfig`` satisfy it, keeping ``common`` decoupled
+    from either entry point's concrete config.
+    """
+
+    teleop: IsaacTeleopConfig
+    robot: RobotConfig
+    launch_plugin: str | None
+    reset_to_origin: bool
+    reset_duration: float
+    align: bool
+    align_duration: float
+
+
+# Per-device bundle consumed by the shared loop. ``compute`` returns None to mean
+# "idle -> hold at the measured pose"; ``startup`` warms up; ``cleanup`` reaps/disconnects.
+@dataclass(frozen=True)
+class Device:
+    compute: Callable[[RobotObservation | None], RobotAction | None]
+    startup: Callable[[], None]
+    cleanup: Callable[[], None]
+
+
+def hold_action(obs: RobotObservation, motor_names: list[str]) -> dict[str, float]:
+    """Re-send the measured joints — the explicit hold when a device is idle."""
+    return {f"{name}.pos": float(obs[f"{name}.pos"]) for name in motor_names}
+
+
+class HoldLatch:
+    """Resolve the per-frame action, holding one LATCHED pose while the device is idle.
+
+    Re-sending the freshly measured joints on every idle frame would ratchet the arm
+    downward: under gravity the P-only servo settles below its goal by a steady-state
+    error, so each re-command of the measurement lowers the goal by that error again.
+    Latching the target once on the active->idle transition holds a fixed pose instead.
+    """
+
+    def __init__(self, motor_names: list[str]):
+        self._motor_names = motor_names
+        self._held: dict[str, float] | None = None
+
+    def resolve(self, action: RobotAction | None, obs: RobotObservation) -> RobotAction:
+        """Pass through an active action (clearing the latch); latch + hold when idle."""
+        if action is not None:
+            self._held = None
+            return action
+        if self._held is None:
+            self._held = hold_action(obs, self._motor_names)
+        return self._held
+
+
+def slew(
+    robot,
+    motor_names: list[str],
+    target_fn: Callable[[], dict[str, float]],
+    duration_s: float,
+) -> None:
+    """Linearly slew all joints from their current measured pose toward a target.
+
+    ``target_fn`` is called EACH step, so the leader can pass a live re-read (landing on its
+    current pose at ``alpha == 1`` for a continuous handoff) while XR passes a constant.
+    """
+    obs = robot.get_observation()
+    start = {name: float(obs[f"{name}.pos"]) for name in motor_names}
+    n_steps = max(1, int(duration_s * FPS))
+    for step in range(1, n_steps + 1):
+        alpha = step / n_steps
+        target = target_fn()
+        action = {f"{name}.pos": start[name] + alpha * (target[name] - start[name]) for name in motor_names}
+        robot.send_action(action)
+        precise_sleep(1.0 / FPS)
+
+
+# ============================================================================
+# XR controller device
+# ============================================================================
+
+# Per-frame EE rate limit [m]. With raise_on_jump=False, EEBoundsAndSafety clamps an
+# over-limit step instead of raising, absorbing a tracking glitch as one slow frame. At
+# FPS=30, 0.1 m/frame caps EE speed at ~3 m/s. (end_effector_bounds clips the absolute target.)
+MAX_EE_STEP_M = 0.1
+
+# Soft-orientation IK weight: small but nonzero so the wrist follows the hand while position
+# dominates (the 5-DOF SO-101 cannot realize an arbitrary orientation). 0.0 = position-only.
+IK_ORIENTATION_WEIGHT = 0.01
+
+
+def _ensure_so101_urdf() -> str:
+    """Return the cached SO-101 URDF path, fetching the ``so101`` folder (URDF + meshes) from
+    the public ``lerobot/robot-urdfs`` HF bucket into the LeRobot cache on first use."""
+    dest_dir = HF_LEROBOT_HOME / "robot-urdfs" / "so101"
+    urdf_path = dest_dir / "so101_new_calib.urdf"
+    # Completeness marker written only after a FULL sync: the URDF file alone is not a
+    # completeness signal (an interrupted first sync can leave the meshes it references
+    # missing, which the URDF's mere existence would then hide forever). Re-syncing is
+    # idempotent and repairs a partial cache; delete the folder to force a re-download.
+    marker = dest_dir / ".sync_complete"
+    if not marker.exists():
+        from huggingface_hub import sync_bucket
+
+        sync_bucket("hf://buckets/lerobot/robot-urdfs/so101", str(dest_dir), quiet=True)
+        marker.touch()
+    return str(urdf_path)
+
+
+# Default duration [s] for the startup reset-to-origin slew.
+RESET_DURATION_S = 5.0
+
+# Optional cached file written by override_reset_pose.py. When present it takes priority over RESET_ORIGIN_DEG.
+RESET_POSE_FILE = str(HF_LEROBOT_HOME / "reset_poses" / "{robot_name}" / "{robot_id}.json")
+
+# Reset target in each motor's native units (arm joints in degrees, gripper RANGE_0_100,
+# 100 = open). An empirically comfortable pose (elbow/wrist bent) avoiding the singularity of
+# a fully-extended arm; assumes standard calibration. Override per-arm via override_reset_pose.py.
+RESET_ORIGIN_DEG: dict[str, float] = {
+    "shoulder_pan": -4.0,
+    "shoulder_lift": -103.0,
+    "elbow_flex": 97.0,
+    "wrist_flex": 78.0,
+    "wrist_roll": -65.0,
+    "gripper": 0.0,
+}
+
+
+def _load_reset_target(reset_pose_file: Path, motor_names: list[str]) -> dict[str, float]:
+    """Return reset targets: the saved reset pose if present, else RESET_ORIGIN_DEG."""
+    if reset_pose_file.exists():
+        saved = json.loads(reset_pose_file.read_text())
+        # Fill any missing motors from the fallback dict.
+        return {name: float(saved.get(name, RESET_ORIGIN_DEG.get(name, 0.0))) for name in motor_names}
+    return {name: RESET_ORIGIN_DEG.get(name, 0.0) for name in motor_names}
+
+
+# CloudXR web client URL opened in the headset (Isaac Teleop quick start, step 5).
+_CLOUDXR_WEB_CLIENT_URL = "https://nvidia.github.io/IsaacTeleop/client"
+# WSS-proxy / self-signed-cert port the operator accepts in-browser before connecting.
+_CLOUDXR_WSS_PORT = 48322
+# How often to re-print the connection hint while waiting for the headset [s].
+_XR_CONNECT_REMINDER_S = 15.0
+# Virtual / bridge / USB-gadget interfaces a headset can't reach over the network — skip
+# by name prefix (``docker0``, compose ``br-*``, ``veth*``, libvirt ``virbr*``, and the
+# Tegra USB device-mode bridge ``l4tbr0``).
+_SKIP_IFACE_PREFIXES = ("docker", "br-", "veth", "virbr", "l4tbr")
+
+
+def _primary_ipv4() -> str | None:
+    """The workstation's primary outbound IPv4, via the UDP-socket trick (``connect()`` on a
+    datagram socket selects the egress interface without sending packets)."""
+    with socket.socket(socket.AF_INET, socket.SOCK_DGRAM) as s:
+        try:
+            s.connect(("8.8.8.8", 80))
+            return s.getsockname()[0]
+        except OSError:
+            return None
+
+
+def _candidate_ipv4s() -> list[tuple[str, str]]:
+    """Return ``[(interface, ipv4), ...]`` the headset might reach this workstation at.
+
+    Lists each interface's IPv4 via ``psutil`` (dropping loopback, link-local, and the
+    virtual/bridge interfaces in ``_SKIP_IFACE_PREFIXES``), primary outbound first. Falls
+    back to just the primary IP when ``psutil`` is unavailable.
+    """
+    primary = _primary_ipv4()
+    found: list[tuple[str, str]] = []
+    try:
+        import psutil
+
+        for iface, addrs in psutil.net_if_addrs().items():
+            if iface.startswith(_SKIP_IFACE_PREFIXES):
+                continue
+            for addr in addrs:
+                if addr.family != socket.AF_INET:
+                    continue
+                ip = addr.address
+                if ip.startswith("127.") or ip.startswith("169.254."):
+                    continue
+                found.append((iface, ip))
+    except Exception:
+        if primary:
+            found.append(("default", primary))
+    found.sort(key=lambda t: t[1] != primary)  # primary outbound interface first
+    return found
+
+
+def _print_xr_connect_help() -> None:
+    """Print how to connect the headset to this workstation over CloudXR."""
+    ips = _candidate_ipv4s()
+    print("\n" + "=" * 76)
+    print("Connect your XR headset to this workstation over NVIDIA CloudXR:")
+    print(f"  1. In the headset, open the CloudXR web client:  {_CLOUDXR_WEB_CLIENT_URL}")
+    print("  2. Enter this workstation's IP address:")
+    if ips:
+        for iface, ip in ips:
+            print(f"        {ip:<15}  ({iface})")
+        if len(ips) > 1:
+            print("     (use the address on the same network as your headset)")
+    else:
+        print("        <could not determine — check `hostname -I` / `ip addr`>")
+    print(f"  3. Accept the self-signed cert at https://<that-ip>:{_CLOUDXR_WSS_PORT}/ , then Connect.")
+    print("=" * 76 + "\n")
+
+
+def _wait_for_xr_controller(teleop_device: XRController) -> None:
+    """Block until the XR controller is tracked, polling ``get_action()`` and re-printing a
+    reminder every ``_XR_CONNECT_REMINDER_S``. User-paced; ``Ctrl-C`` aborts (no hard timeout).
+    """
+    _print_xr_connect_help()
+    print("Waiting for the headset controllers to start streaming…  (Ctrl-C to abort)")
+    last_reminder = time.time()
+    while True:
+        teleop_device.get_action()  # steps the session; updates is_tracking
+        if teleop_device.is_tracking:
+            print("Headset connected — controllers are streaming.")
+            return
+        if time.time() - last_reminder >= _XR_CONNECT_REMINDER_S:
+            print("…still waiting for the headset to connect (Ctrl-C to abort).")
+            last_reminder = time.time()
+        time.sleep(1.0 / FPS)
+
+
+def setup_xr(cfg: LoopConfig, robot, motor_names: list[str]) -> Device:
+    """Build the XR controller device bundle (clutch + soft-orientation IK pipeline)."""
+    kinematics_solver = RobotKinematics(
+        urdf_path=_ensure_so101_urdf(),
+        target_frame_name="gripper_frame_link",
+        joint_names=motor_names,
+    )
+
+    teleop_config = cfg.teleop  # XRControllerConfig (selected via --teleop.type=xr_controller)
+    teleop_device = XRController(teleop_config)
+
+    # The clutch (below) turns the raw grip pose into an absolute base-frame ee_pose; this
+    # pipeline maps it to joint targets: rename -> bounds/rate-limit -> IK.
+    xr_to_robot_joints_processor = RobotProcessorPipeline[tuple[RobotAction, RobotObservation], RobotAction](
+        steps=[
+            MapXRControllerActionToRobotAction(),
+            # raise_on_jump=False: an over-limit step (e.g. a tracking glitch) is clamped +
+            # warned instead of raised, since a crash mid-loop would leave the arm uncontrolled.
+            # z floor 0.0 keeps a stray target above the table; x/y stay at a loose [-1,1]m box.
+            EEBoundsAndSafety(
+                end_effector_bounds={"min": [-1.0, -1.0, 0.0], "max": [1.0, 1.0, 1.0]},
+                max_ee_step_m=MAX_EE_STEP_M,
+                raise_on_jump=False,
+            ),
+            # initial_guess_current_joints=False: warm-start from the previous IK solution so
+            # the joint trajectory stays continuous frame-to-frame.
+            InverseKinematicsEEToJoints(
+                kinematics=kinematics_solver,
+                motor_names=motor_names,
+                initial_guess_current_joints=False,
+                orientation_weight=IK_ORIENTATION_WEIGHT,
+            ),
+        ],
+        to_transition=robot_action_observation_to_transition,
+        to_output=transition_to_robot_action,
+    )
+
+    # The clutch is built in startup() (after the optional reset slew, seeded from the
+    # post-slew MEASURED pose) and shared with compute() via nonlocal.
+    clutch: Clutch | None = None
+    prev_enabled = False
+
+    def startup() -> None:
+        nonlocal clutch
+        # Connect and wait for the operator to don the headset BEFORE moving the arm, so the
+        # reset slew happens while they are watching in VR.
+        teleop_device.connect()
+        if not teleop_device.is_connected:
+            raise ValueError("Teleop is not connected!")
+        _wait_for_xr_controller(teleop_device)
+
+        if cfg.reset_to_origin:
+            reset_pose_file = Path(RESET_POSE_FILE.format(robot_name=robot.name, robot_id=robot.id))
+            target = _load_reset_target(reset_pose_file, motor_names)
+            source = str(reset_pose_file) if reset_pose_file.exists() else "hardcoded defaults"
+            print(f"Reset target source: {source}")
+            print(f"Resetting to origin over {cfg.reset_duration:.1f} s…")
+            slew(robot, motor_names, lambda: target, cfg.reset_duration)
+            print("Reset complete.")
+
+        # Seed the clutch home from the arm's measured pose (FK of the current joints) so the
+        # first engage is jump-free, whether or not a reset slew ran.
+        obs0 = robot.get_observation()
+        q_measured_deg = np.array([float(obs0[f"{name}.pos"]) for name in motor_names], dtype=float)
+        home_base_T_ee = kinematics_solver.forward_kinematics(q_measured_deg)  # noqa: N806
+        clutch = Clutch(home_base_T_ee)
+
+        print("Starting teleop loop. Squeeze and move the controller to teleoperate the robot...")
+
+    def compute(robot_obs: RobotObservation | None) -> RobotAction | None:
+        nonlocal prev_enabled
+        if clutch is None:  # set in startup(), which runs before compute()
+            raise RuntimeError("compute() called before startup(); the clutch is not initialized")
+        xr_action = teleop_device.get_action()
+        grip_pos = np.asarray(xr_action["grip_pos"], dtype=float)
+        grip_quat = np.asarray(xr_action["grip_quat"], dtype=float)
+        squeeze = float(xr_action["squeeze"])
+        trigger = float(xr_action["trigger"])
+        enabled = squeeze > teleop_config.clutch_threshold
+
+        # On the engage edge, latch the clutch home at the arm's MEASURED EE pose (FK of
+        # the live joints) and the controller origin so the per-frame delta starts at zero.
+        # Latching the last commanded pose instead would snap the arm back to it at full
+        # servo speed if the arm moved while disengaged (gravity sag, external contact).
+        is_engage_frame = enabled and not prev_enabled
+        if is_engage_frame:
+            q_measured = np.array([float(robot_obs[f"{name}.pos"]) for name in motor_names], dtype=float)
+            measured_base_T_ee = kinematics_solver.forward_kinematics(q_measured)  # noqa: N806
+            clutch.engage(grip_pos, grip_quat, measured_base_T_ee=measured_base_T_ee)
+            # Re-anchor the pipeline state at the measured pose as well: EEBoundsAndSafety's
+            # rate limiter and the IK warm start otherwise still reference the stale
+            # pre-disengage command and would fight the fresh home for several frames.
+            xr_to_robot_joints_processor.reset()
+        prev_enabled = enabled
+
+        # SAFETY GATE: command the robot ONLY while the clutch is engaged; otherwise return
+        # None so the loop holds the measured joints (releasing the clutch freezes the arm).
+        if not enabled:
+            return None
+
+        # Rebase the raw grip pose onto the EE, then run the pipeline. closedness = trigger.
+        ee_pos, ee_quat = clutch.rebase(grip_pos, grip_quat)
+        ee_action = {
+            "ee_pose": np.concatenate([ee_pos, ee_quat]).astype(np.float32),
+            "closedness": trigger,
+        }
+        return xr_to_robot_joints_processor((ee_action, robot_obs))
+
+    return Device(compute=compute, startup=startup, cleanup=teleop_device.disconnect)
+
+
+# ============================================================================
+# SO-101 leader arm device
+# ============================================================================
+
+# Default duration [s] for the startup alignment slew (follower current -> leader first pose).
+ALIGN_DURATION_S = 3.0
+
+# How long to wait for the leader plugin to start streaming before aligning / looping.
+LEADER_WARMUP_TIMEOUT_S = 20.0
+
+# The plugin converts the leader's servo ticks to radians, so it reuses the serial SO-101
+# leader's calibration, stored by lerobot-calibrate under SO101Leader.name == "so_leader".
+SO_LEADER_CALIBRATION_NAME = "so_leader"
+
+
+def _leader_calibration_path(cfg: LoopConfig) -> Path | None:
+    """Infer the calibration JSON the launched plugin should read, or None.
+
+    Path convention: ``HF_LEROBOT_CALIBRATION / teleoperators / so_leader / {--teleop.id}.json``
+    (or ``--teleop.calibration_dir`` if set). Returns None (plugin falls back to defaults) when
+    it does not exist, warning if an id was given, or when no ``--teleop.id`` is set.
+    """
+    if not cfg.teleop.id:
+        return None
+    calib_dir = cfg.teleop.calibration_dir or (
+        HF_LEROBOT_CALIBRATION / TELEOPERATORS / SO_LEADER_CALIBRATION_NAME
+    )
+    calib_path = Path(calib_dir) / f"{cfg.teleop.id}.json"
+    if calib_path.is_file():
+        return calib_path
+    print(
+        f"WARNING: no leader calibration at {calib_path}; the plugin will use built-in defaults. "
+        f"Calibrate with the serial leader (`lerobot-calibrate --teleop.type=so101_leader "
+        f"--teleop.id={cfg.teleop.id}`) or the plugin's `calibrate` subcommand."
+    )
+    return None
+
+
+def _wait_for_leader(teleop: SO101LeaderArm, timeout_s: float) -> dict[str, float]:
+    """Poll the leader until it streams a live frame; return that frame's ``{joint}.pos``.
+
+    Raises ``SystemExit`` if no live frame arrives within ``timeout_s`` (plugin not pushing,
+    wrong ``--teleop.collection_id``, or CloudXR not up).
+    """
+    print(f"Waiting up to {timeout_s:.0f}s for the so101_leader plugin to stream…")
+    deadline = time.time() + timeout_s
+    while time.time() < deadline:
+        action = teleop.get_action()
+        if teleop.is_tracking:
+            print("Leader is streaming.")
+            return action
+        time.sleep(1.0 / FPS)
+    raise SystemExit(
+        f"FAILED: leader did not stream within {timeout_s:.0f}s. Is the so101_leader plugin "
+        "running and pushing (check --teleop.collection_id)? Is CloudXR up?"
+    )
+
+
+def _maybe_launch_plugin(cfg: LoopConfig) -> subprocess.Popen | None:
+    """Spawn the so101_leader plugin if ``--launch_plugin <path>`` was given (after connect())."""
+    if cfg.launch_plugin is None:
+        return None
+    if not Path(cfg.launch_plugin).exists():
+        raise SystemExit(
+            f"plugin binary not found: {cfg.launch_plugin} (build it in the IsaacTeleop repo first)"
+        )
+    leader_port = cfg.teleop.port  # SO101LeaderArmConfig.port, forwarded to the plugin
+    backend = f"leader on {leader_port}" if leader_port else "synthetic trajectory"
+    print(f"launching plugin: {cfg.launch_plugin} ({backend})")
+    # Positional args: [device_path] [collection_id] [calibration_file]. Empty device_path ->
+    # synthetic backend. Calibration (only real hardware needs it) is appended when a port is set.
+    argv = [cfg.launch_plugin, leader_port, cfg.teleop.collection_id]
+    if leader_port:
+        calib_path = _leader_calibration_path(cfg)
+        if calib_path is not None:
+            argv.append(str(calib_path))
+            print(f"  leader calibration: {calib_path}")
+    # Spawned after connect() so it inherits the CloudXR runtime env (XR_RUNTIME_JSON, ...).
+    proc = subprocess.Popen(argv)
+    time.sleep(1.5)  # let it create its OpenXR session and start pushing
+    return proc
+
+
+def setup_leader(cfg: LoopConfig, robot, motor_names: list[str]) -> Device:
+    """Build the SO-101 leader arm device bundle (1:1 joint mirror)."""
+    teleop_config = cfg.teleop  # SO101LeaderArmConfig (selected via --teleop.type=so101_leader)
+    teleop = SO101LeaderArm(teleop_config)
+
+    plugin_proc: subprocess.Popen | None = None
+
+    def startup() -> None:
+        nonlocal plugin_proc
+        # connect() auto-launches CloudXR (unless opted out); spawn the plugin AFTER so it
+        # inherits the runtime env. The plugin is reaped in cleanup().
+        teleop.connect()
+        plugin_proc = _maybe_launch_plugin(cfg)
+
+        if not teleop.is_connected:
+            raise ValueError("Teleop is not connected!")
+
+        # Block until the leader streams a live frame (clear error if it never does).
+        _wait_for_leader(teleop, LEADER_WARMUP_TIMEOUT_S)
+
+        if cfg.align:
+            print(f"Aligning follower to leader over {cfg.align_duration:.1f}s…")
+
+            # Re-read the live leader pose once per step so alpha=1 lands on its current pose
+            # from a single coherent frame.
+            def _leader_target() -> dict[str, float]:
+                leader_now = teleop.get_action()
+                return {name: float(leader_now[f"{name}.pos"]) for name in motor_names}
+
+            slew(robot, motor_names, _leader_target, cfg.align_duration)
+            print("Alignment complete.")
+
+        print(
+            "Starting joint-mirror loop. Back-drive the leader to teleoperate the follower… (Ctrl-C to stop)"
+        )
+
+    def compute(robot_obs: RobotObservation | None) -> RobotAction | None:
+        leader_action = teleop.get_action()
+        # Hold the follower at its measured pose when the leader drops out (stale stream)
+        # rather than commanding a possibly-old target.
+        if not teleop.is_tracking:
+            return None
+        return leader_action
+
+    def cleanup() -> None:
+        # A plugin-reaping failure must not skip the session disconnect (and vice versa
+        # the disconnect runs after the plugin stops pushing on it).
+        try:
+            if plugin_proc is not None:
+                plugin_proc.terminate()
+                try:
+                    plugin_proc.wait(timeout=5)
+                except subprocess.TimeoutExpired:
+                    plugin_proc.kill()
+        finally:
+            teleop.disconnect()
+
+    return Device(compute=compute, startup=startup, cleanup=cleanup)
+
+
+# ============================================================================
+# Shared setup
+# ============================================================================
+
+
+def build_device(cfg: LoopConfig) -> tuple:
+    """Connect the follower, build the selected Isaac device, and run its pre-loop startup.
+
+    Connects the follower FIRST (so the startup slew / clutch-home seed can read live joints),
+    dispatches on ``--teleop.type``, then runs ``device.startup()`` before returning. On any
+    failure after ``connect()`` the follower is disconnected so the connection never leaks.
+
+    Returns ``(robot, device, motor_names)``.
+    """
+    # Default the CloudXR input profile to this example's default.env unless the user overrode
+    # it via --teleop.cloudxr_env_file.
+    if cfg.teleop.cloudxr_env_file is None:
+        cfg.teleop.cloudxr_env_file = CLOUDXR_ENV_FILE
+
+    # SO-101/SO-100 only (both share the SO-101 URDF), reject other followers.
+    supported_robots = {"so101_follower", "so100_follower"}
+    if cfg.robot.type not in supported_robots:
+        raise ValueError(
+            f"This example only supports SO-101/SO-100 followers ({sorted(supported_robots)}), "
+            f"but got --robot.type={cfg.robot.type}."
+        )
+
+    # The degree-based pipeline relies on --robot.use_degrees (default True).
+    robot = make_robot_from_config(cfg.robot)
+    # Connect FIRST so the startup slew and clutch-home seed can read live joints.
+    robot.connect()
+    # Everything after connect() can fail; this runs outside the callers' try/finally, so
+    # disconnect the follower on any failure to avoid leaking the connection.
+    device: Device | None = None
+    try:
+        # Joint names in action order, read from {name}.pos action features (robot-agnostic).
+        motor_names = [key.removesuffix(".pos") for key in robot.action_features if key.endswith(".pos")]
+
+        if isinstance(cfg.teleop, SO101LeaderArmConfig):
+            device = setup_leader(cfg, robot, motor_names)
+        else:
+            device = setup_xr(cfg, robot, motor_names)
+
+        device.startup()
+    except BaseException:
+        # Reap a partially-started device, then always disconnect the follower.
+        if device is not None:
+            with suppress(Exception):
+                device.cleanup()
+        robot.disconnect()
+        raise
+
+    return robot, device, motor_names
+
+
+# ============================================================================
+# Keyboard control
+# ============================================================================
+
+
+def init_keyboard_listener():
+    """Recording shortcuts, terminal-first so they work over SSH.
+
+    Whenever stdin is a TTY we use the stdlib :class:`TerminalKeyListener` directly rather
+    than upstream's pynput-first :func:`init_keyboard_listener`, whose global listener would
+    capture the workstation console instead of this (often SSH) terminal. With no TTY we defer
+    to upstream (pynput on a GUI, else headless no-op).
+    """
+    if not (sys.stdin is not None and sys.stdin.isatty()):
+        from lerobot.utils.keyboard_input import init_keyboard_listener as _upstream
+
+        return _upstream()
+
+    from lerobot.utils.keyboard_input import TerminalKeyListener, apply_recording_control
+
+    events = {"exit_early": False, "rerecord_episode": False, "stop_recording": False}
+
+    # n/r/q are the arrow/Esc equivalents that survive escape-sequence splitting over laggy
+    # SSH/VNC links. Case-insensitive so Shift+letter still works.
+    def on_key(name: str) -> None:
+        key = name.lower()
+        if key in ("right", "n"):
+            apply_recording_control("right", events)
+        elif key in ("left", "r"):
+            apply_recording_control("left", events)
+        elif key in ("esc", "q"):
+            apply_recording_control("esc", events)
+
+    listener = TerminalKeyListener(on_key)
+    listener.start()
+    logging.info(
+        "Keyboard control via terminal — keep this terminal focused: "
+        "Right/n = end episode early, Left/r = re-record, Esc/q = stop."
+    )
+    return listener, events

examples/isaac_teleop_to_so101/default.env

@@ -0,0 +1,21 @@
+# CloudXR device-profile overrides for the Isaac Teleop XR -> SO-101 example.
+#
+# Passed to isaacteleop's CloudXRLauncher as `env_config` (via
+# XRControllerConfig.cloudxr_env_file). Format: KEY=value, one per line; `#`
+# comments and blank lines ignored; $VARS / ~ expanded. See
+# isaacteleop/cloudxr/env_config.py::_load_env_file.
+#
+# Runtime-resolved keys (XR_RUNTIME_JSON, XRT_NO_STDIN, NV_CXR_RUNTIME_DIR,
+# NV_CXR_OUTPUT_DIR) are reserved and ignored if set here.
+
+# Transport profile the runtime advertises (CloudXR default: auto-webrtc).
+# "Quest3" also covers the Pico 4. Other values: auto-native, AppleVisionPro.
+NV_DEVICE_PROFILE=Quest3
+
+# Input device discovery channels (both default to true; pinned for clarity).
+NV_CXR_ENABLE_PUSH_DEVICES=true
+NV_CXR_ENABLE_TENSOR_DATA=true
+
+# Runtime logs to ~/.cloudxr/logs — helps debug connection issues
+# (e.g. "Failed to get OpenXR system: -35").
+NV_CXR_FILE_LOGGING=true

examples/isaac_teleop_to_so101/isaac_teleop/__init__.py

@@ -0,0 +1,40 @@
+#!/usr/bin/env python
+
+# Copyright 2026 NVIDIA Corporation and The HuggingFace Inc. team. All rights reserved.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""NVIDIA Isaac Teleop teleoperators for LeRobot.
+
+Each input device is an :class:`IsaacTeleopTeleoperator` subclass: :class:`XRController`
+(XR/VR controller) and :class:`SO101LeaderArm` (back-drivable SO-101 leader arm) ship today.
+"""
+
+from .base import IsaacTeleopTeleoperator
+from .clutch import Clutch
+from .config_isaac_teleop import IsaacTeleopConfig, SO101LeaderArmConfig, XRControllerConfig
+from .teleop_so101_leader_arm import SO101LeaderArm, leader_joints_to_robot_action
+from .teleop_xr_controller import XRController
+from .xr_controller_processor import MapXRControllerActionToRobotAction
+
+__all__ = [
+    "Clutch",
+    "IsaacTeleopConfig",
+    "IsaacTeleopTeleoperator",
+    "MapXRControllerActionToRobotAction",
+    "SO101LeaderArm",
+    "SO101LeaderArmConfig",
+    "XRController",
+    "XRControllerConfig",
+    "leader_joints_to_robot_action",
+]

examples/isaac_teleop_to_so101/isaac_teleop/base.py

@@ -0,0 +1,282 @@
+#!/usr/bin/env python
+
+# Copyright 2026 NVIDIA Corporation and The HuggingFace Inc. team. All rights reserved.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""Shared base for NVIDIA Isaac Teleop-backed LeRobot teleoperators.
+
+Isaac Teleop is a multi-modal framework: a single ``TeleopSession`` can be driven by
+XR controllers, hand tracking, Manus gloves, etc. Each modality is a
+:class:`Teleoperator` subclass in its own ``teleop_<device>.py``.
+
+:class:`IsaacTeleopTeleoperator` owns what those devices share — the session
+lifecycle, the per-step staleness/worker-health guard, and the no-op calibration
+tracking devices need. A concrete device implements :meth:`_build_pipeline` (its
+retargeting graph) and :meth:`get_action` (usually via :meth:`_step`).
+
+``isaacteleop`` is an optional NVIDIA dependency (install instructions in the example's
+``README.md``); its imports are guarded behind an availability check at module top, so this
+module imports without it and constructing a device fails fast with install instructions.
+"""
+
+from __future__ import annotations
+
+import abc
+import logging
+import os
+from collections.abc import Mapping
+from pathlib import Path
+from typing import TYPE_CHECKING, Any
+
+from lerobot.teleoperators.teleoperator import Teleoperator
+from lerobot.utils.import_utils import is_package_available
+
+from .config_isaac_teleop import IsaacTeleopConfig
+
+_isaacteleop_available = is_package_available("isaacteleop")
+
+if TYPE_CHECKING or _isaacteleop_available:
+    from isaacteleop.cloudxr import CloudXRLauncher
+    from isaacteleop.retargeting_engine.interface import (
+        ExecutionEvents,
+        ExecutionState,
+        GraphExecutable,
+        RetargeterIO,
+    )
+    from isaacteleop.teleop_session_manager import TeleopSession, TeleopSessionConfig
+else:
+    CloudXRLauncher = None
+    ExecutionEvents = None
+    ExecutionState = None
+    GraphExecutable = None
+    RetargeterIO = None
+    TeleopSession = None
+    TeleopSessionConfig = None
+
+logger = logging.getLogger(__name__)
+
+# Gripper closedness [0, 1] -> SO-101 follower motor units [0, 100] (RANGE_0_100, 100 = OPEN).
+# Shared by the XR processor and leader device, which invert via ``pos = (1 - c) * SCALE``.
+_GRIPPER_MOTOR_SCALE = 100.0
+
+
+def _require_isaacteleop() -> None:
+    """Fail fast with install pointers when the optional ``isaacteleop`` package is missing."""
+    if not _isaacteleop_available:
+        raise ImportError(
+            "The 'isaacteleop' package is required for Isaac Teleop devices but is not "
+            "installed. See examples/isaac_teleop_to_so101/README.md for install instructions."
+        )
+
+
+class IsaacTeleopTeleoperator(Teleoperator):
+    """Abstract base for teleoperators backed by an Isaac Teleop ``TeleopSession``.
+
+    Owns the session lifecycle and the per-step health guard; subclasses supply
+    :meth:`_build_pipeline` and :meth:`get_action`.
+    """
+
+    config_class = IsaacTeleopConfig
+
+    def __init__(self, config: IsaacTeleopConfig):
+        _require_isaacteleop()
+        super().__init__(config)
+        self.config: IsaacTeleopConfig = config
+        self._session: TeleopSession | None = None
+        self._cloudxr_launcher: CloudXRLauncher | None = None
+
+    # ------------------------------------------------------------------
+    # Pipeline construction (device override point)
+    # ------------------------------------------------------------------
+
+    @abc.abstractmethod
+    def _build_pipeline(self) -> GraphExecutable:
+        """Build this device's retargeting pipeline (the ``GraphExecutable`` for
+        ``TeleopSessionConfig.pipeline``). Called once in :meth:`connect`; its output
+        keys must match what :meth:`get_action` unpacks.
+        """
+        raise NotImplementedError
+
+    # ------------------------------------------------------------------
+    # Lifecycle (shared)
+    # ------------------------------------------------------------------
+
+    @property
+    def is_connected(self) -> bool:
+        return self._session is not None
+
+    @property
+    def is_calibrated(self) -> bool:
+        return True  # Tracking devices are self-calibrating.
+
+    def calibrate(self) -> None:
+        pass
+
+    def configure(self) -> None:
+        pass
+
+    def connect(self, calibrate: bool = True) -> None:
+        """Auto-launch the CloudXR runtime (unless opted out) and open the session.
+
+        The CloudXR launch blocks ~30s and, on the first run, prompts on stdin for the
+        EULA (accept once via ``python -m isaacteleop.cloudxr --accept-eula``). Opt out
+        when CloudXR runs externally via ``config.auto_launch_cloudxr=False`` or
+        ``LEROBOT_CLOUDXR_SKIP_AUTOLAUNCH=1`` (env var wins).
+        """
+        if self._session is not None:
+            raise RuntimeError("Already connected. Call disconnect() first.")
+
+        self._ensure_cloudxr_runtime()
+
+        try:
+            pipeline = self._build_pipeline()
+            session_config = TeleopSessionConfig(app_name=self.config.app_name, pipeline=pipeline)
+            self._session = TeleopSession(session_config)
+            self._session.__enter__()
+        except Exception:
+            self._session = None
+            try:
+                self._stop_cloudxr_runtime()
+            except Exception:
+                logger.exception("Failed to stop CloudXR runtime during connect() rollback")
+            raise
+        logger.info("Isaac Teleop session started: %s", self.config.app_name)
+
+    def disconnect(self) -> None:
+        try:
+            if self._session is not None:
+                # Null the handle BEFORE __exit__: even a failed session teardown must not
+                # wedge the device as is_connected (blocking every later connect/disconnect).
+                session = self._session
+                self._session = None
+                session.__exit__(None, None, None)
+                logger.info("Isaac Teleop session ended")
+        finally:
+            # Reap the CloudXR runtime even if session teardown raised, and even if no
+            # session was ever established (e.g. the launcher came up but session creation
+            # failed before this point); a no-op when we never launched CloudXR (opt-out /
+            # externally-owned runtime), so we never stop a runtime we don't own.
+            self._stop_cloudxr_runtime()
+
+    # ------------------------------------------------------------------
+    # CloudXR runtime (shared)
+    # ------------------------------------------------------------------
+
+    def _ensure_cloudxr_runtime(self) -> None:
+        """Auto-launch the CloudXR runtime once, unless opted out.
+
+        Idempotent (no-op once the launcher is up). ``LEROBOT_CLOUDXR_SKIP_AUTOLAUNCH``
+        is checked first and wins over ``config.auto_launch_cloudxr``. Constructing
+        :class:`CloudXRLauncher` mutates the process env (``XR_RUNTIME_JSON`` etc.) and
+        blocks until the runtime is ready or raises :class:`RuntimeError`.
+        """
+        if self._cloudxr_launcher is not None:
+            return
+
+        if os.environ.get("LEROBOT_CLOUDXR_SKIP_AUTOLAUNCH", "").strip() == "1":
+            logger.info(
+                "LEROBOT_CLOUDXR_SKIP_AUTOLAUNCH=1 set; skipping CloudXR auto-launch "
+                "(assuming CloudXR is already running externally)"
+            )
+            return
+
+        if not self.config.auto_launch_cloudxr:
+            logger.info(
+                "config.auto_launch_cloudxr is False; skipping CloudXR auto-launch "
+                "(assuming CloudXR is already running externally)"
+            )
+            return
+
+        logger.info("Launching CloudXR runtime (first run may prompt for EULA and take ~30s)...")
+
+        self._cloudxr_launcher = CloudXRLauncher(
+            install_dir=str(Path.home() / ".cloudxr"),
+            env_config=self.config.cloudxr_env_file,
+            accept_eula=False,
+        )
+
+    def _stop_cloudxr_runtime(self) -> None:
+        """Stop the auto-launched CloudXR runtime, if any.
+
+        Clean stop nulls the handle. On :class:`RuntimeError` the handle is RETAINED so
+        the launcher's ``atexit`` hook owns the retry — a later :meth:`connect` then
+        treats the retained runtime as still up and will not relaunch.
+        """
+        if self._cloudxr_launcher is None:
+            return
+        try:
+            self._cloudxr_launcher.stop()
+        except RuntimeError:
+            logger.warning("CloudXR runtime could not be terminated; handle retained for atexit cleanup")
+        else:
+            self._cloudxr_launcher = None
+            logger.info("CloudXR runtime stopped")
+
+    def send_feedback(self, feedback: dict[str, Any]) -> None:
+        pass  # Haptic feedback not yet implemented.
+
+    # ------------------------------------------------------------------
+    # Stepping (shared)
+    # ------------------------------------------------------------------
+
+    def _running_events(self) -> ExecutionEvents:
+        """Constant ``RUNNING`` ``ExecutionEvents`` for a device with no clutch lifecycle.
+
+        Keeps the stream flowing; ``reset`` stays ``False``. A clutched device that needs
+        a real lifecycle should build its own ``ExecutionEvents`` instead.
+        """
+        return ExecutionEvents(execution_state=ExecutionState.RUNNING, reset=False)
+
+    def _step(
+        self,
+        *,
+        execution_events: ExecutionEvents | None = None,
+        external_inputs: Mapping[str, Any] | None = None,
+    ) -> RetargeterIO:
+        """Step the session once and return the raw pipeline outputs.
+
+        Applies the shared guard: re-raises a retargeting-worker exception and warns on a
+        stale frame. Subclasses call this from :meth:`get_action`.
+
+        Args:
+            execution_events: The ``ExecutionEvents`` driving the session this frame.
+                Devices with a lifecycle (clutch) MUST pass this every frame — when
+                ``None``, ``TeleopSession.step`` auto-fires ``RUNNING`` (the clutch would
+                latch immediately and never stop).
+            external_inputs: Per-step inputs (e.g. a static ``base_T_anchor``) in the
+                ``{leaf_node_name: {output_port_name: TensorGroup}}`` shape ``step`` expects.
+
+        Raises:
+            RuntimeError: If not connected, or if the retargeting worker raised.
+        """
+        if self._session is None:
+            raise RuntimeError("Not connected. Call connect() first.")
+
+        result = self._session.step(
+            execution_events=execution_events,
+            external_inputs=external_inputs,
+        )
+
+        info = self._session.last_step_info
+        if info is not None:
+            if info.worker_exception is not None:
+                raise RuntimeError(
+                    "Isaac Teleop retargeting worker raised an exception"
+                ) from info.worker_exception
+            if info.frame_deadline_miss:
+                logger.warning(
+                    "Isaac Teleop frame deadline miss (returned_age_frames=%s)",
+                    info.returned_age_frames,
+                )
+        return result

examples/isaac_teleop_to_so101/isaac_teleop/clutch.py

@@ -0,0 +1,102 @@
+#!/usr/bin/env python
+
+# Copyright 2026 NVIDIA Corporation and The HuggingFace Inc. team. All rights reserved.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""Engage-relative clutch for the XR -> SO-101 teleop loop.
+
+Turns the raw controller grip pose into an absolute base-frame EE target, so the XR
+device can stay a thin raw-pose reader. Pure numpy + the local ``Rotation`` helper (no
+``isaacteleop``), so it is unit-testable without the XR runtime.
+"""
+
+from __future__ import annotations
+
+import numpy as np
+
+from lerobot.utils.rotation import Rotation
+
+
+class Clutch:
+    """Engage-relative clutch for both position AND orientation.
+
+    Latch an origin on engage, then track the base-frame delta from it, applied
+    independently to position and orientation. State:
+
+    - ``_last_commanded_pos`` / ``_last_commanded_rot``: last commanded EE pose; held
+      while disengaged so the arm freezes where it was left.
+    - ``_home_pos`` / ``_home_rot``: latched on engage — the EE pose the delta applies to.
+      The position comes from the arm's MEASURED pose when the caller provides it (so an
+      arm that moved while disengaged is not snapped back to a stale command); the
+      orientation always comes from the last commanded rotation (see NOTE below).
+    - ``_origin_pos`` / ``_origin_rot``: latched on engage — the controller pose the delta
+      is measured against.
+
+    Each engaged frame :meth:`rebase` returns::
+
+        pos = home_pos + (grip_pos - origin_pos)  # 1:1 controller -> EE translation
+        rot = (R_ctrl @ R_origin ^ -1) @ R_home  # base-frame delta, left-composed
+
+    On the engage edge the output is exactly the home pose (no teleport). The orientation
+    delta is left-composed (base frame), so hand rotation about base Z maps to EE rotation
+    about base Z. A re-clutch latches a fresh home/origin.
+
+    NOTE: ``_home_rot`` is the last *commanded* orientation even when the measured pose is
+    supplied: the 5-DOF SO-101 tracks orientation only softly, so its measured wrist
+    orientation persistently differs from the command, and latching the measurement would
+    inject that offset into the commanded signal on every re-clutch. Position has no such
+    tracking gap, and there latching the measurement is what prevents the snap-back.
+    """
+
+    def __init__(self, home_base_T_ee: np.ndarray):  # noqa: N803
+        # Seed the held pose from the arm's measured startup EE pose so the first
+        # engage latches home there (no jump on the first squeeze).
+        home = np.asarray(home_base_T_ee, dtype=float)
+        self._last_commanded_pos = home[:3, 3].copy()
+        self._last_commanded_rot = Rotation.from_matrix(home[:3, :3])
+        self._home_pos = self._last_commanded_pos.copy()
+        self._home_rot = self._last_commanded_rot
+        self._origin_pos = np.zeros(3, dtype=float)
+        self._origin_rot = Rotation.from_quat(np.array([0.0, 0.0, 0.0, 1.0]))
+
+    def engage(
+        self,
+        grip_pos: np.ndarray,
+        grip_quat: np.ndarray,
+        measured_base_T_ee: np.ndarray | None = None,  # noqa: N803
+    ) -> None:
+        """Latch the engage home (where the arm is now) and controller origin.
+
+        Pass ``measured_base_T_ee`` (FK of the measured joints) so the home POSITION is
+        where the arm physically is — if the arm moved while disengaged (gravity sag,
+        external contact), latching the stale last-commanded position would make the
+        first engaged frame command a full-speed jump back to it. The home ORIENTATION
+        always stays the last commanded one (see the class NOTE).
+        """
+        if measured_base_T_ee is not None:
+            self._home_pos = np.asarray(measured_base_T_ee, dtype=float)[:3, 3].copy()
+        else:
+            self._home_pos = self._last_commanded_pos.copy()
+        self._home_rot = self._last_commanded_rot
+        self._origin_pos = np.asarray(grip_pos, dtype=float).copy()
+        self._origin_rot = Rotation.from_quat(np.asarray(grip_quat, dtype=float))
+
+    def rebase(self, grip_pos: np.ndarray, grip_quat: np.ndarray) -> tuple[np.ndarray, np.ndarray]:
+        """Return the absolute base-frame EE target ``(pos [m], quat [xyzw])`` for this frame."""
+        pos = self._home_pos + (np.asarray(grip_pos, dtype=float) - self._origin_pos)
+        rot_ctrl = Rotation.from_quat(np.asarray(grip_quat, dtype=float))
+        rot = (rot_ctrl * self._origin_rot.inv()) * self._home_rot
+        self._last_commanded_pos = pos.copy()
+        self._last_commanded_rot = rot
+        return pos, rot.as_quat()

examples/isaac_teleop_to_so101/isaac_teleop/config_isaac_teleop.py

@@ -0,0 +1,135 @@
+#!/usr/bin/env python
+
+# Copyright 2026 NVIDIA Corporation and The HuggingFace Inc. team. All rights reserved.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""Configuration dataclasses for NVIDIA Isaac Teleop-backed teleoperators.
+
+:class:`IsaacTeleopConfig` holds the shared fields; each device adds its own subclass
+(e.g. :class:`XRControllerConfig`, :class:`SO101LeaderArmConfig`).
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import ClassVar
+
+from lerobot.teleoperators.config import TeleoperatorConfig
+
+
+@dataclass(kw_only=True)
+class IsaacTeleopConfig(TeleoperatorConfig):
+    """Shared config for all Isaac Teleop-backed teleoperators.
+
+    Uses its own draccus ``_choice_registry`` (decoupled from the global
+    :class:`TeleoperatorConfig` one) so ``--teleop.type`` on a field typed
+    ``IsaacTeleopConfig`` resolves against ONLY the Isaac devices — letting them claim
+    short names (``xr_controller``, ``so101_leader``) without colliding with the global
+    registry. These devices are selected by the example scripts, not routed through
+    ``make_teleoperator_from_config``.
+    """
+
+    _choice_registry: ClassVar[dict] = {}
+
+    app_name: str = "LeTeleop"
+    """Application name for the OpenXR / Isaac Teleop session."""
+
+    auto_launch_cloudxr: bool = True
+    """Auto-launch the CloudXR runtime on :meth:`connect`. Set ``False`` (or export
+    ``LEROBOT_CLOUDXR_SKIP_AUTOLAUNCH=1``, which wins) when CloudXR runs externally.
+    """
+
+    cloudxr_env_file: str | None = None
+    """Optional CloudXR device-profile ``.env`` (an INPUT profile selecting the headset
+    transport) passed to ``CloudXRLauncher``. ``None`` keeps the default auto-WebRTC profile.
+    """
+
+
+# Static rebase from the OpenXR controller anchor frame (X=Right, Y=Up, Z=Backward) into the
+# robot base frame (X=Forward, Y=Left, Z=Up). A proper rotation (det=+1): controller motion
+# forward -> robot +X, right -> robot -Y (i.e. rightward), up -> robot +Z.
+_DEFAULT_BASE_T_ANCHOR: list[list[float]] = [
+    [0.0, 0.0, -1.0, 0.0],
+    [-1.0, 0.0, 0.0, 0.0],
+    [0.0, 1.0, 0.0, 0.0],
+    [0.0, 0.0, 0.0, 1.0],
+]
+
+
+@IsaacTeleopConfig.register_subclass("xr_controller")
+@dataclass(kw_only=True)
+class XRControllerConfig(IsaacTeleopConfig):
+    """Config for Isaac Teleop XR (VR) controller teleoperation.
+
+    Exposes the raw base-frame grip pose, squeeze, and trigger via ``ControllersSource``.
+    No retargeters: the clutch and gripper mapping live in the owning loop.
+    """
+
+    hand_side: str = "right"
+    """Which controller hand to use: ``"left"`` or ``"right"``. A plain ``str`` (validated in
+    ``__post_init__``) because draccus cannot decode ``Literal``-typed fields from the CLI."""
+
+    clutch_threshold: float = 0.5
+    """Squeeze value above which the owning loop's clutch engages (held-to-enable). The
+    device reports only the raw squeeze; the threshold is applied by the loop."""
+
+    base_T_anchor: list[list[float]] = field(  # noqa: N815  (frameA_T_frameB transform-matrix convention)
+        # Fresh copy per instance: returning the module-level list itself would alias one
+        # mutable matrix across every config.
+        default_factory=lambda: [row.copy() for row in _DEFAULT_BASE_T_ANCHOR]
+    )
+    """Static 4x4 [row-major] transform rebasing the OpenXR controller anchor frame into
+    the robot base frame. Defaults to OpenXR (X=Right, Y=Up, Z=Backward) -> robot
+    (X=Forward, Y=Left, Z=Up). Plain nested lists so the config stays serializable.
+    """
+
+    def __post_init__(self):
+        if self.hand_side not in ("left", "right"):
+            raise ValueError(f"hand_side must be 'left' or 'right', got {self.hand_side!r}")
+
+
+# Provisional gripper open/close endpoints [rad], normalizing the streamed gripper angle
+# into the follower's RANGE_0_100 jaw target. Derived from the so101_leader plugin README's
+# example calibration (home_ticks=2048, range 2000..3000; angle = (ticks-home)*2*pi/4096).
+_DEFAULT_GRIPPER_OPEN_RAD = -0.074
+_DEFAULT_GRIPPER_CLOSE_RAD = 1.460
+
+
+@IsaacTeleopConfig.register_subclass("so101_leader")
+@dataclass(kw_only=True)
+class SO101LeaderArmConfig(IsaacTeleopConfig):
+    """Config for an Isaac Teleop SO-101 *leader arm* (generic joint-space device).
+
+    Mirrors the leader's joint angles 1:1 onto a follower SO-101. The leader state is
+    streamed in radians by the native ``so101_leader`` plugin and read via a
+    ``JointStateSource``; the device converts arm joints to degrees and the gripper to the
+    follower's RANGE_0_100 jaw target (no IK/clutch/retargeter on the LeRobot side).
+    """
+
+    port: str = ""
+    """Serial port of the physical LEADER arm (e.g. ``/dev/ttyACM1``), forwarded to the
+    plugin (which reads the servos) when the example launches it. Empty -> the plugin runs
+    its synthetic trajectory."""
+
+    collection_id: str = "so101_leader"
+    """Tensor collection id the leader plugin pushes on; must match the running
+    ``so101_leader`` plugin (its second positional arg, default ``"so101_leader"``)."""
+
+    gripper_open_rad: float = _DEFAULT_GRIPPER_OPEN_RAD
+    """Leader gripper angle [rad] at fully OPEN -> follower jaw 100. Provisional default;
+    set from the plugin's ``calibrate`` subcommand. See ``_DEFAULT_GRIPPER_OPEN_RAD``."""
+
+    gripper_close_rad: float = _DEFAULT_GRIPPER_CLOSE_RAD
+    """Leader gripper angle [rad] at fully CLOSED -> follower jaw 0. Provisional default;
+    set from the plugin's ``calibrate`` subcommand. See ``_DEFAULT_GRIPPER_CLOSE_RAD``."""

examples/isaac_teleop_to_so101/isaac_teleop/teleop_so101_leader_arm.py

@@ -0,0 +1,186 @@
+#!/usr/bin/env python
+
+# Copyright 2026 NVIDIA Corporation and The HuggingFace Inc. team. All rights reserved.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""SO-101 leader-arm device for NVIDIA Isaac Teleop, exposed to LeRobot.
+
+The leader is a back-drivable SO-101 whose six joint angles are streamed (in radians) by
+the native ``so101_leader`` plugin; this device reads them via a ``JointStateSource`` and
+converts them into follower-ready ``{joint}.pos``. Same kinematics as the follower, so it
+needs no retargeting — a 1:1 joint mirror, direct joint drive.
+
+Units (converted in the device so the output is always follower-valid):
+
+* arm joints: ``rad2deg`` — correct only if the leader's calibrated zero and the follower's
+  homing map to the same physical zero (the standard same-hardware assumption).
+* gripper: normalized from ``[gripper_open_rad, gripper_close_rad]`` to RANGE_0_100.
+
+``isaacteleop`` imports are guarded behind the availability flag so this module — and the
+pure :func:`leader_joints_to_robot_action` converter — import without it (construction
+fails fast via the base class).
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+import numpy as np
+
+from lerobot.types import RobotAction
+
+from .base import _GRIPPER_MOTOR_SCALE, IsaacTeleopTeleoperator, _isaacteleop_available
+from .config_isaac_teleop import SO101LeaderArmConfig
+
+if TYPE_CHECKING or _isaacteleop_available:
+    from isaacteleop.retargeting_engine.deviceio_source_nodes import JointStateSource
+    from isaacteleop.retargeting_engine.interface import OutputCombiner
+else:
+    JointStateSource = None
+    OutputCombiner = None
+
+# Canonical SO-101 DOF names and order — matches the plugin stream and the follower's motor
+# order. Passed to the ``JointStateSource`` as its output layout; the source maps by name and
+# :func:`_joints_group_to_rad` reads back by name, so a layout mismatch can't mislabel a DOF.
+SO101_LEADER_JOINTS = [
+    "shoulder_pan",
+    "shoulder_lift",
+    "elbow_flex",
+    "wrist_flex",
+    "wrist_roll",
+    "gripper",
+]
+
+
+def leader_joints_to_robot_action(
+    joints_rad: dict[str, float],
+    *,
+    gripper_joint: str,
+    gripper_open_rad: float,
+    gripper_close_rad: float,
+) -> RobotAction:
+    """Convert streamed leader joint angles [rad] to follower-ready ``{joint}.pos``.
+
+    Pure (no ``isaacteleop``, no I/O). Iteration follows ``joints_rad`` insertion order, so
+    pass it in :data:`SO101_LEADER_JOINTS` order for a stable layout. Arm joints are
+    converted ``rad2deg``; ``gripper_joint`` is normalized from
+    ``[gripper_open_rad, gripper_close_rad]`` to RANGE_0_100 (clipped).
+    """
+    action: RobotAction = {}
+    span = gripper_close_rad - gripper_open_rad
+    for name, rad in joints_rad.items():
+        if name == gripper_joint:
+            # Closedness c=0 at open, c=1 at closed; invert to the follower's 100=open jaw.
+            closedness = 0.0 if span == 0.0 else (rad - gripper_open_rad) / span
+            closedness = min(1.0, max(0.0, closedness))
+            action[f"{name}.pos"] = (1.0 - closedness) * _GRIPPER_MOTOR_SCALE
+        else:
+            action[f"{name}.pos"] = float(np.rad2deg(rad))
+    return action
+
+
+def _joints_group_to_rad(joints) -> dict[str, float]:
+    """Read a ``JointStateSource`` output group into ``{joint_name: angle [rad]}``.
+
+    Pure (duck-typed on the group). The group is positional but each slot carries its joint
+    name in ``group.group_type.types``; we key off those names (not a positional index) so a
+    layout mismatch surfaces as a wrong/missing key here rather than a mislabeled DOF.
+    """
+    names = [t.name for t in joints.group_type.types]
+    return {name: float(joints[i]) for i, name in enumerate(names)}
+
+
+class SO101LeaderArm(IsaacTeleopTeleoperator):
+    """SO-101 leader-arm teleoperator (joint-space), direct joint mirror to the follower.
+
+    Reads the six joint angles off a single ``JointStateSource`` each frame; no retargeter,
+    no clutch. When the leader is not streaming, :meth:`get_action` returns the held-last
+    joints and :attr:`is_tracking` is ``False`` so the owning loop can hold the follower.
+    """
+
+    config_class = SO101LeaderArmConfig
+    name = "isaac_teleop_so101_leader"
+
+    def __init__(self, config: SO101LeaderArmConfig):
+        super().__init__(config)
+        self.config: SO101LeaderArmConfig = config
+        # Held-last joint angles [rad], seeded at zero (URDF/home pose) so the first frames
+        # before the plugin starts pushing read as the home pose, not garbage.
+        self._last_joints_rad: dict[str, float] = dict.fromkeys(SO101_LEADER_JOINTS, 0.0)
+        # Whether the most recent get_action() read live leader data (vs held-last).
+        self._is_tracking = False
+
+    # ------------------------------------------------------------------
+    # Pipeline construction
+    # ------------------------------------------------------------------
+
+    def _build_pipeline(self) -> OutputCombiner:
+        """Build the joint-mirror pipeline: a single ``JointStateSource`` leaf that converts
+        the raw stream into a name-keyed joint group. No retargeter (shared kinematics)."""
+        source = JointStateSource(
+            name="so101_leader",
+            collection_id=self.config.collection_id,
+            joint_names=SO101_LEADER_JOINTS,
+        )
+        return OutputCombiner({"joints": source.output(JointStateSource.JOINTS)})
+
+    # ------------------------------------------------------------------
+    # Action features
+    # ------------------------------------------------------------------
+
+    @property
+    def action_features(self) -> dict[str, type]:
+        # Matches the serial SOLeader's action features so this is a drop-in joint-space
+        # leader: one float `{joint}.pos` per DOF, sendable straight to an SO-101 follower.
+        return {f"{name}.pos": float for name in SO101_LEADER_JOINTS}
+
+    @property
+    def feedback_features(self) -> dict[str, type]:
+        return {}
+
+    @property
+    def is_tracking(self) -> bool:
+        """Whether the last :meth:`get_action` read live leader data (vs held-last)."""
+        return self._is_tracking
+
+    # ------------------------------------------------------------------
+    # Action extraction
+    # ------------------------------------------------------------------
+
+    def get_action(self) -> RobotAction:
+        """Step the session and return the leader joints as follower-ready ``{joint}.pos``.
+
+        When the leader is streaming, the live angles are cached and converted; otherwise the
+        held-last angles are reused and :attr:`is_tracking` is set ``False``.
+        """
+        result = self._step(execution_events=self._running_events())
+
+        joints = result["joints"]
+        # The JointStateSource output is Optional: absent (is_none) when the device is
+        # inactive. Treat that as "not tracking" and reuse the held-last angles.
+        self._is_tracking = not getattr(joints, "is_none", False)
+        if self._is_tracking:
+            try:
+                self._last_joints_rad = _joints_group_to_rad(joints)
+            except (AttributeError, IndexError, KeyError, TypeError, ValueError):
+                # A partially-populated / malformed group on an odd frame: keep held-last, but
+                # report it as not-tracking so the loop holds the follower rather than trusting it.
+                self._is_tracking = False
+
+        return leader_joints_to_robot_action(
+            self._last_joints_rad,
+            gripper_joint="gripper",
+            gripper_open_rad=self.config.gripper_open_rad,
+            gripper_close_rad=self.config.gripper_close_rad,
+        )

examples/isaac_teleop_to_so101/isaac_teleop/teleop_xr_controller.py

@@ -0,0 +1,204 @@
+#!/usr/bin/env python
+
+# Copyright 2026 NVIDIA Corporation and The HuggingFace Inc. team. All rights reserved.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""XR (VR) controller device for NVIDIA Isaac Teleop, exposed to LeRobot.
+
+A deliberately thin reader: exposes the raw controller grip pose off
+``ControllersSource`` (statically rebased into the robot base frame by
+``ControllerTransform``), plus squeeze and trigger. No retargeters and no clutch —
+the clutch rebasing and gripper mapping live downstream in the owning loop, so this
+device is stateless across frames.
+
+``isaacteleop`` imports are guarded behind the availability flag so this module imports
+without it (construction fails fast via the base class).
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any
+
+import numpy as np
+
+from lerobot.types import RobotAction
+
+from .base import IsaacTeleopTeleoperator, _isaacteleop_available
+from .config_isaac_teleop import XRControllerConfig
+
+if TYPE_CHECKING or _isaacteleop_available:
+    from isaacteleop.retargeting_engine.deviceio_source_nodes import ControllersSource
+    from isaacteleop.retargeting_engine.interface import OutputCombiner, TensorGroup, ValueInput
+    from isaacteleop.retargeting_engine.tensor_types import TransformMatrix
+    from isaacteleop.retargeting_engine.tensor_types.indices import ControllerInputIndex
+else:
+    ControllersSource = None
+    OutputCombiner = None
+    TensorGroup = None
+    ValueInput = None
+    TransformMatrix = None
+    ControllerInputIndex = None
+
+# Source-node name for the static base_T_anchor rebase input fed via
+# ``TeleopSession.step(external_inputs=...)`` each frame.
+_BASE_T_ANCHOR_INPUT = "base_T_anchor"
+
+
+class XRController(IsaacTeleopTeleoperator):
+    """Raw XR controller grip-pose teleoperator (base-frame), no retargeters.
+
+    Reads the raw grip pose + squeeze + trigger off a ``ControllersSource`` rebased into
+    the robot base frame. :meth:`get_action` returns the absolute base-frame grip pose
+    untouched; the owning loop owns the clutch and gripper mapping.
+    """
+
+    config_class = XRControllerConfig
+    name = "isaac_teleop_controller"
+
+    def __init__(self, config: XRControllerConfig):
+        super().__init__(config)
+        self.config: XRControllerConfig = config
+
+        # Constant base_T_anchor input, built once in connect() (a TensorGroup is heavy and
+        # isaacteleop-backed) and reused every step.
+        self._external_inputs: dict[str, Any] | None = None
+        # Whether the last get_action() read a tracked controller; the owning loop polls this
+        # to wait for the operator to connect before driving the arm.
+        self._is_tracking = False
+
+    # ------------------------------------------------------------------
+    # Pipeline construction
+    # ------------------------------------------------------------------
+
+    def _build_pipeline(self) -> OutputCombiner:
+        """Build the raw-grip-pose pipeline: a ``ControllersSource`` rebased into the base
+        frame by ``ControllerTransform``, exposed verbatim as ``"controller"``. No retargeters.
+        """
+        side = self.config.hand_side
+        controller_key = f"controller_{side}"
+
+        controllers = ControllersSource(name="controllers")
+        # Static base_T_anchor rebase fed via external_inputs each step.
+        xform = ValueInput(_BASE_T_ANCHOR_INPUT, TransformMatrix())
+        transformed = controllers.transformed(xform.output("value"))
+        ctrl = transformed.output(controller_key)
+
+        return OutputCombiner({"controller": ctrl})
+
+    def _build_external_inputs(self) -> dict[str, Any]:
+        """Materialize the constant ``base_T_anchor`` external input (once, in connect)."""
+        tg = TensorGroup(TransformMatrix())
+        tg[0] = np.asarray(self.config.base_T_anchor, dtype=np.float32)
+        return {_BASE_T_ANCHOR_INPUT: {"value": tg}}
+
+    def connect(self, calibrate: bool = True) -> None:
+        super().connect(calibrate=calibrate)
+        try:
+            self._external_inputs = self._build_external_inputs()
+        except Exception:
+            # Roll the session/runtime back so a failed connect() leaves no half-state
+            # (a live session behind a raised connect would leak the CloudXR runtime).
+            self.disconnect()
+            raise
+
+    # ------------------------------------------------------------------
+    # Action features
+    # ------------------------------------------------------------------
+
+    @property
+    def action_features(self) -> dict:
+        return {
+            "grip_pos": {
+                "dtype": "float32",
+                "shape": (3,),
+                "names": {"x": 0, "y": 1, "z": 2},
+            },
+            "grip_quat": {
+                "dtype": "float32",
+                "shape": (4,),
+                "names": {"qx": 0, "qy": 1, "qz": 2, "qw": 3},
+            },
+            # ``get_action`` returns scalars for these two, so the advertised
+            # shape is () (0-d) to stay consistent with the returned values.
+            "squeeze": {
+                "dtype": "float32",
+                "shape": (),
+                "names": None,
+            },
+            "trigger": {
+                "dtype": "float32",
+                "shape": (),
+                "names": None,
+            },
+        }
+
+    @property
+    def feedback_features(self) -> dict:
+        return {}
+
+    @property
+    def is_tracking(self) -> bool:
+        """Whether the last :meth:`get_action` read a tracked controller. ``False`` until the
+        headset is connected over CloudXR and its controllers are live; the owning loop polls
+        it to wait for the operator before commanding the arm."""
+        return self._is_tracking
+
+    # ------------------------------------------------------------------
+    # Action extraction
+    # ------------------------------------------------------------------
+
+    def get_action(self) -> RobotAction:
+        """Step the session and return the raw base-frame grip pose.
+
+        Reads the grip pose + squeeze + trigger off the transformed controller stream (with
+        the constant ``base_T_anchor`` rebase). When the controller is not tracked, returns
+        identity pose and squeeze/trigger = 0.0 so the owning loop freezes the arm.
+
+        Returns:
+            ``{"grip_pos": (3,) [m], "grip_quat": (4,) [qx,qy,qz,qw], "squeeze": float,
+            "trigger": float}`` — pose in the robot base frame; squeeze/trigger in ``[0, 1]``.
+        """
+        result = self._step(execution_events=self._running_events(), external_inputs=self._external_inputs)
+
+        # Optional controller group is None until the headset is connected and its controllers
+        # are live; expose that as is_tracking so the loop can wait before driving the arm.
+        controller = result["controller"]
+        grip_pos = np.zeros(3, dtype=np.float32)
+        grip_quat = np.array([0.0, 0.0, 0.0, 1.0], dtype=np.float32)
+        squeeze = 0.0
+        trigger = 0.0
+        self._is_tracking = not getattr(controller, "is_none", False)
+        if self._is_tracking:
+            # Read ALL four fields into locals before committing any of them: a failure on a
+            # partially-populated frame must not mix live values with the safe defaults (a
+            # live squeeze paired with a defaulted trigger=0.0 would keep the clutch engaged
+            # while commanding the gripper fully open, dropping whatever is grasped). On
+            # failure the defaults stand untouched and the frame reports not-tracked.
+            try:
+                pos = np.asarray(controller[ControllerInputIndex.GRIP_POSITION], dtype=np.float32)
+                quat = np.asarray(controller[ControllerInputIndex.GRIP_ORIENTATION], dtype=np.float32)
+                squeeze_val = float(controller[ControllerInputIndex.SQUEEZE_VALUE])
+                trigger_val = float(controller[ControllerInputIndex.TRIGGER_VALUE])
+            except (IndexError, KeyError, TypeError, ValueError):
+                self._is_tracking = False
+            else:
+                grip_pos, grip_quat = pos, quat
+                squeeze, trigger = squeeze_val, trigger_val
+
+        return {
+            "grip_pos": grip_pos,
+            "grip_quat": grip_quat,
+            "squeeze": squeeze,
+            "trigger": trigger,
+        }

examples/isaac_teleop_to_so101/isaac_teleop/xr_controller_processor.py

@@ -0,0 +1,87 @@
+#!/usr/bin/env python
+
+# Copyright 2026 NVIDIA Corporation and The HuggingFace Inc. team. All rights reserved.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""Processor step that maps XR controller actions to robot EE targets.
+
+Analogous to ``MapPhoneActionToRobotAction``, this bridges the clutch-rebased EE pose to
+the IK pipeline's input contract (``EEBoundsAndSafety`` -> ``InverseKinematicsEEToJoints``).
+Pure (no ``isaacteleop``), so it is unit-testable without the XR runtime.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from lerobot.configs.types import FeatureType, PipelineFeatureType, PolicyFeature
+from lerobot.processor import ProcessorStepRegistry, RobotActionProcessorStep
+from lerobot.types import RobotAction
+from lerobot.utils.rotation import Rotation
+
+from .base import _GRIPPER_MOTOR_SCALE
+
+
+@ProcessorStepRegistry.register("map_xr_controller_action_to_robot_action")
+@dataclass
+class MapXRControllerActionToRobotAction(RobotActionProcessorStep):
+    """Maps an absolute base-frame EE pose + gripper closedness to the IK input contract.
+
+    Pure, stateless rename (the owning loop's clutch already produced the absolute base-frame
+    target). Each frame it writes:
+
+    - ``ee.x/y/z`` = ``ee_pose[:3]`` (position [m]);
+    - ``ee.wx/wy/wz`` = rotvec of ``ee_pose[3:7]`` (orientation; the IK tracks it softly at a
+      small ``orientation_weight`` on the 5-DOF SO-101);
+    - ``ee.gripper_pos`` = ``(1 - closedness) * _GRIPPER_MOTOR_SCALE`` (jaw target [0, 100],
+      RANGE_0_100 where 100 = open, so closedness is inverted).
+
+    Input keys: ``ee_pose`` ``(7,)`` ``[x,y,z,qx,qy,qz,qw]``, ``closedness`` float in [0, 1].
+    """
+
+    def action(self, action: RobotAction) -> RobotAction:
+        ee_pose = action.pop("ee_pose")
+        closedness = float(action.pop("closedness"))
+
+        action["ee.x"] = float(ee_pose[0])
+        action["ee.y"] = float(ee_pose[1])
+        action["ee.z"] = float(ee_pose[2])
+        # Orientation target as a rotvec (quat [qx,qy,qz,qw] -> axis-angle); the IK
+        # consumes ee.w* as a rotvec and tracks it with orientation_weight.
+        rotvec = Rotation.from_quat(ee_pose[3:7]).as_rotvec()
+        action["ee.wx"] = float(rotvec[0])
+        action["ee.wy"] = float(rotvec[1])
+        action["ee.wz"] = float(rotvec[2])
+        # Inverted: closedness c=1 (closed) -> 0, c=0 (open) -> 100 (SO-101 calibration).
+        action["ee.gripper_pos"] = (1.0 - closedness) * _GRIPPER_MOTOR_SCALE
+        return action
+
+    def transform_features(
+        self, features: dict[PipelineFeatureType, dict[str, PolicyFeature]]
+    ) -> dict[PipelineFeatureType, dict[str, PolicyFeature]]:
+        for feat in ["ee_pose", "closedness"]:
+            features[PipelineFeatureType.ACTION].pop(feat, None)
+
+        for feat in [
+            "ee.x",
+            "ee.y",
+            "ee.z",
+            "ee.wx",
+            "ee.wy",
+            "ee.wz",
+            "ee.gripper_pos",
+        ]:
+            features[PipelineFeatureType.ACTION][feat] = PolicyFeature(type=FeatureType.ACTION, shape=(1,))
+
+        return features

examples/isaac_teleop_to_so101/override_reset_pose.py

@@ -0,0 +1,73 @@
+#!/usr/bin/env python
+
+# Copyright 2026 NVIDIA Corporation and The HuggingFace Inc. team. All rights reserved.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""Save the current SO-101 joint positions as the reset-origin pose (override).
+
+Move the arm to the desired reset pose by hand (torque off), then run this script to write
+those joints to a per-arm file in the LeRobot cache. ``teleoperate.py`` / ``record.py`` load
+it on startup (matched by ``--robot.id``) as the reset target instead of the defaults.
+
+Usage::
+
+    # 1. Move arm to desired reset pose by hand
+    python -m examples.isaac_teleop_to_so101.override_reset_pose [--port /dev/ttyACM0] [--id so101_follower_arm]
+
+    # 2. Launch teleop with the SAME --robot.id — it will now reset to this pose on startup
+    python -m examples.isaac_teleop_to_so101.teleoperate --robot.type=so101_follower --robot.port=/dev/ttyACM0 --robot.id=so101_follower_arm --teleop.type=xr_controller
+"""
+
+import argparse
+import json
+from pathlib import Path
+
+from lerobot.robots.so_follower import SO100Follower, SO100FollowerConfig
+
+from .common import RESET_POSE_FILE
+
+
+def parse_args():
+    parser = argparse.ArgumentParser(
+        description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter
+    )
+    parser.add_argument("--port", type=str, default="/dev/ttyACM0")
+    parser.add_argument("--id", type=str, default="so101_follower_arm")
+    return parser.parse_args()
+
+
+def main():
+    args = parse_args()
+    robot = SO100Follower(SO100FollowerConfig(port=args.port, id=args.id, use_degrees=True))
+    robot.connect()
+    # Always disconnect the follower so a failure never leaks the serial connection.
+    try:
+        obs = robot.get_observation()
+        motor_names = list(robot.bus.motors.keys())
+        pose = {name: float(obs[f"{name}.pos"]) for name in motor_names}
+    finally:
+        robot.disconnect()
+
+    print("Current joint positions:")
+    for name, val in pose.items():
+        print(f"  {name:20s}: {val:.2f}")
+
+    reset_pose_file = Path(RESET_POSE_FILE.format(robot_name=robot.name, robot_id=robot.id))
+    reset_pose_file.parent.mkdir(parents=True, exist_ok=True)
+    reset_pose_file.write_text(json.dumps(pose, indent=2))
+    print(f"\nSaved to {reset_pose_file}")
+
+
+if __name__ == "__main__":
+    main()

examples/isaac_teleop_to_so101/record.py

@@ -0,0 +1,321 @@
+#!/usr/bin/env python
+
+# Copyright 2026 NVIDIA Corporation and The HuggingFace Inc. team. All rights reserved.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""Record a LeRobot dataset via NVIDIA Isaac Teleop -> SO-101.
+
+Runs ``teleoperate.py``'s control loop while also saving each frame to a LeRobot dataset.
+``--teleop.type`` selects the device (``xr_controller`` | ``so101_leader``) as in
+``teleoperate.py``.
+
+Usage::
+
+    # XR (VR) controller: clutch + soft-orientation IK
+    python -m examples.isaac_teleop_to_so101.record \\
+        --robot.type=so101_follower \\
+        --robot.port=/dev/ttyACM0 \\
+        --robot.id=so101_follower_arm \\
+        --teleop.type=xr_controller \\
+        --robot.cameras="{ front: {type: opencv, index_or_path: 0, width: 640, height: 480, fps: 30}}" \\
+        --dataset.repo_id=<hf_user>/<dataset_name> \\
+        --dataset.single_task="Pick up vial from rack on the left side" \\
+        --dataset.num_episodes=3 \\
+        --dataset.episode_time_s=20 \\
+        --dataset.reset_time_s=5
+
+    # SO-101 leader arm: 1:1 joint mirror (real leader on /dev/ttyACM1)
+    python -m examples.isaac_teleop_to_so101.record \\
+        --robot.type=so101_follower --robot.port=/dev/ttyACM0 --robot.id=so101_follower_arm \\
+        --teleop.type=so101_leader --teleop.port=/dev/ttyACM1 --teleop.id=so101_leader_arm \\
+        --launch_plugin=/path/to/IsaacTeleop/install/plugins/so101_leader/so101_leader_plugin \\
+        --dataset.repo_id=<hf_user>/<dataset_name> --dataset.single_task="Pick up the cube" \\
+        --dataset.num_episodes=3 --dataset.episode_time_s=20 --dataset.reset_time_s=5
+
+The loop/launch knobs mirror ``teleoperate.py`` (tagged ``[xr]`` / ``[leader]`` below).
+
+Keyboard shortcuts: Right/n = end episode early and save, Left/r = discard + re-record,
+Esc/q = stop after the current episode. All frames are recorded (including hold frames).
+"""
+
+import logging
+import time
+from dataclasses import asdict, dataclass
+from pprint import pformat
+
+from lerobot.cameras import CameraConfig  # noqa: F401
+from lerobot.cameras.opencv import OpenCVCameraConfig  # noqa: F401
+from lerobot.common.control_utils import sanity_check_dataset_robot_compatibility
+from lerobot.configs import parser
+from lerobot.configs.dataset import DatasetRecordConfig
+from lerobot.datasets import (
+    LeRobotDataset,
+    VideoEncodingManager,
+    aggregate_pipeline_dataset_features,
+    create_initial_features,
+    safe_stop_image_writer,
+)
+from lerobot.processor import make_default_processors
+from lerobot.robots import RobotConfig
+from lerobot.robots.so_follower import SOFollowerConfig  # noqa: F401  (registers so101_follower)
+from lerobot.utils.constants import ACTION, OBS_STR
+from lerobot.utils.feature_utils import build_dataset_frame, combine_feature_dicts
+from lerobot.utils.robot_utils import precise_sleep
+from lerobot.utils.utils import init_logging
+
+from .common import (
+    ALIGN_DURATION_S,
+    RESET_DURATION_S,
+    Device,
+    HoldLatch,
+    build_device,
+    init_keyboard_listener,
+)
+from .isaac_teleop import IsaacTeleopConfig
+
+
+@dataclass
+class RecordConfig:
+    """CLI config for Isaac Teleop -> SO-101 dataset recording.
+
+    ``--robot.*`` / ``--teleop.*`` / ``--dataset.*`` configure the follower, device, and
+    recording; the loop/launch knobs below carry the same ``[xr]`` / ``[leader]`` tags as
+    ``teleoperate.py``. Use ``--flag=false`` for booleans (draccus style).
+    """
+
+    robot: RobotConfig
+    # --teleop.type=xr_controller|so101_leader, resolved against IsaacTeleopConfig's registry.
+    teleop: IsaacTeleopConfig
+    dataset: DatasetRecordConfig
+
+    # [leader] Path to the so101_leader plugin binary to spawn after CloudXR is up (it then
+    # inherits the runtime env). None (default) -> assume the plugin already runs externally.
+    launch_plugin: str | None = None
+
+    # [xr] Slew all joints to the reset pose before the first episode (--reset_to_origin=false to
+    # keep the arm where it is). After the slew the clutch seeds its home from the measured pose.
+    reset_to_origin: bool = True
+    # [xr] Duration [s] of the reset-to-origin slew (passed through to setup_xr).
+    reset_duration: float = RESET_DURATION_S
+
+    # [leader] Slew the follower to the leader's first pose before mirroring (--align=false to
+    # begin the 1:1 mirror immediately; the follower may snap).
+    align: bool = True
+    # [leader] Duration [s] of the startup alignment slew.
+    align_duration: float = ALIGN_DURATION_S
+
+    # Resume recording on an existing (previously interrupted) dataset.
+    resume: bool = False
+
+
+@safe_stop_image_writer
+def _record_loop(
+    robot,
+    device: Device,
+    motor_names: list[str],
+    events: dict,
+    fps: int,
+    dataset: LeRobotDataset | None = None,
+    control_time_s: float = 0.0,
+    single_task: str | None = None,
+) -> None:
+    """Run one episode (or reset phase) of the control loop.
+
+    When ``dataset`` is None the loop still controls the robot (so the operator
+    can reposition the arm during the reset window) but does not record frames.
+    """
+    control_interval = 1.0 / fps
+    timestamp = 0.0
+    start_t = time.perf_counter()
+    record_frames = dataset is not None
+    hold = HoldLatch(motor_names)
+
+    while timestamp < control_time_s:
+        loop_start = time.perf_counter()
+
+        if events["exit_early"]:
+            events["exit_early"] = False
+            break
+
+        obs = robot.get_observation()
+
+        if record_frames:
+            observation_frame = build_dataset_frame(dataset.features, obs, prefix=OBS_STR)
+
+        # Device idle (XR clutch disengaged, or leader stream stale) -> hold the pose
+        # latched on the active->idle edge.
+        action = hold.resolve(device.compute(obs), obs)
+
+        robot.send_action(action)
+
+        if record_frames:
+            action_frame = build_dataset_frame(dataset.features, action, prefix=ACTION)
+            dataset.add_frame({**observation_frame, **action_frame, "task": single_task})
+
+        dt_s = time.perf_counter() - loop_start
+        precise_sleep(max(control_interval - dt_s, 0.0))
+        timestamp = time.perf_counter() - start_t
+
+
+@parser.wrap()
+def record(cfg: RecordConfig) -> LeRobotDataset:
+    init_logging()
+    logging.info(pformat(asdict(cfg)))
+
+    # Connect the follower, build the selected Isaac device, and run its pre-loop startup
+    # (reset slew / leader align) — shared with teleoperate.py.
+    robot, device, motor_names = build_device(cfg)
+
+    # Build dataset feature spec.  The IK pipeline lives inside device.compute(), so the
+    # action features are exactly robot.action_features (joint positions in degrees).
+    teleop_proc, _, obs_proc = make_default_processors()
+    dataset_features = combine_feature_dicts(
+        aggregate_pipeline_dataset_features(
+            pipeline=teleop_proc,
+            initial_features=create_initial_features(action=robot.action_features),
+            use_videos=cfg.dataset.video,
+        ),
+        aggregate_pipeline_dataset_features(
+            pipeline=obs_proc,
+            initial_features=create_initial_features(observation=robot.observation_features),
+            use_videos=cfg.dataset.video,
+        ),
+    )
+
+    num_cameras = len(robot.cameras) if hasattr(robot, "cameras") else 0
+    image_writer_threads = cfg.dataset.num_image_writer_threads_per_camera * num_cameras
+
+    dataset: LeRobotDataset | None = None
+    listener = None
+    try:
+        if cfg.resume:
+            dataset = LeRobotDataset.resume(
+                cfg.dataset.repo_id,
+                root=cfg.dataset.root,
+                batch_encoding_size=cfg.dataset.video_encoding_batch_size,
+                rgb_encoder=cfg.dataset.rgb_encoder,
+                depth_encoder=cfg.dataset.depth_encoder,
+                encoder_threads=cfg.dataset.encoder_threads,
+                streaming_encoding=cfg.dataset.streaming_encoding,
+                encoder_queue_maxsize=cfg.dataset.encoder_queue_maxsize,
+                image_writer_processes=cfg.dataset.num_image_writer_processes if num_cameras > 0 else 0,
+                image_writer_threads=image_writer_threads if num_cameras > 0 else 0,
+            )
+            sanity_check_dataset_robot_compatibility(dataset, robot, cfg.dataset.fps, dataset_features)
+        else:
+            cfg.dataset.stamp_repo_id()
+            dataset = LeRobotDataset.create(
+                cfg.dataset.repo_id,
+                cfg.dataset.fps,
+                root=cfg.dataset.root,
+                robot_type=robot.name,
+                features=dataset_features,
+                use_videos=cfg.dataset.video,
+                image_writer_processes=cfg.dataset.num_image_writer_processes,
+                image_writer_threads=image_writer_threads,
+                batch_encoding_size=cfg.dataset.video_encoding_batch_size,
+                rgb_encoder=cfg.dataset.rgb_encoder,
+                depth_encoder=cfg.dataset.depth_encoder,
+                encoder_threads=cfg.dataset.encoder_threads,
+                streaming_encoding=cfg.dataset.streaming_encoding,
+                encoder_queue_maxsize=cfg.dataset.encoder_queue_maxsize,
+            )
+
+        listener, events = init_keyboard_listener()
+
+        loop_kwargs = {
+            "robot": robot,
+            "device": device,
+            "motor_names": motor_names,
+            "events": events,
+            "fps": cfg.dataset.fps,
+            "single_task": cfg.dataset.single_task,
+        }
+
+        with VideoEncodingManager(dataset):
+            recorded_episodes = 0
+            while recorded_episodes < cfg.dataset.num_episodes and not events["stop_recording"]:
+                logging.info(f"Recording episode {dataset.num_episodes}")
+                _record_loop(
+                    **loop_kwargs,
+                    dataset=dataset,
+                    control_time_s=cfg.dataset.episode_time_s,
+                )
+
+                # Reset window: give the operator time to reposition the scene.
+                # Skipped for the last episode (or if stop_recording was set).
+                if not events["stop_recording"] and (
+                    recorded_episodes < cfg.dataset.num_episodes - 1 or events["rerecord_episode"]
+                ):
+                    logging.info("Reset the environment")
+                    _record_loop(
+                        **loop_kwargs,
+                        dataset=None,
+                        control_time_s=cfg.dataset.reset_time_s,
+                    )
+
+                if events["rerecord_episode"]:
+                    logging.info("Re-record episode")
+                    events["rerecord_episode"] = False
+                    events["exit_early"] = False
+                    dataset.clear_episode_buffer()
+                    continue
+
+                dataset.save_episode()
+                recorded_episodes += 1
+
+    finally:
+        logging.info("Stop recording")
+
+        # Hardware teardown FIRST, each step guarded: the arm must be freed promptly (not
+        # after a potentially long finalize/encode), a cleanup failure must not skip the
+        # follower disconnect (which is what disables torque), and neither must prevent
+        # the dataset from being finalized below.
+        try:
+            device.cleanup()
+        except Exception:
+            logging.exception("Device cleanup failed")
+        try:
+            if robot.is_connected:
+                robot.disconnect()
+        except Exception:
+            logging.exception("Robot disconnect failed")
+
+        # Restore the terminal before the (potentially long) finalize/encode.
+        if listener is not None:
+            try:
+                listener.stop()
+            except Exception:
+                logging.exception("Keyboard listener stop failed")
+
+        if dataset is not None:
+            dataset.finalize()
+
+        if cfg.dataset.push_to_hub:
+            if dataset is not None and dataset.num_episodes > 0:
+                dataset.push_to_hub(tags=cfg.dataset.tags, private=cfg.dataset.private)
+            else:
+                logging.warning("No episodes saved — skipping push to hub")
+
+        logging.info("Exiting")
+
+    return dataset
+
+
+def main():
+    record()
+
+
+if __name__ == "__main__":
+    main()

examples/isaac_teleop_to_so101/teleoperate.py

@@ -0,0 +1,117 @@
+#!/usr/bin/env python
+
+# Copyright 2026 NVIDIA Corporation and The HuggingFace Inc. team. All rights reserved.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""Teleoperate an SO-101 follower arm via NVIDIA Isaac Teleop.
+
+``lerobot-teleoperate``-style CLI (draccus): ``--teleop.type`` selects the Isaac device
+(``xr_controller`` | ``so101_leader``), ``--robot.*`` the follower::
+
+    # XR (VR) controller: clutch + soft-orientation IK
+    python -m examples.isaac_teleop_to_so101.teleoperate --robot.type=so101_follower \
+        --robot.port=/dev/ttyACM0 --robot.id=so101_follower_arm --teleop.type=xr_controller
+
+    # SO-101 leader arm: 1:1 joint mirror (real leader on /dev/ttyACM1)
+    python -m examples.isaac_teleop_to_so101.teleoperate --robot.type=so101_follower \
+        --robot.port=/dev/ttyACM0 --robot.id=so101_follower_arm --teleop.type=so101_leader \
+        --teleop.port=/dev/ttyACM1 --teleop.id=so101_leader_arm \
+        --launch_plugin=/code/Teleop/install/plugins/so101_leader/so101_leader_plugin
+
+``--teleop.type`` resolves against the Isaac device registry (see :class:`IsaacTeleopConfig`),
+distinct from the serial ``so101_leader``. The pipelines, clutch/IK/align internals, and
+reset-pose behavior live in ``common.py``. Requires the ``isaacteleop`` package and an OpenXR
+runtime (install instructions in this folder's ``README.md``).
+"""
+
+import time
+from dataclasses import dataclass
+
+from lerobot.configs import parser
+from lerobot.robots import RobotConfig
+from lerobot.robots.so_follower import SOFollowerConfig  # noqa: F401  (registers so101_follower)
+from lerobot.utils.robot_utils import precise_sleep
+
+from .common import (
+    ALIGN_DURATION_S,
+    FPS,
+    RESET_DURATION_S,
+    HoldLatch,
+    build_device,
+)
+from .isaac_teleop import IsaacTeleopConfig
+
+
+@dataclass
+class TeleoperateConfig:
+    """``lerobot-teleoperate``-style CLI for the Isaac Teleop -> SO-101 example.
+
+    The fields below are the loop/launch knobs (not part of either device's config); the
+    ``[xr]`` / ``[leader]`` tags mark which device a knob applies to. Use ``--flag=false``
+    for booleans (draccus style).
+    """
+
+    # Isaac Teleop input device + its knobs (--teleop.type=xr_controller|so101_leader,
+    # then --teleop.<field>=...). Resolved against IsaacTeleopConfig's own choice registry.
+    teleop: IsaacTeleopConfig
+    # SO-101 FOLLOWER arm (--robot.type=so101_follower --robot.port=/dev/ttyACM0 --robot.id=...).
+    robot: RobotConfig
+
+    # [leader] Path to the so101_leader plugin binary to spawn AFTER CloudXR is up (it then
+    # inherits the runtime env). None (default) -> assume the plugin already runs externally.
+    # The leader's serial port is --teleop.port (forwarded to the plugin; empty -> synthetic).
+    launch_plugin: str | None = None
+
+    # [xr] Slew all joints to a default reset pose before the loop (--reset_to_origin=false to
+    # keep the arm where it is). After the slew the clutch seeds its home from the measured pose.
+    reset_to_origin: bool = True
+    # [xr] Duration [s] of the reset-to-origin slew.
+    reset_duration: float = RESET_DURATION_S
+
+    # [leader] Slew the follower to the leader's first pose before mirroring (--align=false to
+    # begin the 1:1 mirror immediately; the follower may snap).
+    align: bool = True
+    # [leader] Duration [s] of the startup alignment slew.
+    align_duration: float = ALIGN_DURATION_S
+
+
+@parser.wrap()
+def teleoperate(cfg: TeleoperateConfig):
+    robot, device, motor_names = build_device(cfg)
+    hold = HoldLatch(motor_names)
+    try:
+        while True:
+            t0 = time.perf_counter()
+            obs = robot.get_observation()
+            # Idle (compute() -> None) holds the pose latched on the active->idle edge.
+            action = hold.resolve(device.compute(obs), obs)
+            robot.send_action(action)
+            precise_sleep(max(1.0 / FPS - (time.perf_counter() - t0), 0.0))
+    except KeyboardInterrupt:
+        pass
+    finally:
+        # A failing device cleanup must not skip the follower disconnect (which is what
+        # disables torque on the arm).
+        try:
+            device.cleanup()
+        finally:
+            robot.disconnect()
+
+
+def main():
+    teleoperate()
+
+
+if __name__ == "__main__":
+    main()

examples/lekiwi/evaluate.py

@@ -17,7 +17,7 @@
 import logging
 import time
 
-from lerobot.common.control_utils import init_keyboard_listener, predict_action
+from lerobot.common.control_utils import predict_action
 from lerobot.datasets import LeRobotDataset
 from lerobot.policies import make_pre_post_processors
 from lerobot.policies.act import ACTPolicy
@@ -26,6 +26,7 @@ from lerobot.processor import make_default_processors
 from lerobot.robots.lekiwi import LeKiwiClient, LeKiwiClientConfig
 from lerobot.utils.constants import ACTION, OBS_STR
 from lerobot.utils.feature_utils import build_dataset_frame, hw_to_dataset_features
+from lerobot.utils.keyboard_input import init_keyboard_listener
 from lerobot.utils.robot_utils import precise_sleep
 from lerobot.utils.utils import log_say
 from lerobot.utils.visualization_utils import init_rerun, log_rerun_data

examples/lekiwi/record.py

@@ -14,7 +14,6 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
-from lerobot.common.control_utils import init_keyboard_listener
 from lerobot.datasets import LeRobotDataset
 from lerobot.processor import make_default_processors
 from lerobot.robots.lekiwi import LeKiwiClient, LeKiwiClientConfig
@@ -23,6 +22,7 @@ from lerobot.teleoperators.keyboard import KeyboardTeleop, KeyboardTeleopConfig
 from lerobot.teleoperators.so_leader import SO100Leader, SO100LeaderConfig
 from lerobot.utils.constants import ACTION, OBS_STR
 from lerobot.utils.feature_utils import hw_to_dataset_features
+from lerobot.utils.keyboard_input import init_keyboard_listener
 from lerobot.utils.utils import log_say
 from lerobot.utils.visualization_utils import init_rerun
 

examples/phone_to_so100/evaluate.py

@@ -18,7 +18,7 @@ import logging
 import time
 
 from lerobot.cameras.opencv import OpenCVCameraConfig
-from lerobot.common.control_utils import init_keyboard_listener, predict_action
+from lerobot.common.control_utils import predict_action
 from lerobot.configs import FeatureType, PolicyFeature
 from lerobot.datasets import LeRobotDataset, aggregate_pipeline_dataset_features, create_initial_features
 from lerobot.model.kinematics import RobotKinematics
@@ -41,6 +41,7 @@ from lerobot.robots.so_follower.robot_kinematic_processor import (
 from lerobot.types import RobotAction, RobotObservation
 from lerobot.utils.constants import ACTION, OBS_STR
 from lerobot.utils.feature_utils import build_dataset_frame, combine_feature_dicts
+from lerobot.utils.keyboard_input import init_keyboard_listener
 from lerobot.utils.robot_utils import precise_sleep
 from lerobot.utils.utils import log_say
 from lerobot.utils.visualization_utils import init_rerun, log_rerun_data

examples/phone_to_so100/record.py

@@ -15,7 +15,6 @@
 # limitations under the License.
 
 from lerobot.cameras.opencv import OpenCVCameraConfig
-from lerobot.common.control_utils import init_keyboard_listener
 from lerobot.datasets import LeRobotDataset, aggregate_pipeline_dataset_features, create_initial_features
 from lerobot.model.kinematics import RobotKinematics
 from lerobot.processor import (
@@ -39,6 +38,7 @@ from lerobot.teleoperators.phone.config_phone import PhoneOS
 from lerobot.teleoperators.phone.phone_processor import MapPhoneActionToRobotAction
 from lerobot.types import RobotAction, RobotObservation
 from lerobot.utils.feature_utils import combine_feature_dicts
+from lerobot.utils.keyboard_input import init_keyboard_listener
 from lerobot.utils.utils import log_say
 from lerobot.utils.visualization_utils import init_rerun
 

examples/policy_server/server.yaml

@@ -1,115 +0,0 @@
-# Copyright 2026 The HuggingFace Inc. team. All rights reserved.
-#
-# Licensed under the Apache License, Version 2.0 (the "License");
-# you may not use this file except in compliance with the License.
-# You may obtain a copy of the License at
-#
-#     http://www.apache.org/licenses/LICENSE-2.0
-#
-# Unless required by applicable law or agreed to in writing, software
-# distributed under the License is distributed on an "AS IS" BASIS,
-# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
-# See the License for the specific language governing permissions and
-# limitations under the License.
-
-# Example manifest for `lerobot-policy-server --manifest server.yaml`.
-#
-# One process = one (model, revision, dtype, device) on one GPU. Dynamic
-# model loading is deliberately unsupported: pre-warmed processes keep
-# capacity planning honest. Every field below can also be overridden on
-# the command line via draccus, e.g. --model.repo_or_path=... or
-# --zenoh.connect_endpoints='["tcp/other-router:7447"]'.
-#
-# Field names mirror the dataclasses in src/lerobot/policy_server/manifest.py.
-
-# --- Which policy this process serves, and where it runs ------------------
-model:
-  # Hub repo id (org/name) or a local checkpoint directory. Required.
-  repo_or_path: lerobot/pi0_towels
-  # Hub revision: branch, tag, or commit sha.
-  revision: main
-  # Optional torch dtype cast applied after load (e.g. "bfloat16",
-  # "float16"). null keeps the checkpoint's native dtype.
-  dtype: bfloat16
-  # Inference device, e.g. "cuda", "cuda:1", "cpu".
-  device: cuda
-
-# --- Task namespace --------------------------------------------------------
-# The task this service is published under. VLA clients may override the
-# task per session unless `pin_task` is true, in which case session opens
-# with a different task string are rejected.
-default_task: "fold the towel"
-pin_task: false
-# Optional override for the <task_slug> key segment of the Zenoh prefix
-# (defaults to a slug of `default_task`).
-service_name: ""
-
-# --- Serving mode & capacity ------------------------------------------------
-# "auto" resolves from the policy classification: shared for verified
-# chunk-stateless policies (act/pi0/pi05, smolvla with n_obs_steps=1),
-# exclusive otherwise. Chunk-stateful policies — e.g. diffusion, whose
-# predict_action_chunk reads select_action-fed queues — are always forced
-# to "exclusive" (max_sessions=1); "shared" cannot override that.
-serving_mode: auto
-
-# Capacity rule-of-thumb: with t = server seconds per inference, r = each
-# client's request rate (self-clocked to ~1-4 Hz, not the control rate),
-# H = RTC execution horizon, and dt = control period:
-#   max_sessions ~= min( 0.8 / (r*t),  (H*dt/2 - network RTT) / t )
-# e.g. ACT @ 20 ms, 1 Hz refresh -> ~40 clients/GPU; Pi0 @ 150 ms -> ~5.
-# Session opens beyond this are rejected with the current load in the
-# reply, so clients retry another replica.
-max_sessions: 5
-
-# Dummy inferences run at startup so the first real request does not pay
-# for CUDA graph/kernel warmup.
-warmup_inferences: 2
-
-# --- FPS contract -----------------------------------------------------------
-# Control rate the policy was trained at. Clients reporting a different
-# fps get a warning — or a hard reject when `strict_fps` is true.
-trained_fps: 30.0
-strict_fps: false
-
-# --- Real Time Chunking (RTC) -----------------------------------------------
-# Global to this process: init_rtc_processor mutates the policy instance,
-# so RTC is a per-process decision, not per-session. Only rtc-capable
-# families (pi0/pi05/smolvla) honor it; others are downgraded to plain
-# chunk-append at session open.
-rtc:
-  enabled: true
-  # Number of actions executed from each chunk before the next chunk is
-  # blended in (the H in the capacity formula above).
-  execution_horizon: 10
-
-# --- Housekeeping ------------------------------------------------------------
-# Sessions with no liveliness token and no traffic for this long are
-# garbage-collected (belt-and-braces behind liveliness GC).
-session_idle_timeout_s: 300.0
-
-# --- Transport ----------------------------------------------------------------
-# Robots and servers both *dial out* to a zenohd router in production
-# (mode: client). mode: peer + listen_endpoints supports router-less LAN
-# and loopback test deployments. Multicast scouting is always disabled:
-# fleet discovery is configuration, not protocol magic.
-zenoh:
-  mode: client
-  connect_endpoints:
-    - tcp/router.gpu-cluster.internal:7447
-  listen_endpoints: []
-  # mTLS material (PEM paths). All three are required for tls/ endpoints;
-  # leave them null for plain tcp/ inside a trusted network.
-  # tls_root_ca_certificate: /etc/lerobot/tls/ca.pem
-  # tls_connect_certificate: /etc/lerobot/tls/server.pem
-  # tls_connect_private_key: /etc/lerobot/tls/server.key
-  # Escape hatch: raw JSON5 merged into the zenoh config last.
-  # extra_config_json5: '{transport: {link: {tx: {queue: {size: {data: 4}}}}}}'
-
-# --- Observability -------------------------------------------------------------
-# HTTP health + Prometheus metrics port; 0 disables the endpoint.
-health_port: 9100
-
-# Optional bounded request/response capture for offline replay.
-debug:
-  capture_dir: null
-  capture_max: 256

examples/so100_to_so100_EE/evaluate.py

@@ -18,7 +18,7 @@ import logging
 import time
 
 from lerobot.cameras.opencv import OpenCVCameraConfig
-from lerobot.common.control_utils import init_keyboard_listener, predict_action
+from lerobot.common.control_utils import predict_action
 from lerobot.configs import FeatureType, PolicyFeature
 from lerobot.datasets import LeRobotDataset, aggregate_pipeline_dataset_features, create_initial_features
 from lerobot.model.kinematics import RobotKinematics
@@ -41,6 +41,7 @@ from lerobot.robots.so_follower.robot_kinematic_processor import (
 from lerobot.types import RobotAction, RobotObservation
 from lerobot.utils.constants import ACTION, OBS_STR
 from lerobot.utils.feature_utils import build_dataset_frame, combine_feature_dicts
+from lerobot.utils.keyboard_input import init_keyboard_listener
 from lerobot.utils.robot_utils import precise_sleep
 from lerobot.utils.utils import log_say
 from lerobot.utils.visualization_utils import init_rerun, log_rerun_data

examples/so100_to_so100_EE/record.py

@@ -16,7 +16,6 @@
 
 
 from lerobot.cameras.opencv import OpenCVCameraConfig
-from lerobot.common.control_utils import init_keyboard_listener
 from lerobot.datasets import LeRobotDataset, aggregate_pipeline_dataset_features, create_initial_features
 from lerobot.model.kinematics import RobotKinematics
 from lerobot.processor import (
@@ -36,6 +35,7 @@ from lerobot.scripts.lerobot_record import record_loop
 from lerobot.teleoperators.so_leader import SO100Leader, SO100LeaderConfig
 from lerobot.types import RobotAction, RobotObservation
 from lerobot.utils.feature_utils import combine_feature_dicts
+from lerobot.utils.keyboard_input import init_keyboard_listener
 from lerobot.utils.utils import log_say
 from lerobot.utils.visualization_utils import init_rerun
 

examples/tutorial/async-inf/policy_server.py

@@ -0,0 +1,17 @@
+from lerobot.async_inference.configs import PolicyServerConfig
+from lerobot.async_inference.policy_server import serve
+
+
+def main():
+    host = ...  # something like "127.0.0.1" if you're exposing to localhost
+    port = ...  # something like 8080
+
+    config = PolicyServerConfig(
+        host=host,
+        port=port,
+    )
+    serve(config)
+
+
+if __name__ == "__main__":
+    main()

examples/tutorial/async-inf/robot_client.py

@@ -0,0 +1,62 @@
+import threading
+
+from lerobot.async_inference.configs import RobotClientConfig
+from lerobot.async_inference.helpers import visualize_action_queue_size
+from lerobot.async_inference.robot_client import RobotClient
+from lerobot.cameras.opencv import OpenCVCameraConfig
+from lerobot.robots.so_follower import SO100FollowerConfig
+
+
+def main():
+    # these cameras must match the ones expected by the policy - find your cameras with lerobot-find-cameras
+    # check the config.json on the Hub for the policy you are using to see the expected camera specs
+    camera_cfg = {
+        "up": OpenCVCameraConfig(index_or_path=0, width=640, height=480, fps=30),
+        "side": OpenCVCameraConfig(index_or_path=1, width=640, height=480, fps=30),
+    }
+
+    # # find ports using lerobot-find-port
+    follower_port = ...  # something like "/dev/tty.usbmodem58760431631"
+
+    # # the robot ids are used the load the right calibration files
+    follower_id = ...  # something like "follower_so100"
+
+    robot_cfg = SO100FollowerConfig(port=follower_port, id=follower_id, cameras=camera_cfg)
+
+    server_address = ...  # something like "127.0.0.1:8080" if using localhost
+
+    # 3. Create client configuration
+    client_cfg = RobotClientConfig(
+        robot=robot_cfg,
+        server_address=server_address,
+        policy_device="mps",
+        client_device="cpu",
+        policy_type="act",
+        pretrained_name_or_path="<user>/robot_learning_tutorial_act",
+        chunk_size_threshold=0.5,  # g
+        actions_per_chunk=50,  # make sure this is less than the max actions of the policy
+    )
+
+    # 4. Create and start client
+    client = RobotClient(client_cfg)
+
+    # 5. Provide a textual description of the task
+    task = ...
+
+    if client.start():
+        # Start action receiver thread
+        action_receiver_thread = threading.Thread(target=client.receive_actions, daemon=True)
+        action_receiver_thread.start()
+
+        try:
+            # Run the control loop
+            client.control_loop(task)
+        except KeyboardInterrupt:
+            client.stop()
+            action_receiver_thread.join()
+            # (Optionally) plot the action queue size
+            visualize_action_queue_size(client.action_queue_size)
+
+
+if __name__ == "__main__":
+    main()

pyproject.toml

@@ -25,7 +25,7 @@ discord = "https://discord.gg/s3KuuzsPFb"
 
 [project]
 name = "lerobot"
-version = "0.5.2"
+version = "0.6.1"
 description = "🤗 LeRobot: State-of-the-art Machine Learning for Real-World Robotics in Pytorch"
 dynamic = ["readme"]
 license = { text = "Apache-2.0" }
@@ -124,7 +124,8 @@ hardware = [
     "lerobot[deepdiff-dep]",
 ]
 viz = [
-    "rerun-sdk>=0.24.0,<0.27.0",
+    "rerun-sdk>=0.24.0,<0.34.0",
+    "foxglove-sdk>=0.25.1,<0.26.0",
 ]
 # ── User-facing composite extras (map to CLI scripts) ─────
 # lerobot-record, lerobot-replay, lerobot-calibrate, lerobot-teleoperate, etc.
@@ -140,7 +141,14 @@ av-dep = ["av>=15.0.0,<16.0.0"]
 pygame-dep = ["pygame>=2.5.1,<2.7.0"]
 # NOTE: 0.9.16 links against liburdfdom_sensor.so.4, which is unavailable on Ubuntu 24.04
 # (noble ships urdfdom 3.x). Cap below 0.9.16 until system urdfdom 4.x is broadly available.
-placo-dep = ["placo>=0.9.6,<0.9.16"]
+#
+# NOTE: placo pulls in pin (Pinocchio), whose binary wheels dlopen specific cmeel sonames
+# (liburdfdom_sensor.so.4.0, libtinyxml2.so.10) but declare only `>=` floors on their cmeel
+# packages. The 2026-05-21 major bumps (cmeel-urdfdom 6.0.0 -> .so.6, cmeel-tinyxml2 11.0.0
+# -> .so.11) ship newer sonames, so left unpinned the resolver grabs them and `import placo`
+# fails at load with "liburdfdom_sensor.so.4.0: cannot open shared object file" (see #3755).
+# There is no cmeel-urdfdom 5.x; <5 selects the 4.x ABI the placo/pin wheels are built against.
+placo-dep = ["placo>=0.9.6,<0.9.16", "cmeel-urdfdom>=4,<5", "cmeel-tinyxml2<11"]
 transformers-dep = ["transformers>=5.4.0,<5.6.0"]
 grpcio-dep = ["grpcio>=1.73.1,<2.0.0", "protobuf>=6.31.1,<8.0.0"]
 accelerate-dep = ["accelerate>=1.14.0,<2.0.0"]
@@ -156,6 +164,7 @@ pynput-dep = ["pynput>=1.7.8,<1.9.0"]
 pyzmq-dep = ["pyzmq>=26.2.1,<28.0.0"]
 motorbridge-dep = ["motorbridge>=0.3.2,<0.4.0"]
 motorbridge-smart-servo-dep = ["motorbridge-smart-servo>=0.0.4,<0.1.0"]
+timm-dep = ["timm>=1.0.0,<1.1.0"]
 
 # Motors
 feetech = ["feetech-servo-sdk>=1.0.0,<2.0.0", "lerobot[pyserial-dep]", "lerobot[deepdiff-dep]"]
@@ -211,26 +220,44 @@ groot = [
     "lerobot[transformers-dep]",
     "lerobot[peft-dep]",
     "lerobot[diffusers-dep]",
+    "lerobot[dataset]", # NOTE: processor_groot builds a LeRobotDataset for relative-action training stats
     "dm-tree>=0.1.8,<1.0.0",
-    "timm>=1.0.0,<1.1.0",
+    "lerobot[timm-dep]",
     "decord>=0.6.0,<1.0.0; (platform_machine == 'AMD64' or platform_machine == 'x86_64')",
-    "ninja>=1.11.1,<2.0.0",
-    "flash-attn>=2.5.9,<3.0.0 ; sys_platform != 'darwin'"
 ]
 sarm = ["lerobot[transformers-dep]", "pydantic>=2.0.0,<3.0.0", "faker>=33.0.0,<35.0.0", "lerobot[matplotlib-dep]", "lerobot[qwen-vl-utils-dep]"]
 robometer = ["lerobot[transformers-dep]", "lerobot[qwen-vl-utils-dep]", "lerobot[peft-dep]"]
 topreward = ["lerobot[transformers-dep]"]
 xvla = ["lerobot[transformers-dep]"]
 eo1 = ["lerobot[transformers-dep]", "lerobot[qwen-vl-utils-dep]"]
+fastwam = [
+    "lerobot[transformers-dep]",
+    "lerobot[diffusers-dep]",
+]
+evo1 = ["lerobot[transformers-dep]"]
 hilserl = ["lerobot[transformers-dep]", "lerobot[dataset]", "gym-hil>=0.1.14,<0.2.0", "lerobot[grpcio-dep]", "lerobot[placo-dep]"]
 vla_jepa = ["lerobot[transformers-dep]", "lerobot[diffusers-dep]", "lerobot[qwen-vl-utils-dep]"]
+lingbot_va = ["lerobot[transformers-dep]", "lerobot[diffusers-dep]", "lerobot[accelerate-dep]"]
 
 # Features
-# Remote inference over Zenoh: lerobot-policy-server + lerobot-rollout --inference.type=remote.
-# Keep zenohd routers on the same minor version as the Python binding.
-async = ["eclipse-zenoh>=1.9,<2.0", "msgpack>=1.0.0,<2.0.0"]
+async = ["lerobot[grpcio-dep]", "lerobot[matplotlib-dep]"]
 peft = ["lerobot[transformers-dep]", "lerobot[peft-dep]"]
 
+# Annotation pipeline (lerobot-annotate). The only backend is ``openai``,
+# which talks to any OpenAI-compatible server (``vllm serve`` /
+# ``transformers serve`` / hosted). Distributed runs use Hugging Face Jobs
+# (see examples/annotations/run_hf_job.py).
+annotations = [
+    "lerobot[dataset]",
+    "lerobot[transformers-dep]",
+    "openai>=1.40,<2.0",
+    # ``vllm`` is intentionally NOT a hard dep: it pins an older torch, and
+    # uv's single unified lock would then cap ``torch`` for every extra
+    # (e.g. forcing 2.8 while ``torchcodec`` in [dataset] needs 2.11 -> ABI
+    # break in CI). The HF Jobs image (``vllm/vllm-openai``) provides vLLM;
+    # install it locally only if you run your own ``vllm serve``.
+]
+
 # Development
 dev = ["pre-commit>=3.7.0,<5.0.0", "debugpy>=1.8.1,<1.9.0", "lerobot[grpcio-dep]", "grpcio-tools>=1.73.1,<2.0.0", "mypy>=1.19.1", "ruff>=0.14.1", "lerobot[notebook]"]
 notebook = ["jupyter>=1.0.0,<2.0.0", "ipykernel>=6.0.0,<7.0.0"]
@@ -288,10 +315,13 @@ all = [
     "lerobot[pi]",
     "lerobot[molmoact2]",
     "lerobot[smolvla]",
-    # "lerobot[groot]", TODO(Steven): Gr00t requires specific installation instructions for flash-attn
+    "lerobot[fastwam]",
+    "lerobot[groot]",
     "lerobot[xvla]",
+    "lerobot[evo1]",
     "lerobot[hilserl]",
     "lerobot[vla_jepa]",
+    "lerobot[lingbot_va]",
     "lerobot[async]",
     "lerobot[dev]",
     "lerobot[test]",
@@ -325,8 +355,8 @@ lerobot-find-joint-limits="lerobot.scripts.lerobot_find_joint_limits:main"
 lerobot-imgtransform-viz="lerobot.scripts.lerobot_imgtransform_viz:main"
 lerobot-edit-dataset="lerobot.scripts.lerobot_edit_dataset:main"
 lerobot-setup-can="lerobot.scripts.lerobot_setup_can:main"
+lerobot-annotate="lerobot.scripts.lerobot_annotate:main"
 lerobot-rollout="lerobot.scripts.lerobot_rollout:main"
-lerobot-policy-server="lerobot.scripts.lerobot_policy_server:main"
 
 # ---------------- Tool Configurations ----------------
 
@@ -344,7 +374,7 @@ torch = [{ index = "pytorch-cu128", marker = "sys_platform == 'linux'" }]
 torchvision = [{ index = "pytorch-cu128", marker = "sys_platform == 'linux'" }]
 
 [tool.setuptools.package-data]
-lerobot = ["envs/*.json"]
+lerobot = ["envs/*.json", "annotations/steerable_pipeline/prompts/*.txt"]
 
 [tool.setuptools.packages.find]
 where = ["src"]
@@ -424,7 +454,8 @@ default.extend-ignore-identifiers-re = [
     "is_compileable",
     "ROBOTIS",
     "OT_VALUE",
-    "VanderBilt"
+    "VanderBilt",
+    "seperated_timestep",
 ]
 
 # TODO: Uncomment when ready to use
@@ -519,6 +550,11 @@ ignore_errors = false
 # module = "lerobot.rl.*"
 # ignore_errors = false
 
+
+# [[tool.mypy.overrides]]
+# module = "lerobot.async_inference.*"
+# ignore_errors = false
+
 [[tool.mypy.overrides]]
 module = "lerobot.transport.*"
 ignore_errors = false

requirements-macos.txt

@@ -1,729 +0,0 @@
-#
-# This file is autogenerated by pip-compile with Python 3.12
-# by the following command:
-#
-#    pip-compile --output-file=requirements-macos.txt requirements.in
-#
--e .[all]
-    # via -[all]
-absl-py==2.4.0
-    # via
-    #   dm-control
-    #   dm-env
-    #   dm-tree
-    #   labmaze
-    #   mujoco
-accelerate==1.13.0
-    # via
-    #   lerobot
-    #   peft
-aiohappyeyeballs==2.6.1
-    # via aiohttp
-aiohttp==3.13.3
-    # via fsspec
-aiosignal==1.4.0
-    # via aiohttp
-annotated-doc==0.0.4
-    # via
-    #   fastapi
-    #   typer
-annotated-types==0.7.0
-    # via pydantic
-anyio==4.12.1
-    # via
-    #   httpx
-    #   starlette
-    #   watchfiles
-asttokens==3.0.1
-    # via stack-data
-attrs==25.4.0
-    # via
-    #   aiohttp
-    #   dm-tree
-    #   jsonlines
-    #   rerun-sdk
-av==15.1.0
-    # via
-    #   lerobot
-    #   qwen-vl-utils
-certifi==2026.2.25
-    # via
-    #   httpcore
-    #   httpx
-    #   requests
-    #   sentry-sdk
-cffi==2.0.0
-    # via pymunk
-cfgv==3.5.0
-    # via pre-commit
-charset-normalizer==3.4.5
-    # via requests
-click==8.3.1
-    # via
-    #   typer
-    #   uvicorn
-    #   wandb
-cloudpickle==3.1.2
-    # via gymnasium
-cmake==4.1.3
-    # via lerobot
-cmeel==0.59.0
-    # via
-    #   cmeel-assimp
-    #   cmeel-boost
-    #   cmeel-console-bridge
-    #   cmeel-octomap
-    #   cmeel-qhull
-    #   cmeel-tinyxml2
-    #   cmeel-urdfdom
-    #   cmeel-zlib
-    #   coal-library
-    #   eigenpy
-    #   eiquadprog
-    #   pin
-    #   placo
-    #   rhoban-cmeel-jsoncpp
-cmeel-assimp==5.4.3.1
-    # via coal-library
-cmeel-boost==1.87.0.1
-    # via
-    #   coal-library
-    #   eigenpy
-    #   eiquadprog
-    #   pin
-cmeel-console-bridge==1.0.2.3
-    # via cmeel-urdfdom
-cmeel-octomap==1.10.0
-    # via coal-library
-cmeel-qhull==8.0.2.1
-    # via coal-library
-cmeel-tinyxml2==10.0.0
-    # via cmeel-urdfdom
-cmeel-urdfdom==4.0.1
-    # via pin
-cmeel-zlib==1.3.1
-    # via cmeel-assimp
-coal-library==3.0.1
-    # via pin
-contourpy==1.3.3
-    # via
-    #   lerobot
-    #   matplotlib
-coverage[toml]==7.13.4
-    # via pytest-cov
-cycler==0.12.1
-    # via matplotlib
-datasets==4.6.1
-    # via lerobot
-debugpy==1.8.20
-    # via lerobot
-decorator==5.2.1
-    # via ipython
-deepdiff==8.6.1
-    # via lerobot
-diffusers==0.35.2
-    # via lerobot
-dill==0.4.0
-    # via
-    #   datasets
-    #   multiprocess
-distlib==0.4.0
-    # via virtualenv
-dm-control==1.0.37
-    # via gym-aloha
-dm-env==1.6
-    # via dm-control
-dm-tree==0.1.9
-    # via
-    #   dm-control
-    #   dm-env
-docopt==0.6.2
-    # via num2words
-draccus==0.10.0
-    # via lerobot
-dynamixel-sdk==3.8.4
-    # via lerobot
-eigenpy==3.10.3
-    # via coal-library
-einops==0.8.2
-    # via lerobot
-eiquadprog==1.2.9
-    # via placo
-etils[epath,epy]==1.14.0
-    # via mujoco
-executing==2.2.1
-    # via stack-data
-faker==34.0.2
-    # via lerobot
-farama-notifications==0.0.4
-    # via gymnasium
-fastapi==0.135.1
-    # via
-    #   lerobot
-    #   teleop
-feetech-servo-sdk==1.0.0
-    # via lerobot
-filelock==3.25.0
-    # via
-    #   datasets
-    #   diffusers
-    #   huggingface-hub
-    #   python-discovery
-    #   torch
-    #   virtualenv
-fonttools==4.61.1
-    # via matplotlib
-frozenlist==1.8.0
-    # via
-    #   aiohttp
-    #   aiosignal
-fsspec[http]==2026.2.0
-    # via
-    #   datasets
-    #   etils
-    #   huggingface-hub
-    #   torch
-gitdb==4.0.12
-    # via gitpython
-gitpython==3.1.46
-    # via wandb
-glfw==2.10.0
-    # via
-    #   dm-control
-    #   mujoco
-grpcio==1.73.1
-    # via
-    #   grpcio-tools
-    #   lerobot
-    #   reachy2-sdk
-    #   reachy2-sdk-api
-grpcio-tools==1.73.1
-    # via
-    #   lerobot
-    #   reachy2-sdk-api
-gym-aloha==0.1.3
-    # via lerobot
-gym-hil==0.1.13
-    # via lerobot
-gym-pusht==0.1.6
-    # via lerobot
-gymnasium==1.2.3
-    # via
-    #   gym-aloha
-    #   gym-hil
-    #   gym-pusht
-    #   lerobot
-    #   metaworld
-h11==0.16.0
-    # via
-    #   httpcore
-    #   uvicorn
-hebi-py==2.11.0
-    # via lerobot
-hf-xet==1.3.2
-    # via huggingface-hub
-hidapi==0.14.0.post4
-    # via
-    #   gym-hil
-    #   lerobot
-httpcore==1.0.9
-    # via httpx
-httptools==0.7.1
-    # via uvicorn
-httpx==0.28.1
-    # via
-    #   datasets
-    #   huggingface-hub
-huggingface-hub==1.6.0
-    # via
-    #   accelerate
-    #   datasets
-    #   diffusers
-    #   lerobot
-    #   peft
-    #   tokenizers
-    #   transformers
-identify==2.6.17
-    # via pre-commit
-idna==3.11
-    # via
-    #   anyio
-    #   httpx
-    #   requests
-    #   yarl
-imageio[ffmpeg]==2.37.2
-    # via
-    #   gym-aloha
-    #   gym-hil
-    #   lerobot
-    #   metaworld
-    #   scikit-image
-imageio-ffmpeg==0.6.0
-    # via imageio
-importlib-metadata==8.7.1
-    # via diffusers
-iniconfig==2.3.0
-    # via pytest
-ipython==9.11.0
-    # via meshcat
-ipython-pygments-lexers==1.1.1
-    # via ipython
-ischedule==1.2.7
-    # via placo
-jedi==0.19.2
-    # via ipython
-jinja2==3.1.6
-    # via torch
-jsonlines==4.0.0
-    # via lerobot
-kiwisolver==1.4.9
-    # via matplotlib
-labmaze==1.0.6
-    # via dm-control
-lazy-loader==0.5
-    # via scikit-image
-librt==0.8.1
-    # via mypy
-lxml==6.0.2
-    # via dm-control
-markdown-it-py==4.0.0
-    # via rich
-markupsafe==3.0.3
-    # via jinja2
-matplotlib==3.10.8
-    # via lerobot
-matplotlib-inline==0.2.1
-    # via ipython
-mdurl==0.1.2
-    # via markdown-it-py
-mergedeep==1.3.4
-    # via draccus
-meshcat==0.3.2
-    # via placo
-metaworld==3.0.0
-    # via lerobot
-mock-serial==0.0.1
-    # via lerobot
-mpmath==1.3.0
-    # via sympy
-mujoco==3.5.0
-    # via
-    #   dm-control
-    #   gym-aloha
-    #   gym-hil
-    #   metaworld
-multidict==6.7.1
-    # via
-    #   aiohttp
-    #   yarl
-multiprocess==0.70.18
-    # via datasets
-mypy==1.19.1
-    # via lerobot
-mypy-extensions==1.1.0
-    # via
-    #   mypy
-    #   typing-inspect
-networkx==3.6.1
-    # via
-    #   scikit-image
-    #   torch
-nodeenv==1.10.0
-    # via pre-commit
-num2words==0.5.14
-    # via lerobot
-numpy==2.2.6
-    # via
-    #   accelerate
-    #   cmeel-boost
-    #   contourpy
-    #   datasets
-    #   diffusers
-    #   dm-control
-    #   dm-env
-    #   dm-tree
-    #   gymnasium
-    #   hebi-py
-    #   imageio
-    #   labmaze
-    #   lerobot
-    #   matplotlib
-    #   meshcat
-    #   metaworld
-    #   mujoco
-    #   opencv-python
-    #   opencv-python-headless
-    #   pandas
-    #   peft
-    #   pyquaternion
-    #   reachy2-sdk
-    #   rerun-sdk
-    #   scikit-image
-    #   scipy
-    #   shapely
-    #   teleop
-    #   tifffile
-    #   torchvision
-    #   transformers
-    #   transforms3d
-opencv-python==4.13.0.92
-    # via
-    #   gym-pusht
-    #   reachy2-sdk
-opencv-python-headless==4.12.0.88
-    # via lerobot
-orderly-set==5.5.0
-    # via deepdiff
-packaging==25.0
-    # via
-    #   accelerate
-    #   datasets
-    #   huggingface-hub
-    #   lazy-loader
-    #   lerobot
-    #   matplotlib
-    #   peft
-    #   pytest
-    #   qwen-vl-utils
-    #   reachy2-sdk
-    #   scikit-image
-    #   transformers
-    #   wandb
-pandas==2.3.3
-    # via
-    #   datasets
-    #   lerobot
-parso==0.8.6
-    # via jedi
-pathspec==1.0.4
-    # via mypy
-peft==0.18.1
-    # via lerobot
-pexpect==4.9.0
-    # via ipython
-pillow==12.1.1
-    # via
-    #   diffusers
-    #   imageio
-    #   matplotlib
-    #   meshcat
-    #   qwen-vl-utils
-    #   rerun-sdk
-    #   scikit-image
-    #   torchvision
-pin==3.4.0
-    # via placo
-placo==0.9.16
-    # via lerobot
-platformdirs==4.9.4
-    # via
-    #   python-discovery
-    #   virtualenv
-    #   wandb
-pluggy==1.6.0
-    # via
-    #   pytest
-    #   pytest-cov
-pre-commit==4.5.1
-    # via lerobot
-prompt-toolkit==3.0.52
-    # via ipython
-propcache==0.4.1
-    # via
-    #   aiohttp
-    #   yarl
-protobuf==6.31.1
-    # via
-    #   dm-control
-    #   grpcio-tools
-    #   lerobot
-    #   reachy2-sdk
-    #   reachy2-sdk-api
-    #   wandb
-psutil==7.2.2
-    # via
-    #   accelerate
-    #   imageio
-    #   peft
-ptyprocess==0.7.0
-    # via pexpect
-pure-eval==0.2.3
-    # via stack-data
-pyarrow==23.0.1
-    # via
-    #   datasets
-    #   rerun-sdk
-pycparser==3.0
-    # via cffi
-pydantic==2.12.5
-    # via
-    #   fastapi
-    #   wandb
-pydantic-core==2.41.5
-    # via pydantic
-pygame==2.6.1
-    # via
-    #   gym-hil
-    #   gym-pusht
-    #   lerobot
-pygments==2.19.2
-    # via
-    #   ipython
-    #   ipython-pygments-lexers
-    #   pytest
-    #   rich
-pymunk==6.11.1
-    # via
-    #   gym-pusht
-    #   lerobot
-pyngrok==7.5.1
-    # via meshcat
-pynput==1.8.1
-    # via
-    #   gym-hil
-    #   lerobot
-pyobjc-core==12.1
-    # via
-    #   pyobjc-framework-applicationservices
-    #   pyobjc-framework-cocoa
-    #   pyobjc-framework-coretext
-    #   pyobjc-framework-quartz
-pyobjc-framework-applicationservices==12.1
-    # via pynput
-pyobjc-framework-cocoa==12.1
-    # via
-    #   pyobjc-framework-applicationservices
-    #   pyobjc-framework-coretext
-    #   pyobjc-framework-quartz
-pyobjc-framework-coretext==12.1
-    # via pyobjc-framework-applicationservices
-pyobjc-framework-quartz==12.1
-    # via
-    #   pynput
-    #   pyobjc-framework-applicationservices
-    #   pyobjc-framework-coretext
-pyopengl==3.1.10
-    # via
-    #   dm-control
-    #   mujoco
-pyparsing==3.3.2
-    # via
-    #   dm-control
-    #   matplotlib
-pyquaternion==0.9.9
-    # via reachy2-sdk
-pyrealsense2-macosx==2.56.5
-    # via lerobot
-pyserial==3.5
-    # via
-    #   dynamixel-sdk
-    #   feetech-servo-sdk
-    #   lerobot
-pytest==8.4.2
-    # via
-    #   lerobot
-    #   pytest-cov
-    #   pytest-timeout
-    #   teleop
-pytest-cov==7.0.0
-    # via lerobot
-pytest-timeout==2.4.0
-    # via lerobot
-python-dateutil==2.9.0.post0
-    # via
-    #   faker
-    #   matplotlib
-    #   pandas
-python-discovery==1.1.1
-    # via virtualenv
-python-dotenv==1.2.2
-    # via uvicorn
-pytz==2026.1.post1
-    # via pandas
-pyyaml==6.0.3
-    # via
-    #   accelerate
-    #   datasets
-    #   draccus
-    #   hebi-py
-    #   huggingface-hub
-    #   peft
-    #   pre-commit
-    #   pyngrok
-    #   pyyaml-include
-    #   transformers
-    #   uvicorn
-    #   wandb
-pyyaml-include==1.4.1
-    # via draccus
-pyzmq==27.1.0
-    # via
-    #   lerobot
-    #   meshcat
-qwen-vl-utils==0.0.14
-    # via lerobot
-reachy2-sdk==1.0.15
-    # via lerobot
-reachy2-sdk-api==1.0.21
-    # via reachy2-sdk
-regex==2026.2.28
-    # via
-    #   diffusers
-    #   transformers
-requests==2.32.5
-    # via
-    #   datasets
-    #   diffusers
-    #   dm-control
-    #   qwen-vl-utils
-    #   teleop
-    #   wandb
-rerun-sdk==0.26.2
-    # via lerobot
-rhoban-cmeel-jsoncpp==1.9.4.9
-    # via placo
-rich==14.3.3
-    # via typer
-safetensors==0.7.0
-    # via
-    #   accelerate
-    #   diffusers
-    #   lerobot
-    #   peft
-    #   transformers
-scikit-image==0.25.2
-    # via
-    #   gym-pusht
-    #   lerobot
-scipy==1.17.1
-    # via
-    #   dm-control
-    #   lerobot
-    #   metaworld
-    #   scikit-image
-    #   torchdiffeq
-sentry-sdk==2.54.0
-    # via wandb
-shapely==2.1.2
-    # via gym-pusht
-shellingham==1.5.4
-    # via typer
-six==1.17.0
-    # via
-    #   pynput
-    #   python-dateutil
-smmap==5.0.3
-    # via gitdb
-stack-data==0.6.3
-    # via ipython
-starlette==0.52.1
-    # via fastapi
-sympy==1.14.0
-    # via torch
-teleop==0.1.4
-    # via lerobot
-termcolor==3.3.0
-    # via lerobot
-tifffile==2026.3.3
-    # via scikit-image
-tokenizers==0.22.2
-    # via transformers
-toml==0.10.2
-    # via draccus
-torch==2.10.0
-    # via
-    #   accelerate
-    #   lerobot
-    #   peft
-    #   torchdiffeq
-    #   torchvision
-torchcodec==0.10.0
-    # via lerobot
-torchdiffeq==0.2.5
-    # via lerobot
-torchvision==0.25.0
-    # via lerobot
-tornado==6.5.4
-    # via meshcat
-tqdm==4.67.3
-    # via
-    #   datasets
-    #   dm-control
-    #   huggingface-hub
-    #   peft
-    #   transformers
-traitlets==5.14.3
-    # via
-    #   ipython
-    #   matplotlib-inline
-transformers==5.3.0
-    # via
-    #   lerobot
-    #   peft
-transforms3d==0.4.2
-    # via teleop
-typer==0.24.1
-    # via
-    #   huggingface-hub
-    #   transformers
-typing-extensions==4.15.0
-    # via
-    #   aiosignal
-    #   anyio
-    #   etils
-    #   faker
-    #   fastapi
-    #   gymnasium
-    #   huggingface-hub
-    #   mypy
-    #   pydantic
-    #   pydantic-core
-    #   rerun-sdk
-    #   starlette
-    #   torch
-    #   typing-inspect
-    #   typing-inspection
-    #   wandb
-typing-inspect==0.9.0
-    # via draccus
-typing-inspection==0.4.2
-    # via
-    #   fastapi
-    #   pydantic
-tzdata==2025.3
-    # via pandas
-u-msgpack-python==2.8.0
-    # via meshcat
-urllib3==2.6.3
-    # via
-    #   requests
-    #   sentry-sdk
-uvicorn[standard]==0.41.0
-    # via teleop
-uvloop==0.22.1
-    # via uvicorn
-virtualenv==21.1.0
-    # via pre-commit
-wandb==0.24.2
-    # via lerobot
-watchfiles==1.1.1
-    # via uvicorn
-wcwidth==0.6.0
-    # via prompt-toolkit
-websocket-client==1.9.0
-    # via teleop
-websockets==16.0
-    # via uvicorn
-wrapt==2.1.2
-    # via dm-tree
-xxhash==3.6.0
-    # via datasets
-yarl==1.23.0
-    # via aiohttp
-zipp==3.23.0
-    # via
-    #   etils
-    #   importlib-metadata
-
-# The following packages are considered to be unsafe in a requirements file:
-# setuptools

requirements-ubuntu.txt

@@ -1,882 +0,0 @@
-#
-# This file is autogenerated by pip-compile with Python 3.12
-# by the following command:
-#
-#    pip-compile --output-file=requirements-ubuntu.txt requirements.in
-#
--e .[all]
-    # via -[all]
-absl-py==2.4.0
-    # via
-    #   dm-control
-    #   dm-env
-    #   dm-tree
-    #   labmaze
-    #   mujoco
-    #   tensorboard
-accelerate==1.13.0
-    # via
-    #   lerobot
-    #   peft
-aiohappyeyeballs==2.6.1
-    # via aiohttp
-aiohttp==3.13.3
-    # via fsspec
-aiosignal==1.4.0
-    # via aiohttp
-annotated-doc==0.0.4
-    # via
-    #   fastapi
-    #   typer
-annotated-types==0.7.0
-    # via pydantic
-antlr4-python3-runtime==4.9.3
-    # via
-    #   hydra-core
-    #   omegaconf
-anyio==4.12.1
-    # via
-    #   httpx
-    #   starlette
-    #   watchfiles
-asttokens==3.0.1
-    # via stack-data
-attrs==25.4.0
-    # via
-    #   aiohttp
-    #   dm-tree
-    #   jsonlines
-    #   jsonschema
-    #   referencing
-    #   rerun-sdk
-av==15.1.0
-    # via
-    #   lerobot
-    #   qwen-vl-utils
-bddl==1.0.1
-    # via hf-libero
-certifi==2026.2.25
-    # via
-    #   httpcore
-    #   httpx
-    #   requests
-    #   sentry-sdk
-cffi==2.0.0
-    # via pymunk
-cfgv==3.5.0
-    # via pre-commit
-charset-normalizer==3.4.5
-    # via requests
-click==8.3.1
-    # via
-    #   typer
-    #   uvicorn
-    #   wandb
-cloudpickle==3.1.2
-    # via
-    #   gymnasium
-    #   hf-libero
-cmake==4.1.3
-    # via lerobot
-cmeel==0.59.0
-    # via
-    #   cmeel-assimp
-    #   cmeel-boost
-    #   cmeel-console-bridge
-    #   cmeel-octomap
-    #   cmeel-qhull
-    #   cmeel-tinyxml2
-    #   cmeel-urdfdom
-    #   cmeel-zlib
-    #   coal-library
-    #   eigenpy
-    #   eiquadprog
-    #   pin
-    #   placo
-    #   rhoban-cmeel-jsoncpp
-cmeel-assimp==5.4.3.1
-    # via coal-library
-cmeel-boost==1.87.0.1
-    # via
-    #   coal-library
-    #   eigenpy
-    #   eiquadprog
-    #   pin
-cmeel-console-bridge==1.0.2.3
-    # via cmeel-urdfdom
-cmeel-octomap==1.10.0
-    # via coal-library
-cmeel-qhull==8.0.2.1
-    # via coal-library
-cmeel-tinyxml2==10.0.0
-    # via cmeel-urdfdom
-cmeel-urdfdom==4.0.1
-    # via pin
-cmeel-zlib==1.3.1
-    # via cmeel-assimp
-coal-library==3.0.1
-    # via pin
-contourpy==1.3.3
-    # via
-    #   lerobot
-    #   matplotlib
-coverage[toml]==7.13.4
-    # via pytest-cov
-cuda-bindings==12.9.4
-    # via torch
-cuda-pathfinder==1.4.1
-    # via cuda-bindings
-cycler==0.12.1
-    # via matplotlib
-datasets==4.6.1
-    # via lerobot
-debugpy==1.8.20
-    # via lerobot
-decorator==5.2.1
-    # via ipython
-deepdiff==8.6.1
-    # via lerobot
-diffusers==0.35.2
-    # via lerobot
-dill==0.4.0
-    # via
-    #   datasets
-    #   multiprocess
-distlib==0.4.0
-    # via virtualenv
-dm-control==1.0.37
-    # via gym-aloha
-dm-env==1.6
-    # via dm-control
-dm-tree==0.1.9
-    # via
-    #   dm-control
-    #   dm-env
-docopt==0.6.2
-    # via num2words
-draccus==0.10.0
-    # via lerobot
-dynamixel-sdk==3.8.4
-    # via lerobot
-easydict==1.13
-    # via hf-libero
-egl-probe==1.0.2
-    # via robomimic
-eigenpy==3.10.3
-    # via coal-library
-einops==0.8.2
-    # via
-    #   hf-libero
-    #   lerobot
-eiquadprog==1.2.9
-    # via placo
-etils[epath,epy]==1.14.0
-    # via mujoco
-evdev==1.9.3
-    # via pynput
-executing==2.2.1
-    # via stack-data
-faker==34.0.2
-    # via lerobot
-farama-notifications==0.0.4
-    # via gymnasium
-fastapi==0.135.1
-    # via
-    #   lerobot
-    #   teleop
-fastjsonschema==2.21.2
-    # via nbformat
-feetech-servo-sdk==1.0.0
-    # via lerobot
-filelock==3.25.0
-    # via
-    #   datasets
-    #   diffusers
-    #   huggingface-hub
-    #   python-discovery
-    #   torch
-    #   virtualenv
-fonttools==4.61.1
-    # via matplotlib
-frozenlist==1.8.0
-    # via
-    #   aiohttp
-    #   aiosignal
-fsspec[http]==2026.2.0
-    # via
-    #   datasets
-    #   etils
-    #   huggingface-hub
-    #   torch
-future==1.0.0
-    # via hf-libero
-gitdb==4.0.12
-    # via gitpython
-gitpython==3.1.46
-    # via wandb
-glfw==2.10.0
-    # via
-    #   dm-control
-    #   mujoco
-grpcio==1.73.1
-    # via
-    #   grpcio-tools
-    #   lerobot
-    #   reachy2-sdk
-    #   reachy2-sdk-api
-    #   tensorboard
-grpcio-tools==1.73.1
-    # via
-    #   lerobot
-    #   reachy2-sdk-api
-gym-aloha==0.1.3
-    # via lerobot
-gym-hil==0.1.13
-    # via lerobot
-gym-pusht==0.1.6
-    # via lerobot
-gymnasium==1.2.3
-    # via
-    #   gym-aloha
-    #   gym-hil
-    #   gym-pusht
-    #   hf-libero
-    #   lerobot
-    #   metaworld
-h11==0.16.0
-    # via
-    #   httpcore
-    #   uvicorn
-h5py==3.16.0
-    # via robomimic
-hebi-py==2.11.0
-    # via lerobot
-hf-egl-probe==1.0.2
-    # via hf-libero
-hf-libero==0.1.3
-    # via lerobot
-hf-xet==1.3.2
-    # via huggingface-hub
-hidapi==0.14.0.post4
-    # via
-    #   gym-hil
-    #   lerobot
-httpcore==1.0.9
-    # via httpx
-httptools==0.7.1
-    # via uvicorn
-httpx==0.28.1
-    # via
-    #   datasets
-    #   huggingface-hub
-huggingface-hub==1.6.0
-    # via
-    #   accelerate
-    #   datasets
-    #   diffusers
-    #   lerobot
-    #   peft
-    #   tokenizers
-    #   transformers
-hydra-core==1.3.2
-    # via hf-libero
-identify==2.6.17
-    # via pre-commit
-idna==3.11
-    # via
-    #   anyio
-    #   httpx
-    #   requests
-    #   yarl
-imageio[ffmpeg]==2.37.2
-    # via
-    #   gym-aloha
-    #   gym-hil
-    #   lerobot
-    #   metaworld
-    #   robomimic
-    #   scikit-image
-imageio-ffmpeg==0.6.0
-    # via
-    #   imageio
-    #   robomimic
-importlib-metadata==8.7.1
-    # via diffusers
-iniconfig==2.3.0
-    # via pytest
-ipython==9.11.0
-    # via meshcat
-ipython-pygments-lexers==1.1.1
-    # via ipython
-ischedule==1.2.7
-    # via placo
-jedi==0.19.2
-    # via ipython
-jinja2==3.1.6
-    # via torch
-jsonlines==4.0.0
-    # via lerobot
-jsonschema==4.26.0
-    # via nbformat
-jsonschema-specifications==2025.9.1
-    # via jsonschema
-jupyter-core==5.9.1
-    # via nbformat
-jupytext==1.19.1
-    # via bddl
-kiwisolver==1.4.9
-    # via matplotlib
-labmaze==1.0.6
-    # via dm-control
-lazy-loader==0.5
-    # via scikit-image
-librt==0.8.1
-    # via mypy
-llvmlite==0.46.0
-    # via numba
-lxml==6.0.2
-    # via dm-control
-markdown==3.10.2
-    # via tensorboard
-markdown-it-py==4.0.0
-    # via
-    #   jupytext
-    #   mdit-py-plugins
-    #   rich
-markupsafe==3.0.3
-    # via
-    #   jinja2
-    #   werkzeug
-matplotlib==3.10.8
-    # via
-    #   hf-libero
-    #   lerobot
-matplotlib-inline==0.2.1
-    # via ipython
-mdit-py-plugins==0.5.0
-    # via jupytext
-mdurl==0.1.2
-    # via markdown-it-py
-mergedeep==1.3.4
-    # via draccus
-meshcat==0.3.2
-    # via placo
-metaworld==3.0.0
-    # via lerobot
-mock-serial==0.0.1
-    # via lerobot
-mpmath==1.3.0
-    # via sympy
-mujoco==3.5.0
-    # via
-    #   dm-control
-    #   gym-aloha
-    #   gym-hil
-    #   hf-libero
-    #   metaworld
-    #   robosuite
-multidict==6.7.1
-    # via
-    #   aiohttp
-    #   yarl
-multiprocess==0.70.18
-    # via datasets
-mypy==1.19.1
-    # via lerobot
-mypy-extensions==1.1.0
-    # via
-    #   mypy
-    #   typing-inspect
-nbformat==5.10.4
-    # via jupytext
-networkx==3.6.1
-    # via
-    #   bddl
-    #   scikit-image
-    #   torch
-nodeenv==1.10.0
-    # via pre-commit
-num2words==0.5.14
-    # via lerobot
-numba==0.64.0
-    # via robosuite
-numpy==2.2.6
-    # via
-    #   accelerate
-    #   bddl
-    #   cmeel-boost
-    #   contourpy
-    #   datasets
-    #   diffusers
-    #   dm-control
-    #   dm-env
-    #   dm-tree
-    #   gymnasium
-    #   h5py
-    #   hebi-py
-    #   hf-libero
-    #   imageio
-    #   labmaze
-    #   lerobot
-    #   matplotlib
-    #   meshcat
-    #   metaworld
-    #   mujoco
-    #   numba
-    #   opencv-python
-    #   opencv-python-headless
-    #   pandas
-    #   peft
-    #   pyquaternion
-    #   reachy2-sdk
-    #   rerun-sdk
-    #   robomimic
-    #   robosuite
-    #   scikit-image
-    #   scipy
-    #   shapely
-    #   teleop
-    #   tensorboard
-    #   tensorboardx
-    #   tifffile
-    #   torchvision
-    #   transformers
-    #   transforms3d
-nvidia-cublas-cu12==12.8.4.1
-    # via
-    #   nvidia-cudnn-cu12
-    #   nvidia-cusolver-cu12
-    #   torch
-nvidia-cuda-cupti-cu12==12.8.90
-    # via torch
-nvidia-cuda-nvrtc-cu12==12.8.93
-    # via torch
-nvidia-cuda-runtime-cu12==12.8.90
-    # via torch
-nvidia-cudnn-cu12==9.10.2.21
-    # via torch
-nvidia-cufft-cu12==11.3.3.83
-    # via torch
-nvidia-cufile-cu12==1.13.1.3
-    # via torch
-nvidia-curand-cu12==10.3.9.90
-    # via torch
-nvidia-cusolver-cu12==11.7.3.90
-    # via torch
-nvidia-cusparse-cu12==12.5.8.93
-    # via
-    #   nvidia-cusolver-cu12
-    #   torch
-nvidia-cusparselt-cu12==0.7.1
-    # via torch
-nvidia-nccl-cu12==2.27.5
-    # via torch
-nvidia-nvjitlink-cu12==12.8.93
-    # via
-    #   nvidia-cufft-cu12
-    #   nvidia-cusolver-cu12
-    #   nvidia-cusparse-cu12
-    #   torch
-nvidia-nvshmem-cu12==3.4.5
-    # via torch
-nvidia-nvtx-cu12==12.8.90
-    # via torch
-omegaconf==2.3.0
-    # via hydra-core
-opencv-python==4.13.0.92
-    # via
-    #   gym-pusht
-    #   hf-libero
-    #   reachy2-sdk
-    #   robosuite
-opencv-python-headless==4.12.0.88
-    # via lerobot
-orderly-set==5.5.0
-    # via deepdiff
-packaging==25.0
-    # via
-    #   accelerate
-    #   datasets
-    #   huggingface-hub
-    #   hydra-core
-    #   jupytext
-    #   lazy-loader
-    #   lerobot
-    #   matplotlib
-    #   peft
-    #   pytest
-    #   qwen-vl-utils
-    #   reachy2-sdk
-    #   scikit-image
-    #   tensorboard
-    #   tensorboardx
-    #   transformers
-    #   wandb
-pandas==2.3.3
-    # via
-    #   datasets
-    #   lerobot
-parso==0.8.6
-    # via jedi
-pathspec==1.0.4
-    # via mypy
-peft==0.18.1
-    # via lerobot
-pexpect==4.9.0
-    # via ipython
-pillow==12.1.1
-    # via
-    #   diffusers
-    #   imageio
-    #   matplotlib
-    #   meshcat
-    #   qwen-vl-utils
-    #   rerun-sdk
-    #   robosuite
-    #   scikit-image
-    #   tensorboard
-    #   torchvision
-pin==3.4.0
-    # via placo
-placo==0.9.16
-    # via lerobot
-platformdirs==4.9.4
-    # via
-    #   jupyter-core
-    #   python-discovery
-    #   virtualenv
-    #   wandb
-pluggy==1.6.0
-    # via
-    #   pytest
-    #   pytest-cov
-pre-commit==4.5.1
-    # via lerobot
-prompt-toolkit==3.0.52
-    # via ipython
-propcache==0.4.1
-    # via
-    #   aiohttp
-    #   yarl
-protobuf==6.31.1
-    # via
-    #   dm-control
-    #   grpcio-tools
-    #   lerobot
-    #   reachy2-sdk
-    #   reachy2-sdk-api
-    #   tensorboard
-    #   tensorboardx
-    #   wandb
-psutil==7.2.2
-    # via
-    #   accelerate
-    #   imageio
-    #   peft
-    #   robomimic
-ptyprocess==0.7.0
-    # via pexpect
-pure-eval==0.2.3
-    # via stack-data
-pyarrow==23.0.1
-    # via
-    #   datasets
-    #   rerun-sdk
-pycparser==3.0
-    # via cffi
-pydantic==2.12.5
-    # via
-    #   fastapi
-    #   wandb
-pydantic-core==2.41.5
-    # via pydantic
-pygame==2.6.1
-    # via
-    #   gym-hil
-    #   gym-pusht
-    #   lerobot
-pygments==2.19.2
-    # via
-    #   ipython
-    #   ipython-pygments-lexers
-    #   pytest
-    #   rich
-pymunk==6.11.1
-    # via
-    #   gym-pusht
-    #   lerobot
-pyngrok==7.5.1
-    # via meshcat
-pynput==1.8.1
-    # via
-    #   gym-hil
-    #   lerobot
-pyopengl==3.1.10
-    # via
-    #   dm-control
-    #   mujoco
-pyparsing==3.3.2
-    # via
-    #   dm-control
-    #   matplotlib
-pyquaternion==0.9.9
-    # via reachy2-sdk
-pyrealsense2==2.56.5.9235
-    # via lerobot
-pyserial==3.5
-    # via
-    #   dynamixel-sdk
-    #   feetech-servo-sdk
-    #   lerobot
-pytest==8.4.2
-    # via
-    #   bddl
-    #   lerobot
-    #   pytest-cov
-    #   pytest-timeout
-    #   teleop
-pytest-cov==7.0.0
-    # via lerobot
-pytest-timeout==2.4.0
-    # via lerobot
-python-dateutil==2.9.0.post0
-    # via
-    #   faker
-    #   matplotlib
-    #   pandas
-python-discovery==1.1.1
-    # via virtualenv
-python-dotenv==1.2.2
-    # via uvicorn
-python-xlib==0.33
-    # via pynput
-pytz==2026.1.post1
-    # via pandas
-pyyaml==6.0.3
-    # via
-    #   accelerate
-    #   datasets
-    #   draccus
-    #   hebi-py
-    #   huggingface-hub
-    #   jupytext
-    #   omegaconf
-    #   peft
-    #   pre-commit
-    #   pyngrok
-    #   pyyaml-include
-    #   transformers
-    #   uvicorn
-    #   wandb
-pyyaml-include==1.4.1
-    # via draccus
-pyzmq==27.1.0
-    # via
-    #   lerobot
-    #   meshcat
-qwen-vl-utils==0.0.14
-    # via lerobot
-reachy2-sdk==1.0.15
-    # via lerobot
-reachy2-sdk-api==1.0.21
-    # via reachy2-sdk
-referencing==0.37.0
-    # via
-    #   jsonschema
-    #   jsonschema-specifications
-regex==2026.2.28
-    # via
-    #   diffusers
-    #   transformers
-requests==2.32.5
-    # via
-    #   datasets
-    #   diffusers
-    #   dm-control
-    #   qwen-vl-utils
-    #   teleop
-    #   wandb
-rerun-sdk==0.26.2
-    # via lerobot
-rhoban-cmeel-jsoncpp==1.9.4.9
-    # via placo
-rich==14.3.3
-    # via typer
-robomimic==0.2.0
-    # via hf-libero
-robosuite==1.4.0
-    # via hf-libero
-rpds-py==0.30.0
-    # via
-    #   jsonschema
-    #   referencing
-safetensors==0.7.0
-    # via
-    #   accelerate
-    #   diffusers
-    #   lerobot
-    #   peft
-    #   transformers
-scikit-image==0.25.2
-    # via
-    #   gym-pusht
-    #   lerobot
-scipy==1.17.1
-    # via
-    #   dm-control
-    #   lerobot
-    #   metaworld
-    #   robosuite
-    #   scikit-image
-    #   torchdiffeq
-sentry-sdk==2.54.0
-    # via wandb
-shapely==2.1.2
-    # via gym-pusht
-shellingham==1.5.4
-    # via typer
-six==1.17.0
-    # via
-    #   pynput
-    #   python-dateutil
-    #   python-xlib
-smmap==5.0.3
-    # via gitdb
-stack-data==0.6.3
-    # via ipython
-starlette==0.52.1
-    # via fastapi
-sympy==1.14.0
-    # via torch
-teleop==0.1.4
-    # via lerobot
-tensorboard==2.20.0
-    # via robomimic
-tensorboard-data-server==0.7.2
-    # via tensorboard
-tensorboardx==2.6.4
-    # via robomimic
-termcolor==3.3.0
-    # via
-    #   lerobot
-    #   robomimic
-thop==0.1.1.post2209072238
-    # via hf-libero
-tifffile==2026.3.3
-    # via scikit-image
-tokenizers==0.22.2
-    # via transformers
-toml==0.10.2
-    # via draccus
-torch==2.10.0
-    # via
-    #   accelerate
-    #   lerobot
-    #   peft
-    #   robomimic
-    #   thop
-    #   torchdiffeq
-    #   torchvision
-torchcodec==0.10.0
-    # via lerobot
-torchdiffeq==0.2.5
-    # via lerobot
-torchvision==0.25.0
-    # via
-    #   lerobot
-    #   robomimic
-tornado==6.5.4
-    # via meshcat
-tqdm==4.67.3
-    # via
-    #   datasets
-    #   dm-control
-    #   huggingface-hub
-    #   peft
-    #   robomimic
-    #   transformers
-traitlets==5.14.3
-    # via
-    #   ipython
-    #   jupyter-core
-    #   matplotlib-inline
-    #   nbformat
-transformers==5.3.0
-    # via
-    #   hf-libero
-    #   lerobot
-    #   peft
-transforms3d==0.4.2
-    # via teleop
-triton==3.6.0
-    # via torch
-typer==0.24.1
-    # via
-    #   huggingface-hub
-    #   transformers
-typing-extensions==4.15.0
-    # via
-    #   aiosignal
-    #   anyio
-    #   etils
-    #   faker
-    #   fastapi
-    #   gymnasium
-    #   huggingface-hub
-    #   mypy
-    #   pydantic
-    #   pydantic-core
-    #   referencing
-    #   rerun-sdk
-    #   starlette
-    #   torch
-    #   typing-inspect
-    #   typing-inspection
-    #   wandb
-typing-inspect==0.9.0
-    # via draccus
-typing-inspection==0.4.2
-    # via
-    #   fastapi
-    #   pydantic
-tzdata==2025.3
-    # via pandas
-u-msgpack-python==2.8.0
-    # via meshcat
-urllib3==2.6.3
-    # via
-    #   requests
-    #   sentry-sdk
-uvicorn[standard]==0.41.0
-    # via teleop
-uvloop==0.22.1
-    # via uvicorn
-virtualenv==21.1.0
-    # via pre-commit
-wandb==0.24.2
-    # via
-    #   hf-libero
-    #   lerobot
-watchfiles==1.1.1
-    # via uvicorn
-wcwidth==0.6.0
-    # via prompt-toolkit
-websocket-client==1.9.0
-    # via teleop
-websockets==16.0
-    # via uvicorn
-werkzeug==3.1.6
-    # via tensorboard
-wrapt==2.1.2
-    # via dm-tree
-xxhash==3.6.0
-    # via datasets
-yarl==1.23.0
-    # via aiohttp
-zipp==3.23.0
-    # via
-    #   etils
-    #   importlib-metadata
-
-# The following packages are considered to be unsafe in a requirements file:
-# setuptools

requirements.in

@@ -1,9 +0,0 @@
-# requirements.in
-
-# requirements-macos.txt was generated on macOS and is platform-specific (macOS 26.3.1 25D2128 arm64).
-# Darwin MacBook-Pro.local 25.3.0 Darwin Kernel Version 25.3.0: Wed Jan 28 20:54:55 PST 2026; root:xnu-12377.91.3~2/RELEASE_ARM64_T8132 arm64
-
-# requirements-ubuntu.txt was generated on Linux and is platform-specific (Ubuntu 24.04.4 LTS x86_64).
-# Linux lerobot-linux 6.17.0-14-generic #14~24.04.1-Ubuntu SMP PREEMPT_DYNAMIC Thu Jan 15 15:52:10 UTC 2 x86_64 x86_64 x86_64 GNU/Linux
-
--e .[all]

src/lerobot/annotations/__init__.py

@@ -0,0 +1,15 @@
+#!/usr/bin/env python
+
+# Copyright 2026 The HuggingFace Inc. team. All rights reserved.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.

src/lerobot/annotations/steerable_pipeline/__init__.py

@@ -0,0 +1,36 @@
+#!/usr/bin/env python
+
+# Copyright 2026 The HuggingFace Inc. team. All rights reserved.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+"""Steerable annotation pipeline producing ``language_persistent`` and
+``language_events`` columns for LeRobot datasets.
+
+The pipeline is decomposed into three independently runnable modules whose
+outputs are staged per-episode before a final parquet rewrite:
+
+- :mod:`.modules.plan_subtasks_memory` (the ``plan`` module) — persistent styles
+- :mod:`.modules.interjections_and_speech` (the ``interjections`` module) — event styles + speech
+- :mod:`.modules.general_vqa` (the ``vqa`` module) — event-style VQA pairs
+"""
+
+from .config import AnnotationPipelineConfig
+from .validator import StagingValidator, ValidationReport
+from .writer import LanguageColumnsWriter
+
+__all__ = [
+    "AnnotationPipelineConfig",
+    "LanguageColumnsWriter",
+    "StagingValidator",
+    "ValidationReport",
+]

src/lerobot/annotations/steerable_pipeline/config.py

@@ -0,0 +1,211 @@
+#!/usr/bin/env python
+
+# Copyright 2026 The HuggingFace Inc. team. All rights reserved.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any
+
+
+@dataclass
+class PlanConfig:
+    """``plan`` module: subtasks + plan + memory + task augmentation."""
+
+    enabled: bool = True
+
+    # ``task_aug`` rephrasings at t=0 (renderer rotates ${task} among them); 0 disables.
+    n_task_rephrasings: int = 10
+
+    # Derive the task from video instead of episode_task: off / if_short / always.
+    # Affects prompts only; ``meta/tasks.parquet`` is untouched.
+    derive_task_from_video: str = "if_short"
+    derive_task_min_words: int = 3
+
+    # --- Frame input: timestamped contact sheets (always on) ---------------
+    # The subtask describe/segment passes ALWAYS render the episode as
+    # macrodata/refiner-style contact sheets: sampled frames packed into JPEG
+    # grids with each frame's timestamp burned into its corner, so the VLM
+    # cites the exact source time of a boundary directly. This is far cheaper
+    # in vision tokens than one image per frame (≈2× faster subtask generation
+    # in practice), which is why the sampling is dense by default.
+    #
+    # ``frames_per_second`` is the sampling rate: 2.0 = one frame every 0.5s.
+    frames_per_second: float = 2.0
+    # Frame budget per VLM call (= columns × rows × sheets). When a whole
+    # episode sampled at ``frames_per_second`` exceeds this, the episode is
+    # AUTOMATICALLY split into consecutive windows of
+    # ``max_frames_per_prompt`` frames each (one describe→segment call per
+    # window, still at the full ``frames_per_second`` density), and the
+    # per-window spans are merged + stitched into one contiguous cover. So an
+    # episode of any length is always covered at the full sampling density.
+    max_frames_per_prompt: int = 60
+    contact_sheet_columns: int = 5
+    contact_sheet_frames_per_sheet: int = 20
+    contact_sheet_frame_width: int = 224
+    contact_sheet_quality: int = 84
+
+    min_subtask_seconds: float = 1.5
+    plan_max_steps: int = 8
+
+    # Narrate-only grounding pass before segmenting — best defense against subtasks
+    # invented from the task text (+1 VLM call/episode).
+    subtask_describe_first: bool = True
+
+    # Emit ``style="plan"`` rows at each boundary; False = subtasks + memory only.
+    emit_plan: bool = True
+
+    # Emit ``style="memory"`` rows at each boundary; False = subtasks (+ plan) only.
+    # Symmetric counterpart of ``emit_plan``.
+    emit_memory: bool = True
+
+    # (subtask spans are always stitched to a contiguous full-episode cover; not configurable.)
+
+    # Optional EgoMimic-style 5-axis task augmentation; replaces n_task_rephrasings.
+    task_aug_axes: TaskAugAxesConfig = field(default_factory=lambda: TaskAugAxesConfig())
+
+
+@dataclass
+class TaskAugAxesConfig:
+    """5-axis t=0 task augmentation (EgoMimic-style): synonym / omit_arm /
+    omit_orientation / omit_grasp_method / combined. Replaces n_task_rephrasings
+    when enabled; each variant becomes a ``task_aug`` row. Axes with nothing to
+    omit emit fewer entries. Defaults (3+3+2+2+2) match EgoMimic."""
+
+    enabled: bool = False
+
+    synonym_paraphrase: int = 3
+    omit_arm: int = 3
+    omit_orientation: int = 2
+    omit_grasp_method: int = 2
+    combined_omissions: int = 2
+
+
+@dataclass
+class InterjectionsConfig:
+    """``interjections`` module: interjections + paired speech."""
+
+    enabled: bool = True
+
+    # Each emits a paired (interjection, speech) row + a plan refresh at that ts.
+    max_interjections_per_episode: int = 3
+    interjection_min_t: float = 2.0
+
+    # Frame window centered on the timestamp so the VLM sees motion, not one frame.
+    interjection_window_seconds: float = 2.0
+    interjection_window_frames: int = 4
+
+
+@dataclass
+class VqaConfig:
+    """``vqa`` module: general VQA."""
+
+    enabled: bool = True
+    vqa_emission_hz: float = 1.0
+    K: int = 1
+    """Consecutive frames per emission tick. The VLM grounds on the FIRST frame,
+    so K>1 smears stale labels onto moved frames. Default 1 (no smear)."""
+    question_types: tuple[str, ...] = ("bbox", "keypoint", "count", "attribute", "spatial")
+
+    # True: ground VQA only on --vlm.camera_key (default: every camera).
+    restrict_to_default_camera: bool = False
+
+
+@dataclass
+class VlmConfig:
+    """Shared Qwen-VL client configuration."""
+
+    # Only ``openai`` (OpenAI-compatible vLLM server, auto-spawned when
+    # auto_serve=True); ``stub`` is for tests.
+    backend: str = "openai"
+    model_id: str = "Qwen/Qwen3.6-27B"
+
+    # OpenAI-compatible endpoint; ``EMPTY`` key works for local servers.
+    api_base: str = "http://localhost:8000/v1"
+    api_key: str = "EMPTY"
+
+    # Spawn a server if none answers api_base; False = fail fast on a remote.
+    auto_serve: bool = True
+    serve_port: int = 8000
+    # Override the auto-serve command; ``{port}`` substituted per replica.
+    serve_command: str | None = None
+
+    # Independent servers for round-robin routing (one per GPU). num_gpus=0 = one each.
+    parallel_servers: int = 1
+    num_gpus: int = 0
+    client_concurrency: int = 16
+    serve_ready_timeout_s: float = 600.0
+
+    max_new_tokens: int = 512
+    temperature: float = 0.2
+
+    # Auto-serve context length (None → 32768); other vLLM flags go in serve_command.
+    max_model_len: int | None = None
+
+    # Camera for keyframes; None → first ``observation.images.*`` key.
+    camera_key: str | None = None
+    # Forwarded as extra_body.chat_template_kwargs (e.g. {"enable_thinking": false}).
+    chat_template_kwargs: dict[str, Any] | None = None
+
+
+@dataclass
+class ExecutorConfig:
+    """Executor settings (intra-process episode concurrency; distribution via HF Jobs)."""
+
+    # Episodes processed concurrently per phase; main knob for saturating the servers.
+    episode_parallelism: int = 16
+
+
+@dataclass
+class AnnotationPipelineConfig:
+    """Top-level config for ``lerobot-annotate`` (rewrites data shards in place)."""
+
+    # Hub dataset: download source when ``root`` unset; push target when push_to_hub
+    # is on and ``new_repo_id`` unset.
+    repo_id: str | None = None
+
+    # Separate push target (matches the LeRobot edit tools). Unset → push in place.
+    new_repo_id: str | None = None
+
+    root: Path | None = None
+
+    # Defaults to ``<root>/.annotate_staging/``.
+    staging_dir: Path | None = None
+
+    seed: int = 1729
+
+    plan: PlanConfig = field(default_factory=PlanConfig)
+    interjections: InterjectionsConfig = field(default_factory=InterjectionsConfig)
+    vqa: VqaConfig = field(default_factory=VqaConfig)
+
+    vlm: VlmConfig = field(default_factory=VlmConfig)
+    executor: ExecutorConfig = field(default_factory=ExecutorConfig)
+
+    skip_validation: bool = False
+    only_episodes: tuple[int, ...] | None = None
+
+    # Keyframe decode backend forwarded to ``decode_video_frames``. None →
+    # library default (torchcodec when available, else PyAV). Or pin
+    # ``"torchcodec"`` / ``"pyav"`` explicitly.
+    video_backend: str | None = None
+
+    # Upload to the Hub (new_repo_id if set, else repo_id; one must be set).
+    push_to_hub: bool = False
+    push_private: bool = False
+    push_commit_message: str | None = None
+
+    def resolved_staging_dir(self, root: Path) -> Path:
+        return self.staging_dir if self.staging_dir is not None else root / ".annotate_staging"

src/lerobot/annotations/steerable_pipeline/executor.py

@@ -0,0 +1,253 @@
+#!/usr/bin/env python
+
+# Copyright 2026 The HuggingFace Inc. team. All rights reserved.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+"""In-process executor that runs the annotation phases.
+
+The executor runs **six phases** in dependency order:
+
+    phase 1: ``plan`` module (plan + subtasks + memory)
+    phase 2: ``interjections`` module (interjections + speech)
+    phase 3: ``plan`` plan-update pass — re-runs plan emission at every
+             interjection timestamp produced by phase 2
+    phase 4: ``vqa`` module (VQA)
+    phase 5: validator
+    phase 6: writer
+
+Phase 3 is why the ``plan`` module must be re-entered after the
+``interjections`` module — to refresh ``plan`` rows at interjection
+timestamps.
+
+Distributed execution is provided by Hugging Face Jobs (see
+``examples/annotations/run_hf_job.py``); the runner inside the job
+invokes ``lerobot-annotate`` which uses this in-process executor.
+Episode-level concurrency is controlled by
+``ExecutorConfig.episode_parallelism``.
+"""
+
+from __future__ import annotations
+
+import logging
+import time
+from concurrent.futures import ThreadPoolExecutor, as_completed
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any
+
+from .config import AnnotationPipelineConfig
+from .reader import EpisodeRecord, iter_episodes
+from .staging import EpisodeStaging
+from .validator import StagingValidator
+from .writer import LanguageColumnsWriter
+
+logger = logging.getLogger(__name__)
+
+
+@dataclass
+class PhaseResult:
+    """Summary of one pipeline phase across all episodes."""
+
+    name: str
+    episodes_processed: int
+    episodes_skipped: int
+
+
+@dataclass
+class PipelineRunSummary:
+    """Aggregated result returned by :meth:`Executor.run`."""
+
+    phases: list[PhaseResult]
+    written_paths: list[Path]
+    validation_report: Any  # ValidationReport, kept Any to avoid import cycle
+
+
+@dataclass
+class Executor:
+    """Run all six phases over a dataset root in-process.
+
+    Episode-level concurrency comes from ``ExecutorConfig.episode_parallelism``
+    (a thread pool); cluster-level concurrency comes from running this
+    executor inside a Hugging Face Job. Tests construct the executor
+    directly with stub modules.
+    """
+
+    config: AnnotationPipelineConfig
+    plan: Any  # PlanSubtasksMemoryModule
+    interjections: Any  # InterjectionsAndSpeechModule
+    vqa: Any  # GeneralVqaModule
+    writer: LanguageColumnsWriter
+    validator: StagingValidator
+
+    def run(self, root: Path) -> PipelineRunSummary:
+        records = list(iter_episodes(root, only_episodes=self.config.only_episodes))
+        n = len(records)
+        if n == 0:
+            raise ValueError(f"No episodes found under {root}/data/")
+
+        print(f"[annotate] {n} episodes total", flush=True)
+
+        staging_dir = self.config.resolved_staging_dir(root)
+        staging_dir.mkdir(parents=True, exist_ok=True)
+
+        phases: list[PhaseResult] = []
+
+        # Phase 1: ``plan`` module (plan + subtasks + memory)
+        phases.append(self._run_module_phase("plan", records, staging_dir, self.plan))
+        # Phase 2: ``interjections`` module (interjections + speech). It
+        # reads the ``plan`` module's subtask rows from the same staging
+        # tree to ground the interjection prompt in the correct local subtask.
+        phases.append(self._run_module_phase("interjections", records, staging_dir, self.interjections))
+        # Phase 3: ``plan`` plan-update pass at interjection timestamps.
+        phases.append(self._run_plan_update_phase(records, staging_dir))
+        # Phase 4: ``vqa`` module (VQA)
+        phases.append(self._run_module_phase("vqa", records, staging_dir, self.vqa))
+
+        print("[annotate] running validator...", flush=True)
+        report = self.validator.validate(records, staging_dir)
+        if not report.ok and not self.config.skip_validation:
+            raise RuntimeError(f"Staging validation failed: {report.summary()}")
+        print(f"[annotate] validator: {report.summary()}", flush=True)
+
+        print(f"[annotate] writing parquet shards into {root}/data/...", flush=True)
+        written = self.writer.write_all(records, staging_dir, root)
+        print(f"[annotate] wrote {len(written)} shard(s); pipeline complete", flush=True)
+
+        # Keep meta/info.json aligned with the parquet schema we just wrote.
+        # Idempotent and additive: existing user metadata is preserved.
+        self._ensure_annotation_metadata_in_info(root)
+
+        return PipelineRunSummary(phases=phases, written_paths=written, validation_report=report)
+
+    @staticmethod
+    def _ensure_annotation_metadata_in_info(root: Path) -> None:
+        """Write language features and canonical tools to ``meta/info.json``.
+
+        ``LanguageColumnsWriter`` adds ``language_persistent`` and
+        ``language_events`` to parquet shards. The metadata must advertise
+        those columns too, otherwise non-streaming ``LeRobotDataset`` loads
+        cast against the old schema and fail on the extra parquet columns.
+        """
+        from lerobot.datasets.io_utils import load_info, write_info  # noqa: PLC0415
+        from lerobot.datasets.language import SAY_TOOL_SCHEMA, language_feature_info  # noqa: PLC0415
+
+        info_path = root / "meta" / "info.json"
+        if not info_path.exists():
+            return
+        try:
+            info = load_info(root)
+        except Exception as exc:  # noqa: BLE001
+            print(f"[annotate] could not read {info_path}: {exc}", flush=True)
+            return
+
+        changed = False
+
+        merged_features = {**info.features, **language_feature_info()}
+        if merged_features != info.features:
+            info.features = merged_features
+            changed = True
+
+        existing = info.tools or []
+        names = {(t.get("function") or {}).get("name") for t in existing if isinstance(t, dict)}
+        if SAY_TOOL_SCHEMA["function"]["name"] not in names:
+            info.tools = [*existing, SAY_TOOL_SCHEMA]
+            changed = True
+
+        if changed:
+            write_info(info, root)
+            print(
+                "[annotate] meta/info.json: "
+                f"language_features={list(language_feature_info())}, "
+                f"tools={[t['function']['name'] for t in (info.tools or [])]}",
+                flush=True,
+            )
+
+    def _run_module_phase(
+        self,
+        name: str,
+        records: list[EpisodeRecord],
+        staging_dir: Path,
+        module: Any,
+    ) -> PhaseResult:
+        if not module.enabled:
+            print(f"[annotate] phase={name} skipped (module disabled)", flush=True)
+            return PhaseResult(name=name, episodes_processed=0, episodes_skipped=len(records))
+        n = len(records)
+        parallelism = max(1, min(self.config.executor.episode_parallelism, n))
+        print(
+            f"[annotate] phase={name} starting on {n} episode(s) (parallelism={parallelism})",
+            flush=True,
+        )
+        t0 = time.time()
+
+        def _do(idx_record: tuple[int, EpisodeRecord]) -> tuple[int, int, float]:
+            i, record = idx_record
+            ep_start = time.time()
+            staging = EpisodeStaging(staging_dir, record.episode_index)
+            module.run_episode(record, staging)
+            return i, record.episode_index, time.time() - ep_start
+
+        processed = 0
+        if parallelism == 1:
+            for i, record in enumerate(records, 1):
+                _, ep_idx, elapsed = _do((i, record))
+                processed += 1
+                print(
+                    f"[annotate]   {name} episode {i}/{n} (idx={ep_idx}) done in {elapsed:.1f}s",
+                    flush=True,
+                )
+        else:
+            with ThreadPoolExecutor(max_workers=parallelism) as pool:
+                futures = [pool.submit(_do, (i, r)) for i, r in enumerate(records, 1)]
+                for fut in as_completed(futures):
+                    i, ep_idx, elapsed = fut.result()
+                    processed += 1
+                    print(
+                        f"[annotate]   {name} episode {processed}/{n} "
+                        f"(idx={ep_idx}, submit_order={i}) done in {elapsed:.1f}s",
+                        flush=True,
+                    )
+        total = time.time() - t0
+        print(f"[annotate] phase={name} complete: {processed}/{n} in {total:.1f}s", flush=True)
+        return PhaseResult(name=name, episodes_processed=processed, episodes_skipped=0)
+
+    def _run_plan_update_phase(  # noqa: PLR0915
+        self, records: list[EpisodeRecord], staging_dir: Path
+    ) -> PhaseResult:
+        """Re-emit ``plan`` rows at each timestamp the ``interjections`` module produced.
+
+        The ``plan`` module owns the prompt; the ``interjections`` module
+        produced the timestamps. This phase therefore calls back into the
+        ``plan`` module with the interjection timestamps so its existing
+        prompt path is reused.
+        """
+        if not self.plan.enabled or not self.interjections.enabled:
+            return PhaseResult(name="plan_update", episodes_processed=0, episodes_skipped=len(records))
+        processed = 0
+        for record in records:
+            staging = EpisodeStaging(staging_dir, record.episode_index)
+            interjection_rows = [
+                row for row in staging.read("interjections") if row.get("style") == "interjection"
+            ]
+            interjection_times = [float(row["timestamp"]) for row in interjection_rows]
+            interjection_texts = [str(row.get("content") or "") for row in interjection_rows]
+            if interjection_times:
+                self.plan.run_plan_updates(record, staging, interjection_times, interjection_texts)
+                processed += 1
+        # Episodes without any interjections are skipped (no plan refresh
+        # needed); count them so the summary's processed+skipped == total.
+        return PhaseResult(
+            name="plan_update",
+            episodes_processed=processed,
+            episodes_skipped=len(records) - processed,
+        )

src/lerobot/annotations/steerable_pipeline/frames.py

@@ -0,0 +1,483 @@
+#!/usr/bin/env python
+
+# Copyright 2026 The HuggingFace Inc. team. All rights reserved.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+"""Keyframe extraction for the annotation pipeline.
+
+Modules attach decoded camera frames to their VLM prompts so the model can
+ground subtask decomposition, interjection scenarios, and VQA in actual
+visual content. The pipeline shares one provider across modules and one
+episode at a time, with a small per-episode cache so multiple modules
+querying the same timestamp pay decode cost once.
+"""
+
+from __future__ import annotations
+
+import io
+import logging
+import math
+import threading
+from collections.abc import Sequence
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any, Protocol
+
+import PIL.Image
+import torch
+
+from lerobot.configs import RGBEncoderConfig
+from lerobot.datasets.video_utils import decode_video_frames, reencode_video
+
+from .reader import EpisodeRecord, snap_to_frame
+
+logger = logging.getLogger(__name__)
+
+
+class FrameProvider(Protocol):
+    """Decodes camera frames at episode-relative timestamps."""
+
+    @property
+    def camera_keys(self) -> list[str]:
+        """All ``observation.images.*`` feature keys this provider can decode."""
+
+    def frames_at(
+        self,
+        record: EpisodeRecord,
+        timestamps: list[float],
+        camera_key: str | None = None,
+    ) -> list[Any]:
+        """Return one decoded frame per timestamp from ``camera_key`` (or default).
+
+        Frames are ``torch.Tensor`` (``C, H, W`` uint8) — the shape
+        :func:`lerobot.datasets.video_utils.decode_video_frames` returns.
+        :func:`to_image_blocks` converts them to PIL only at the VLM-message
+        boundary.
+
+        Empty list if the camera is unavailable. ``camera_key=None`` falls back
+        to the provider's default camera so existing single-camera callers
+        (the ``plan`` and ``interjections`` modules) keep working unchanged.
+        """
+
+    def video_for_episode(
+        self,
+        record: EpisodeRecord,
+        max_frames: int,
+        camera_key: str | None = None,
+    ) -> list[Any]:
+        """Return up to ``max_frames`` decoded frames covering the whole episode.
+
+        Sampling is uniform across the episode duration. Frames are
+        ``torch.Tensor`` (``C, H, W`` uint8); :func:`to_video_block` wraps
+        them into one ``{"type":"video", "video":<list>}`` block for a
+        Qwen-VL-compatible model that pools temporally itself. Empty list if
+        no camera available.
+        """
+
+
+@dataclass
+class _NullProvider:
+    """No-op provider used when the dataset has no video keys or in tests."""
+
+    @property
+    def camera_keys(self) -> list[str]:
+        return []
+
+    def frames_at(
+        self,
+        record: EpisodeRecord,
+        timestamps: list[float],
+        camera_key: str | None = None,
+    ) -> list[Any]:
+        return []
+
+    def video_for_episode(
+        self,
+        record: EpisodeRecord,
+        max_frames: int,
+        camera_key: str | None = None,
+    ) -> list[Any]:
+        return []
+
+
+def null_provider() -> FrameProvider:
+    return _NullProvider()
+
+
+@dataclass
+class VideoFrameProvider:
+    """Decodes frames from the dataset's ``observation.images.*`` streams.
+
+    By default the *first* camera key is used for the ``plan`` module
+    (subtask decomposition) and the ``interjections`` module (interjection
+    scenarios) — those prompts care about *what is happening*, not which
+    angle. The ``vqa`` module instead iterates over every camera in
+    :attr:`camera_keys` so each frame's
+    grounded answer (bbox/keypoint/...) is tagged with the camera it was
+    grounded against.
+
+    ``camera_key`` overrides the default-camera choice but does not restrict
+    :attr:`camera_keys`. Pass ``camera_key`` explicitly to ``frames_at`` /
+    ``video_for_episode`` to read a non-default stream.
+
+    Caches up to ``cache_size`` decoded frames per process to keep
+    co-timestamped ``interjections`` + ``plan`` plan-update calls cheap.
+    """
+
+    root: Path
+    camera_key: str | None = None
+    tolerance_s: float = 1e-2
+    cache_size: int = 256
+    # Keyframe decode backend forwarded to
+    # :func:`lerobot.datasets.video_utils.decode_video_frames`. ``None``
+    # uses the library default (torchcodec when available, else PyAV).
+    video_backend: str | None = None
+    _meta: Any = field(default=None, init=False, repr=False)
+    _cache: dict = field(default_factory=dict, init=False, repr=False)
+    _camera_keys: list[str] = field(default_factory=list, init=False, repr=False)
+    # Pipeline runs the three module phases under a ThreadPoolExecutor (see
+    # ``ExecutorConfig.episode_parallelism``); guard the dict cache and the
+    # one-shot warn flag against concurrent updates from worker threads.
+    _lock: threading.Lock = field(default_factory=threading.Lock, init=False, repr=False)
+    # Serializes decode_video_frames calls: torchcodec hands out one
+    # ``VideoDecoder`` per file from a process-wide cache, and the decoder
+    # is not safe to drive from multiple threads at once.
+    _decode_lock: threading.Lock = field(default_factory=threading.Lock, init=False, repr=False)
+    _warned_decode_fail: bool = field(default=False, init=False, repr=False)
+
+    def __post_init__(self) -> None:
+        from lerobot.datasets.dataset_metadata import LeRobotDatasetMetadata  # noqa: PLC0415
+
+        self._meta = LeRobotDatasetMetadata(repo_id="local", root=self.root)
+        # Only ``video_keys`` are decodable here: the clip/decode paths read
+        # ``videos/<key>/from_timestamp`` from episode metadata, which exists
+        # only for video-stored cameras. Image-stored cameras (also in
+        # ``camera_keys``) would KeyError, so restrict the list — and the
+        # default — to video keys.
+        # Depth cameras are excluded from the annotation pipeline for now.
+        depth_keys = set(self._meta.depth_keys)
+        keys = [key for key in self._meta.video_keys if key not in depth_keys]
+        # Last-resort fallback: if metadata didn't surface any video keys but
+        # the caller explicitly named a camera (``--vlm.camera_key=...``),
+        # trust them — the key is by definition known to exist on the dataset.
+        if not keys and self.camera_key:
+            keys = [self.camera_key]
+        self._camera_keys = keys
+        if self.camera_key is None:
+            self.camera_key = keys[0] if keys else None
+
+    @property
+    def camera_keys(self) -> list[str]:
+        """All ``observation.images.*`` keys available on this dataset."""
+        return list(self._camera_keys)
+
+    def frames_at(
+        self,
+        record: EpisodeRecord,
+        timestamps: list[float],
+        camera_key: str | None = None,
+    ) -> list[Any]:
+        target = camera_key if camera_key is not None else self.camera_key
+        if not timestamps or target is None:
+            return []
+        # Snap each request to the nearest real frame timestamp: callers
+        # sample uniform grids whose points land mid-frame, and
+        # ``decode_video_frames`` rejects queries farther than
+        # ``tolerance_s`` from a decodable frame. Snapping also dedupes
+        # repeat queries through the cache.
+        if record.frame_timestamps:
+            timestamps = [snap_to_frame(float(ts), record.frame_timestamps) for ts in timestamps]
+
+        out: list[Any] = []
+        misses: list[float] = []
+        miss_indices: list[int] = []
+        with self._lock:
+            for i, ts in enumerate(timestamps):
+                key = (record.episode_index, target, round(float(ts), 6))
+                cached = self._cache.get(key)
+                if cached is not None:
+                    out.append(cached)
+                else:
+                    out.append(None)
+                    misses.append(float(ts))
+                    miss_indices.append(i)
+
+        if misses:
+            decoded = self._decode(record.episode_index, misses, target)
+            # ``_decode`` returns exactly one frame per requested timestamp,
+            # or an empty list if decoding failed wholesale. A partial list
+            # would mean a frame/timestamp misalignment, so only pair them up
+            # when the counts match (``strict=True`` then guards regressions).
+            if len(decoded) == len(miss_indices):
+                with self._lock:
+                    for i, frame in zip(miss_indices, decoded, strict=True):
+                        out[i] = frame
+                        key = (record.episode_index, target, round(float(timestamps[i]), 6))
+                        if len(self._cache) >= self.cache_size:
+                            self._cache.pop(next(iter(self._cache)))
+                        self._cache[key] = frame
+        # filter out any None left over from decode failures
+        return [frame for frame in out if frame is not None]
+
+    def video_for_episode(
+        self,
+        record: EpisodeRecord,
+        max_frames: int,
+        camera_key: str | None = None,
+    ) -> list[Any]:
+        """Return up to ``max_frames`` frames uniformly sampled across the episode.
+
+        The whole episode duration is covered; the model picks subtask
+        boundaries from the temporal pooling it does internally. Frames are
+        ``torch.Tensor`` (see :meth:`frames_at`).
+        """
+        target = camera_key if camera_key is not None else self.camera_key
+        if max_frames <= 0 or target is None or not record.frame_timestamps:
+            return []
+        n_frames = min(max_frames, len(record.frame_timestamps))
+        if n_frames == len(record.frame_timestamps):
+            timestamps = list(record.frame_timestamps)
+        else:
+            t0 = record.frame_timestamps[0]
+            t_last = record.frame_timestamps[-1]
+            if t_last <= t0:
+                timestamps = [float(t0)] * n_frames
+            else:
+                step = (t_last - t0) / (n_frames - 1) if n_frames > 1 else 0.0
+                timestamps = [float(t0 + i * step) for i in range(n_frames)]
+        return self.frames_at(record, timestamps, camera_key=target)
+
+    def episode_clip_path(self, record: EpisodeRecord, cache_dir: Path) -> Path | None:
+        """Extract the episode's subclip to ``cache_dir/ep_{idx:06d}.mp4``.
+
+        Returns ``None`` if the dataset has no video tracks or extraction
+        failed. Skips re-extract when the cached clip already exists.
+        Re-encodes to H.264 via
+        :func:`lerobot.datasets.video_utils.reencode_video` so the resulting
+        mp4 is decodable by every downstream video processor — stream-copy
+        would inherit the source codec (often AV1 in modern LeRobot
+        datasets), which vllm's libav build cannot decode.
+        """
+        if self.camera_key is None:
+            return None
+        cache_dir.mkdir(parents=True, exist_ok=True)
+        out_path = cache_dir / f"ep_{record.episode_index:06d}.mp4"
+        if out_path.exists() and out_path.stat().st_size > 0:
+            return out_path
+        ep = self._meta.episodes[record.episode_index]
+        from_timestamp = float(ep[f"videos/{self.camera_key}/from_timestamp"])
+        to_timestamp = float(ep[f"videos/{self.camera_key}/to_timestamp"])
+        src = self.root / self._meta.get_video_file_path(record.episode_index, self.camera_key)
+        encoder = RGBEncoderConfig(vcodec="h264", pix_fmt="yuv420p", g=None, crf=23, preset="ultrafast")
+        try:
+            reencode_video(
+                src,
+                out_path,
+                video_encoder=encoder,
+                overwrite=True,
+                start_time_s=from_timestamp,
+                end_time_s=to_timestamp,
+            )
+        except Exception:
+            logger.warning(
+                "clip extraction failed for episode %s (%s)", record.episode_index, src, exc_info=True
+            )
+            return None
+        return out_path if out_path.exists() and out_path.stat().st_size > 0 else None
+
+    def _decode(self, episode_index: int, timestamps: list[float], camera_key: str) -> list[Any]:
+        """Decode ``timestamps`` from the episode's video as ``(C, H, W)`` tensors.
+
+        Delegates to :func:`lerobot.datasets.video_utils.decode_video_frames`
+        (torchcodec when available, PyAV otherwise; ``video_backend`` pins
+        one explicitly). Returns one frame per requested timestamp, or ``[]``
+        if decoding failed — callers treat ``[]`` as "no frames available".
+        """
+        ep = self._meta.episodes[episode_index]
+        from_timestamp = ep[f"videos/{camera_key}/from_timestamp"]
+        shifted = [from_timestamp + ts for ts in timestamps]
+        video_path = self.root / self._meta.get_video_file_path(episode_index, camera_key)
+
+        try:
+            # The module phases decode under a ThreadPoolExecutor (see
+            # ``ExecutorConfig.episode_parallelism``) but torchcodec's cached
+            # per-file decoder is single-threaded, so serialize decodes on a
+            # dedicated lock. Frame extraction is a small fraction of episode
+            # wall time (VLM calls dominate), so the contention is cheap.
+            with self._decode_lock:
+                # Stacked ``(N, C, H, W)`` uint8 tensor; one row per timestamp.
+                decoded = decode_video_frames(
+                    video_path, shifted, self.tolerance_s, backend=self.video_backend, return_uint8=True
+                )
+            return list(decoded)
+        except Exception as exc:
+            # Log loudly the first time so a silent vqa-module no-op (every
+            # prompt skipped because frames_at returned []) is debuggable from
+            # the job log instead of post-hoc parquet inspection. Subsequent
+            # failures stay quiet.
+            with self._lock:
+                already_warned = self._warned_decode_fail
+                if not already_warned:
+                    self._warned_decode_fail = True
+            if not already_warned:
+                logger.warning(
+                    "VideoFrameProvider._decode failed for episode=%s camera=%s video_path=%s backend=%s: %s",
+                    episode_index,
+                    camera_key,
+                    video_path,
+                    self.video_backend,
+                    exc,
+                    exc_info=exc,
+                )
+            return []
+
+
+def make_frame_provider(
+    root: Path, camera_key: str | None = None, video_backend: str | None = None
+) -> FrameProvider:
+    """Build a :class:`VideoFrameProvider` if videos are present, else null."""
+    try:
+        provider = VideoFrameProvider(root=root, camera_key=camera_key, video_backend=video_backend)
+    except Exception:
+        return null_provider()
+    if provider.camera_key is None:
+        return null_provider()
+    return provider
+
+
+def _frame_to_pil(frame: Any) -> Any:
+    """Materialise a decoded frame as a ``PIL.Image`` for the VLM message.
+
+    Frames flow through the provider as ``torch.Tensor`` (``C, H, W`` uint8,
+    straight from :func:`decode_video_frames`); PIL is only created here, at
+    the VLM-message boundary, because the chat backends expect PIL images /
+    data URLs. Non-tensor inputs (e.g. test stubs) pass through untouched.
+    """
+    if not isinstance(frame, torch.Tensor):
+        return frame
+    array = frame.detach().cpu()
+    if array.ndim == 3 and array.shape[0] in (1, 3):
+        array = array.permute(1, 2, 0)  # (C, H, W) -> (H, W, C)
+    if array.shape[-1] == 1:
+        array = array.squeeze(-1)
+    return PIL.Image.fromarray(array.to(torch.uint8).numpy())
+
+
+def to_image_blocks(frames: list[Any]) -> list[dict[str, Any]]:
+    """Convert decoded frames to Qwen-VL-compatible image content blocks."""
+    return [{"type": "image", "image": _frame_to_pil(frame)} for frame in frames]
+
+
+def to_video_block(frames: list[Any]) -> list[dict[str, Any]]:
+    """Wrap a list of decoded frames as one Qwen-VL video block.
+
+    Returns ``[]`` when the list is empty, so the caller can splat the result
+    into a content array without a separate emptiness check.
+    """
+    if not frames:
+        return []
+    return [{"type": "video", "video": [_frame_to_pil(frame) for frame in frames]}]
+
+
+def to_video_url_block(url: str | None, fps: float = 2.0) -> list[dict[str, Any]]:
+    """Wrap a video file URL as one ``video_url`` block.
+
+    Used by the ``openai`` backend (transformers serve / vllm serve /
+    ktransformers serve), where the server handles frame sampling.
+    Returns ``[]`` when ``url`` is ``None`` so the caller can splat.
+    """
+    if not url:
+        return []
+    return [{"type": "video_url", "video_url": {"url": url}, "fps": fps}]
+
+
+def _draw_timestamp_badge(image: PIL.Image.Image, timestamp: float) -> PIL.Image.Image:
+    """Burn ``timestamp`` (seconds) into the top-left corner of ``image``.
+
+    A solid black badge with white text, so a VLM reading a contact sheet can
+    cite the exact source time of each tile (e.g. ``012.50s``) directly,
+    instead of the caller having to map tile position back to time. Mirrors
+    the macrodata/refiner contact-sheet convention.
+    """
+    from PIL import ImageDraw, ImageFont
+
+    result = image.copy()
+    draw = ImageDraw.Draw(result)
+    font = ImageFont.load_default()
+    label = f"{timestamp:06.2f}s"
+    left, top, right, bottom = draw.textbbox((0, 0), label, font=font)
+    text_w, text_h = right - left, bottom - top
+    pad = max(3, round(min(image.width, image.height) * 0.018))
+    draw.rectangle((0, 0, text_w + pad * 2, text_h + pad * 2), fill=(0, 0, 0))
+    draw.text((pad - left, pad - top), label, fill=(255, 255, 255), font=font)
+    return result
+
+
+def to_contact_sheet_blocks(
+    frames: Sequence[Any],
+    timestamps: Sequence[float],
+    *,
+    columns: int = 5,
+    frames_per_sheet: int = 20,
+    frame_width: int = 224,
+    quality: int = 84,
+) -> list[dict[str, Any]]:
+    """Pack decoded frames into timestamped JPEG contact-sheet image blocks.
+
+    Each frame is resized to ``frame_width`` wide, stamped with its
+    episode-relative timestamp, and tiled row-major into grids of
+    ``frames_per_sheet`` (``columns`` wide). One ``{"type":"image", ...}``
+    block is returned per grid; many frames collapse into a few images, so a
+    long episode's temporal coverage stays dense at a fraction of the vision
+    tokens N separate frames would cost. ``frames`` and ``timestamps`` must be
+    aligned and equal length. Returns ``[]`` for empty input.
+    """
+    from PIL import Image
+
+    if not frames:
+        return []
+    columns = max(1, columns)
+    frames_per_sheet = max(1, frames_per_sheet)
+    rows_per_sheet = math.ceil(frames_per_sheet / columns)
+
+    tiles: list[PIL.Image.Image] = []
+    for ts, frame in zip(timestamps, frames, strict=False):
+        img = _frame_to_pil(frame)
+        if not isinstance(img, PIL.Image.Image):
+            continue
+        img = img.convert("RGB")
+        if img.width != frame_width:
+            height = max(1, round(img.height * frame_width / img.width))
+            img = img.resize((frame_width, height), resample=Image.Resampling.BILINEAR)
+        tiles.append(_draw_timestamp_badge(img, float(ts)))
+    if not tiles:
+        return []
+
+    blocks: list[dict[str, Any]] = []
+    for start in range(0, len(tiles), frames_per_sheet):
+        chunk = tiles[start : start + frames_per_sheet]
+        cell_w = max(tile.width for tile in chunk)
+        cell_h = max(tile.height for tile in chunk)
+        sheet = Image.new("RGB", (cell_w * columns, cell_h * rows_per_sheet), color=(0, 0, 0))
+        for i, tile in enumerate(chunk):
+            x = (i % columns) * cell_w
+            y = (i // columns) * cell_h
+            sheet.paste(tile, (x, y))
+        # JPEG round-trip at ``quality`` to match the refiner convention and
+        # shrink the wire payload; vision-token count is set by resolution, so
+        # the real saving is the grid packing, not the codec.
+        buf = io.BytesIO()
+        sheet.save(buf, format="JPEG", quality=quality)
+        buf.seek(0)
+        blocks.append({"type": "image", "image": Image.open(buf).convert("RGB")})
+    return blocks

src/lerobot/annotations/steerable_pipeline/modules/__init__.py

@@ -0,0 +1,25 @@
+#!/usr/bin/env python
+
+# Copyright 2026 The HuggingFace Inc. team. All rights reserved.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+from .general_vqa import GeneralVqaModule
+from .interjections_and_speech import InterjectionsAndSpeechModule
+from .plan_subtasks_memory import PlanSubtasksMemoryModule
+
+__all__ = [
+    "GeneralVqaModule",
+    "InterjectionsAndSpeechModule",
+    "PlanSubtasksMemoryModule",
+]

src/lerobot/annotations/steerable_pipeline/modules/general_vqa.py

@@ -0,0 +1,248 @@
+#!/usr/bin/env python
+
+# Copyright 2026 The HuggingFace Inc. team. All rights reserved.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+"""``vqa`` module: general VQA at a timed cadence.
+
+Every ``1/hz`` seconds an emission tick fires; each tick anchors ``K``
+consecutive frames, and every anchored frame gets its own VQA pair. Each
+pair is grounded on that single anchor frame — there is no per-pair frame
+window. For datasets with multiple cameras, every anchored frame produces
+one ``(vqa, user)`` + ``(vqa, assistant)`` pair *per camera*: each pair is
+generated against that camera's frame and stamped with the matching
+``camera`` field on the emitted rows. The resolver disambiguates via
+``camera=...``; recipes that consume VQA do so through one sub-recipe
+per camera (see ``recipes/pi05_hirobot.yaml``).
+
+Within a single (frame, camera) we still emit at most one ``(vqa, user)``
+and one ``(vqa, assistant)`` row, so the resolver contract stays scalar.
+
+Question types covered (per the plan's ``vqa`` table): bbox, keypoint,
+count, attribute, spatial. The assistant's ``content`` is a JSON string
+whose schema depends on the question type. Malformed JSON triggers one
+retry inside :meth:`VlmClient.generate_json`.
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+import random
+from collections.abc import Sequence
+from dataclasses import dataclass, field
+from typing import Any
+
+from ..config import VqaConfig
+from ..frames import FrameProvider, null_provider, to_image_blocks
+from ..prompts import load as load_prompt
+from ..reader import EpisodeRecord
+from ..staging import EpisodeStaging
+from ..validator import classify_vqa_answer
+from ..vlm_client import VlmClient
+
+
+def _emission_anchor_indices(frame_timestamps: Sequence[float], hz: float, k: int) -> list[int]:
+    """Return the relative frame indices to anchor VQA emissions to.
+
+    For each emission tick (every ``1/hz`` seconds), we anchor ``k``
+    consecutive frames starting at the tick. Ticks fall on the nearest
+    available source frame timestamp.
+    """
+    if hz <= 0 or k <= 0 or not frame_timestamps:
+        return []
+    t0 = frame_timestamps[0]
+    t_last = frame_timestamps[-1]
+    period = 1.0 / hz
+    indices: list[int] = []
+    t = t0
+    while t <= t_last + 1e-9:
+        # find the index of the nearest frame to t
+        nearest_i = min(range(len(frame_timestamps)), key=lambda i: abs(frame_timestamps[i] - t))
+        for offset in range(k):
+            j = nearest_i + offset
+            if j >= len(frame_timestamps):
+                break
+            if not indices or indices[-1] != j:
+                indices.append(j)
+        t += period
+    # dedupe while preserving order
+    seen: set[int] = set()
+    deduped: list[int] = []
+    for i in indices:
+        if i in seen:
+            continue
+        seen.add(i)
+        deduped.append(i)
+    return deduped
+
+
+@dataclass
+class GeneralVqaModule:
+    """Emit grounded VQA pairs at a timed cadence."""
+
+    vlm: VlmClient
+    config: VqaConfig
+    seed: int = 1729
+    frame_provider: FrameProvider = field(default_factory=null_provider)
+    _warned_no_camera: bool = field(default=False, init=False, repr=False)
+
+    @property
+    def enabled(self) -> bool:
+        return self.config.enabled
+
+    def run_episode(self, record: EpisodeRecord, staging: EpisodeStaging) -> None:
+        if not record.frame_timestamps:
+            staging.write("vqa", [])
+            return
+        rng = random.Random(f"{self.seed}:{record.episode_index}:vqa")
+        anchor_idx = _emission_anchor_indices(
+            record.frame_timestamps, self.config.vqa_emission_hz, self.config.K
+        )
+        cameras = self._target_cameras()
+        if not cameras:
+            # No camera available — emit nothing rather than producing
+            # untagged rows that would fail validation. Surface a loud one-
+            # time warning so this is never silently a no-op.
+            if not self._warned_no_camera:
+                logging.getLogger(__name__).warning(
+                    "vqa module found no cameras on the frame provider — "
+                    "every episode will emit zero VQA rows. Check that the "
+                    "dataset declares observation.images.* features in "
+                    "meta/info.json; passing --vlm.camera_key=<key> at the "
+                    "CLI now also seeds the cameras list as a fallback."
+                )
+                self._warned_no_camera = True
+            staging.write("vqa", [])
+            return
+
+        # Build all messages first (one per (frame, camera)), then issue them
+        # as a single batched generate_json call so the client can fan them
+        # out concurrently.
+        per_call: list[tuple[float, str, str, list[dict[str, Any]]]] = []
+        for idx in anchor_idx:
+            ts = float(record.frame_timestamps[idx])
+            qtype = rng.choice(self.config.question_types)
+            for camera in cameras:
+                messages = self._build_messages(record, qtype, ts, camera)
+                # Skip cameras that decoded to zero frames at this ts: no point
+                # asking the VLM to ground a bbox without an image.
+                if not _has_image_block(messages):
+                    continue
+                per_call.append((ts, camera, qtype, messages))
+
+        if not per_call:
+            staging.write("vqa", [])
+            return
+
+        results = self.vlm.generate_json([m for _, _, _, m in per_call])
+
+        rows: list[dict[str, Any]] = []
+        for (ts, camera, _qtype, _messages), result in zip(per_call, results, strict=True):
+            qa = self._postprocess(result)
+            if qa is None:
+                continue
+            question, answer = qa
+            rows.append(
+                {
+                    "role": "user",
+                    "content": question,
+                    "style": "vqa",
+                    "timestamp": ts,
+                    "camera": camera,
+                    "tool_calls": None,
+                }
+            )
+            rows.append(
+                {
+                    "role": "assistant",
+                    "content": json.dumps(answer, sort_keys=True),
+                    "style": "vqa",
+                    "timestamp": ts,
+                    "camera": camera,
+                    "tool_calls": None,
+                }
+            )
+        staging.write("vqa", rows)
+
+    def _target_cameras(self) -> list[str]:
+        """Return the cameras the ``vqa`` module should iterate per anchored frame.
+
+        Defaults to every camera the provider exposes. Datasets with no
+        cameras (or test/null providers) yield an empty list, which makes
+        ``run_episode`` a no-op.
+
+        When ``config.restrict_to_default_camera`` is set, VQA grounds on
+        only the provider's default camera (the single ``--vlm.camera_key``
+        stream), matching the plan / interjection modules so the whole
+        pipeline focuses on one view.
+        """
+        all_cameras = list(getattr(self.frame_provider, "camera_keys", []) or [])
+        if getattr(self.config, "restrict_to_default_camera", False):
+            default = getattr(self.frame_provider, "camera_key", None)
+            if default and default in all_cameras:
+                return [default]
+            # ``restrict_to_default_camera`` is set but the configured default
+            # isn't one the provider exposes. Returning it anyway would make
+            # ``_decode`` raise a KeyError deep in frame extraction, so warn and
+            # fall through to every available camera instead.
+            if default:
+                logging.getLogger(__name__).warning(
+                    "restrict_to_default_camera is set but camera_key=%r is not in the "
+                    "provider's cameras %s; grounding VQA on all available cameras instead.",
+                    default,
+                    all_cameras,
+                )
+        return all_cameras
+
+    def _build_messages(
+        self,
+        record: EpisodeRecord,
+        question_type: str,
+        frame_timestamp: float,
+        camera_key: str,
+    ) -> list[dict[str, Any]]:
+        prompt = load_prompt("vqa").format(
+            episode_task=record.episode_task,
+            question_type=question_type,
+        )
+        images = self.frame_provider.frames_at(record, [frame_timestamp], camera_key=camera_key)
+        content = [*to_image_blocks(images), {"type": "text", "text": prompt}]
+        return [{"role": "user", "content": content}]
+
+    def _postprocess(self, result: Any) -> tuple[str, dict[str, Any]] | None:
+        if not isinstance(result, dict):
+            return None
+        question = result.get("question")
+        answer = result.get("answer")
+        if not isinstance(question, str) or not question.strip():
+            return None
+        if not isinstance(answer, dict):
+            return None
+        # The validator will enforce shape; here we just sanity-check that the
+        # answer matches *some* known shape so we can drop garbage early.
+        if classify_vqa_answer(answer) is None:
+            return None
+        return question.strip(), answer
+
+
+def _has_image_block(messages: list[dict[str, Any]]) -> bool:
+    """Return True if any user content block is a populated image block."""
+    for msg in messages:
+        content = msg.get("content")
+        if not isinstance(content, list):
+            continue
+        for block in content:
+            if isinstance(block, dict) and block.get("type") == "image":
+                return True
+    return False

src/lerobot/annotations/steerable_pipeline/modules/interjections_and_speech.py

@@ -0,0 +1,211 @@
+#!/usr/bin/env python
+
+# Copyright 2026 The HuggingFace Inc. team. All rights reserved.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+"""``interjections`` module: interjections + paired speech (EVENT styles + speech atoms).
+
+Two sub-passes:
+
+1. At ``t=0``, emit ONLY a speech tool-call atom (acknowledgement of the
+   canonical task). No interjection row — the canonical task is already the
+   user utterance from ``meta/tasks.parquet``.
+
+2. For mid-episode interruptions, emit a co-timestamped pair:
+       {role:user, style:interjection, content:<text>}
+       speech atom (role:assistant, style:None, tool_calls=[say(...)])
+   Both rows go in ``language_events`` at the same timestamp.
+
+The ``plan`` module's :meth:`run_plan_updates` reuses this module's
+interjection timestamps to refresh the ``plan`` row at the same instant.
+"""
+
+from __future__ import annotations
+
+import random
+from collections.abc import Sequence
+from dataclasses import dataclass, field
+from typing import Any
+
+from ..config import InterjectionsConfig
+from ..frames import FrameProvider, null_provider, to_image_blocks
+from ..prompts import load as load_prompt
+from ..reader import EpisodeRecord, reconstruct_subtask_spans, snap_to_frame
+from ..staging import EpisodeStaging
+from ..vlm_client import VlmClient
+from ..writer import speech_atom
+
+
+@dataclass
+class InterjectionsAndSpeechModule:
+    """Generate task-start speech and mid-episode interjection/speech pairs."""
+
+    vlm: VlmClient
+    config: InterjectionsConfig
+    seed: int = 1729
+    frame_provider: FrameProvider = field(default_factory=null_provider)
+
+    @property
+    def enabled(self) -> bool:
+        return self.config.enabled
+
+    def run_episode(self, record: EpisodeRecord, staging: EpisodeStaging) -> None:
+        rows: list[dict[str, Any]] = []
+        if record.frame_timestamps:
+            t0 = float(record.frame_timestamps[0])
+            initial = self._initial_speech(record)
+            if initial:
+                rows.append(speech_atom(t0, initial))
+        # Pull the ``plan`` module's subtask spans for this episode so the
+        # interjection prompt can ground itself in the actual current
+        # subtask at each chosen timestamp. The ``plan`` module ran first.
+        episode_end_t = float(record.frame_timestamps[-1]) if record.frame_timestamps else None
+        subtask_spans = reconstruct_subtask_spans(staging.read("plan"), episode_end_t=episode_end_t)
+        rows.extend(self._mid_episode_interjections(record, subtask_spans))
+        staging.write("interjections", rows)
+
+    @staticmethod
+    def _subtask_at(spans: Sequence[dict[str, Any]], t: float) -> str | None:
+        current: str | None = None
+        for span in spans:
+            if float(span["start"]) <= t:
+                current = span.get("text")
+            else:
+                break
+        return current
+
+    def _initial_speech(self, record: EpisodeRecord) -> str | None:
+        prompt = load_prompt("interjections_initial_speech").format(
+            episode_task=record.episode_task,
+        )
+        messages = [{"role": "user", "content": [{"type": "text", "text": prompt}]}]
+        result = self.vlm.generate_json([messages])[0]
+        if isinstance(result, dict) and isinstance(result.get("text"), str):
+            text = result["text"].strip()
+            if text:
+                return text
+        return None
+
+    def _mid_episode_interjections(
+        self,
+        record: EpisodeRecord,
+        subtask_spans: Sequence[dict[str, Any]],
+    ) -> list[dict[str, Any]]:
+        """Generate interjections aligned with the actual demo trajectory.
+
+        Teleop data is frozen — the robot already executed every step in
+        the video. A *counterfactual* interjection like "actually skip
+        the wipe" contradicts what then happens in the video, which is
+        what qwen36moe-10/11 surfaced as low-quality interjections.
+
+        Instead, anchor every interjection at a subtask boundary and
+        write it as a natural user request for the *upcoming* subtask.
+        The robot's visible next behavior IS the interjection's effect,
+        so the training signal stays consistent: interjection text →
+        plan refresh → action stream all line up.
+        """
+        if self.config.max_interjections_per_episode <= 0:
+            return []
+        if len(subtask_spans) < 2:
+            # Need at least one transition (subtask 0 → subtask 1).
+            return []
+        # Deterministic per-episode RNG so reruns are stable across SLURM jobs.
+        rng = random.Random(f"{self.seed}:{record.episode_index}:interjection")
+
+        # Boundaries: the start time of every subtask except the first
+        # (which is just t0 and is covered by the initial-task speech atom).
+        boundaries: list[tuple[float, str, str]] = []
+        for i in range(1, len(subtask_spans)):
+            ts = float(subtask_spans[i]["start"])
+            if ts < self.config.interjection_min_t:
+                continue
+            prev_text = (subtask_spans[i - 1].get("text") or "").strip()
+            next_text = (subtask_spans[i].get("text") or "").strip()
+            if not next_text:
+                continue
+            boundaries.append((ts, prev_text, next_text))
+        if not boundaries:
+            return []
+
+        n = min(self.config.max_interjections_per_episode, len(boundaries))
+        chosen = sorted(rng.sample(boundaries, n), key=lambda b: b[0])
+
+        out: list[dict[str, Any]] = []
+        for t, prev_subtask, next_subtask in chosen:
+            t_snap = snap_to_frame(t, record.frame_timestamps)
+            # Window straddles the boundary so the VLM sees the end of the
+            # previous subtask and the start of the next one — same
+            # conditioning the policy will see at training time.
+            window_ts = self._window_timestamps(t_snap, record.frame_timestamps)
+            prompt = load_prompt("interjections_interjection").format(
+                episode_task=record.episode_task,
+                prev_subtask=prev_subtask or "(starting from initial state)",
+                next_subtask=next_subtask,
+                timestamp=t_snap,
+                window_seconds=self.config.interjection_window_seconds,
+            )
+            images = self.frame_provider.frames_at(record, window_ts)
+            content = [*to_image_blocks(images), {"type": "text", "text": prompt}]
+            messages = [{"role": "user", "content": content}]
+            result = self.vlm.generate_json([messages])[0]
+            if not isinstance(result, dict):
+                continue
+            interjection_text = result.get("interjection")
+            speech_text = result.get("speech")
+            if not isinstance(interjection_text, str) or not interjection_text.strip():
+                continue
+            if not isinstance(speech_text, str) or not speech_text.strip():
+                continue
+            out.append(
+                {
+                    "role": "user",
+                    "content": interjection_text.strip(),
+                    "style": "interjection",
+                    "timestamp": t_snap,
+                    "tool_calls": None,
+                }
+            )
+            out.append(speech_atom(t_snap, speech_text.strip()))
+        return out
+
+    def _window_timestamps(self, t_anchor: float, frame_timestamps: Sequence[float]) -> list[float]:
+        """Return a small set of frame timestamps centered on ``t_anchor``.
+
+        The window straddles the subtask boundary the interjection sits
+        on: roughly half the frames cover the end of the previous
+        subtask, half cover the start of the next one. The VLM therefore
+        sees BOTH what just finished AND what's about to start, which is
+        the conditioning we need to write a natural "now please do X"
+        request that matches the visible upcoming behavior.
+        """
+        if not frame_timestamps:
+            return [t_anchor]
+        n = max(1, int(self.config.interjection_window_frames))
+        if n == 1:
+            return [t_anchor]
+        window = float(self.config.interjection_window_seconds)
+        step = window / max(1, n - 1)
+        # Center the window on the anchor so half lands before, half after.
+        start_offset = -window / 2.0
+        targets = [t_anchor + start_offset + step * i for i in range(n)]
+        first_ts = float(frame_timestamps[0])
+        last_ts = float(frame_timestamps[-1])
+        snapped: list[float] = []
+        seen: set[float] = set()
+        for tgt in targets:
+            clamped = min(last_ts, max(first_ts, tgt))
+            t = snap_to_frame(clamped, frame_timestamps)
+            if t not in seen:
+                seen.add(t)
+                snapped.append(t)
+        return snapped or [t_anchor]

src/lerobot/annotations/steerable_pipeline/modules/plan_subtasks_memory.py

@@ -0,0 +1,780 @@
+#!/usr/bin/env python
+
+# Copyright 2026 The HuggingFace Inc. team. All rights reserved.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+"""``plan`` module: subtask decomposition + plan + memory (PERSISTENT styles)."""
+
+from __future__ import annotations
+
+import logging
+from collections.abc import Sequence
+from dataclasses import dataclass, field
+from typing import Any
+
+from ..config import PlanConfig
+from ..frames import (
+    FrameProvider,
+    null_provider,
+    to_contact_sheet_blocks,
+)
+from ..prompts import load as load_prompt
+from ..reader import EpisodeRecord, reconstruct_subtask_spans, snap_to_frame
+from ..staging import EpisodeStaging
+from ..vlm_client import VlmClient
+
+logger = logging.getLogger(__name__)
+
+
+# Prepended to every describe / segment prompt so the VLM knows the images are
+# timestamped contact-sheet grids, not a single video, and reads the burned-in
+# per-tile timestamp when choosing boundaries.
+def _contact_sheet_preamble(columns: int) -> str:
+    return (
+        "CONTACT SHEETS — how to read the images below:\n"
+        f"- Each image is a grid of sampled video frames, {columns} per row, "
+        "with time running left-to-right then top-to-bottom (row-major).\n"
+        "- Each frame has its timestamp burned into the top-left corner, e.g. "
+        '"012.50s". Use that printed timestamp (not the tile position) when you '
+        "choose start/end times; boundaries should land on or near a printed "
+        "timestamp.\n"
+        "- Frames continue across grids: an action may span the end of one sheet "
+        "and the start of the next, so do not place a boundary just because a new "
+        "image begins.\n\n"
+    )
+
+
+# Appended to every describe (and segment) prompt. A visual, causal definition
+# of where one event ends and the next begins — adapted from macrodata/refiner —
+# to sharpen cut points while the existing prompt keeps owning the imperative
+# phrasing.
+_CAUSAL_BOUNDARY_RULES = (
+    "EVENT BOUNDARIES — where one event ends and the next begins:\n"
+    "- Start a new event whenever the world state changes: an object becomes "
+    "held (the gripper closes on it), an object is released (the gripper opens "
+    "and it stays put), an object reaches a new location, a lid/door/drawer "
+    "changes open/closed state, a tool starts or stops affecting a surface, or "
+    "contents visibly move (e.g. poured).\n"
+    "- If a single action changes the same state gradually and continuously, "
+    "keep it as ONE event — do not split it.\n"
+    "- If the same action repeats on different objects or target locations, "
+    "treat each repetition as a separate event.\n"
+    "- Do NOT create boundaries for idle time, camera motion, hesitation, or "
+    "tiny hand adjustments."
+)
+
+
+@dataclass
+class PlanSubtasksMemoryModule:
+    """Generate subtask spans, plan, and memory rows.
+
+    All output is persistent (lives in ``language_persistent``):
+
+    - ``subtask`` rows: one per span, stamped at the span's *start* timestamp
+      (snapped to an exact frame).
+    - ``plan`` rows: emitted at ``t=0``; refreshed at every interjection
+      timestamp via :meth:`run_plan_updates` (called by the executor after
+      the ``interjections`` module completes).
+    - ``memory`` rows: emitted at each subtask boundary (= subtask start
+      timestamp from the second subtask onward).
+    """
+
+    vlm: VlmClient
+    config: PlanConfig
+    frame_provider: FrameProvider = field(default_factory=null_provider)
+
+    @property
+    def enabled(self) -> bool:
+        return self.config.enabled
+
+    def run_episode(self, record: EpisodeRecord, staging: EpisodeStaging) -> None:
+        rows: list[dict[str, Any]] = []
+        # Task driving every plan-module prompt: canonical episode_task, or a
+        # video-derived one when it's empty/placeholder (see derive_task_*).
+        effective_task = self._resolve_effective_task(record)
+        # task_aug rows at t=0: phrasings the renderer rotates ${task} through.
+        # Either the structured 5-axis taxonomy (task_aug_axes.enabled) or
+        # free-form n_task_rephrasings; the effective task is always emitted
+        # first so the rotation covers the source-of-truth phrasing.
+        t0 = float(record.frame_timestamps[0]) if record.frame_timestamps else 0.0
+        variants: list[str] | None = None
+        if self.config.task_aug_axes.enabled and effective_task:
+            variants = self._generate_task_aug_by_axes(effective_task, self.config.task_aug_axes)
+        elif self.config.n_task_rephrasings > 0 and effective_task:
+            variants = self._generate_task_rephrasings(effective_task, n=self.config.n_task_rephrasings)
+        if variants is not None:
+            rows.extend(self._task_aug_rows([effective_task, *variants], t0))
+
+        subtask_spans = self._generate_subtasks(record, task=effective_task)
+
+        # subtask rows
+        for span in subtask_spans:
+            rows.append(
+                {
+                    "role": "assistant",
+                    "content": span["text"],
+                    "style": "subtask",
+                    "timestamp": snap_to_frame(span["start"], record.frame_timestamps),
+                    "tool_calls": None,
+                }
+            )
+        # Plan rows at every subtask boundary (incl. t=0). The plan is a
+        # numbered list of still-todo subtasks, so re-emitting at each
+        # boundary makes it shrink as work progresses — ${plan} at frame t is
+        # exactly what's left to do.
+        if self.config.emit_plan:
+            for span in subtask_spans:
+                boundary_t = snap_to_frame(span["start"], record.frame_timestamps)
+                plan_text = self._generate_plan(
+                    record, subtask_spans, refresh_t=boundary_t, task=effective_task
+                )
+                if plan_text is not None:
+                    rows.append(
+                        {
+                            "role": "assistant",
+                            "content": plan_text,
+                            "style": "plan",
+                            "timestamp": float(boundary_t),
+                            "tool_calls": None,
+                        }
+                    )
+        # memory rows at every subtask boundary except the very first start;
+        # skipped entirely when ``emit_memory`` is False (subtasks-only / plan-only).
+        prior_memory = ""
+        memory_boundaries = enumerate(subtask_spans[1:], start=1) if self.config.emit_memory else []
+        for i, span in memory_boundaries:
+            completed = subtask_spans[i - 1]["text"]
+            remaining = [s["text"] for s in subtask_spans[i:]]
+            mem_text = self._generate_memory(record, prior_memory, completed, remaining, task=effective_task)
+            if mem_text:
+                ts = snap_to_frame(span["start"], record.frame_timestamps)
+                rows.append(
+                    {
+                        "role": "assistant",
+                        "content": mem_text,
+                        "style": "memory",
+                        "timestamp": ts,
+                        "tool_calls": None,
+                    }
+                )
+                prior_memory = mem_text
+        staging.write("plan", rows)
+
+    # ------------------------------------------------------------------
+    # Task derivation + rephrasings
+    # ------------------------------------------------------------------
+
+    _PLACEHOLDER_TASKS: frozenset[str] = frozenset(
+        {
+            "debug",
+            "test",
+            "tbd",
+            "todo",
+            "n/a",
+            "na",
+            "untitled",
+            "unnamed",
+            "default",
+            "placeholder",
+        }
+    )
+
+    def _resolve_effective_task(self, record: EpisodeRecord) -> str:
+        """Decide which task string drives the ``plan`` module for this episode.
+
+        Returns the user-supplied ``record.episode_task`` unless
+        ``derive_task_from_video`` says otherwise (see config docstring).
+        Falls back gracefully to the canonical task if video derivation
+        fails.
+        """
+        canonical = (record.episode_task or "").strip()
+        mode = (self.config.derive_task_from_video or "off").strip().lower()
+        if mode == "always":
+            derived = self._derive_task_from_video(record)
+            return derived or canonical
+        if mode == "if_short" and self._task_seems_bad(canonical):
+            derived = self._derive_task_from_video(record)
+            if derived:
+                return derived
+        return canonical
+
+    def _task_seems_bad(self, task: str) -> bool:
+        if not task:
+            return True
+        if len(task.split()) < int(self.config.derive_task_min_words):
+            return True
+        return task.lower() in self._PLACEHOLDER_TASKS
+
+    @staticmethod
+    def _task_aug_rows(phrasings: Sequence[str], t0: float) -> list[dict[str, Any]]:
+        """Build deduplicated ``task_aug`` rows (role=user) at ``t0``."""
+        seen: set[str] = set()
+        rows: list[dict[str, Any]] = []
+        for phrasing in phrasings:
+            key = phrasing.strip()
+            if not key or key in seen:
+                continue
+            seen.add(key)
+            rows.append(
+                {"role": "user", "content": key, "style": "task_aug", "timestamp": t0, "tool_calls": None}
+            )
+        return rows
+
+    # ------------------------------------------------------------------
+    # VLM call helpers — every plan-module prompt follows the same shape:
+    # build messages → single VLM call → pull a named field.
+    # ------------------------------------------------------------------
+
+    def _vlm_field(self, messages: list[dict[str, Any]], field: str) -> Any:
+        """Run a single VLM call and return ``result[field]`` or ``None``.
+
+        Centralizes the ``vlm.generate_json([m])[0]`` + ``isinstance(dict)``
+        dance every prompt-call site needs.
+        """
+        result = self.vlm.generate_json([messages])[0]
+        if isinstance(result, dict):
+            return result.get(field)
+        return None
+
+    @staticmethod
+    def _text_message(text: str) -> list[dict[str, Any]]:
+        """One-shot text-only user message wrapped for ``generate_json``."""
+        return [{"role": "user", "content": [{"type": "text", "text": text}]}]
+
+    def _video_message(
+        self,
+        record: EpisodeRecord,
+        prompt: str,
+        window: tuple[float, float] | None = None,
+    ) -> list[dict[str, Any]]:
+        """User message combining the (optionally windowed) contact sheets with ``prompt``.
+
+        The prompt is always prefixed with a short explanation of how to read
+        the timestamped grids, so the model treats them as one ordered
+        sequence of frames rather than unrelated images.
+        """
+        prompt = _contact_sheet_preamble(self.config.contact_sheet_columns) + prompt
+        content = [*self._episode_video_block(record, window=window), {"type": "text", "text": prompt}]
+        return [{"role": "user", "content": content}]
+
+    def _derive_task_from_video(self, record: EpisodeRecord) -> str | None:
+        """Ask the VLM "what is this video about" with no task hint at all."""
+        text = self._vlm_field(self._video_message(record, load_prompt("plan_video_task")), "task")
+        return text.strip() if isinstance(text, str) and text.strip() else None
+
+    def _generate_task_rephrasings(self, base_task: str, *, n: int) -> list[str]:
+        """Generate ``n`` text-only paraphrases of ``base_task``."""
+        if n <= 0 or not base_task:
+            return []
+        prompt = load_prompt("plan_task_rephrasings").format(base_task=base_task, n=n)
+        raw = self._vlm_field(self._text_message(prompt), "rephrasings")
+        if not isinstance(raw, list):
+            return []
+        out = [item.strip().strip('"').strip("'") for item in raw if isinstance(item, str)]
+        return [s for s in out if s][:n]
+
+    # ------------------------------------------------------------------
+    # Structured 5-axis task augmentation (EgoMimic-style taxonomy)
+    # ------------------------------------------------------------------
+
+    def _generate_task_aug_by_axes(self, base_task: str, axes_cfg: Any) -> list[str]:
+        """One VLM call → variants along the 5-axis taxonomy.
+
+        Variants from all axes are flattened into a single list (the
+        downstream pipeline doesn't need to know about the per-axis
+        bucketing — every variant becomes a ``task_aug`` row). Order
+        is preserved for reproducibility: synonym_paraphrase first,
+        then omit_arm, then omit_orientation, then omit_grasp_method,
+        then combined_omissions.
+        """
+        if not base_task:
+            return []
+        prompt = load_prompt("plan_task_aug_axes").format(
+            base_task=base_task,
+            n_synonym=axes_cfg.synonym_paraphrase,
+            n_omit_arm=axes_cfg.omit_arm,
+            n_omit_orientation=axes_cfg.omit_orientation,
+            n_omit_grasp_method=axes_cfg.omit_grasp_method,
+            n_combined=axes_cfg.combined_omissions,
+        )
+        result = self.vlm.generate_json([self._text_message(prompt)])[0]
+        if not isinstance(result, dict):
+            return []
+        ordered_axes = (
+            "synonym_paraphrase",
+            "omit_arm",
+            "omit_orientation",
+            "omit_grasp_method",
+            "combined_omissions",
+        )
+        flat: list[str] = []
+        seen: set[str] = set()
+        for axis in ordered_axes:
+            entries = result.get(axis)
+            if not isinstance(entries, list):
+                continue
+            for item in entries:
+                if not isinstance(item, str):
+                    continue
+                key = item.strip().strip('"').strip("'")
+                if not key or key in seen:
+                    continue
+                seen.add(key)
+                flat.append(key)
+        return flat
+
+    def _episode_video_block(
+        self, record: EpisodeRecord, window: tuple[float, float] | None = None
+    ) -> list[dict[str, Any]]:
+        """Timestamped contact sheets for the describe / segmentation prompts.
+
+        Always renders the (optionally windowed) episode as contact sheets:
+        frames sampled at ``frames_per_second`` and packed into timestamped
+        JPEG grids. ``max_frames_per_prompt`` caps the frame count; whole
+        episodes that exceed it are windowed upstream in
+        :meth:`_generate_subtasks` so each call stays within budget while the
+        full episode keeps its sampling density.
+
+        When ``window=(w0, w1)`` is given the badges are WINDOW-RELATIVE
+        (``ts - w0``) to match the window-relative time frame the
+        segmentation prompt works in (spans are offset back to absolute time
+        afterwards).
+        """
+        if not record.frame_timestamps:
+            return []
+        if window is not None:
+            w0, w1 = float(window[0]), float(window[1])
+            dur = max(0.0, w1 - w0)
+            n = max(1, int(round(dur * self.config.frames_per_second)) + 1)
+            n = min(n, self.config.max_frames_per_prompt)
+            if n <= 1 or dur <= 0.0:
+                timestamps = [0.5 * (w0 + w1)]
+            else:
+                step = dur / (n - 1)
+                timestamps = [w0 + i * step for i in range(n)]
+            frames = self.frame_provider.frames_at(record, timestamps)
+            rel = [ts - w0 for ts in timestamps[: len(frames)]]
+            return self._contact_sheet_blocks(frames, rel)
+        episode_duration = record.frame_timestamps[-1] - record.frame_timestamps[0]
+        n = max(1, int(round(episode_duration * self.config.frames_per_second)) + 1)
+        n = min(n, self.config.max_frames_per_prompt)
+        timestamps = self._uniform_episode_timestamps(record, n)
+        frames = self.frame_provider.frames_at(record, timestamps)
+        return self._contact_sheet_blocks(frames, timestamps[: len(frames)])
+
+    @staticmethod
+    def _uniform_episode_timestamps(record: EpisodeRecord, n: int) -> list[float]:
+        """``n`` episode-relative timestamps spanning ``[t0, t_last]`` uniformly."""
+        ts = record.frame_timestamps
+        if n >= len(ts):
+            return [float(t) for t in ts]
+        t0, t_last = float(ts[0]), float(ts[-1])
+        if t_last <= t0 or n <= 1:
+            return [t0] * max(1, n)
+        step = (t_last - t0) / (n - 1)
+        return [t0 + i * step for i in range(n)]
+
+    def _contact_sheet_blocks(self, frames: list[Any], timestamps: list[float]) -> list[dict[str, Any]]:
+        """Build timestamped contact-sheet image blocks from decoded frames."""
+        return to_contact_sheet_blocks(
+            frames,
+            timestamps,
+            columns=self.config.contact_sheet_columns,
+            frames_per_sheet=self.config.contact_sheet_frames_per_sheet,
+            frame_width=self.config.contact_sheet_frame_width,
+            quality=self.config.contact_sheet_quality,
+        )
+
+    def run_plan_updates(
+        self,
+        record: EpisodeRecord,
+        staging: EpisodeStaging,
+        interjection_times: Sequence[float],
+        interjection_texts: Sequence[str] | None = None,
+    ) -> None:
+        """Append additional ``plan`` rows at every interjection timestamp.
+
+        Plans refresh ONLY on user interjections (event-driven). The
+        interjection text is forwarded into the prompt so the refreshed plan
+        reflects the user's correction.
+        """
+        if not self.config.emit_plan:
+            return
+        existing = staging.read("plan")
+        # Pass the last frame timestamp so the final span is closed (else its
+        # end == start, zero duration, and a refresh inside it is missed).
+        episode_end_t = float(record.frame_timestamps[-1]) if record.frame_timestamps else None
+        spans = reconstruct_subtask_spans(existing, episode_end_t=episode_end_t)
+        already_planned: set[float] = {float(r["timestamp"]) for r in existing if r.get("style") == "plan"}
+        new_rows = list(existing)
+
+        texts: list[str | None] = (
+            [None] * len(interjection_times)
+            if interjection_texts is None
+            else [str(t) if t else None for t in interjection_texts]
+        )
+        for raw_t, inter_text in zip(interjection_times, texts, strict=True):
+            t = snap_to_frame(raw_t, record.frame_timestamps)
+            if t in already_planned:
+                continue
+            already_planned.add(t)
+            plan_text = self._generate_plan(record, spans, refresh_t=t, interjection=inter_text)
+            if plan_text is not None:
+                new_rows.append(
+                    {
+                        "role": "assistant",
+                        "content": plan_text,
+                        "style": "plan",
+                        "timestamp": t,
+                        "tool_calls": None,
+                    }
+                )
+        staging.write("plan", new_rows)
+
+    def _generate_subtasks(self, record: EpisodeRecord, *, task: str | None = None) -> list[dict[str, Any]]:
+        """Generate subtask spans, optionally via a multi-call quality chain.
+
+        Single call (default): watch video → emit subtask JSON.
+
+        Multi-call (opt-in, higher quality, more VLM calls):
+          1. ``subtask_describe_first`` — a grounding pass that narrates
+             ONLY what is visible (no JSON commitment to subtasks yet);
+             its description is injected into the segmentation prompt so
+             the model segments its own grounded observations instead of
+             pattern-matching the task text.
+          2. segmentation — emit subtask JSON (as before).
+        """
+        if record.row_count == 0 or not record.frame_timestamps:
+            return []
+        episode_duration = record.frame_timestamps[-1] - record.frame_timestamps[0]
+        effective_task = task if task is not None else record.episode_task
+
+        # ---- Auto-windowing (keeps the full sampling density) --------
+        # Contact sheets are cheap, but a whole long episode sampled at
+        # ``frames_per_second`` can still exceed ``max_frames_per_prompt``.
+        # When it does, split into consecutive windows of exactly that many
+        # frames (one describe→segment call each, still at the full sampling
+        # density), then merge + stitch — so an episode of any length is
+        # covered at full density rather than subsampled into one sparse call.
+        fps = max(1e-6, float(self.config.frames_per_second))
+        n_whole = int(round(episode_duration * fps)) + 1
+        if n_whole > self.config.max_frames_per_prompt:
+            window_s = self.config.max_frames_per_prompt / fps
+            return self._generate_subtasks_windowed(record, effective_task, window_s)
+
+        # ---- Pass 1 (optional): grounding description ----------------
+        observation_block = ""
+        if getattr(self.config, "subtask_describe_first", False):
+            description = self._describe_episode(record, effective_task)
+            if description:
+                observation_block = (
+                    "You watched this video and described, chronologically, "
+                    "ONLY what the robot actually does:\n"
+                    f'"""{description}"""\n\n'
+                    "Segment THAT grounded description (cross-checked against "
+                    "the video) into atomic subtasks. Do not introduce any "
+                    "action that is not in your description above.\n\n"
+                )
+
+        # ---- Pass 2: segmentation ------------------------------------
+        prompt = self._with_causal_rules(
+            load_prompt("plan_subtasks").format(
+                episode_task=effective_task,
+                min_subtask_seconds=self.config.min_subtask_seconds,
+                max_steps=self.config.plan_max_steps,
+                episode_duration=f"{episode_duration:.3f}",
+                observation_block=observation_block,
+            )
+        )
+        spans = self._vlm_field(self._video_message(record, prompt), "subtasks")
+        cleaned = self._clean_spans(spans, record)
+        if not cleaned:
+            return []
+
+        # ---- Full-episode coverage stitch ----------------------------
+        # The VLM can start after t0 or leave gaps, so frames fall through
+        # with no active subtask. Always stitch into a contiguous
+        # [t0, t_last] cover.
+        cleaned = self._stitch_full_coverage(cleaned, record)
+
+        return cleaned
+
+    def _generate_subtasks_windowed(
+        self, record: EpisodeRecord, task: str, window_s: float
+    ) -> list[dict[str, Any]]:
+        """Subtask generation in fixed-length windows at constant fps.
+
+        Splits ``[t0, t_last]`` into consecutive windows of ``window_s``
+        seconds, runs the describe -> segment chain on each window's own
+        frames (sampled at ``frames_per_second``), offsets
+        each window's spans back to absolute episode time, then merges +
+        stitches into a contiguous whole-episode cover.
+        """
+        t0 = float(record.frame_timestamps[0])
+        t_last = float(record.frame_timestamps[-1])
+        all_spans: list[dict[str, Any]] = []
+        w0 = t0
+        n_windows = 0
+        while w0 < t_last - 1e-6:
+            w1 = min(w0 + window_s, t_last)
+            all_spans.extend(self._subtasks_for_window(record, task, w0, w1))
+            n_windows += 1
+            w0 = w1
+        logger.info(
+            "episode %d: windowed subtask gen over %d window(s) of %.1fs -> %d raw spans",
+            record.episode_index,
+            n_windows,
+            window_s,
+            len(all_spans),
+        )
+        # Merge across windows: clamp to the absolute episode, sort, and
+        # frame-snap to distinct starts (handles any boundary collisions).
+        cleaned = self._clean_spans(all_spans, record)
+        if not cleaned:
+            return []
+        return self._stitch_full_coverage(cleaned, record)
+
+    def _subtasks_for_window(
+        self, record: EpisodeRecord, task: str, w0: float, w1: float
+    ) -> list[dict[str, Any]]:
+        """Run describe -> segment on one ``[w0, w1]`` window.
+
+        The model works in window-RELATIVE time ``[0, L]`` (it perceives
+        the window as a clip starting at 0); spans are offset back to
+        absolute ``[w0, w1]`` before returning.
+        """
+        window = (w0, w1)
+        win_len = max(0.0, w1 - w0)
+
+        observation_block = ""
+        if getattr(self.config, "subtask_describe_first", False):
+            description = self._describe_episode(record, task, window=window)
+            if description:
+                observation_block = (
+                    "You watched this video clip and described, chronologically, "
+                    "ONLY what the robot actually does:\n"
+                    f'"""{description}"""\n\n'
+                    "Segment THAT grounded description (cross-checked against "
+                    "the clip) into atomic subtasks. Do not introduce any "
+                    "action that is not in your description above.\n\n"
+                )
+
+        prompt = self._with_causal_rules(
+            load_prompt("plan_subtasks").format(
+                episode_task=task,
+                min_subtask_seconds=self.config.min_subtask_seconds,
+                max_steps=self.config.plan_max_steps,
+                episode_duration=f"{win_len:.3f}",
+                observation_block=observation_block,
+            )
+        )
+        spans = self._vlm_field(self._video_message(record, prompt, window=window), "subtasks")
+        # Window-relative clamp; no frame-snap dedupe yet (done on the
+        # merged absolute set).
+        cleaned = self._clean_spans(spans, record, bounds=(0.0, win_len), dedupe=False)
+        if not cleaned:
+            return []
+
+        # Offset window-relative spans back to absolute episode time.
+        for s in cleaned:
+            s["start"] = w0 + float(s["start"])
+            s["end"] = w0 + float(s["end"])
+        return cleaned
+
+    def _stitch_full_coverage(
+        self, spans: list[dict[str, Any]], record: EpisodeRecord
+    ) -> list[dict[str, Any]]:
+        """Make subtask spans tile the full episode with no gaps.
+
+        * The first subtask starts at the episode's first frame ``t0``
+          (any idle / approach before the first labelled action is folded
+          into it), so every early frame has an active subtask.
+        * Each subtask's ``end`` is snapped to the next subtask's
+          ``start`` (gaps between spans are closed), and the final
+          subtask's ``end`` extends to the last frame ``t_last``.
+
+        Starts are otherwise left as the (already frame-snapped, distinct)
+        values the VLM produced — only the FIRST start is pulled
+        back to ``t0``, which can't collide with a later span because it
+        was already the earliest. Purely deterministic; runs after the
+        VLM passes.
+        """
+        if not spans or not record.frame_timestamps:
+            return spans
+        t0 = float(record.frame_timestamps[0])
+        t_last = float(record.frame_timestamps[-1])
+        spans = sorted(spans, key=lambda s: float(s["start"]))
+        spans[0]["start"] = t0
+        for i in range(len(spans) - 1):
+            spans[i]["end"] = float(spans[i + 1]["start"])
+        spans[-1]["end"] = t_last
+        for s in spans:
+            if float(s["end"]) < float(s["start"]):
+                s["end"] = float(s["start"])
+        return spans
+
+    @staticmethod
+    def _with_causal_rules(prompt: str) -> str:
+        """Append the causal event-boundary rules to a describe/segment prompt."""
+        return f"{prompt}\n\n{_CAUSAL_BOUNDARY_RULES}"
+
+    def _clean_spans(
+        self,
+        spans: Any,
+        record: EpisodeRecord,
+        bounds: tuple[float, float] | None = None,
+        dedupe: bool = True,
+    ) -> list[dict[str, Any]]:
+        """Clamp / sort / (optionally) dedupe raw VLM subtask spans into valid rows.
+
+        ``bounds`` overrides the clamp range — pass the window's
+        ``(w_lo, w_hi)`` when cleaning window-relative spans, or leave
+        ``None`` to clamp to the whole episode ``[t0, t_last]``.
+        ``dedupe`` runs the frame-snap distinct-start step; skip it for
+        window-relative spans (frame snapping is done once on the merged,
+        absolute-time set).
+        """
+        if not spans:
+            return []
+        if bounds is not None:
+            lo, hi = float(bounds[0]), float(bounds[1])
+        else:
+            lo = record.frame_timestamps[0]
+            hi = record.frame_timestamps[-1]
+        cleaned: list[dict[str, Any]] = []
+        for span in spans:
+            try:
+                start = float(span["start"])
+                end = float(span["end"])
+                text = str(span["text"]).strip()
+            except (KeyError, ValueError, TypeError):
+                continue
+            start = max(lo, min(start, hi))
+            end = max(lo, min(end, hi))
+            if end < start:
+                start, end = end, start
+            if not text:
+                continue
+            cleaned.append({"text": text, "start": start, "end": end})
+        cleaned.sort(key=lambda s: s["start"])
+        if dedupe:
+            return self._dedupe_starts_to_distinct_frames(cleaned, record)
+        return cleaned
+
+    def _describe_episode(
+        self, record: EpisodeRecord, task: str, window: tuple[float, float] | None = None
+    ) -> str:
+        """Grounding pass: free-form chronological description of the (windowed) video."""
+        prompt = self._with_causal_rules(load_prompt("plan_subtask_describe").format(episode_task=task))
+        text = self._vlm_field(self._video_message(record, prompt, window=window), "description")
+        return text.strip() if isinstance(text, str) and text.strip() else ""
+
+    @staticmethod
+    def _dedupe_starts_to_distinct_frames(
+        spans: list[dict[str, Any]], record: EpisodeRecord
+    ) -> list[dict[str, Any]]:
+        """Bump same-frame subtask starts onto distinct frames.
+
+        Two consecutive VLM spans whose ``start`` rounds to the same
+        source frame (after :func:`snap_to_frame`) would otherwise emit
+        two ``style=subtask`` rows at the identical persistent
+        timestamp. The training-time renderer's ``active_at(t,
+        style=subtask)`` resolver can't disambiguate that and raises
+        ``Ambiguous resolver for style='subtask'``.
+
+        Walk the (sorted-by-start) spans, snap each to its frame, and
+        if the snapped frame is already taken push the span onto the
+        next unused frame so both subtasks survive on distinct
+        timestamps. If the episode ends before a free frame is found,
+        the trailing span is dropped with a warning — better than
+        poisoning the render.
+        """
+        if not spans:
+            return spans
+        frames = record.frame_timestamps
+        if not frames:
+            return spans
+        used: set[float] = set()
+        out: list[dict[str, Any]] = []
+        for span in spans:
+            ts = snap_to_frame(span["start"], frames)
+            if ts in used:
+                next_ts = next((f for f in frames if f > ts and f not in used), None)
+                if next_ts is None:
+                    logger.warning(
+                        "episode %d: subtask %r snapped to occupied frame "
+                        "%.3f and no free later frame exists — dropping",
+                        record.episode_index,
+                        span.get("text"),
+                        ts,
+                    )
+                    continue
+                ts = next_ts
+            used.add(ts)
+            new_span = {**span, "start": ts}
+            if float(new_span.get("end", ts)) < ts:
+                new_span["end"] = ts
+            out.append(new_span)
+        return out
+
+    def _generate_plan(
+        self,
+        record: EpisodeRecord,  # noqa: ARG002  (kept for signature stability)
+        subtask_spans: Sequence[dict[str, Any]],
+        *,
+        refresh_t: float | None = None,
+        interjection: str | None = None,  # noqa: ARG002
+        task: str | None = None,  # noqa: ARG002
+    ) -> str | None:
+        """Deterministic plan = numbered list of *still-todo* subtasks.
+
+        No VLM call: a plain numbered list keeps the plan aligned with the
+        upcoming subtasks (the old VLM "compact hierarchical plan" prompt
+        cost a round-trip per episode/refresh and could diverge).
+
+            1. <subtask 1>
+            2. <subtask 2>
+
+        On a refresh at ``refresh_t`` (from ``run_plan_updates`` on
+        interjections, and ``run_episode`` at each boundary), only subtasks
+        starting at or after ``refresh_t`` are included — so it always
+        describes what's left.
+        """
+        if not subtask_spans:
+            return None
+        remaining = [
+            s for s in subtask_spans if refresh_t is None or float(s.get("start", 0.0)) >= float(refresh_t)
+        ]
+        if not remaining:
+            # Past the last subtask boundary on a late refresh — nothing
+            # left to plan; emit None so the caller skips the row.
+            return None
+        return "\n".join(f"{i}. {span.get('text', '').strip()}" for i, span in enumerate(remaining, start=1))
+
+    def _generate_memory(
+        self,
+        record: EpisodeRecord,
+        prior_memory: str,
+        completed: str,
+        remaining: Sequence[str],
+        *,
+        task: str | None = None,
+    ) -> str:
+        prompt = load_prompt("plan_memory").format(
+            episode_task=(task if task is not None else record.episode_task),
+            prior_memory=prior_memory or "(none)",
+            completed_subtask=completed,
+            remaining_subtasks=", ".join(remaining) if remaining else "(none)",
+        )
+        memory = self._vlm_field(self._text_message(prompt), "memory")
+        return memory.strip() if isinstance(memory, str) else ""

src/lerobot/annotations/steerable_pipeline/prompts/__init__.py

@@ -0,0 +1,33 @@
+#!/usr/bin/env python
+
+# Copyright 2026 The HuggingFace Inc. team. All rights reserved.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+"""Prompt templates loaded as plain text.
+
+One file per use site. Templates use ``str.format(**vars)`` substitution; we
+intentionally avoid jinja2 here so the templates remain inspectable in
+plain editors and roundtrip cleanly through ``ruff format``.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+_DIR = Path(__file__).parent
+
+
+def load(name: str) -> str:
+    """Read prompt template ``name.txt`` from the ``prompts/`` directory."""
+    path = _DIR / f"{name}.txt"
+    return path.read_text(encoding="utf-8")

src/lerobot/annotations/steerable_pipeline/prompts/interjections_initial_speech.txt

@@ -0,0 +1,12 @@
+The user just asked the robot: "{episode_task}".
+
+Generate a short verbal acknowledgement the robot would speak back before
+beginning the task. Style: compact, confident, friendly.
+
+Examples (Hi Robot, Shi 2025): "Sure, I won't put cheese on it.",
+"OK, starting with the sponge.", "Got it.".
+
+Prefer very short replies: "Got it.", "On it.", "OK."
+
+Output strictly valid JSON:
+  {{ "text": "<the spoken acknowledgement>" }}

src/lerobot/annotations/steerable_pipeline/prompts/interjections_interjection.txt

@@ -0,0 +1,46 @@
+You are generating training data for a Hi Robot-style hierarchical
+robot policy. The robot in this demonstration has ALREADY executed
+every step shown in the video — we cannot retroactively change the
+action stream. To keep training data consistent with the video, the
+"interjection" must align with what the robot is *about to do next* in
+the demonstration, framed as a natural mid-task user request.
+
+The episode's overall task: "{episode_task}".
+
+The images above show roughly {window_seconds:.1f} seconds straddling a
+subtask boundary in the demonstration:
+
+- Subtask the robot just finished: "{prev_subtask}"
+- Subtask the robot is about to start: "{next_subtask}"
+- Time into episode: {timestamp:.2f}s
+
+Write ONE compact interjection the user would naturally say at this
+moment to prompt / confirm / encourage the robot to do "{next_subtask}".
+Keep it like a mid-task coaching cue, not a full instruction paragraph.
+Also write the robot's compact verbal acknowledgement.
+
+Hard rules:
+
+- The interjection MUST be consistent with the next subtask. The user
+  cannot ask for something different from what the robot then does in
+  the video. If you're tempted to say "actually skip X" or "do Y
+  instead", DO NOT — those would contradict the demonstration.
+- The interjection must reference an object, location, or action that
+  is plausible given the visible scene and the next subtask text.
+- One short phrase or sentence each. Conversational, not robotic.
+- Prefer direct cues: "{next_subtask}, please."; "Now {next_subtask}."
+- Keep robot speech very short: "OK.", "On it.", "Doing that."
+
+Style examples (vary the phrasing — don't reuse these verbatim):
+  - "Now go ahead and {next_subtask}."
+  - "Great, can you {next_subtask} next?"
+  - "{next_subtask}, please."
+  - "Before you continue, please {next_subtask}."
+  - "Looking good — {next_subtask} now."
+  - "Okay, {next_subtask}."
+
+Output strictly valid JSON:
+  {{
+    "interjection": "<short cue from the user, asking for the next subtask>",
+    "speech":       "<short robot acknowledgement>"
+  }}

src/lerobot/annotations/steerable_pipeline/prompts/plan_memory.txt

@@ -0,0 +1,36 @@
+You are updating the robot's compressed semantic memory at the boundary of
+a completed subtask.
+
+Reference (verbatim from MEM, Torne 2026):
+"Remove or compress information in the language memory whenever
+appropriate. Keep ONLY the minimal set of relevant information for future
+task execution. Specific object attributes (colors, precise quantities of
+each item) get discarded when their details won't affect subsequent
+actions. Functional outcomes (where items went, how many) are preserved."
+
+Episode task: "{episode_task}"
+Previous memory: {prior_memory}
+Just-completed subtask: "{completed_subtask}"
+Remaining subtasks (for relevance judgement only): {remaining_subtasks}
+
+Write the memory as a short FIRST-PERSON, PAST-TENSE narrative of what the
+robot has accomplished so far — the running story it would tell itself.
+
+Authoring rules:
+- First person, past tense. Every sentence starts with "I": "I picked
+  up...", "I opened...", "I moved to...".
+- One or two short sentences. Extend the previous memory with the
+  just-completed subtask; do not rewrite it from scratch.
+- Keep WHAT happened (functional outcomes — where items went, how many),
+  drop HOW (grasp details, motions).
+- Compress completed steps and drop object attributes (colors, exact
+  counts) once they no longer affect the remaining subtasks.
+
+Example (MEM, Torne 2026):
+  Before: "I prepared the pot and got the potatoes, milk, and butter. I
+           moved to the drawer."
+  After:  "I prepared the pot and got the ingredients. I opened the
+           drawer with the masher."
+
+Output strictly valid JSON:
+  {{ "memory": "<one or two short first-person past-tense sentences>" }}

src/lerobot/annotations/steerable_pipeline/prompts/plan_subtask_describe.txt

@@ -0,0 +1,27 @@
+You are watching a teleoperated robot demonstration from a single
+camera. The user asked the robot to: "{episode_task}"
+
+This is an OBSERVATION pass. Watch the entire clip and describe, in
+chronological order, ONLY what the robot physically does — the concrete
+motions, approaches, contacts, grasps, releases, and relocations you can
+actually SEE in the frames.
+
+Hard rules:
+- Describe only motion visible in the video. Do NOT use the task
+  instruction to guess steps that aren't shown. The instruction is the
+  goal; the video is ground truth.
+- Do NOT segment into named subtasks yet and do NOT output JSON beyond
+  the single field below. Just narrate what happens.
+- Give an approximate timestamp (in seconds) for each distinct event,
+  e.g. "0.0-1.4s: the base drives forward toward the stove".
+- Do NOT invent objects, grasps, destinations, or steps. If the robot
+  only does one thing (e.g. it just navigates and the clip ends), say
+  exactly that and nothing more.
+- Be concrete and literal. "the gripper closes on the mug" — not "the
+  robot prepares to make coffee".
+
+Output strictly valid JSON:
+
+  {{
+    "description": "<chronological, timestamped description of ONLY what is visible>"
+  }}

src/lerobot/annotations/steerable_pipeline/prompts/plan_subtasks.txt

@@ -0,0 +1,112 @@
+You are labeling a teleoperated robot demonstration.
+
+The user originally asked: "{episode_task}"
+
+You are shown the entire demonstration as a single video. Watch the
+whole clip, then segment it into a list of consecutive atomic subtasks
+the robot performs.
+
+{observation_block}GROUNDING — read this first, it overrides everything below:
+- Label ONLY what the robot actually does in the video. Every subtask
+  you emit must correspond to motion you can SEE in specific frames.
+- Do NOT invent, anticipate, or pad. If the robot only does one thing
+  (e.g. it just navigates to a location and the clip ends), emit
+  EXACTLY ONE subtask. Many demonstrations are a single atomic skill.
+- ``max_steps`` below is a hard CEILING, not a target. Emitting fewer
+  subtasks than the ceiling is not just allowed, it is expected for
+  short / atomic demonstrations. One correct subtask is far better
+  than several invented ones.
+- If the video does not clearly show the action implied by the task,
+  describe what you actually see — do NOT fabricate the task's steps
+  from the instruction text. The instruction tells you the goal; the
+  VIDEO is the ground truth for what happened.
+
+Authoring rules — Hi Robot atom granularity, pi0.7-style short prompts:
+
+- Each subtask = one COMPOSITE atomic skill the low-level policy can
+  execute end-to-end. A "skill" bundles its own approach motion with
+  its terminal action — do NOT split the approach off as its own
+  subtask. The whole-arm policy already learns to reach as part of
+  every manipulation primitive.
+- Write each subtask as an IMPERATIVE COMMAND, starting with one of
+  these verbs (extend only when none fits):
+    pick up <obj>           — approach + grasp + lift in one subtask
+    put <obj> on/in <loc>   — transport + release in one subtask
+    place <obj> on/in <loc> — synonym of "put"; pick one and stay consistent
+    push <obj>              — contact + linear shove
+    pull <obj>              — contact + linear retract
+    turn <knob/dial/handle> — rotary actuation
+    press <button>          — single-press contact
+    open <drawer/door/lid>  — full open motion
+    close <drawer/door/lid> — full close motion
+    pour <src> into <dst>   — tilt + flow
+    insert <obj> into <slot>— alignment + push-fit
+    go to <loc>             — ONLY when no grasp / actuation follows
+                             (e.g. a pure relocation between phases).
+                             If the next subtask grasps something at
+                             that location, drop "go to ..." and just
+                             write "pick up ..." instead.
+- Forbidden ultra-fine splits — the VLM is NOT allowed to emit these
+  as standalone subtasks; fold them into the parent composite:
+    "move to X"   → fold into "pick up X" (or whatever follows)
+    "reach for X" → fold into "pick up X"
+    "grasp X"     → fold into "pick up X"
+    "lift X"      → fold into "pick up X" (or "put X on Y" if it's
+                    the transport phase of a place)
+    "release X"   → fold into "put X on Y" (or "place X in Y")
+- Keep it SHORT — a verb phrase, not a sentence. Drop articles
+  ("the", "a") and adverbs ("carefully", "slowly"). Add a "how"
+  detail (which hand, which grasp point) ONLY when it is needed to
+  disambiguate. Every subtask must begin with one of the verbs
+  above (no leading nouns, no "then", no "first").
+- NEVER use third person. Never write "the robot", "the arm", "the
+  gripper moves", "it picks up" — the robot is implied. Command it,
+  do not describe it.
+- Use the exact object nouns from the task above. If the task says
+  "cube", every subtask says "cube" — never switch to "block". If it
+  says "box", never switch to "bin"/"container". Keep vocabulary
+  consistent across the whole episode.
+- Good: "pick up blue cube", "put blue cube in box", "open drawer",
+  "turn red knob", "press start button", "go to sink".
+- Bad: "move to blue cube" (approach as its own subtask — forbidden,
+  must be folded into "pick up blue cube"); "the robot arm moves
+  towards the blue cube" (third person, too long); "carefully pick
+  up the cube" (adverb, article); "release the yellow block"
+  ("block" when the task said "cube", and "release" must be folded
+  into a "put"/"place" subtask).
+- Subtasks are non-overlapping and cover the full episode in order.
+  Choose the cut points yourself based on what you see in the video
+  (gripper open/close events, contact, regrasps, transitions).
+- Each subtask spans at least {min_subtask_seconds} seconds. If a
+  candidate span would be shorter, merge it into its neighbour
+  rather than emitting it.
+- Do not exceed {max_steps} subtasks total. Fewer, larger composites
+  are preferred over many micro-steps.
+- Every subtask's [start_time, end_time] must lie within
+  [0.0, {episode_duration}] seconds.
+
+SPECIAL CASES — verb disambiguation (each rule is narrowly visual and
+fires ONLY on the spatial situation it names; it must not change how you
+label any other situation):
+- STACK vs PUT: if an object is placed ON TOP OF another specific object
+  (not on a flat table / shelf / counter), use "stack ... on ...", not
+  "put". "stack blue book on green book", NOT "put blue book on table".
+- INSERT vs PUT: if an object goes INTO a fitted slot / hole / socket /
+  receptacle (push-fit), use "insert ... into ...", not "put".
+- RETRIEVE/PICK-UP vs PUT (direction): watch the gripper. If it CLOSES
+  on the object and the object moves WITH the hand, it is "pick up" /
+  "retrieve" (object leaves its location). If the gripper OPENS and the
+  object stays where the hand left it, it is "put" / "place" (object
+  arrives at a location). Decide by which way the object moves, not by
+  where the hand ends up.
+- POUR vs PUT: only use "pour" when the source is tilted and contents
+  flow out; moving a full container without tilting is "put"/"place".
+
+Output strictly valid JSON of shape:
+
+  {{
+    "subtasks": [
+      {{"text": "<short imperative verb phrase>", "start": <float>, "end": <float>}},
+      ...
+    ]
+  }}

src/lerobot/annotations/steerable_pipeline/prompts/plan_task_aug_axes.txt

@@ -0,0 +1,67 @@
+You are generating structured augmentations of a robot task instruction
+for training a language-conditioned policy. Unlike free-form rephrasing,
+your variants follow a NAMED 5-axis taxonomy — each axis omits or varies
+a specific element of the task while preserving its meaning.
+
+Original task: "{base_task}"
+
+Produce variants along five named axes. Each axis has a target count.
+The whole batch should expose the policy to maximum linguistic diversity
+WITHOUT changing what the robot is supposed to do.
+
+Axes and target counts:
+
+  synonym_paraphrase ({n_synonym}):
+    Different wording / verbs / sentence structure. ALL information
+    from the original task is preserved — same object, same arm
+    specification if present, same orientation if present, same grasp
+    if present.
+
+  omit_arm ({n_omit_arm}):
+    Drop the left/right/both arm specification from the task. Skip
+    entirely (emit 0 entries) if the original task does NOT mention an
+    arm. Do not invent an arm specification just to omit it.
+
+  omit_orientation ({n_omit_orientation}):
+    Drop orientation cues (upright, sideways, facing the user,
+    long-edge-first, etc.). Skip entirely if no orientation cue is
+    present in the original task.
+
+  omit_grasp_method ({n_omit_grasp_method}):
+    Drop the grip / grasp method specification (pinch, wrap, hold by
+    the rim, etc.). Skip entirely if no grasp method is mentioned.
+
+  combined_omissions ({n_combined}):
+    Combine TWO of the above omissions simultaneously (e.g. drop both
+    arm and orientation). Skip entirely if fewer than two of (arm,
+    orientation, grasp_method) appear in the original task.
+
+Hard rules:
+- Each variant MUST preserve the core action, the target object, AND
+  the goal / destination. Do not change which object is involved, where
+  it goes, or the high-level action. "Navigate to the stove" may become
+  "go to the stove" or "head over to the stove" — it must NEVER become
+  "wander around the kitchen", "explore the room", or anything that
+  drops or generalises the stove destination. If you cannot vary the
+  wording without changing the goal, emit fewer variants.
+- Only the FIVE listed elements (wording, arm, orientation, grasp
+  method, or a combination) may be varied or omitted. The verb's
+  meaning, the object, and the destination are fixed.
+- Each variant is plain prose, no markdown, no quotes, no list numbers.
+- Each variant must be DISTINCT from every other variant in the entire
+  output, both within and across axes. Near-duplicates are not allowed.
+- If an axis cannot reach its target count because the original task
+  lacks the omittable element, emit fewer entries — do NOT pad the
+  axis with paraphrases that belong to a different axis.
+- Variants should not all start with verbs — vary sentence structure
+  (some imperative, some polite request, some question).
+
+Output strictly valid JSON of shape:
+
+  {{
+    "synonym_paraphrase": ["<v1>", "<v2>", ...],
+    "omit_arm": ["<v1>", "<v2>", ...],
+    "omit_orientation": ["<v1>", ...],
+    "omit_grasp_method": ["<v1>", ...],
+    "combined_omissions": ["<v1>", ...]
+  }}

src/lerobot/annotations/steerable_pipeline/prompts/plan_task_rephrasings.txt

@@ -0,0 +1,32 @@
+You are generating training data for a Hi Robot-style policy. We need
+{n} alternative phrasings of the same robot task so the policy sees
+diverse user prompts during training instead of the same canonical
+string repeated every frame.
+
+Original task:
+"{base_task}"
+
+Generate exactly {n} alternative phrasings of the same task. Vary:
+
+- formality (casual / polite / curt)
+- verbosity (mostly short imperative; occasional polite request)
+- word choice (synonyms, different verbs)
+- sentence structure (imperative / question / suggestion)
+
+Hard rules:
+- Each phrasing MUST preserve the exact meaning of the original task.
+  Do not change which object is involved, the destination, or the
+  action. Do not add extra steps. Do not invent new objects.
+- Each phrasing must be a short phrase or sentence, plain prose, no
+  markdown, no quotes, no list numbers.
+- Phrasings must be distinct — no near-duplicates.
+- Output exactly {n} entries.
+
+Output strictly valid JSON:
+  {{
+    "rephrasings": [
+      "<phrasing 1>",
+      "<phrasing 2>",
+      ...
+    ]
+  }}

src/lerobot/annotations/steerable_pipeline/prompts/plan_video_task.txt

@@ -0,0 +1,17 @@
+The video above shows a robot manipulation episode in full. Look at
+the entire video and describe in ONE concise sentence what the robot
+is doing.
+
+Rules:
+- One sentence, in natural English, like a user instruction.
+- Capture the goal of the demonstration, not low-level motions.
+  Example: "place the yellow cube into the red bin" — not "move the
+  end-effector down 5cm and close the gripper".
+- 4 to 15 words. Plain prose, no markdown, no bullets, no quotes.
+- Do not invent objects or actions that aren't visible.
+- Do not output anything other than the JSON object below.
+
+Output strictly valid JSON:
+  {{
+    "task": "<single concise sentence describing what the robot does in this video>"
+  }}

src/lerobot/annotations/steerable_pipeline/prompts/vqa.txt

@@ -0,0 +1,32 @@
+You are generating a frame-grounded visual question/answer pair for
+chain-of-thought training. Reference: ECoT (Zawalski 2024) and Steerable
+Policies — both train policies on grounded features such as bounding box
+pixel coordinates, keypoints, counts, attributes, and spatial relations.
+
+The frame shows a robot working on: "{episode_task}".
+
+Question types and the EXACT answer JSON shape required for each:
+
+  bbox       => {{"detections": [{{"label": "<obj>", "bbox_format": "xyxy",
+                                    "bbox": [x1, y1, x2, y2]}}, ...]}}
+                bbox is in pixel coordinates (x_min, y_min, x_max, y_max).
+                ECoT example: "a white cup [124, 25, 176, 113]".
+
+  keypoint   => {{"label": "<point>", "point_format": "xy",
+                  "point": [x, y]}}
+
+  count      => {{"label": "<obj>", "count": <int>,
+                  "note": "<optional short note>"}}
+
+  attribute  => {{"label": "<obj>", "attribute": "<color|shape|state|...>",
+                  "value": "<observed value>"}}
+
+  spatial    => {{"subject": "<obj>", "relation": "<left_of|right_of|on|in|"
+                  "above|below|near>", "object": "<obj>"}}
+
+Generate a question of type "{question_type}". Output strictly valid JSON:
+
+  {{
+    "question": "<short, frame-grounded question>",
+    "answer":   <object whose shape matches the schema above>
+  }}