refactor: consolidate VLM classes into single QwenVL implementation

Remove Qwen2VL, Qwen3VL, Qwen35VL in favor of one QwenVL class that
uses AutoModelForImageTextToText and works with the whole Qwen VL
family. Moves shared _parse_skills_response to BaseVLM and extracts
_build_messages/_prepare_inputs/_decode helpers to reduce duplication.

Made-with: Cursor

.gitignore

@@ -173,5 +173,7 @@ outputs/
 
 # Dev folders
 .cache/*
+*.stl
+*.urdf
 *.xml
 *.part

CONTRIBUTING.md

@@ -2,7 +2,7 @@
 
 Everyone is welcome to contribute, and we value everybody's contribution. Code is not the only way to help the community. Answering questions, helping others, reaching out, and improving the documentation are immensely valuable.
 
-Whichever way you choose to contribute, please be mindful to respect our [code of conduct](https://github.com/huggingface/lerobot/blob/main/CODE_OF_CONDUCT.md) and our [AI policy](https://github.com/huggingface/lerobot/blob/main/AI_POLICY.md).
+Whichever way you choose to contribute, please be mindful to respect our [code of conduct](./CODE_OF_CONDUCT.md) and our [AI policy](./AI_POLICY.md).
 
 ## Ways to Contribute
 
@@ -32,7 +32,7 @@ git remote add upstream https://github.com/huggingface/lerobot.git
 
 ### 2. Environment Installation
 
-Please follow our [Installation Guide](https://huggingface.co/docs/lerobot/installation) for the environment setup & installation from source.
+Please follow our [Installation Guide](./docs/source/installation.mdx) for the environment setup & installation from source.
 
 ## Running Tests & Quality Checks
 
@@ -75,8 +75,8 @@ pytest -sv tests/test_specific_feature.py
 
 Use the templates for required fields and examples.
 
-- **Issues:** Follow the [ticket template](https://github.com/huggingface/lerobot/blob/main/.github/ISSUE_TEMPLATE/bug-report.yml).
-- **Pull requests:** Rebase on `upstream/main`, use a descriptive branch (don't work on `main`), run `pre-commit` and tests locally, and follow the [PR template](https://github.com/huggingface/lerobot/blob/main/.github/PULL_REQUEST_TEMPLATE.md).
+- **Issues:** Follow the [ticket template](./.github/ISSUE_TEMPLATE/bug-report.yml).
+- **Pull requests:** Rebase on `upstream/main`, use a descriptive branch (don't work on `main`), run `pre-commit` and tests locally, and follow the [PR template](./.github/PULL_REQUEST_TEMPLATE.md).
 
 One member of the LeRobot team will then review your contribution.
 

README.md

@@ -100,11 +100,11 @@ lerobot-train \
   --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**            | [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)            |
+| 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)                                                             |
+| **Reinforcement Learning** | [HIL-SERL](./docs/source/hilserl.mdx), [TDMPC](./docs/source/policy_tdmpc_README.md) & QC-FQL (coming soon)                                                                                                  |
+| **VLAs Models**            | [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) |
 
 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
 
@@ -165,7 +165,7 @@ If you are referencing our research or the academic paper, please also cite our
 
 ## Contribute
 
-We welcome contributions from everyone in the community! To get started, please read our [CONTRIBUTING.md](https://github.com/huggingface/lerobot/blob/main/CONTRIBUTING.md) guide. Whether you're adding a new feature, improving documentation, or fixing a bug, your help and feedback are invaluable. We're incredibly excited about the future of open-source robotics and can't wait to work with you on what's next—thank you for your support!
+We welcome contributions from everyone in the community! To get started, please read our [CONTRIBUTING.md](./CONTRIBUTING.md) guide. Whether you're adding a new feature, improving documentation, or fixing a bug, your help and feedback are invaluable. We're incredibly excited about the future of open-source robotics and can't wait to work with you on what's next—thank you for your support!
 
 <p align="center">
   <img alt="SO101 Video" src="./media/readme/so100_video.webp" width="640px">

docker/Dockerfile.user

@@ -18,8 +18,6 @@
 # docker build -f docker/Dockerfile.user -t lerobot-user .
 # docker run -it --rm lerobot-user
 
-# With USB physical access : docker run -it --device=/dev/ -v /dev/:/dev/ --rm lerobot-user
-
 # Configure the base image
 ARG PYTHON_VERSION=3.12
 FROM python:${PYTHON_VERSION}-slim

docs/source/_toctree.yml

@@ -19,10 +19,6 @@
     title: Multi GPU training
   - local: peft_training
     title: Training with PEFT (e.g., LoRA)
-  - local: rename_map
-    title: Using Rename Map and Empty Cameras
-  - local: umi_pi0_relative_ee
-    title: UMI Data with pi0 Relative EE Actions
   title: "Tutorials"
 - sections:
   - local: lerobot-dataset-v3
@@ -51,8 +47,6 @@
     title: NVIDIA GR00T N1.5
   - local: xvla
     title: X-VLA
-  - local: multi_task_dit
-    title: Multitask DiT Policy
   - local: walloss
     title: WALL-OSS
   title: "Policies"
@@ -89,8 +83,6 @@
     title: Processors for Robots and Teleoperators
   - local: env_processor
     title: Environment Processors
-  - local: action_representations
-    title: Action Representations
   title: "Robot Processors"
 - sections:
   - local: so101

docs/source/action_representations.mdx

@@ -1,238 +0,0 @@
-# Action Representations
-
-This guide explains the different ways robot actions can be represented in LeRobot, how they relate to each other, and when to use each one.
-
-## Joint Space vs End-Effector Space
-
-Before discussing action representations, it helps to understand the two coordinate spaces actions can live in.
-
-### Joint Space
-
-Joint-space actions directly specify target positions for each motor. For a 6-DOF arm with a gripper, a joint-space action might look like:
-
-```
-action = [shoulder_pan: 45.0, shoulder_lift: -20.0, elbow: -30.0, wrist_pitch: 10.0, wrist_roll: 0.0, wrist_yaw: 5.0, gripper: 0.8]
-```
-
-Joint space is the default in LeRobot. It is simple, requires no kinematics model, and maps directly to motor commands. Most beginner setups (SO-100, Koch) use joint-space actions.
-
-### End-Effector (EE) Space
-
-End-effector-space actions specify the desired position and orientation of the robot's tool tip (gripper) in Cartesian coordinates:
-
-```
-action = [x: 0.25, y: -0.10, z: 0.15, wx: 0.0, wy: 0.0, wz: 0.1, gripper: 0.8]
-```
-
-EE space is more intuitive for tasks like pick-and-place because it directly describes where the gripper should go, but it requires a kinematics model (URDF) to convert between EE poses and joint angles.
-
-### Converting Between Spaces
-
-LeRobot provides processor steps for converting between joint and EE spaces using forward and inverse kinematics. These are built on top of `RobotKinematics`, which loads a URDF model of your robot.
-
-```python
-from lerobot.model.kinematics import RobotKinematics
-from lerobot.robots.so_follower.robot_kinematic_processor import (
-    ForwardKinematicsJointsToEE,
-    InverseKinematicsEEToJoints,
-)
-
-kinematics = RobotKinematics(
-    urdf_path="./SO101/so101_new_calib.urdf",
-    target_frame_name="gripper_frame_link",
-    joint_names=["shoulder", "elbow", "wrist_pitch", "wrist_roll", "wrist_yaw"],
-)
-
-# Joints → EE (for observations: "where is my gripper?")
-fk_step = ForwardKinematicsJointsToEE(kinematics=kinematics, motor_names=[...])
-
-# EE → Joints (for actions: "move my gripper here")
-ik_step = InverseKinematicsEEToJoints(kinematics=kinematics, motor_names=[...])
-```
-
-See [`examples/so100_to_so100_EE/`](https://github.com/huggingface/lerobot/tree/main/examples/so100_to_so100_EE) for a complete working example of recording, replaying, and evaluating with EE-space actions on an SO-100 arm.
-
-## Absolute, Relative, and Delta Actions
-
-Regardless of whether you work in joint space or EE space, the action values can be expressed in three different ways. The terminology follows [UMI (Chi et al., 2024)](https://arxiv.org/abs/2402.10329).
-
-### Absolute Actions (LeRobot default)
-
-Each action specifies the target position directly.
-
-**Example** (joint space, chunk of 4):
-
-```
-current_state = [45.0, -30.0, 10.0]
-
-action_chunk = [
-    [46.0, -29.0, 11.0],   # go to 46, -29, 11
-    [47.5, -27.0, 12.0],   # go to 47.5, -27, 12
-    [49.0, -25.0, 13.5],   # go to 49, -25, 13.5
-    [50.0, -24.0, 15.0],   # go to 50, -24, 15
-]
-```
-
-Each value is a target position in the robot's coordinate frame. Simple and direct, but requires a consistent global coordinate frame. This is the default in LeRobot.
-
-### Relative Actions (used by OpenPI / pi0)
-
-Each action in the chunk is an offset from the **current state at the moment of prediction**. All actions in the chunk share the same reference point:
-
-```
-current_state = [45.0, -30.0, 10.0]
-
-relative_chunk = [
-    [1.0,  1.0, 1.0],   # +1 from current → target 46, -29, 11
-    [2.5,  3.0, 2.0],   # +2.5 from current → target 47.5, -27, 12
-    [4.0,  5.0, 3.5],   # +4 from current → target 49, -25, 13.5
-    [5.0,  6.0, 5.0],   # +5 from current → target 50, -24, 15
-]
-```
-
-The conversion is straightforward: `relative = absolute - current_state`. To recover absolute: `absolute = relative + current_state`.
-
-**Why use relative actions?** The model learns to predict offsets centered around zero, which is easier to normalize and leads to more stable training. Because every chunk references the same current state, there is no error accumulation across chunks.
-
-### Delta Actions (sequential differences)
-
-Each action is an offset from the **previous action** (or from the current state for the first step):
-
-```
-current_state = [45.0, -30.0, 10.0]
-
-delta_chunk = [
-    [1.0,  1.0, 1.0],   # current → 46, -29, 11
-    [1.5,  2.0, 1.0],   # previous action → 47.5, -27, 12
-    [1.5,  2.0, 1.5],   # previous action → 49, -25, 13.5
-    [1.0,  1.0, 1.5],   # previous action → 50, -24, 15
-]
-```
-
-Here each step is relative to the one before it. To recover absolute positions you must sum all previous deltas, which means errors accumulate over time. UMI explicitly argues against this representation for this reason.
-
-### Visual Comparison
-
-The figure below (based on a figure from [UMI, Chi et al., 2024](https://arxiv.org/abs/2402.10329)) illustrates the key difference. With **relative trajectory**, every action in the chunk points back to the same origin (current state), so a new inference step cleanly resets the reference. With **delta**, each action depends on the previous one, so errors accumulate. **Absolute** actions require a consistent global coordinate frame.
-
-<img
-  src="https://huggingface.co/datasets/huggingface/documentation-images/resolve/main/lerobot/action_representations_umi.png"
-  alt="Relative Trajectory as Action Representation (UMI, Chi et al., 2024)"
-  width="85%"
-/>
-
-## Using Relative Actions in LeRobot
-
-LeRobot provides `RelativeActionsProcessorStep` to convert between absolute and relative actions inside the processor pipeline. This is how pi0, pi0.5, and pi0_fast support relative actions.
-
-> **Note:** All pi models (pi0, pi0.5, pi0*fast) apply relative conversion \_before* normalization (`relative → normalize`), so the normalizer always sees delta (relative) values. This means **relative action stats are required** for all of them when training with `use_relative_actions=true`. In pi0_fast the `RelativeActionsProcessorStep` only modifies the action — the state observation is unchanged — so `NormalizerProcessorStep` still runs before the state tokenizer and the tokenizer continues to receive normalized state as expected.
-
-### How it works
-
-During **training** (preprocessing), actions are converted from absolute to relative before the model sees them:
-
-```
-raw absolute action → RelativeActionsProcessorStep → normalize → model
-```
-
-During **inference** (postprocessing), model predictions are converted back to absolute before being sent to the robot:
-
-```
-model output → unnormalize → AbsoluteActionsProcessorStep → robot
-```
-
-The `AbsoluteActionsProcessorStep` reads the cached current state from its paired `RelativeActionsProcessorStep`, so the two must be wired together (handled automatically by the policy factory).
-
-### Enabling relative actions for the pi family (pi0, pi0.5, pi0_fast)
-
-**Step 1**: Precompute relative action statistics for your dataset:
-
-```bash
-lerobot-edit-dataset \
-    --repo_id your_dataset \
-    --operation.type recompute_stats \
-    --operation.relative_action true \
-    --operation.chunk_size 50 \
-    --operation.relative_exclude_joints "['gripper']"
-```
-
-**Step 2**: Train with relative actions enabled:
-
-```bash
-lerobot-train \
-    --dataset.repo_id=your_dataset \
-    --policy.type=pi0 \
-    --policy.use_relative_actions=true \
-    --policy.relative_exclude_joints='["gripper"]'
-```
-
-The `relative_exclude_joints` parameter specifies joints that should remain in absolute space. For example, gripper commands are typically binary (open/close) and don't benefit from relative encoding.
-
-### Combining relative actions with RTC
-
-[RTC](https://arxiv.org/abs/2506.07339) runs policy inference at high frequency and sends actions to the robot as they are predicted rather than waiting for a full chunk. Relative actions and RTC are fully compatible: because every chunk in relative mode references the **same** current state (captured at the start of inference), each predicted action in the chunk remains a valid offset even if the robot has already moved. No special handling is needed — `RelativeActionsProcessorStep` caches the state once per inference call and `AbsoluteActionsProcessorStep` applies it to every action in the streamed output.
-
-### Combining relative actions with EE space
-
-Relative actions work in both joint space and EE space. For example, if your dataset stores EE actions, relative encoding converts them to offsets from the current EE pose:
-
-```
-current_ee_state = [x: 0.25, y: -0.10, z: 0.15, gripper: 0.8]
-
-absolute_ee_chunk = [
-    [0.26, -0.09, 0.16, 0.8],
-    [0.28, -0.07, 0.18, 0.8],
-]
-
-relative_ee_chunk = [
-    [0.01,  0.01, 0.01, 0.0],   # offset from current EE pose
-    [0.03,  0.03, 0.03, 0.0],   # offset from current EE pose
-]
-```
-
-## Processing Pipeline Summary
-
-Here is how the different processors compose. Each arrow is a processor step, and they can be chained in a `RobotProcessorPipeline` or `PolicyProcessorPipeline`:
-
-```
-                    ┌─────────────────────────────────────────┐
-   Action Space     │   Joint Space  ←──IK──→  EE Space      │
-                    │   ForwardKinematicsJointsToEE           │
-                    │   InverseKinematicsEEToJoints           │
-                    └─────────────────────────────────────────┘
-
-                    ┌─────────────────────────────────────────┐
-   State Derivation │   Action column  ────→  State + Action  │
-                    │   DeriveStateFromActionStep (pre only)  │
-                    │   (UMI-style: state from action chunk)  │
-                    └─────────────────────────────────────────┘
-
-                    ┌─────────────────────────────────────────┐
-   Action Repr.     │   Absolute  ←────→  Relative            │
-                    │   RelativeActionsProcessorStep (pre)    │
-                    │   AbsoluteActionsProcessorStep (post)   │
-                    └─────────────────────────────────────────┘
-
-                    ┌─────────────────────────────────────────┐
-   State Repr.      │   Absolute  ────→  Relative             │
-                    │   RelativeStateProcessorStep (pre only) │
-                    └─────────────────────────────────────────┘
-
-                    ┌─────────────────────────────────────────┐
-   Normalization    │   Raw  ←────→  Normalized               │
-                    │   NormalizerProcessorStep (pre)         │
-                    │   UnnormalizerProcessorStep (post)      │
-                    └─────────────────────────────────────────┘
-```
-
-A typical training preprocessor might chain: `raw absolute joint actions → relative → normalize`. A typical inference postprocessor: `unnormalize → absolute → (optionally IK to joints)`.
-
-With UMI-style relative proprioception (`use_relative_state=True`), the preprocessor also converts observation.state to offsets from the current timestep via `RelativeStateProcessorStep` before normalization. This is a pre-processing-only step (state is an input, not an output).
-
-With `derive_state_from_action=True`, the preprocessor first runs `DeriveStateFromActionStep` to extract a 2-step state from the extended action chunk. This enables full UMI-style training without a separate `observation.state` column. See the [UMI pi0 guide](umi_pi0_relative_ee) for details.
-
-## References
-
-- [Universal Manipulation Interface (UMI)](https://arxiv.org/abs/2402.10329) - Chi et al., 2024. Defines the relative trajectory action representation and compares it with absolute and delta actions.
-- [Introduction to Processors](./introduction_processors) - How processor pipelines work in LeRobot.
-- [`examples/so100_to_so100_EE/`](https://github.com/huggingface/lerobot/tree/main/examples/so100_to_so100_EE) - Complete example of recording and evaluating with EE-space actions.

docs/source/async.mdx

@@ -310,4 +310,4 @@ Asynchronous inference represents a significant advancement in real-time robotic
 - **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).
+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/lerobot/lerobot/issues).

docs/source/bring_your_own_policies.mdx

@@ -41,15 +41,13 @@ requires = # your-build-system
 
 ## Step 2: Define the Policy Configuration
 
-Create a configuration class that inherits from [`PreTrainedConfig`](https://github.com/huggingface/lerobot/blob/main/src/lerobot/configs/policies.py) and registers your policy type:
-Here is a template to get you started, customize the parameters and methods as needed for your policy's architecture and training requirements.
+Create a configuration class that inherits from `PreTrainedConfig` and registers your policy type:
 
 ```python
 # configuration_my_custom_policy.py
 from dataclasses import dataclass, field
 from lerobot.configs.policies import PreTrainedConfig
-from lerobot.optim.optimizers import AdamWConfig
-from lerobot.optim.schedulers import CosineDecayWithWarmupSchedulerConfig
+from lerobot.configs.types import NormalizationMode
 
 @PreTrainedConfig.register_subclass("my_custom_policy")
 @dataclass
@@ -63,56 +61,22 @@ class MyCustomPolicyConfig(PreTrainedConfig):
         hidden_dim: Hidden dimension for the policy network
         # Add your policy-specific parameters here
     """
-
-    horizon: int = 50
-    n_action_steps: int = 50
-    hidden_dim: int = 256
-
-    optimizer_lr: float = 1e-4
-    optimizer_weight_decay: float = 1e-4
+    # ...PreTrainedConfig fields...
+    pass
 
     def __post_init__(self):
         super().__post_init__()
-        if self.n_action_steps > self.horizon:
-            raise ValueError("n_action_steps cannot exceed horizon")
+        # Add any validation logic here
 
     def validate_features(self) -> None:
         """Validate input/output feature compatibility."""
-        if not self.image_features:
-            raise ValueError("MyCustomPolicy requires at least one image feature.")
-        if self.action_feature is None:
-            raise ValueError("MyCustomPolicy requires 'action' in output_features.")
-
-    def get_optimizer_preset(self) -> AdamWConfig:
-        return AdamWConfig(lr=self.optimizer_lr, weight_decay=self.optimizer_weight_decay)
-
-    def get_scheduler_preset(self):
-        return None
-
-    @property
-    def observation_delta_indices(self) -> list[int] | None:
-        """Relative timestep offsets the dataset loader provides per observation.
-
-        Return `None` for single-frame policies. For temporal policies that consume
-        multiple past or future frames, return a list of offsets, e.g. `[-20, -10, 0, 10]` for
-        3 past frames at stride 10 and 1 future frame at stride 10.
-        """
-        return None
-
-    @property
-    def action_delta_indices(self) -> list[int]:
-        """Relative timestep offsets for the action chunk the dataset loader returns.
-        """
-        return list(range(self.horizon))
-
-    @property
-    def reward_delta_indices(self) -> None:
-        return None
+        # Implement validation logic for your policy's requirements
+        pass
 ```
 
 ## Step 3: Implement the Policy Class
 
-Create your policy implementation by inheriting from [`PreTrainedPolicy`](https://github.com/huggingface/lerobot/blob/main/src/lerobot/policies/pretrained.py):
+Create your policy implementation by inheriting from LeRobot's base `PreTrainedPolicy` class:
 
 ```python
 # modeling_my_custom_policy.py
@@ -121,73 +85,37 @@ import torch.nn as nn
 from typing import Any
 
 from lerobot.policies.pretrained import PreTrainedPolicy
-from lerobot.utils.constants import ACTION
 from .configuration_my_custom_policy import MyCustomPolicyConfig
 
 class MyCustomPolicy(PreTrainedPolicy):
-    config_class = MyCustomPolicyConfig  # must match the string in @register_subclass
+    config_class = MyCustomPolicyConfig
     name = "my_custom_policy"
 
     def __init__(self, config: MyCustomPolicyConfig, dataset_stats: dict[str, Any] = None):
         super().__init__(config, dataset_stats)
-        config.validate_features()  # not called automatically by the base class
-        self.config = config
-        self.model = ...  # your nn.Module here
-
-    def reset(self):
-        """Reset episode state."""
         ...
-
-    def get_optim_params(self) -> dict:
-        """Return parameters to pass to the optimizer (e.g. with per-group lr/wd)."""
-        return {"params": self.parameters()}
-
-    def predict_action_chunk(self, batch: dict[str, torch.Tensor], **kwargs) -> torch.Tensor:
-        """Return the full action chunk (B, chunk_size, action_dim) for the current observation."""
-        ...
-
-    def select_action(self, batch: dict[str, torch.Tensor], **kwargs) -> torch.Tensor:
-        """Return a single action for the current timestep (called at inference)."""
-        ...
-
-    def forward(self, batch: dict[str, torch.Tensor]) -> dict[str, torch.Tensor]:
-        """Compute the training loss.
-
-        `batch["action_is_pad"]` is a bool mask of shape (B, horizon) that marks
-        timesteps padded because the episode ended before `horizon` steps, you
-        can exclude those from your loss.
-        """
-        actions = batch[ACTION]
-        action_is_pad = batch.get("action_is_pad")
-        ...
-        return {"loss": ...}
 ```
 
 ## Step 4: Add Data Processors
 
-Create processor functions. For a concrete reference, see [processor_act.py](https://github.com/huggingface/lerobot/blob/main/src/lerobot/policies/act/processor_act.py) or [processor_diffusion.py](https://github.com/huggingface/lerobot/blob/main/src/lerobot/policies/diffusion/processor_diffusion.py).
+Create processor functions:
 
 ```python
 # processor_my_custom_policy.py
 from typing import Any
 import torch
 
-from lerobot.processor import PolicyAction, PolicyProcessorPipeline
-
 
 def make_my_custom_policy_pre_post_processors(
     config,
-    dataset_stats: dict[str, dict[str, torch.Tensor]] | None = None,
 ) -> tuple[
     PolicyProcessorPipeline[dict[str, Any], dict[str, Any]],
     PolicyProcessorPipeline[PolicyAction, PolicyAction],
 ]:
-    preprocessor = ...   # build your PolicyProcessorPipeline for inputs
-    postprocessor = ...  # build your PolicyProcessorPipeline for outputs
-    return preprocessor, postprocessor
-```
+    """Create preprocessing and postprocessing functions for your policy."""
+    pass  # Define your preprocessing and postprocessing logic here
 
-**Important - function naming:** LeRobot discovers your processor by name. The function **must** be called `make_{policy_name}_pre_post_processors` (matching the string you passed to `@PreTrainedConfig.register_subclass`).
+```
 
 ## Step 5: Package Initialization
 

docs/source/earthrover_mini_plus.mdx

@@ -204,26 +204,22 @@ Replace `your_username/dataset_name` with your Hugging Face username and a name
 
 Your dataset includes:
 
-**Your Actions (2 features)**:
+**Your Actions (2 things)**:
 
-- `linear_velocity`: How much you moved forward/backward
-- `angular_velocity`: How much you turned left/right
+- How much you moved forward/backward
+- How much you turned left/right
 
-**Robot Observations (24 features)**:
+**Robot Observations (12 things)**:
 
 - Front camera video
 - Rear camera video
 - Current speed
 - Battery level
-- Orientation
-- GPS (latitude, longitude, signal strength)
+- Which way the robot is facing
+- GPS location (latitude, longitude, signal strength)
 - Network signal strength
 - Vibration level
-- Lamp state (on/off)
-- Accelerometer (x, y, z)
-- Gyroscope (x, y, z)
-- Magnetometer (x, y, z)
-- Wheel RPMs (4 wheels)
+- Lamp status (on/off)
 
 ### Where Your Data Goes
 

docs/source/il_robots.mdx

@@ -424,7 +424,7 @@ robot = SO100Follower(robot_config)
 robot.connect()
 
 dataset = LeRobotDataset("<hf_username>/<dataset_repo_id>", episodes=[episode_idx])
-actions = dataset.select_columns("action")
+actions = dataset.hf_dataset.select_columns("action")
 
 log_say(f"Replaying episode {episode_idx}")
 for idx in range(dataset.num_frames):

docs/source/multi_task_dit.mdx

@@ -1,340 +0,0 @@
-# Multitask DiT Policy
-
-Multitask Diffusion Transformer (DiT) Policy is an evolution of the original Diffusion Policy architecture, which leverages a large DiT with text and vision conditioning for multitask robot learning. This implementation supports both diffusion and flow matching objectives for action generation, enabling robots to perform diverse manipulation tasks conditioned on language instructions.
-
-## Model Overview
-
-The model uses:
-
-- **CLIP Vision Encoder**: Processes RGB images from multiple camera views
-- **CLIP Text Encoder**: Encodes language task instructions (frozen weights with learnable projection)
-- **Diffusion Transformer**: Predicts action sequences conditioned on observations and language
-- **Two Objectives**: Supports both diffusion (DDPM/DDIM) and flow matching for action generation
-
-This model is exciting because you can achieve extremely high dexterity, competitive with multi-billion parameter
-VLAs, with only ~450M parameters and significantly less training.
-
-## Installation Requirements
-
-Multitask DiT Policy has additional dependencies. Install it with:
-
-```bash
-pip install lerobot[multi_task_dit]
-```
-
-This will install all necessary dependencies including the HuggingFace Transformers library for CLIP models.
-
-## Usage
-
-To use Multitask DiT in your LeRobot configuration, specify the policy type as:
-
-```python
-policy.type=multi_task_dit
-```
-
-## Training
-
-### Basic Training Command
-
-Here's a complete training command for training Multitask DiT on your dataset:
-
-```bash
-lerobot-train \
-  --dataset.repo_id=YOUR_DATASET \
-  --output_dir=./outputs/multitask_dit_training \
-  --batch_size=32 \
-  --steps=5000 \
-  --save_freq=500 \
-  --log_freq=100 \
-  --policy.type=multi_task_dit \
-  --policy.device=cuda \
-  --policy.repo_id="HF_USER/multitask-dit-your-robot" \
-  --wandb.enable=true
-```
-
-### Recommended Hyperparameters and Dataset Details (30Hz Control Frequency)
-
-For reliable performance, start with these suggested default hyperparameters:
-
-```bash
-lerobot-train \
-  --dataset.repo_id=YOUR_DATASET \
-  --output_dir=./outputs/mutitask_dit_training \
-  --batch_size=320 \
-  --steps=30000 \
-  --policy.type=multi_task_dit \
-  --policy.device=cuda \
-  --policy.horizon=32 \
-  --policy.n_action_steps=24 \
-  --policy.objective=diffusion \
-  --policy.noise_scheduler_type=DDPM \
-  --policy.num_train_timesteps=100 \
-  --policy.repo_id="HF_USER/multitask-dit-your-robot" \
-  --wandb.enable=true
-```
-
-**Key Parameters:**
-
-- **Batch Size**: 192-320 - If you have access to a GPU that can support this, you will get the best training dynamics
-- **Horizon**: 32 - number of action steps to predict, ~1.0 sec at 30Hz
-- **n_action_steps**: 24 - ~0.8 seconds at 30Hz
-- **Objective**: `diffusion` - start with diffusion and experiment with flow matching if generation quality is poor
-- **Training Steps**: >30k steps recommended for a single task
-
-### Training Configuration Parameters
-
-#### Objective Selection
-
-Choose between diffusion and flow matching:
-
-```bash
-# Diffusion objective (default)
---policy.objective=diffusion \
---policy.noise_scheduler_type=DDPM \  # or "DDIM"
---policy.num_train_timesteps=100 \
---policy.num_inference_steps=10 \  # For faster inference
---policy.beta_schedule=squaredcos_cap_v2 \  # Noise schedule type
---policy.prediction_type=epsilon \  # "epsilon" (predict noise) or "sample" (predict clean)
---policy.clip_sample=true \  # Clip samples during denoising
---policy.clip_sample_range=1.0  # Clipping range [-x, x]
-
-# Flow matching objective
---policy.objective=flow_matching \
---policy.timestep_sampling_strategy=beta \  # or "uniform" | the beta sampling strategy performance appears much better in practice
---policy.num_integration_steps=100 \
---policy.integration_method=euler \  # or "rk4"
---policy.sigma_min=0.0  # Minimum noise in flow interpolation path
-```
-
-#### Transformer Architecture
-
-Adjust model capacity based on dataset size:
-
-```bash
-# Small datasets (< 100 examples)
---policy.num_layers=4 \
---policy.hidden_dim=512 \
---policy.num_heads=8  # should ideally be hidden_dim // 64
-
-# Medium datasets (100-5k examples) - default
---policy.num_layers=6 \
---policy.hidden_dim=512 \
---policy.num_heads=8  # should ideally be hidden_dim // 64
-
-# Large datasets (> 5k examples)
---policy.num_layers=8 \
---policy.hidden_dim=512 \
---policy.num_heads=8   # should ideally be hidden_dim // 64
-```
-
-**Positional Encoding Options:**
-
-The model supports two positional encoding methods for action sequences:
-
-```bash
-# Rotary Position Embedding (RoPE) - default, recommended
---policy.use_rope=true \
---policy.rope_base=10000.0  # Base frequency for RoPE
-
-# Absolute positional encoding
---policy.use_positional_encoding=true  # Disables RoPE when true
-```
-
-**Other Transformer Parameters:**
-
-```bash
---policy.dropout=0.1  # Dropout rate for DiT blocks (0.0-1.0)
---policy.timestep_embed_dim=256  # Timestep embedding dimension
-```
-
-#### Vision Encoder Configuration
-
-```bash
-# Use different CLIP model for more expressivity at the cost of inference time
-# experiment with larger or smaller models depending on the complexity of your tasks and size of dataset
---policy.vision_encoder_name=openai/clip-vit-large-patch14
-
-# Use separate vision encoder per camera
-# This may be useful when cameras have significantly different characteristics, but
-# be wary of increased VRAM footprint.
---policy.use_separate_rgb_encoder_per_camera=true
-
-# Image preprocessing
---policy.image_resize_shape=[XXX,YYY] \ # you may need to resize your images for inference speed ups
---policy.image_crop_shape=[224,224] \
---policy.image_crop_is_random=true  # Random during training, center at inference
-```
-
-#### Text Encoder Configuration
-
-```bash
-# Use different CLIP text encoder model
-# same as vision: experiment with larger or smaller models depending on the
-# complexity of your tasks and size of dataset
---policy.text_encoder_name=openai/clip-vit-large-patch14
-```
-
-#### Learning Rate Configuration
-
-The vision encoder uses a separate learning rate multiplier, where 1/10th is suggested to be the ideal staritng point:
-
-```bash
---policy.optimizer_lr=2e-5 \
---policy.vision_encoder_lr_multiplier=0.1  # Vision encoder LR = 0.1 * optimizer_lr
-```
-
-### Training Tuning Guidelines
-
-#### 1. Flow Matching with Beta Sampling
-
-The original diffusion implementation here is based on the work described in [TRI's LBM paper](https://arxiv.org/abs/2507.05331)
-
-Additionally, we have implemented a flow-matching objective, which is described at a high-level in [Boston Dynamics blog post](https://bostondynamics.com/blog/large-behavior-models-atlas-find-new-footing/).
-
-Consider testing the flow-matching objective and evaluating performance differences for your task:
-
-```bash
---policy.objective=flow_matching \
---policy.timestep_sampling_strategy=beta \
---policy.timestep_sampling_alpha=1.5 \
---policy.timestep_sampling_beta=1.0 \
---policy.timestep_sampling_s=0.999
-```
-
-This hasn't been shown to be a silver bullet across every user case, but it occasionally results in smoother and more consistent actions.
-
-#### 2. Number of Transformer Layers
-
-Match model capacity to your dataset size:
-
-- **Small datasets** (< 100 examples): Reduce to 4 layers
-- **Large datasets** (> 5k examples): Increase to 8 layers
-
-#### 3. `horizon` Tuning
-
-The model can be sensitive to the horizon you choose. Start with around a 1 second horizon based on your control frequency:
-
-- **30 Hz frequency**: `horizon=30`
-- **10 Hz frequency**: `horizon=10`
-
-Then experiment with increasing from there. The horizon determines how far into the future the model predicts actions.
-
-#### 4. `n_action_steps` Sensitivity
-
-The model can also be very sensitive to `n_action_steps`. Start with it being around 0.8 seconds based on your control frequency and tune from there:
-
-- **Lower values**: More reactive but potentially less stable for long-horizon tasks
-- **Higher values**: Better for long-horizon execution but open-loop failures are limited in their recovery
-
-### Inference Tuning
-
-For faster inference, use DDIM with fewer sampling steps:
-
-```bash
---policy.noise_scheduler_type=DDIM \
---policy.num_inference_steps=10
-```
-
-### Resuming Training
-
-To resume training from a checkpoint:
-
-```bash
-lerobot-train \
-  --config_path=./outputs/mutitask_dit_training/checkpoints/last/pretrained_model/train_config.json \
-  --resume=true
-```
-
-The checkpoint directory should contain `model.safetensors` and `config.json` files (saved automatically during training). When resuming, the configuration is loaded from the checkpoint, so you don't need to specify other parameters.
-
-## Common Failure Modes and Debugging
-
-Training these models can be finicky. Here are common failure modes and debugging approaches:
-
-### Idling / No Motion
-
-The model may "collapse" during inference, resulting in static or no motion. This can occur when:
-
-1. **Insufficient training data**: If you only have 20-50 examples, try to roughly double your dataset size. Once you have above 300 examples, if you're still seeing this, the task may be too complex.
-
-2. **Multiple similar tasks**: When your dataset contains multiple similar tasks (e.g., picking up 2 different objects), the model may rely too heavily on language conditioning which might not be rich enough.
-
-**Debugging tips:**
-
-- Increase dataset size (double until you get to over 300 examples)
-- Train for longer, up to 100k steps, even when the loss flatlines
-- Check if the model is receiving proper language instructions or increase diversity of instruction
-
-### Executing the Wrong Task
-
-Sometimes the robot will completely ignore your instruction and perform some other task. This generally only happens if you have trained on multiple tasks.
-
-**Potential causes:**
-
-- Language instruction ambiguity
-- Insufficient task-specific training data
-- Model confusion between similar tasks in the multitask dataset
-
-**Debugging tips:**
-
-- Verify language instruction specificity, especially if descriptions are similar between multiple tasks
-- Check task distribution in your training dataset and add weighting to the failing/ignored task
-- Consider task-specific fine-tuning
-
-### Training Instability
-
-If training loss is unstable or diverging:
-
-- Try adjusting learning rate between `1e-5` and `3e-4`
-- Increase batch size if possible
-- Check that your dataset normalization is correct
-- Verify image preprocessing is working correctly
-
-## Performance Considerations
-
-### GPU Requirements
-
-- **Inference**: At least an RTX 5070 Ti (or equivalent GPU) is recommended for reasonable speed performance
-- **Training**: A GPU with enough VRAM to load batch sizes of >64 is ideal, which will vary depending on the number of image observations, etc
-
-### Batch Size Recommendations
-
-- **Minimum**: 64 (less than this may result in unstable training)
-- **Recommended**: 256-320 (best performance, requires larger GPU)
-
-## Example: Training on Custom Dataset
-
-Here's a complete example training on a custom dataset:
-
-```bash
-lerobot-train \
-  --dataset.repo_id=YOUR_DATASET \
-  --output_dir=./outputs/mutitask_dit_training \
-  --batch_size=320 \
-  --steps=30000 \
-  --save_freq=1000 \
-  --log_freq=100 \
-  --eval_freq=1000 \
-  --policy.type=multi_task_dit \
-  --policy.device=cuda \
-  --policy.horizon=32 \
-  --policy.n_action_steps=24 \
-  --policy.objective=diffusion \
-  --policy.noise_scheduler_type=DDPM \
-  --policy.num_layers=6 \
-  --policy.hidden_dim=512 \
-  --policy.vision_encoder_name=openai/clip-vit-base-patch16 \
-  --policy.image_resize_shape=[320,240] \
-  --policy.image_crop_shape=[224,224] \
-  --policy.repo_id="HF_USER/multitask-dit-your-robot" \
-  --wandb.enable=true \
-  --wandb.project=multitask_dit
-```
-
-## References
-
-For more details on the technical implementation and architecture, see:
-
-- [A Careful Examination of Large Behavior Models for Multitask Dexterous Manipulation](https://arxiv.org/abs/2507.05331)
-- [Large Behavior Models and Atlas Find New Footing](https://bostondynamics.com/blog/large-behavior-models-atlas-find-new-footing/)
-- [Dissecting and Open-Sourcing Multitask Diffusion Transformer Policy](https://brysonkjones.substack.com/p/dissecting-and-open-sourcing-multitask-diffusion-transformer-policy)

docs/source/pi0.mdx

@@ -91,46 +91,6 @@ lerobot-train \
 
 **💡 Tip**: Setting `train_expert_only=true` freezes the VLM and trains only the action expert and projections, allowing finetuning with reduced memory usage.
 
-## Relative Actions
-
-By default, π₀ predicts absolute actions. You can enable **relative actions** so the model predicts offsets relative to the current robot state. This can improve training stability for certain setups.
-
-To use relative actions, first recompute your dataset stats in relative space via the CLI:
-
-```bash
-lerobot-edit-dataset \
-    --repo_id your_dataset \
-    --operation.type recompute_stats \
-    --operation.relative_action true \
-    --operation.chunk_size 50 \
-    --operation.relative_exclude_joints "['gripper']" \
-    --push_to_hub true
-```
-
-Or equivalently in Python:
-
-```python
-from lerobot.datasets.lerobot_dataset import LeRobotDataset
-from lerobot.datasets.dataset_tools import recompute_stats
-
-dataset = LeRobotDataset("your_dataset")
-recompute_stats(dataset, relative_action=True, chunk_size=50, relative_exclude_joints=["gripper"])
-dataset.push_to_hub()
-```
-
-The `chunk_size` should match your policy's `chunk_size` (default 50 for π₀). `relative_exclude_joints` lists joint names that should remain in absolute space (e.g. gripper commands). Use `--push_to_hub true` to upload the updated stats to the Hub.
-
-Then train with relative actions enabled:
-
-```bash
-lerobot-train \
-    --dataset.repo_id=your_dataset \
-    --policy.type=pi0 \
-    --policy.use_relative_actions=true \
-    --policy.relative_exclude_joints='["gripper"]' \
-    ...
-```
-
 ## License
 
 This model follows the **Apache 2.0 License**, consistent with the original [OpenPI repository](https://github.com/Physical-Intelligence/openpi).

docs/source/pi05.mdx

@@ -97,46 +97,6 @@ python src/lerobot/datasets/v30/augment_dataset_quantile_stats.py \
 
 Or train pi05 with this normalization mapping: `--policy.normalization_mapping='{"ACTION": "MEAN_STD", "STATE": "MEAN_STD", "VISUAL": "IDENTITY"}'`
 
-## Relative Actions
-
-By default, π₀.₅ predicts absolute actions. You can enable **relative actions** so the model predicts offsets relative to the current robot state. This can improve training stability for certain setups.
-
-To use relative actions, first recompute your dataset stats in relative space via the CLI:
-
-```bash
-lerobot-edit-dataset \
-    --repo_id your_dataset \
-    --operation.type recompute_stats \
-    --operation.relative_action true \
-    --operation.chunk_size 50 \
-    --operation.relative_exclude_joints "['gripper']" \
-    --push_to_hub true
-```
-
-Or equivalently in Python:
-
-```python
-from lerobot.datasets.lerobot_dataset import LeRobotDataset
-from lerobot.datasets.dataset_tools import recompute_stats
-
-dataset = LeRobotDataset("your_dataset")
-recompute_stats(dataset, relative_action=True, chunk_size=50, relative_exclude_joints=["gripper"])
-dataset.push_to_hub()
-```
-
-The `chunk_size` should match your policy's `chunk_size` (default 50 for π₀.₅). `relative_exclude_joints` lists joint names that should remain in absolute space (e.g. gripper commands). Use `--push_to_hub true` to upload the updated stats to the Hub.
-
-Then train with relative actions enabled:
-
-```bash
-lerobot-train \
-    --dataset.repo_id=your_dataset \
-    --policy.type=pi05 \
-    --policy.use_relative_actions=true \
-    --policy.relative_exclude_joints='["gripper"]' \
-    ...
-```
-
 ## Performance Results
 
 ### Libero Benchmark Results

docs/source/policy_multi_task_dit_README.md

@@ -1,37 +0,0 @@
-# Multitask DiT Policy
-
-## Citation
-
-If you use this work, please cite the following works:
-
-```bibtex
-@misc{jones2025multitaskditpolicy,
-  author = {Bryson Jones},
-  title = {Dissecting and Open-Sourcing Multitask Diffusion Transformer Policy},
-  year = {2025},
-  url = {https://brysonkjones.substack.com/p/dissecting-and-open-sourcing-multitask-diffusion-transformer-policy},
-  note = {Blog post}
-}
-```
-
-```bibtex
-@misc{trilbmteam2025carefulexaminationlargebehaviormodels,
-  author       = {TRI LBM Team},
-  title        = {A Careful Examination of Large Behavior Models for Multitask Dexterous Manipulation},
-  year         = {2025},
-  eprint       = {arXiv:2507.05331},
-  archivePrefix = {arXiv},
-  primaryClass = {cs.RO},
-  url          = {https://arxiv.org/abs/2507.05331}
-}
-```
-
-```bibtex
-@misc{bostondynamics2025largebehaviormodelsatlas,
-  author       = {Boston Dynamics and TRI Research Team},
-  title        = {Large Behavior Models and Atlas Find New Footing},
-  year         = {2025},
-  url          = {https://bostondynamics.com/blog/large-behavior-models-atlas-find-new-footing/},
-  note         = {Blog post}
-}
-```

docs/source/rename_map.mdx

@@ -1,114 +0,0 @@
-# Rename Map and Empty Cameras
-
-When you train, evaluate, or record with a robot policy, your **dataset** or **environment** provides observations under one set of keys (e.g. `observation.images.front`, `observation.images.eagle`), while your **policy** expects another (e.g. `observation.images.image`, `observation.images.image2`). The **rename map** bridges that gap without changing the policy or data source.
-
-> **Scope:** The rename map only renames **observation** keys (images and state). Action keys are not affected.
-
-## Why observation keys don't always match
-
-Policies have a fixed set of **input feature names** baked into their pretrained config. For example:
-
-- [pi0fast-libero](https://huggingface.co/lerobot/pi0fast-libero) expects `observation.images.base_0_rgb` and `observation.images.left_wrist_0_rgb`.
-- [xvla-base](https://huggingface.co/lerobot/xvla-base) expects `observation.images.image`, `observation.images.image2`, and `observation.images.image3`.
-
-Your dataset might use different names entirely (e.g. `observation.images.front`, `observation.images.eagle`, `observation.images.glove`), and your eval environment might use yet another set. Rather than editing the policy config or renaming columns in the dataset, you pass a **rename map**: a JSON dictionary that maps source keys to the keys the policy expects. Renaming happens inside the preprocessor pipeline, so the policy always sees its expected keys.
-
-## Using the rename map
-
-Pass the mapping as a JSON string on the command line. The convention is always:
-
-```
---rename_map='{"source_key": "policy_key", ...}'
-```
-
-where **source_key** is what the dataset or environment provides, and **policy_key** is what the policy expects.
-
-Only listed keys are renamed; everything else passes through unchanged. Order of entries doesn't matter.
-
-Supported policies: **PI0**, **PI05**, **PI0Fast**, **SmolVLA**, and **XVLA**.
-
-### Training
-
-Suppose you fine-tune [lerobot/xvla-base](https://huggingface.co/lerobot/xvla-base) on a dataset with images under `observation.images.front`, `observation.images.eagle`, and `observation.images.glove`. XVLA expects `observation.images.image`, `observation.images.image2`, and `observation.images.image3`:
-
-```bash
-lerobot-train \
-  --dataset.repo_id=YOUR_DATASET \
-  --output_dir=./outputs/xvla_training \
-  --job_name=xvla_training \
-  --policy.path="lerobot/xvla-base" \
-  --policy.repo_id="HF_USER/xvla-your-robot" \
-  --policy.dtype=bfloat16 \
-  --policy.action_mode=auto \
-  --steps=20000 \
-  --policy.device=cuda \
-  --policy.freeze_vision_encoder=false \
-  --policy.freeze_language_encoder=false \
-  --policy.train_policy_transformer=true \
-  --policy.train_soft_prompts=true \
-  --rename_map='{"observation.images.front": "observation.images.image", "observation.images.eagle": "observation.images.image2", "observation.images.glove": "observation.images.image3"}'
-```
-
-### Evaluation
-
-A policy that expects `observation.images.base_0_rgb` and `observation.images.left_wrist_0_rgb` (e.g. [pi0fast-libero](https://huggingface.co/lerobot/pi0fast-libero)), but the LIBERO environment returns `observation.images.image` and `observation.images.image2`:
-
-```bash
-lerobot-eval \
-  --policy.path=lerobot/pi0fast-libero \
-  --env.type=libero \
-  ... \
-  --rename_map='{"observation.images.image": "observation.images.base_0_rgb", "observation.images.image2": "observation.images.left_wrist_0_rgb"}'
-```
-
-### Recording
-
-`lerobot-record` also supports rename maps, nested under the dataset config:
-
-```bash
-lerobot-record \ # When running inference
-  --policy.path="<user>/smolVLA_finetuned" \
-  ... \
-  --dataset.rename_map='{"observation.images.glove2": "observation.images.image"}'
-```
-
-## Alternative: edit the policy config directly
-
-If you always use the same dataset or environment, you can **edit the policy's `config.json`** so its observation keys match your data source. Then no rename map is needed.
-
-The tradeoff: modifying the policy config ties it to one data source. A rename map keeps one policy usable across many datasets and environments.
-
-## Empty cameras: fewer views than the policy expects
-
-Some policies are built for a fixed number of image inputs. If your dataset has fewer cameras, you can set **`empty_cameras`** in the policy config instead of modifying the model architecture.
-
-### How it works
-
-Setting `empty_cameras=N` adds N placeholder image features to the policy config, named:
-
-```
-observation.images.empty_camera_0
-observation.images.empty_camera_1
-...
-```
-
-At runtime, these keys have no corresponding data in the batch. The policy fills them with masked dummy tensors (padded with `-1` for SigLIP-based vision encoders, with a zero attention mask), so the extra image slots are effectively ignored during training and inference.
-
-### Example
-
-XVLA-base has three visual inputs and `empty_cameras=0` by default. Your dataset only has two cameras:
-
-1. Set `--policy.empty_cameras=1`.
-2. The config adds a third key: `observation.images.empty_camera_0`.
-3. Use the rename map for your two real cameras as usual.
-4. The third slot is masked out — no fake images needed in your dataset.
-
-## Quick reference
-
-| Goal                                      | What to do                                                                  |
-| ----------------------------------------- | --------------------------------------------------------------------------- |
-| Dataset keys ≠ policy keys                | `--rename_map='{"dataset_key": "policy_key", ...}'`                         |
-| Env keys ≠ policy keys (eval)             | `--rename_map='{"env_key": "policy_key", ...}'`                             |
-| Recording with different keys (inference) | `--dataset.rename_map='{"source_key": "policy_key", ...}'`.                 |
-| Fewer cameras than policy expects         | `--policy.empty_cameras=N` (supported by PI0, PI05, PI0Fast, SmolVLA, XVLA) |
-| Avoid passing a rename map                | Edit the policy's `config.json` so its keys match your data source          |

docs/source/so101.mdx

@@ -236,10 +236,10 @@ It is advisable to install one 3-pin cable in the motor after placing them befor
 
 ### Joint 1
 
-- Install both motor horns. Secure the top horn with a M3x6mm screw. No screws are required for the bottom horn.
 - Place the first motor into the base.
 - Fasten the motor with 4 M2x6mm screws (smallest screws). Two from the top and two from the bottom.
 - Slide over the first motor holder and fasten it using two M2x6mm screws (one on each side).
+- Install both motor horns, securing the top horn with a M3x6mm screw.
 - Attach the shoulder part.
 - Tighten the shoulder part with 4 M3x6mm screws on top and 4 M3x6mm screws on the bottom
 - Add the shoulder motor holder.
@@ -255,9 +255,9 @@ It is advisable to install one 3-pin cable in the motor after placing them befor
 
 ### Joint 2
 
-- Install both motor horns. Secure the top horn with a M3x6mm screw. No screws are required for the bottom horn.
 - Slide the second motor in from the top.
 - Fasten the second motor with 4 M2x6mm screws.
+- Attach both motor horns to motor 2, again use the M3x6mm horn screw.
 - Attach the upper arm with 4 M3x6mm screws on each side.
 
 <div class="video-container">
@@ -271,8 +271,8 @@ It is advisable to install one 3-pin cable in the motor after placing them befor
 
 ### Joint 3
 
-- Install both motor horns. Secure the top horn with a M3x6mm screw. No screws are required for the bottom horn.
-- Insert motor 3 and fasten using 4 M2x6mm screws.
+- Insert motor 3 and fasten using 4 M2x6mm screws
+- Attach both motor horns to motor 3 and secure one again with a M3x6mm horn screw.
 - Connect the forearm to motor 3 using 4 M3x6mm screws on each side.
 
 <div class="video-container">
@@ -286,10 +286,9 @@ It is advisable to install one 3-pin cable in the motor after placing them befor
 
 ### Joint 4
 
-- Install both motor horns. Secure the top horn with a M3x6mm screw. No screws are required for the bottom horn.
 - Slide over motor holder 4.
 - Slide in motor 4.
-- Fasten motor 4 with 4 M2x6mm screws.
+- Fasten motor 4 with 4 M2x6mm screws and attach its motor horns, use a M3x6mm horn screw.
 
 <div class="video-container">
   <video controls width="600">
@@ -322,7 +321,7 @@ It is advisable to install one 3-pin cable in the motor after placing them befor
 
 - Attach the gripper to motor 5, attach it to the motor horn on the wrist using 4 M3x6mm screws.
 - Insert the gripper motor and secure it with 2 M2x6mm screws on each side.
-- Install both motor horns on the gripper motor. Secure the top horn with a M3x6mm screw; no screws are required for the bottom horn.
+- Attach the motor horns and again use a M3x6mm horn screw.
 - Install the gripper claw and secure it with 4 M3x6mm screws on both sides.
 
 <div class="video-container">

docs/source/umi_pi0_relative_ee.mdx

@@ -1,227 +0,0 @@
-# UMI Data with pi0 Relative EE Actions
-
-This guide explains how to train a pi0 policy with UMI-style relative end-effector (EE) actions and deploy it on a real OpenArm robot.
-
-**What we will do:**
-
-1. Prepare the dataset (EE pose + gripper in the action column).
-2. Recompute statistics for relative actions.
-3. Train pi0 with `derive_state_from_action=true`.
-4. Evaluate the trained policy on a real robot.
-
-## Background
-
-[UMI (Universal Manipulation Interface)](https://umi-gripper.github.io) collects manipulation data with hand-held grippers, recovering 6-DoF EE poses via SLAM. The key insight from UMI (Chi et al., 2024) is that the action space must include **both EE trajectory and gripper width**, and actions should be expressed as **relative trajectories** (offsets from the current pose).
-
-### Dataset layout
-
-The dataset should have this structure:
-
-| Feature                   | Shape     | Content                                                  |
-| ------------------------- | --------- | -------------------------------------------------------- |
-| `observation.images.cam0` | `[3,H,W]` | Wrist camera image                                       |
-| `action`                  | `[8]`     | `[x, y, z, ax, ay, az, proximal, distal]` (EE + gripper) |
-
-No separate `observation.pose` or `observation.joints` columns are needed — the model derives its proprioception state directly from the action column (`derive_state_from_action=true`).
-
-### Why relative actions?
-
-With relative actions, each action in a chunk is an **offset from the current state** rather than an absolute target:
-
-```
-relative_action[i] = absolute_action[t + i] − state[t]
-```
-
-UMI ablations show this is critical: absolute actions achieve only 25% success vs 100% for relative trajectory on the cup arrangement task. Compared to delta actions (each step relative to the previous), relative trajectory avoids error accumulation. See the [Action Representations](action_representations) guide for details.
-
-### `derive_state_from_action`
-
-When `derive_state_from_action=true`, pi0 derives `observation.state` from the action column during training — no separate state column needed. Under the hood:
-
-- `action_delta_indices` extends to `[-1, 0, 1, ..., chunk_size-1]` (one extra leading timestep).
-- `DeriveStateFromActionStep` extracts `[action[t-1], action[t]]` as a 2-step state and strips the extra timestep from the action chunk.
-- `RelativeActionsProcessorStep` converts actions to offsets from `state[t]`.
-- `RelativeStateProcessorStep` converts the 2-step state to relative proprioception (velocity + zeros) and flattens.
-
-This implies `use_relative_state=true` and `state_obs_steps=2`.
-
-During **inference**, `DeriveStateFromActionStep` is a no-op — state comes from the robot via forward kinematics. `RelativeStateProcessorStep` buffers the previous state and applies the same conversion automatically.
-
-## Step 1: Recompute Stats
-
-After preparing the dataset with EE pose in the action column, recompute statistics with `derive_state_from_action=true`. This computes relative action and state stats so the normalizer sees offset distributions:
-
-```bash
-lerobot-edit-dataset \
-    --repo-id=glannuzel/grabette-dataset \
-    --operation=recompute_stats \
-    --operation.relative_action=true \
-    --operation.relative_exclude_joints='["proximal", "distal"]' \
-    --operation.derive_state_from_action=true \
-    --operation.chunk_size=30 \
-    --push_to_hub=true
-```
-
-| Flag                            | Purpose                                                                         |
-| ------------------------------- | ------------------------------------------------------------------------------- |
-| `relative_action=true`          | Compute stats on `action − state` (relative actions)                            |
-| `relative_exclude_joints`       | Keep gripper dims absolute (they don't benefit from relative encoding)          |
-| `derive_state_from_action=true` | Derive state from action column (implies `relative_state`, `state_obs_steps=2`) |
-| `chunk_size=30`                 | Must match training chunk size                                                  |
-
-## Step 2: Train
-
-```bash
-#!/bin/bash
-set -euo pipefail
-
-export LD_LIBRARY_PATH=$CONDA_PREFIX/lib:${LD_LIBRARY_PATH:-}
-
-DATASET="glannuzel/grabette-dataset"
-NUM_PROCESSES=8
-
-echo "=== Training pi0 on $DATASET (UMI relative EE, ${NUM_PROCESSES} GPUs) ==="
-accelerate launch --multi_gpu --num_processes=$NUM_PROCESSES \
-    -m lerobot.scripts.lerobot_train \
-    --dataset.repo_id="$DATASET" \
-    --dataset.video_backend=pyav \
-    --policy.type=pi0 \
-    --policy.pretrained_path=lerobot/pi0_base \
-    --policy.repo_id=pepijn/grabette-umi-pi0 \
-    --policy.chunk_size=30 \
-    --policy.n_action_steps=30 \
-    --policy.derive_state_from_action=true \
-    --use_relative_actions=true \
-    --policy.relative_exclude_joints='["proximal", "distal"]' \
-    --batch_size=32 \
-    --steps=5000 \
-    --policy.scheduler_decay_steps=5000 \
-    --policy.dtype=bfloat16 \
-    --policy.compile_model=false \
-    --policy.gradient_checkpointing=true \
-    --policy.device=cuda \
-    --output_dir=/fsx/pepijn/outputs/grabette-umi \
-    --job_name=grabette-umi-v2 \
-    --wandb.enable=true \
-    --wandb.disable_artifact=true \
-    --wandb.project=grabette-umi \
-    --log_freq=100 \
-    --save_freq=5000
-```
-
-Key flags:
-
-| Flag                            | Purpose                                                                |
-| ------------------------------- | ---------------------------------------------------------------------- |
-| `derive_state_from_action=true` | Derive proprioception from action column (full UMI mode)               |
-| `use_relative_actions=true`     | Actions are offsets from current state                                 |
-| `relative_exclude_joints`       | `["proximal", "distal"]` — gripper stays absolute, EE pose is relative |
-| `chunk_size=30`                 | Action horizon: 30 steps (~0.65s at 46 FPS)                            |
-| `n_action_steps=30`             | Execute full chunk before replanning                                   |
-
-Note: `derive_state_from_action=true` automatically implies `use_relative_state=true` and `state_obs_steps=2`. No `rename_map` is needed since there are no separate observation columns to rename.
-
-## Step 3: Evaluate
-
-The evaluation script in `examples/umi_pi0_relative_ee/evaluate.py` runs inference on a real OpenArm robot:
-
-```bash
-python examples/umi_pi0_relative_ee/evaluate.py
-```
-
-Edit `HF_MODEL_ID`, camera index, and robot configuration at the top of the file.
-
-### How inference works
-
-At inference, the training dataset has no `observation.state` — it was derived from actions. The evaluate script provides `observation.state` from the robot via forward kinematics:
-
-1. **Robot → FK** — Arm joint positions → EE pose `[x,y,z,ax,ay,az]`, gripper → `[proximal, distal]`. Combined into `observation.state` (8D).
-2. **Preprocessor** (loaded from checkpoint) — `DeriveStateFromActionStep` is a no-op. `RelativeStateProcessorStep` buffers previous state, stacks `[prev, current]`, subtracts current → velocity info. `RelativeActionsProcessorStep` caches state. `NormalizerProcessorStep` normalizes.
-3. **pi0 inference** — Predicts normalized relative action chunk (30 steps).
-4. **Postprocessor** — `UnnormalizerProcessorStep` unnormalizes, `AbsoluteActionsProcessorStep` adds cached state → absolute EE targets.
-5. **IK → Robot** — Absolute `[x,y,z,ax,ay,az]` → arm joint targets with full 6-DOF IK (orientation weight = 1.0). `[proximal, distal]` → direct gripper position commands.
-
-### Latency compensation
-
-Set `LATENCY_SKIP_STEPS` to skip the first few predicted action steps, compensating for system latency:
-
-```python
-LATENCY_SKIP_STEPS = 7  # ceil(total_latency_ms / (1000 / FPS))
-```
-
-At 46 FPS (~22ms/step) with ~150ms total latency: `ceil(150/22) ≈ 7`. Start with 0 for a safe first test.
-
-## Replay Viewer
-
-Visualize any dataset episode in a browser-based 3D viewer before running on hardware. The viewer shows the EE trajectory overlaid on the OpenArm URDF model.
-
-### Quick start
-
-```bash
-python examples/umi_pi0_relative_ee/replay.py
-```
-
-### Options
-
-| Flag        | Default                      | Description                          |
-| ----------- | ---------------------------- | ------------------------------------ |
-| `--repo-id` | `glannuzel/grabette-dataset` | HuggingFace dataset repo to load     |
-| `--episode` | `0`                          | Episode index to replay              |
-| `--port`    | `8765`                       | HTTP server port                     |
-| `--force`   | off                          | Re-extract trajectory even if cached |
-
-### Viewer controls
-
-The panel in the top-left corner shows live EE coordinates and gripper state. Transport controls:
-
-- **Play / Pause** — toggle automatic playback.
-- **Step buttons** (◀ ▶) — advance or rewind one frame.
-- **Reset** (⟳) — jump to frame 0.
-- **Scrubber** — drag to seek.
-- **Speed selector** — 0.25× to 4× playback speed.
-
-### Color legend
-
-| Color              | Meaning                                       |
-| ------------------ | --------------------------------------------- |
-| Red sphere         | Current EE position                           |
-| Yellow trail       | Past trajectory                               |
-| Dark trail         | Future trajectory                             |
-| Orange ring + axes | URDF `ee_target` frame (zero-joint reference) |
-
-## How the Pieces Fit Together
-
-```
-Training (derive_state_from_action=true):
-  DataLoader loads action: [B, 31, 8]  (chunk_size=30 + 1 leading)
-      → DeriveStateFromActionStep
-          state  = action[:, :2, :]     → [B, 2, 8]
-          action = action[:, 1:, :]     → [B, 30, 8]
-      → RelativeActionsProcessorStep    (action -= state[:, -1, :])
-      → RelativeStateProcessorStep      (state offsets from current, flatten → [B, 16])
-      → NormalizerProcessorStep         → pi0 model
-
-Inference:
-  arm joints → FK → observation.state [8D: x,y,z,ax,ay,az,prox,dist]
-                        ↓
-                DeriveStateFromActionStep (no-op)
-                        ↓
-                RelativeActionsProcessorStep (caches state)
-                        ↓
-                RelativeStateProcessorStep (buffers prev, stacks, subtracts, flattens)
-                        ↓
-                NormalizerProcessorStep → pi0 model → relative action chunk [30, 8]
-                        ↓
-                UnnormalizerProcessorStep
-                        ↓
-                AbsoluteActionsProcessorStep (+ cached state → absolute EE)
-                        ↓
-                IK → joint targets → robot
-```
-
-## References
-
-- [UMI: Universal Manipulation Interface](https://umi-gripper.github.io) — Chi et al., 2024. Defines relative trajectory actions.
-- [Action Representations](action_representations) — LeRobot guide comparing absolute, relative, and delta actions.
-- [pi0 documentation](pi0) — Full pi0 configuration including `use_relative_actions`.
-- [`examples/so100_to_so100_EE/`](https://github.com/huggingface/lerobot/tree/main/examples/so100_to_so100_EE) — EE-space evaluation example this builds on.

examples/backward_compatibility/replay.py

@@ -78,7 +78,7 @@ def replay(cfg: ReplayConfig):
 
     robot = make_robot_from_config(cfg.robot)
     dataset = LeRobotDataset(cfg.dataset.repo_id, root=cfg.dataset.root, episodes=[cfg.dataset.episode])
-    actions = dataset.select_columns(ACTION)
+    actions = dataset.hf_dataset.select_columns(ACTION)
     robot.connect()
 
     try:

examples/dataset/load_lerobot_dataset.py

@@ -32,8 +32,7 @@ import torch
 from huggingface_hub import HfApi
 
 import lerobot
-from lerobot.datasets.dataset_metadata import LeRobotDatasetMetadata
-from lerobot.datasets.lerobot_dataset import LeRobotDataset
+from lerobot.datasets.lerobot_dataset import LeRobotDataset, LeRobotDatasetMetadata
 
 
 def main():
@@ -88,8 +87,9 @@ def main():
     # The previous metadata class is contained in the 'meta' attribute of the dataset:
     print(dataset.meta)
 
-    # You can inspect the dataset using its repr:
-    print(dataset)
+    # LeRobotDataset actually wraps an underlying Hugging Face dataset
+    # (see https://huggingface.co/docs/datasets for more information).
+    print(dataset.hf_dataset)
 
     # LeRobot datasets also subclasses PyTorch datasets so you can do everything you know and love from working
     # with the latter, like iterating through the dataset.

examples/lekiwi/evaluate.py

@@ -14,8 +14,8 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
-from lerobot.datasets.feature_utils import hw_to_dataset_features
 from lerobot.datasets.lerobot_dataset import LeRobotDataset
+from lerobot.datasets.utils import hw_to_dataset_features
 from lerobot.policies.act.modeling_act import ACTPolicy
 from lerobot.policies.factory import make_pre_post_processors
 from lerobot.processor import make_default_processors

examples/lekiwi/record.py

@@ -14,8 +14,8 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
-from lerobot.datasets.feature_utils import hw_to_dataset_features
 from lerobot.datasets.lerobot_dataset import LeRobotDataset
+from lerobot.datasets.utils import hw_to_dataset_features
 from lerobot.processor import make_default_processors
 from lerobot.robots.lekiwi.config_lekiwi import LeKiwiClientConfig
 from lerobot.robots.lekiwi.lekiwi_client import LeKiwiClient

examples/lekiwi/replay.py

@@ -35,7 +35,9 @@ def main():
 
     # Fetch the dataset to replay
     dataset = LeRobotDataset("<hf_username>/<dataset_repo_id>", episodes=[EPISODE_IDX])
-    actions = dataset.select_columns(ACTION)
+    # Filter dataset to only include frames from the specified episode since episodes are chunked in dataset V3.0
+    episode_frames = dataset.hf_dataset.filter(lambda x: x["episode_index"] == EPISODE_IDX)
+    actions = episode_frames.select_columns(ACTION)
 
     # Connect to the robot
     robot.connect()
@@ -46,7 +48,7 @@ def main():
 
         print("Starting replay loop...")
         log_say(f"Replaying episode {EPISODE_IDX}")
-        for idx in range(dataset.num_frames):
+        for idx in range(len(episode_frames)):
             t0 = time.perf_counter()
 
             # Get recorded action from dataset

examples/phone_to_so100/evaluate.py

@@ -16,13 +16,15 @@
 
 from lerobot.cameras.opencv.configuration_opencv import OpenCVCameraConfig
 from lerobot.configs.types import FeatureType, PolicyFeature
-from lerobot.datasets.feature_utils import combine_feature_dicts
 from lerobot.datasets.lerobot_dataset import LeRobotDataset
 from lerobot.datasets.pipeline_features import aggregate_pipeline_dataset_features, create_initial_features
+from lerobot.datasets.utils import combine_feature_dicts
 from lerobot.model.kinematics import RobotKinematics
 from lerobot.policies.act.modeling_act import ACTPolicy
 from lerobot.policies.factory import make_pre_post_processors
 from lerobot.processor import (
+    RobotAction,
+    RobotObservation,
     RobotProcessorPipeline,
     make_default_teleop_action_processor,
 )
@@ -38,7 +40,6 @@ from lerobot.robots.so_follower.robot_kinematic_processor import (
     InverseKinematicsEEToJoints,
 )
 from lerobot.scripts.lerobot_record import record_loop
-from lerobot.types import RobotAction, RobotObservation
 from lerobot.utils.control_utils import init_keyboard_listener
 from lerobot.utils.utils import log_say
 from lerobot.utils.visualization_utils import init_rerun

examples/phone_to_so100/record.py

@@ -15,11 +15,11 @@
 # limitations under the License.
 
 from lerobot.cameras.opencv.configuration_opencv import OpenCVCameraConfig
-from lerobot.datasets.feature_utils import combine_feature_dicts
 from lerobot.datasets.lerobot_dataset import LeRobotDataset
 from lerobot.datasets.pipeline_features import aggregate_pipeline_dataset_features, create_initial_features
+from lerobot.datasets.utils import combine_feature_dicts
 from lerobot.model.kinematics import RobotKinematics
-from lerobot.processor import RobotProcessorPipeline
+from lerobot.processor import RobotAction, RobotObservation, RobotProcessorPipeline
 from lerobot.processor.converters import (
     observation_to_transition,
     robot_action_observation_to_transition,
@@ -38,7 +38,6 @@ from lerobot.scripts.lerobot_record import record_loop
 from lerobot.teleoperators.phone.config_phone import PhoneConfig, PhoneOS
 from lerobot.teleoperators.phone.phone_processor import MapPhoneActionToRobotAction
 from lerobot.teleoperators.phone.teleop_phone import Phone
-from lerobot.types import RobotAction, RobotObservation
 from lerobot.utils.control_utils import init_keyboard_listener
 from lerobot.utils.utils import log_say
 from lerobot.utils.visualization_utils import init_rerun

examples/phone_to_so100/replay.py

@@ -18,7 +18,7 @@ import time
 
 from lerobot.datasets.lerobot_dataset import LeRobotDataset
 from lerobot.model.kinematics import RobotKinematics
-from lerobot.processor import RobotProcessorPipeline
+from lerobot.processor import RobotAction, RobotObservation, RobotProcessorPipeline
 from lerobot.processor.converters import (
     robot_action_observation_to_transition,
     transition_to_robot_action,
@@ -27,7 +27,6 @@ from lerobot.robots.so_follower import SO100Follower, SO100FollowerConfig
 from lerobot.robots.so_follower.robot_kinematic_processor import (
     InverseKinematicsEEToJoints,
 )
-from lerobot.types import RobotAction, RobotObservation
 from lerobot.utils.constants import ACTION
 from lerobot.utils.robot_utils import precise_sleep
 from lerobot.utils.utils import log_say
@@ -67,7 +66,9 @@ def main():
 
     # Fetch the dataset to replay
     dataset = LeRobotDataset(HF_REPO_ID, episodes=[EPISODE_IDX])
-    actions = dataset.select_columns(ACTION)
+    # Filter dataset to only include frames from the specified episode since episodes are chunked in dataset V3.0
+    episode_frames = dataset.hf_dataset.filter(lambda x: x["episode_index"] == EPISODE_IDX)
+    actions = episode_frames.select_columns(ACTION)
 
     # Connect to the robot
     robot.connect()
@@ -78,7 +79,7 @@ def main():
 
         print("Starting replay loop...")
         log_say(f"Replaying episode {EPISODE_IDX}")
-        for idx in range(dataset.num_frames):
+        for idx in range(len(episode_frames)):
             t0 = time.perf_counter()
 
             # Get recorded action from dataset

examples/phone_to_so100/teleoperate.py

@@ -16,7 +16,7 @@
 import time
 
 from lerobot.model.kinematics import RobotKinematics
-from lerobot.processor import RobotProcessorPipeline
+from lerobot.processor import RobotAction, RobotObservation, RobotProcessorPipeline
 from lerobot.processor.converters import (
     robot_action_observation_to_transition,
     transition_to_robot_action,
@@ -31,7 +31,6 @@ from lerobot.robots.so_follower.robot_kinematic_processor import (
 from lerobot.teleoperators.phone.config_phone import PhoneConfig, PhoneOS
 from lerobot.teleoperators.phone.phone_processor import MapPhoneActionToRobotAction
 from lerobot.teleoperators.phone.teleop_phone import Phone
-from lerobot.types import RobotAction, RobotObservation
 from lerobot.utils.robot_utils import precise_sleep
 from lerobot.utils.visualization_utils import init_rerun, log_rerun_data
 

examples/port_datasets/port_droid.py

@@ -22,8 +22,7 @@ from pathlib import Path
 import numpy as np
 import tensorflow_datasets as tfds
 
-from lerobot.datasets.dataset_metadata import LeRobotDatasetMetadata
-from lerobot.datasets.lerobot_dataset import LeRobotDataset
+from lerobot.datasets.lerobot_dataset import LeRobotDataset, LeRobotDatasetMetadata
 from lerobot.utils.utils import get_elapsed_time_in_days_hours_minutes_seconds
 
 DROID_SHARDS = 2048

examples/port_datasets/slurm_upload.py

@@ -26,7 +26,7 @@ from huggingface_hub import HfApi
 from huggingface_hub.constants import REPOCARD_NAME
 from port_droid import DROID_SHARDS
 
-from lerobot.datasets.dataset_metadata import CODEBASE_VERSION, LeRobotDatasetMetadata
+from lerobot.datasets.lerobot_dataset import CODEBASE_VERSION, LeRobotDatasetMetadata
 from lerobot.datasets.utils import create_lerobot_dataset_card
 from lerobot.utils.utils import init_logging
 
@@ -155,7 +155,7 @@ class UploadDataset(PipelineStep):
         from datasets.utils.tqdm import disable_progress_bars
         from huggingface_hub import CommitOperationAdd, preupload_lfs_files
 
-        from lerobot.datasets.dataset_metadata import LeRobotDatasetMetadata
+        from lerobot.datasets.lerobot_dataset import LeRobotDatasetMetadata
         from lerobot.utils.utils import init_logging
 
         init_logging()

examples/rtc/eval_dataset.py

@@ -113,9 +113,8 @@ from lerobot.configs import parser
 from lerobot.configs.default import DatasetConfig
 from lerobot.configs.policies import PreTrainedConfig
 from lerobot.configs.types import RTCAttentionSchedule
-from lerobot.datasets.dataset_metadata import LeRobotDatasetMetadata
 from lerobot.datasets.factory import resolve_delta_timestamps
-from lerobot.datasets.lerobot_dataset import LeRobotDataset
+from lerobot.datasets.lerobot_dataset import LeRobotDataset, LeRobotDatasetMetadata
 from lerobot.policies.factory import get_policy_class, make_pre_post_processors
 from lerobot.policies.rtc.configuration_rtc import RTCConfig
 from lerobot.policies.rtc.debug_visualizer import RTCDebugVisualizer

examples/rtc/eval_with_real_robot.py

@@ -63,26 +63,6 @@ Usage:
         --robot.cameras="{ gripper: {type: opencv, index_or_path: 0, width: 640, height: 480, fps: 30}, front: {type: opencv, index_or_path: 1, width: 640, height: 480, fps: 30}}" \
         --task="Move green small object into the purple platform" \
         --duration=120
-
-    # Run RTC with bi_openarm_follower (dual-arm OpenArms) and pi0.5 policy
-    python examples/rtc/eval_with_real_robot.py \
-        --policy.path=lerobot-data-collection/folding_final \
-        --robot.type=bi_openarm_follower \
-        --robot.cameras='{left_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}, right_wrist: {type: opencv, index_or_path: "/dev/video0", width: 1280, height: 720, fps: 30}}' \
-        --robot.left_arm_config.port=can1 \
-        --robot.left_arm_config.side=left \
-        --robot.left_arm_config.can_interface=socketcan \
-        --robot.right_arm_config.port=can0 \
-        --robot.right_arm_config.side=right \
-        --robot.right_arm_config.can_interface=socketcan \
-        --task="Fold the T-shirt properly" \
-        --fps=30 \
-        --duration=2000 \
-        --rtc.enabled=true \
-        --rtc.execution_horizon=20 \
-        --rtc.max_guidance_weight=5.0 \
-        --rtc.prefix_attention_schedule=LINEAR \
-        --device=cuda
 """
 
 import logging
@@ -102,34 +82,26 @@ from lerobot.cameras.zmq.configuration_zmq import ZMQCameraConfig  # noqa: F401
 from lerobot.configs import parser
 from lerobot.configs.policies import PreTrainedConfig
 from lerobot.configs.types import RTCAttentionSchedule
-from lerobot.datasets.feature_utils import build_dataset_frame, hw_to_dataset_features
+from lerobot.datasets.utils import build_dataset_frame, hw_to_dataset_features
 from lerobot.policies.factory import get_policy_class, make_pre_post_processors
 from lerobot.policies.rtc.action_queue import ActionQueue
 from lerobot.policies.rtc.configuration_rtc import RTCConfig
 from lerobot.policies.rtc.latency_tracker import LatencyTracker
-from lerobot.processor import (
-    NormalizerProcessorStep,
-    RelativeActionsProcessorStep,
-    TransitionKey,
-    create_transition,
-)
 from lerobot.processor.factory import (
     make_default_robot_action_processor,
     make_default_robot_observation_processor,
 )
-from lerobot.processor.relative_action_processor import to_relative_actions
 from lerobot.rl.process import ProcessSignalHandler
 from lerobot.robots import (  # noqa: F401
     Robot,
     RobotConfig,
-    bi_openarm_follower,
     bi_so_follower,
     koch_follower,
     so_follower,
     unitree_g1,
 )
 from lerobot.robots.utils import make_robot_from_config
-from lerobot.utils.constants import OBS_IMAGES, OBS_STATE
+from lerobot.utils.constants import OBS_IMAGES
 from lerobot.utils.hub import HubMixin
 from lerobot.utils.utils import init_logging
 
@@ -240,35 +212,6 @@ def is_image_key(k: str) -> bool:
     return k.startswith(OBS_IMAGES)
 
 
-def _reanchor_relative_rtc_prefix(
-    prev_actions_absolute: Tensor,
-    current_state: Tensor,
-    relative_step: RelativeActionsProcessorStep,
-    normalizer_step: NormalizerProcessorStep | None,
-    policy_device: torch.device | str,
-) -> Tensor:
-    """Convert absolute leftovers into model-space for relative-action RTC policies.
-
-    When a policy uses relative actions, the RTC prefix (leftover actions from
-    the previous chunk) is stored in absolute space. Before feeding it back to
-    the policy we need to re-express it relative to the *current* robot state
-    and then re-normalize.
-    """
-    state = current_state.detach().cpu()
-    if state.dim() == 1:
-        state = state.unsqueeze(0)
-
-    action_cpu = prev_actions_absolute.detach().cpu()
-    mask = relative_step._build_mask(action_cpu.shape[-1])
-    relative_actions = to_relative_actions(action_cpu, state, mask)
-
-    transition = create_transition(action=relative_actions)
-    if normalizer_step is not None:
-        transition = normalizer_step(transition)
-
-    return transition[TransitionKey.ACTION].to(policy_device)
-
-
 def get_actions(
     policy,
     robot: RobotWrapper,
@@ -294,15 +237,7 @@ def get_actions(
         fps = cfg.fps
         time_per_chunk = 1.0 / fps
 
-        # Only keep .pos joints + camera streams if the policy was trained on positions,
-        # not the full pos/vel/torque state the robot exposes.
-        observation_features_hw = {
-            key: value
-            for key, value in robot.observation_features().items()
-            if key.endswith(".pos") or isinstance(value, tuple)
-        }
-
-        dataset_features = hw_to_dataset_features(observation_features_hw, "observation")
+        dataset_features = hw_to_dataset_features(robot.observation_features(), "observation")
         policy_device = policy.config.device
 
         # Load preprocessor and postprocessor from pretrained files
@@ -320,25 +255,6 @@ def get_actions(
 
         logger.info("[GET_ACTIONS] Preprocessor/postprocessor loaded successfully with embedded stats")
 
-        relative_step = next(
-            (s for s in preprocessor.steps if isinstance(s, RelativeActionsProcessorStep) and s.enabled),
-            None,
-        )
-        normalizer_step = next(
-            (s for s in preprocessor.steps if isinstance(s, NormalizerProcessorStep)),
-            None,
-        )
-        if relative_step is not None:
-            if relative_step.action_names is None:
-                cfg_names = getattr(cfg.policy, "action_feature_names", None)
-                if cfg_names:
-                    relative_step.action_names = list(cfg_names)
-                else:
-                    relative_step.action_names = [
-                        k for k in robot.robot.action_features if k.endswith(".pos")
-                    ]
-            logger.info("[GET_ACTIONS] Relative actions enabled: will re-anchor RTC prefix")
-
         get_actions_threshold = cfg.action_queue_size_to_get_new_actions
 
         if not cfg.rtc.enabled:
@@ -381,28 +297,6 @@ def get_actions(
 
                 preproceseded_obs = preprocessor(obs_with_policy_features)
 
-                # Re-anchor leftover actions for relative-action policies.
-                # We need the *postprocessed* (absolute) leftover, not the original
-                # (normalized/relative) one that get_left_over() returns.
-                if (
-                    prev_actions is not None
-                    and relative_step is not None
-                    and OBS_STATE in obs_with_policy_features
-                ):
-                    with action_queue.lock:
-                        if action_queue.queue is not None:
-                            prev_actions_abs = action_queue.queue[action_queue.last_index :].clone()
-                        else:
-                            prev_actions_abs = None
-                    if prev_actions_abs is not None and prev_actions_abs.numel() > 0:
-                        prev_actions = _reanchor_relative_rtc_prefix(
-                            prev_actions_absolute=prev_actions_abs,
-                            current_state=obs_with_policy_features[OBS_STATE],
-                            relative_step=relative_step,
-                            normalizer_step=normalizer_step,
-                            policy_device=policy_device,
-                        )
-
                 # Generate actions WITH RTC
                 actions = policy.predict_action_chunk(
                     preproceseded_obs,
@@ -458,8 +352,6 @@ def actor_control(
     try:
         logger.info("[ACTOR] Starting actor thread")
 
-        action_keys = [k for k in robot.action_features() if k.endswith(".pos")]
-
         action_count = 0
         action_interval = 1.0 / cfg.fps
 
@@ -471,7 +363,7 @@ def actor_control(
 
             if action is not None:
                 action = action.cpu()
-                action_dict = {key: action[i].item() for i, key in enumerate(action_keys)}
+                action_dict = {key: action[i].item() for i, key in enumerate(robot.action_features())}
                 action_processed = robot_action_processor((action_dict, None))
                 robot.send_action(action_processed)
 

examples/so100_to_so100_EE/evaluate.py

@@ -16,13 +16,15 @@
 
 from lerobot.cameras.opencv.configuration_opencv import OpenCVCameraConfig
 from lerobot.configs.types import FeatureType, PolicyFeature
-from lerobot.datasets.feature_utils import combine_feature_dicts
 from lerobot.datasets.lerobot_dataset import LeRobotDataset
 from lerobot.datasets.pipeline_features import aggregate_pipeline_dataset_features, create_initial_features
+from lerobot.datasets.utils import combine_feature_dicts
 from lerobot.model.kinematics import RobotKinematics
 from lerobot.policies.act.modeling_act import ACTPolicy
 from lerobot.policies.factory import make_pre_post_processors
 from lerobot.processor import (
+    RobotAction,
+    RobotObservation,
     RobotProcessorPipeline,
     make_default_teleop_action_processor,
 )
@@ -38,7 +40,6 @@ from lerobot.robots.so_follower.robot_kinematic_processor import (
     InverseKinematicsEEToJoints,
 )
 from lerobot.scripts.lerobot_record import record_loop
-from lerobot.types import RobotAction, RobotObservation
 from lerobot.utils.control_utils import init_keyboard_listener
 from lerobot.utils.utils import log_say
 from lerobot.utils.visualization_utils import init_rerun

examples/so100_to_so100_EE/record.py

@@ -16,11 +16,11 @@
 
 
 from lerobot.cameras.opencv.configuration_opencv import OpenCVCameraConfig
-from lerobot.datasets.feature_utils import combine_feature_dicts
 from lerobot.datasets.lerobot_dataset import LeRobotDataset
 from lerobot.datasets.pipeline_features import aggregate_pipeline_dataset_features, create_initial_features
+from lerobot.datasets.utils import combine_feature_dicts
 from lerobot.model.kinematics import RobotKinematics
-from lerobot.processor import RobotProcessorPipeline
+from lerobot.processor import RobotAction, RobotObservation, RobotProcessorPipeline
 from lerobot.processor.converters import (
     observation_to_transition,
     robot_action_observation_to_transition,
@@ -35,7 +35,6 @@ from lerobot.robots.so_follower.robot_kinematic_processor import (
 )
 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.control_utils import init_keyboard_listener
 from lerobot.utils.utils import log_say
 from lerobot.utils.visualization_utils import init_rerun

examples/so100_to_so100_EE/replay.py

@@ -19,7 +19,7 @@ import time
 
 from lerobot.datasets.lerobot_dataset import LeRobotDataset
 from lerobot.model.kinematics import RobotKinematics
-from lerobot.processor import RobotProcessorPipeline
+from lerobot.processor import RobotAction, RobotObservation, RobotProcessorPipeline
 from lerobot.processor.converters import (
     robot_action_observation_to_transition,
     transition_to_robot_action,
@@ -28,7 +28,6 @@ from lerobot.robots.so_follower import SO100Follower, SO100FollowerConfig
 from lerobot.robots.so_follower.robot_kinematic_processor import (
     InverseKinematicsEEToJoints,
 )
-from lerobot.types import RobotAction, RobotObservation
 from lerobot.utils.constants import ACTION
 from lerobot.utils.robot_utils import precise_sleep
 from lerobot.utils.utils import log_say
@@ -68,7 +67,9 @@ def main():
 
     # Fetch the dataset to replay
     dataset = LeRobotDataset(HF_REPO_ID, episodes=[EPISODE_IDX])
-    actions = dataset.select_columns(ACTION)
+    # Filter dataset to only include frames from the specified episode since episodes are chunked in dataset V3.0
+    episode_frames = dataset.hf_dataset.filter(lambda x: x["episode_index"] == EPISODE_IDX)
+    actions = episode_frames.select_columns(ACTION)
 
     # Connect to the robot
     robot.connect()
@@ -79,7 +80,7 @@ def main():
 
         print("Starting replay loop...")
         log_say(f"Replaying episode {EPISODE_IDX}")
-        for idx in range(dataset.num_frames):
+        for idx in range(len(episode_frames)):
             t0 = time.perf_counter()
 
             # Get recorded action from dataset

examples/so100_to_so100_EE/teleoperate.py

@@ -17,7 +17,7 @@
 import time
 
 from lerobot.model.kinematics import RobotKinematics
-from lerobot.processor import RobotProcessorPipeline
+from lerobot.processor import RobotAction, RobotObservation, RobotProcessorPipeline
 from lerobot.processor.converters import (
     robot_action_observation_to_transition,
     robot_action_to_transition,
@@ -30,7 +30,6 @@ from lerobot.robots.so_follower.robot_kinematic_processor import (
     InverseKinematicsEEToJoints,
 )
 from lerobot.teleoperators.so_leader import SO100Leader, SO100LeaderConfig
-from lerobot.types import RobotAction, RobotObservation
 from lerobot.utils.robot_utils import precise_sleep
 from lerobot.utils.visualization_utils import init_rerun, log_rerun_data
 

examples/training/train_policy.py

@@ -19,9 +19,8 @@ from pathlib import Path
 import torch
 
 from lerobot.configs.types import FeatureType
-from lerobot.datasets.dataset_metadata import LeRobotDatasetMetadata
-from lerobot.datasets.feature_utils import dataset_to_policy_features
-from lerobot.datasets.lerobot_dataset import LeRobotDataset
+from lerobot.datasets.lerobot_dataset import LeRobotDataset, LeRobotDatasetMetadata
+from lerobot.datasets.utils import dataset_to_policy_features
 from lerobot.policies.diffusion.configuration_diffusion import DiffusionConfig
 from lerobot.policies.diffusion.modeling_diffusion import DiffusionPolicy
 from lerobot.policies.factory import make_pre_post_processors

examples/training/train_with_streaming.py

@@ -20,9 +20,9 @@ from pathlib import Path
 import torch
 
 from lerobot.configs.types import FeatureType
-from lerobot.datasets.dataset_metadata import LeRobotDatasetMetadata
-from lerobot.datasets.feature_utils import dataset_to_policy_features
+from lerobot.datasets.lerobot_dataset import LeRobotDatasetMetadata
 from lerobot.datasets.streaming_dataset import StreamingLeRobotDataset
+from lerobot.datasets.utils import dataset_to_policy_features
 from lerobot.policies.act.configuration_act import ACTConfig
 from lerobot.policies.act.modeling_act import ACTPolicy
 from lerobot.policies.factory import make_pre_post_processors

examples/tutorial/act/act_training_example.py

@@ -5,9 +5,8 @@ from pathlib import Path
 import torch
 
 from lerobot.configs.types import FeatureType
-from lerobot.datasets.dataset_metadata import LeRobotDatasetMetadata
-from lerobot.datasets.feature_utils import dataset_to_policy_features
-from lerobot.datasets.lerobot_dataset import LeRobotDataset
+from lerobot.datasets.lerobot_dataset import LeRobotDataset, LeRobotDatasetMetadata
+from lerobot.datasets.utils import dataset_to_policy_features
 from lerobot.policies.act.configuration_act import ACTConfig
 from lerobot.policies.act.modeling_act import ACTPolicy
 from lerobot.policies.factory import make_pre_post_processors

examples/tutorial/act/act_using_example.py

@@ -1,7 +1,7 @@
 import torch
 
 from lerobot.cameras.opencv.configuration_opencv import OpenCVCameraConfig
-from lerobot.datasets.dataset_metadata import LeRobotDatasetMetadata
+from lerobot.datasets.lerobot_dataset import LeRobotDatasetMetadata
 from lerobot.policies.act.modeling_act import ACTPolicy
 from lerobot.policies.factory import make_pre_post_processors
 from lerobot.policies.utils import build_inference_frame, make_robot_action

examples/tutorial/diffusion/diffusion_training_example.py

@@ -5,9 +5,8 @@ from pathlib import Path
 import torch
 
 from lerobot.configs.types import FeatureType
-from lerobot.datasets.dataset_metadata import LeRobotDatasetMetadata
-from lerobot.datasets.feature_utils import dataset_to_policy_features
-from lerobot.datasets.lerobot_dataset import LeRobotDataset
+from lerobot.datasets.lerobot_dataset import LeRobotDataset, LeRobotDatasetMetadata
+from lerobot.datasets.utils import dataset_to_policy_features
 from lerobot.policies.diffusion.configuration_diffusion import DiffusionConfig
 from lerobot.policies.diffusion.modeling_diffusion import DiffusionPolicy
 from lerobot.policies.factory import make_pre_post_processors

examples/tutorial/diffusion/diffusion_using_example.py

@@ -1,7 +1,7 @@
 import torch
 
 from lerobot.cameras.opencv.configuration_opencv import OpenCVCameraConfig
-from lerobot.datasets.dataset_metadata import LeRobotDatasetMetadata
+from lerobot.datasets.lerobot_dataset import LeRobotDatasetMetadata
 from lerobot.policies.diffusion.modeling_diffusion import DiffusionPolicy
 from lerobot.policies.factory import make_pre_post_processors
 from lerobot.policies.utils import build_inference_frame, make_robot_action

examples/tutorial/pi0/using_pi0_example.py

@@ -1,7 +1,7 @@
 import torch
 
 from lerobot.cameras.opencv.configuration_opencv import OpenCVCameraConfig
-from lerobot.datasets.feature_utils import hw_to_dataset_features
+from lerobot.datasets.utils import hw_to_dataset_features
 from lerobot.policies.factory import make_pre_post_processors
 from lerobot.policies.pi0.modeling_pi0 import PI0Policy
 from lerobot.policies.utils import build_inference_frame, make_robot_action

examples/tutorial/rl/hilserl_example.py

@@ -6,8 +6,8 @@ from queue import Empty, Full
 import torch
 import torch.optim as optim
 
-from lerobot.datasets.feature_utils import hw_to_dataset_features
 from lerobot.datasets.lerobot_dataset import LeRobotDataset
+from lerobot.datasets.utils import hw_to_dataset_features
 from lerobot.envs.configs import HILSerlProcessorConfig, HILSerlRobotEnvConfig
 from lerobot.policies.sac.configuration_sac import SACConfig
 from lerobot.policies.sac.modeling_sac import SACPolicy

examples/tutorial/smolvla/using_smolvla_example.py

@@ -1,7 +1,7 @@
 import torch
 
 from lerobot.cameras.opencv.configuration_opencv import OpenCVCameraConfig
-from lerobot.datasets.feature_utils import hw_to_dataset_features
+from lerobot.datasets.utils import hw_to_dataset_features
 from lerobot.policies.factory import make_pre_post_processors
 from lerobot.policies.smolvla.modeling_smolvla import SmolVLAPolicy
 from lerobot.policies.utils import build_inference_frame, make_robot_action

examples/umi_pi0_relative_ee/evaluate.py

@@ -1,297 +0,0 @@
-#!/usr/bin/env python
-
-# Copyright 2025 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.
-
-"""
-Inference script for a pi0 model trained with UMI-style relative EE actions
-on an OpenArm robot (single right arm, one wrist camera).
-
-Training dataset layout:
-  observation.images.cam0  [3, 720, 960]
-  action                   [x, y, z, ax, ay, az, proximal, distal]  (shape 8)
-
-The model uses ``derive_state_from_action=true``, so observation.state is
-derived from the action column during training.  At inference the state must
-be provided by the robot — this script uses FK to compute the current EE
-pose and gripper position, which it exposes as ``observation.state``.
-
-Pipeline:
-  1. Read arm joints from robot → FK → observation.state [x,y,z,ax,ay,az,prox,dist]
-  2. Read camera image → observation.images.cam0
-  3. pi0 preprocessor (loaded from checkpoint):
-     - DeriveStateFromActionStep: no-op at inference (state from robot)
-     - RelativeActionsProcessorStep: caches current state
-     - RelativeStateProcessorStep: buffers prev state, stacks [prev,cur],
-       subtracts current → velocity info, flattens
-     - NormalizerProcessorStep: normalizes
-  4. pi0 predicts relative action chunk (30 steps)
-  5. pi0 postprocessor: unnormalize, add cached state → absolute EE
-  6. IK: absolute EE [x,y,z,ax,ay,az] → arm joint targets
-  7. Gripper [proximal, distal] → gripper motor targets
-  8. Send to robot
-
-Usage:
-    python evaluate.py
-"""
-
-from __future__ import annotations
-
-import numpy as np
-from scipy.spatial.transform import Rotation
-
-from lerobot.cameras.opencv.configuration_opencv import OpenCVCameraConfig
-from lerobot.datasets.lerobot_dataset import LeRobotDataset
-from lerobot.model.kinematics import RobotKinematics
-from lerobot.policies.factory import make_pre_post_processors
-from lerobot.policies.pi0.modeling_pi0 import PI0Policy
-from lerobot.processor import RelativeStateProcessorStep
-from lerobot.robots.openarm_follower import OpenArmFollower, OpenArmFollowerConfig
-from lerobot.scripts.lerobot_record import record_loop
-from lerobot.types import RobotAction, RobotObservation
-from lerobot.utils.control_utils import init_keyboard_listener
-from lerobot.utils.utils import log_say
-from lerobot.utils.visualization_utils import init_rerun
-
-# ---------------------------------------------------------------------------
-# Configuration — adapt these to your setup
-# ---------------------------------------------------------------------------
-
-FPS = 46
-EPISODE_TIME_SEC = 60
-TASK_DESCRIPTION = "red cube"
-
-HF_MODEL_ID = "pepijn223/grabette-umi-pi0"
-
-# Latency compensation: skip this many predicted action steps to account for
-# camera + inference + execution latency.  Formula: ceil(total_ms / (1000/FPS)).
-# At 46 FPS (~22ms/step) with ~150ms total latency: ceil(150/22) ≈ 7.
-# Start with 0 for a safe first test, then increase to match measured latency.
-LATENCY_SKIP_STEPS = 0
-
-URDF_PATH = "src/lerobot/robots/openarm_follower/urdf/openarm_bimanual_pybullet.urdf"
-URDF_EE_FRAME = "openarm_right_ee_target"
-
-IK_POSITION_WEIGHT = 1.0
-IK_ORIENTATION_WEIGHT = 1.0
-
-# ---------------------------------------------------------------------------
-# Dataset features for inference
-#
-# The training dataset has only observation.images.cam0 and action.
-# observation.state is derived from action during training
-# (derive_state_from_action=true) but must be supplied by the robot at
-# inference.  We define it here so build_dataset_frame can map FK output
-# to the right feature.
-# ---------------------------------------------------------------------------
-
-DATASET_FEATURES: dict = {
-    "observation.state": {
-        "dtype": "float32",
-        "shape": [8],
-        "names": ["x", "y", "z", "ax", "ay", "az", "proximal", "distal"],
-    },
-    "observation.images.cam0": {
-        "dtype": "video",
-        "shape": [3, 720, 960],
-        "names": ["channels", "height", "width"],
-        "info": {
-            "video.height": 720,
-            "video.width": 960,
-            "video.codec": "h264",
-            "video.pix_fmt": "yuv420p",
-            "video.is_depth_map": False,
-            "video.fps": FPS,
-            "video.channels": 3,
-            "has_audio": False,
-        },
-    },
-    "action": {
-        "dtype": "float32",
-        "shape": [8],
-        "names": ["x", "y", "z", "ax", "ay", "az", "proximal", "distal"],
-    },
-    "timestamp": {"dtype": "float32", "shape": [1], "names": None},
-    "frame_index": {"dtype": "int64", "shape": [1], "names": None},
-    "episode_index": {"dtype": "int64", "shape": [1], "names": None},
-    "index": {"dtype": "int64", "shape": [1], "names": None},
-    "task_index": {"dtype": "int64", "shape": [1], "names": None},
-}
-
-
-# ---------------------------------------------------------------------------
-# FK / IK callables
-# ---------------------------------------------------------------------------
-
-
-class JointsToEE:
-    """FK: raw robot observation → flat dict matching observation.state names.
-
-    Arm joint positions → EE pose [x,y,z,ax,ay,az] via forward kinematics.
-    Gripper motor positions → [proximal, distal].
-    Camera images pass through unchanged.
-    """
-
-    def __init__(self, kinematics: RobotKinematics, arm_motor_names: list[str]):
-        self.kin = kinematics
-        self.arm = arm_motor_names
-
-    def __call__(self, obs: RobotObservation) -> RobotObservation:
-        q = np.array([float(obs[f"{m}.pos"]) for m in self.arm])
-        t = self.kin.forward_kinematics(q)
-        rot = Rotation.from_matrix(t[:3, :3]).as_rotvec()
-
-        out: dict = {
-            "x": float(t[0, 3]),
-            "y": float(t[1, 3]),
-            "z": float(t[2, 3]),
-            "ax": float(rot[0]),
-            "ay": float(rot[1]),
-            "az": float(rot[2]),
-            "proximal": float(obs["proximal.pos"]),
-            "distal": float(obs["distal.pos"]),
-        }
-        for k, v in obs.items():
-            if not k.endswith((".pos", ".vel", ".torque")):
-                out[k] = v
-        return out
-
-
-class EEToJoints:
-    """IK: policy action dict → motor position dict for the robot.
-
-    Reads [x,y,z,ax,ay,az] from the action, runs IK for arm joint targets.
-    Passes [proximal, distal] as direct gripper position commands.
-    """
-
-    def __init__(
-        self,
-        kinematics: RobotKinematics,
-        arm_motor_names: list[str],
-        position_weight: float = 1.0,
-        orientation_weight: float = 1.0,
-    ):
-        self.kin = kinematics
-        self.arm = arm_motor_names
-        self.pw = position_weight
-        self.ow = orientation_weight
-        self.q_curr: np.ndarray | None = None
-
-    def __call__(self, args: tuple[RobotAction, RobotObservation]) -> RobotAction:
-        action, obs = args
-
-        q_raw = np.array([float(obs[f"{m}.pos"]) for m in self.arm])
-        if self.q_curr is None:
-            self.q_curr = q_raw
-
-        t_des = np.eye(4)
-        t_des[:3, :3] = Rotation.from_rotvec([action["ax"], action["ay"], action["az"]]).as_matrix()
-        t_des[:3, 3] = [action["x"], action["y"], action["z"]]
-
-        q_target = self.kin.inverse_kinematics(
-            self.q_curr, t_des, position_weight=self.pw, orientation_weight=self.ow
-        )
-        self.q_curr = q_target
-
-        out: dict = {f"{m}.pos": float(q_target[i]) for i, m in enumerate(self.arm)}
-        out["proximal.pos"] = float(action["proximal"])
-        out["distal.pos"] = float(action["distal"])
-        return out
-
-
-# ---------------------------------------------------------------------------
-# Main
-# ---------------------------------------------------------------------------
-
-
-def main():
-    camera_config = {
-        "cam0": OpenCVCameraConfig(index_or_path=0, width=960, height=720, fps=FPS),
-    }
-    robot_config = OpenArmFollowerConfig(
-        port="can0",
-        id="right_openarm",
-        side="right",
-        cameras=camera_config,
-        max_relative_target=8.0,
-        gripper_port="/dev/ttyUSB0",
-    )
-    robot = OpenArmFollower(robot_config)
-
-    policy = PI0Policy.from_pretrained(HF_MODEL_ID)
-    policy.config.latency_skip_steps = LATENCY_SKIP_STEPS
-
-    arm_motor_names = list(robot.bus.motors.keys())
-
-    kinematics = RobotKinematics(
-        urdf_path=URDF_PATH,
-        target_frame_name=URDF_EE_FRAME,
-        joint_names=arm_motor_names,
-    )
-
-    fk = JointsToEE(kinematics, arm_motor_names)
-    ik = EEToJoints(kinematics, arm_motor_names, IK_POSITION_WEIGHT, IK_ORIENTATION_WEIGHT)
-
-    dataset = LeRobotDataset.create(
-        repo_id="tmp/openarm_eval_scratch",
-        fps=FPS,
-        features=DATASET_FEATURES,
-        robot_type=robot.name,
-        use_videos=True,
-        image_writer_threads=4,
-    )
-
-    preprocessor, postprocessor = make_pre_post_processors(
-        policy_cfg=policy,
-        pretrained_path=HF_MODEL_ID,
-        dataset_stats=dataset.meta.stats,
-        preprocessor_overrides={"device_processor": {"device": str(policy.config.device)}},
-    )
-
-    relative_state_steps = [s for s in preprocessor.steps if isinstance(s, RelativeStateProcessorStep)]
-
-    robot.connect()
-
-    listener, events = init_keyboard_listener()
-    init_rerun(session_name="openarm_umi_pi0_relative_ee_evaluate")
-
-    try:
-        if not robot.is_connected:
-            raise ValueError("Robot is not connected!")
-
-        log_say("Starting policy execution")
-        for step in relative_state_steps:
-            step.reset()
-
-        record_loop(
-            robot=robot,
-            events=events,
-            fps=FPS,
-            policy=policy,
-            preprocessor=preprocessor,
-            postprocessor=postprocessor,
-            dataset=dataset,
-            control_time_s=EPISODE_TIME_SEC,
-            single_task=TASK_DESCRIPTION,
-            display_data=True,
-            robot_action_processor=ik,
-            robot_observation_processor=fk,
-        )
-    finally:
-        robot.disconnect()
-        listener.stop()
-
-
-if __name__ == "__main__":
-    main()

examples/umi_pi0_relative_ee/replay.py

@@ -1,113 +0,0 @@
-#!/usr/bin/env python
-
-# Copyright 2025 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.
-
-"""
-Replay a dataset episode in EE frame using a browser-based URDF viewer.
-
-Extracts ``observation.pose`` from the dataset, saves a trajectory JSON file,
-then launches a local HTTP server and opens the replay viewer.  The trajectory
-is re-centered so frame 0 starts at the OpenArm ``openarm_right_ee_target``
-EE tip (zero-joint pose).
-
-Usage:
-    python replay.py
-    python replay.py --episode 3 --repo-id myuser/mydata
-"""
-
-from __future__ import annotations
-
-import argparse
-import http.server
-import json
-import os
-import threading
-import webbrowser
-from pathlib import Path
-
-VIEWER_DIR = Path(__file__).resolve().parents[2] / "src/lerobot/robots/openarm_follower/urdf"
-TRAJECTORY_FILENAME = "trajectory_ep0.json"
-
-
-def extract_trajectory(repo_id: str, episode: int, output_path: Path) -> dict:
-    from lerobot.datasets.lerobot_dataset import LeRobotDataset
-
-    dataset = LeRobotDataset(repo_id, episodes=[episode])
-    poses = dataset.select_columns("observation.pose")
-    actions = dataset.select_columns("action")
-
-    frames = []
-    for i in range(dataset.num_frames):
-        p = poses[i]["observation.pose"]
-        a = actions[i]["action"]
-        frames.append(
-            {
-                "x": float(p[0]),
-                "y": float(p[1]),
-                "z": float(p[2]),
-                "ax": float(p[3]),
-                "ay": float(p[4]),
-                "az": float(p[5]),
-                "proximal": float(a[0]),
-                "distal": float(a[1]),
-            }
-        )
-    payload = {"fps": dataset.fps, "num_frames": dataset.num_frames, "frames": frames}
-    with open(output_path, "w") as f:
-        json.dump(payload, f)
-    print(f"Extracted {dataset.num_frames} frames at {dataset.fps} FPS → {output_path}")
-    return payload
-
-
-# ---------------------------------------------------------------------------
-# Viewer mode
-# ---------------------------------------------------------------------------
-
-
-def serve_and_open(directory: Path, port: int = 8765):
-    os.chdir(directory)
-    handler = http.server.SimpleHTTPRequestHandler
-    httpd = http.server.HTTPServer(("", port), handler)
-    url = f"http://localhost:{port}/replay_viewer.html"
-    print(f"Serving at {url}")
-    threading.Thread(target=lambda: webbrowser.open(url), daemon=True).start()
-    try:
-        httpd.serve_forever()
-    except KeyboardInterrupt:
-        print("\nServer stopped.")
-        httpd.server_close()
-
-
-def run_viewer(args):
-    trajectory_path = VIEWER_DIR / TRAJECTORY_FILENAME
-    if not trajectory_path.exists() or args.force:
-        extract_trajectory(args.repo_id, args.episode, trajectory_path)
-    else:
-        print(f"Using cached trajectory at {trajectory_path}  (pass --force to re-extract)")
-    serve_and_open(VIEWER_DIR, args.port)
-
-
-def main():
-    parser = argparse.ArgumentParser(description="Replay a dataset episode in EE frame (URDF viewer)")
-    parser.add_argument("--repo-id", default="glannuzel/grabette-dataset")
-    parser.add_argument("--episode", type=int, default=0)
-    parser.add_argument("--port", type=int, default=8765)
-    parser.add_argument("--force", action="store_true", help="Re-extract trajectory even if cached")
-    args = parser.parse_args()
-    run_viewer(args)
-
-
-if __name__ == "__main__":
-    main()

pyproject.toml

@@ -99,7 +99,7 @@ dependencies = [
 # Common
 pygame-dep = ["pygame>=2.5.1,<2.7.0"]
 placo-dep = ["placo>=0.9.6,<0.9.17"]
-transformers-dep = ["transformers==5.3.0"] # TODO(Steven): https://github.com/huggingface/lerobot/pull/3249
+transformers-dep = ["transformers>=5.3.0,<6.0.0"]
 grpcio-dep = ["grpcio==1.73.1", "protobuf>=6.31.1,<6.32.0"]
 can-dep = ["python-can>=4.2.0,<5.0.0"]
 peft-dep = ["peft>=0.18.0,<1.0.0"]
@@ -145,7 +145,6 @@ wallx = [
 ]
 pi = ["lerobot[transformers-dep]", "lerobot[scipy-dep]"]
 smolvla = ["lerobot[transformers-dep]", "num2words>=0.5.14,<0.6.0", "accelerate>=1.7.0,<2.0.0", "safetensors>=0.4.3,<1.0.0"]
-multi_task_dit = ["lerobot[transformers-dep]"]
 groot = [
     "lerobot[transformers-dep]",
     "lerobot[peft]",
@@ -223,6 +222,7 @@ lerobot-eval="lerobot.scripts.lerobot_eval:main"
 lerobot-train="lerobot.scripts.lerobot_train:main"
 lerobot-train-tokenizer="lerobot.scripts.lerobot_train_tokenizer:main"
 lerobot-dataset-viz="lerobot.scripts.lerobot_dataset_viz:main"
+lerobot-dataset-subtask-annotate="lerobot.scripts.lerobot_subtask_annotate:main"
 lerobot-info="lerobot.scripts.lerobot_info:main"
 lerobot-find-joint-limits="lerobot.scripts.lerobot_find_joint_limits:main"
 lerobot-imgtransform-viz="lerobot.scripts.lerobot_imgtransform_viz:main"
@@ -306,8 +306,7 @@ default.extend-ignore-identifiers-re = [
     "thw",
     "inpt",
     "ROBOTIS",
-    "OT_VALUE",
-    "metalness",
+    "OT_VALUE"
 ]
 
 # TODO: Uncomment when ready to use

src/lerobot/async_inference/helpers.py

@@ -23,7 +23,7 @@ from typing import Any
 import torch
 
 from lerobot.configs.types import PolicyFeature
-from lerobot.datasets.feature_utils import build_dataset_frame, hw_to_dataset_features
+from lerobot.datasets.utils import build_dataset_frame, hw_to_dataset_features
 
 # NOTE: Configs need to be loaded for the client to be able to instantiate the policy config
 from lerobot.policies import (  # noqa: F401

src/lerobot/async_inference/policy_server.py

@@ -39,13 +39,15 @@ import grpc
 import torch
 
 from lerobot.policies.factory import get_policy_class, make_pre_post_processors
-from lerobot.processor import PolicyProcessorPipeline
+from lerobot.processor import (
+    PolicyAction,
+    PolicyProcessorPipeline,
+)
 from lerobot.transport import (
     services_pb2,  # type: ignore
     services_pb2_grpc,  # type: ignore
 )
 from lerobot.transport.utils import receive_bytes_in_chunks
-from lerobot.types import PolicyAction
 
 from .configs import PolicyServerConfig
 from .constants import SUPPORTED_POLICIES

src/lerobot/configs/default.py

@@ -27,8 +27,7 @@ class DatasetConfig:
     # "dataset_index" into the returned item. The index mapping is made according to the order in which the
     # datasets are provided.
     repo_id: str
-    # Root directory for a concrete local dataset tree (e.g. 'dataset/path'). If None, local datasets are
-    # looked up under $HF_LEROBOT_HOME/repo_id and Hub downloads use a revision-safe cache under $HF_LEROBOT_HOME/hub.
+    # Root directory where the dataset will be stored (e.g. 'dataset/path'). If None, defaults to $HF_LEROBOT_HOME/repo_id.
     root: str | None = None
     episodes: list[int] | None = None
     image_transforms: ImageTransformsConfig = field(default_factory=ImageTransformsConfig)
@@ -37,16 +36,6 @@ class DatasetConfig:
     video_backend: str = field(default_factory=get_safe_default_codec)
     streaming: bool = False
 
-    def __post_init__(self) -> None:
-        if self.episodes is not None:
-            if any(ep < 0 for ep in self.episodes):
-                raise ValueError(
-                    f"Episode indices must be non-negative, got: {[ep for ep in self.episodes if ep < 0]}"
-                )
-            if len(self.episodes) != len(set(self.episodes)):
-                duplicates = sorted({ep for ep in self.episodes if self.episodes.count(ep) > 1})
-                raise ValueError(f"Episode indices contain duplicates: {duplicates}")
-
 
 @dataclass
 class WandBConfig:
@@ -58,7 +47,6 @@ class WandBConfig:
     notes: str | None = None
     run_id: str | None = None
     mode: str | None = None  # Allowed values: 'online', 'offline' 'disabled'. Defaults to 'online'
-    add_tags: bool = True  # If True, save configuration as tags in the WandB run.
 
 
 @dataclass

src/lerobot/configs/policies.py

@@ -30,8 +30,8 @@ from lerobot.configs.types import FeatureType, PolicyFeature
 from lerobot.optim.optimizers import OptimizerConfig
 from lerobot.optim.schedulers import LRSchedulerConfig
 from lerobot.utils.constants import ACTION, OBS_STATE
-from lerobot.utils.device_utils import auto_select_torch_device, is_amp_available, is_torch_device_available
 from lerobot.utils.hub import HubMixin
+from lerobot.utils.utils import auto_select_torch_device, is_amp_available, is_torch_device_available
 
 T = TypeVar("T", bound="PreTrainedConfig")
 logger = getLogger(__name__)
@@ -115,17 +115,6 @@ class PreTrainedConfig(draccus.ChoiceRegistry, HubMixin, abc.ABC):  # type: igno
     def reward_delta_indices(self) -> list | None:  # type: ignore[type-arg]    #TODO: No implementation
         raise NotImplementedError
 
-    @property
-    def state_delta_indices(self) -> list | None:  # type: ignore[type-arg]
-        """Delta indices specifically for observation.state.
-
-        When not None, overrides ``observation_delta_indices`` for the
-        ``observation.state`` key only. Useful for loading state history
-        (e.g. ``[-1, 0]`` for UMI-style relative proprioception) without
-        also loading multiple image timesteps.
-        """
-        return None
-
     @abc.abstractmethod
     def get_optimizer_preset(self) -> OptimizerConfig:
         raise NotImplementedError

src/lerobot/configs/train.py

@@ -51,7 +51,7 @@ class TrainPipelineConfig(HubMixin):
     # AND for the evaluation environments.
     seed: int | None = 1000
     # Set to True to use deterministic cuDNN algorithms for reproducibility.
-    # This disables cudnn.benchmark and may reduce training speed by ~10-20 percent.
+    # This disables cudnn.benchmark and may reduce training speed by ~10-20%.
     cudnn_deterministic: bool = False
     # Number of workers for the dataloader.
     num_workers: int = 4

src/lerobot/data_processing/data_annotations/__init__.py

@@ -0,0 +1,2 @@
+# Copyright 2024 The HuggingFace Inc. team. All rights reserved.
+# Data annotations for subtasks and VLM-based labeling.

src/lerobot/data_processing/data_annotations/subtask_annotations.py

@@ -0,0 +1,671 @@
+# Copyright 2025 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.
+
+import json
+import subprocess
+import tempfile
+from pathlib import Path
+from typing import TYPE_CHECKING
+
+import cv2
+
+from lerobot.datasets.dataset_tools import add_features
+from lerobot.datasets.lerobot_dataset import LeRobotDataset
+from lerobot.datasets.utils import (
+    create_subtask_index_array,
+    create_subtasks_dataframe,
+    save_subtasks,
+)
+
+if TYPE_CHECKING:
+    from lerobot.data_processing.data_annotations.vlm_annotations import BaseVLM
+
+
+# Skill Annotation Data Structures
+class Skill:
+    """Represents a single atomic skill/subtask in a demonstration."""
+
+    def __init__(self, name: str, start: float, end: float):
+        self.name = name
+        self.start = start  # Start timestamp in seconds
+        self.end = end  # End timestamp in seconds
+
+    def to_dict(self) -> dict:
+        return {"name": self.name, "start": self.start, "end": self.end}
+
+    @classmethod
+    def from_dict(cls, data: dict) -> "Skill":
+        return cls(name=data["name"], start=data["start"], end=data["end"])
+
+    def __repr__(self) -> str:
+        return f"Skill(name='{self.name}', start={self.start:.2f}, end={self.end:.2f})"
+
+
+class EpisodeSkills:
+    """Container for all skills in an episode."""
+
+    def __init__(self, episode_index: int, description: str, skills: list[Skill]):
+        self.episode_index = episode_index
+        self.description = description
+        self.skills = skills
+
+    def to_dict(self) -> dict:
+        return {
+            "episode_index": self.episode_index,
+            "description": self.description,
+            "skills": [s.to_dict() for s in self.skills],
+        }
+
+
+# Video Extraction Utilities
+
+
+class VideoExtractor:
+    """Utilities for extracting and processing video segments from LeRobot datasets."""
+
+    def __init__(self) -> None:
+        pass
+
+    def extract_episode_video(
+        self,
+        video_path: Path,
+        start_timestamp: float,
+        end_timestamp: float,
+        target_fps: int = 1,
+    ) -> Path:
+        """
+        Extract a specific episode segment from a concatenated video file.
+
+        Args:
+            video_path: Path to the source video file
+            start_timestamp: Start time in seconds
+            end_timestamp: End time in seconds
+            target_fps: Target frames per second for output
+
+        Returns:
+            Path to the extracted temporary video file
+        """
+        with tempfile.NamedTemporaryFile(suffix=".mp4", delete=False) as tmp_file:
+            tmp_path = Path(tmp_file.name)
+
+        duration = end_timestamp - start_timestamp
+
+        print(f"Extracting: {start_timestamp:.1f}s - {end_timestamp:.1f}s ({duration:.1f}s)")
+
+        cmd = [
+            "ffmpeg",
+            "-i",
+            str(video_path),
+            "-ss",
+            str(start_timestamp),
+            "-t",
+            str(duration),
+            "-r",
+            str(target_fps),
+            "-c:v",
+            "libx264",
+            "-preset",
+            "ultrafast",
+            "-crf",
+            "23",
+            "-an",
+            "-y",
+            str(tmp_path),
+        ]
+
+        try:
+            subprocess.run(cmd, stdout=subprocess.DEVNULL, stderr=subprocess.DEVNULL, check=True)
+        except subprocess.CalledProcessError as e:
+            raise RuntimeError(f"FFmpeg failed: {e}") from e
+        except FileNotFoundError as e:
+            raise RuntimeError("FFmpeg not found. Please install ffmpeg.") from e
+
+        if not tmp_path.exists() or tmp_path.stat().st_size < 1024:
+            if tmp_path.exists():
+                tmp_path.unlink()
+            raise RuntimeError("Video extraction produced invalid file")
+
+        return tmp_path
+
+    def add_timer_overlay(self, video_path: Path) -> Path:
+        """
+        Add a visible timer overlay to each frame (elapsed time in seconds) in one corner.
+        Used so the VLM can read the timestamp from the image instead of relying on file metadata.
+        Draws a black box with white text at top-right. Writes to a new temporary file and returns its path.
+        """
+        with tempfile.NamedTemporaryFile(suffix=".mp4", delete=False) as out_file:
+            out_path = Path(out_file.name)
+
+        cap = cv2.VideoCapture(str(video_path))
+        if not cap.isOpened():
+            raise RuntimeError("Failed to open video")
+
+        fps = cap.get(cv2.CAP_PROP_FPS) or 1.0
+        w = int(cap.get(cv2.CAP_PROP_FRAME_WIDTH))
+        h = int(cap.get(cv2.CAP_PROP_FRAME_HEIGHT))
+        fourcc = cv2.VideoWriter_fourcc(*"mp4v")
+        writer = cv2.VideoWriter(str(out_path), fourcc, fps, (w, h))
+
+        font = cv2.FONT_HERSHEY_SIMPLEX
+        font_scale = max(1.2, min(h, w) / 350.0)
+        thickness = max(2, int(font_scale))
+
+        padding = 15
+        margin = 30
+
+        frame_idx = 0
+        while True:
+            ret, frame = cap.read()
+            if not ret:
+                break
+
+            t_sec = frame_idx / fps
+            text = f"{t_sec:.2f} s"
+
+            (tw, th), baseline = cv2.getTextSize(text, font, font_scale, thickness)
+
+            # Top-right placement
+            x_text = w - tw - margin - padding
+            y_text = margin + th + padding
+
+            # Rectangle coordinates (black box behind text)
+            x1 = x_text - padding
+            y1 = y_text - th - padding
+            x2 = x_text + tw + padding
+            y2 = y_text + baseline + padding
+
+            # Draw black filled rectangle
+            cv2.rectangle(frame, (x1, y1), (x2, y2), (0, 0, 0), -1)
+
+            # Draw white text
+            cv2.putText(
+                frame,
+                text,
+                (x_text, y_text),
+                font,
+                font_scale,
+                (255, 255, 255),
+                thickness,
+                lineType=cv2.LINE_AA,
+            )
+
+            writer.write(frame)
+            frame_idx += 1
+
+        cap.release()
+        writer.release()
+        if not out_path.exists() or out_path.stat().st_size < 1024:
+            if out_path.exists():
+                out_path.unlink()
+            raise RuntimeError("Timer overlay produced invalid file")
+        return out_path
+
+    def get_video_duration(self, video_path: Path) -> float:
+        """Get duration of a video file in seconds."""
+        cap = cv2.VideoCapture(str(video_path))
+        fps = cap.get(cv2.CAP_PROP_FPS) or 30
+        frame_count = int(cap.get(cv2.CAP_PROP_FRAME_COUNT))
+        cap.release()
+        return frame_count / fps
+
+
+# Skill Annotation Pipeline
+class SkillAnnotator:
+    """
+    Main class for annotating LeRobot datasets with skill labels.
+
+    This class orchestrates the full annotation pipeline:
+    1. Load dataset
+    2. Extract video segments for each episode
+    3. Run VLM-based skill segmentation
+    4. Update dataset task metadata
+    """
+
+    def __init__(
+        self,
+        vlm: "BaseVLM",
+        video_extractor: VideoExtractor | None = None,
+        batch_size: int = 8,
+        add_timer_overlay: bool = True,
+    ):
+        self.vlm = vlm
+        self.video_extractor = video_extractor or VideoExtractor()
+        self.batch_size = batch_size
+        self.add_timer_overlay = add_timer_overlay
+
+    def annotate_dataset(
+        self,
+        dataset: LeRobotDataset,
+        video_key: str,
+        episodes: list[int] | None = None,
+        skip_existing: bool = False,
+        subtask_labels: list[str] | None = None,
+    ) -> dict[int, EpisodeSkills]:
+        """
+        Annotate all episodes in a dataset with skill labels using batched processing.
+
+        Args:
+            dataset: LeRobot dataset to annotate
+            video_key: Key for video observations (e.g., "observation.images.base")
+            episodes: Specific episode indices to annotate (None = all)
+            skip_existing: Skip episodes that already have skill annotations
+            subtask_labels: If provided, model must choose only from these labels (closed vocabulary)
+
+        Returns:
+            Dictionary mapping episode index to EpisodeSkills
+        """
+        episode_indices = episodes or list(range(dataset.meta.total_episodes))
+        annotations: dict[int, EpisodeSkills] = {}
+        failed_episodes: dict[int, str] = {}  # Track failed episodes with error messages
+
+        # Get coarse task description if available
+        coarse_goal = self._get_coarse_goal(dataset)
+
+        # Filter out episodes that already have annotations if skip_existing is True
+        if skip_existing:
+            existing_annotations = load_skill_annotations(dataset.root)
+            if existing_annotations and "episodes" in existing_annotations:
+                # Only skip episodes that exist AND have non-empty skills
+                existing_episode_indices = set()
+                for idx_str, episode_data in existing_annotations["episodes"].items():
+                    idx = int(idx_str)
+                    # Check if skills list exists and is not empty
+                    if "skills" in episode_data and episode_data["skills"]:
+                        existing_episode_indices.add(idx)
+
+                original_count = len(episode_indices)
+                episode_indices = [ep for ep in episode_indices if ep not in existing_episode_indices]
+                skipped_count = original_count - len(episode_indices)
+                if skipped_count > 0:
+                    print(f"Skipping {skipped_count} episodes with existing non-empty annotations")
+
+        if not episode_indices:
+            print("No episodes to annotate (all already annotated)")
+            return annotations
+
+        print(f"Annotating {len(episode_indices)} episodes in batches of {self.batch_size}...")
+
+        # Process episodes in batches
+        for batch_start in range(0, len(episode_indices), self.batch_size):
+            batch_end = min(batch_start + self.batch_size, len(episode_indices))
+            batch_episodes = episode_indices[batch_start:batch_end]
+
+            print(
+                f"Processing batch {batch_start // self.batch_size + 1}/{(len(episode_indices) + self.batch_size - 1) // self.batch_size} (episodes {batch_episodes[0]} to {batch_episodes[-1]})..."
+            )
+
+            try:
+                batch_annotations = self._annotate_episodes_batch(
+                    dataset, batch_episodes, video_key, coarse_goal, subtask_labels
+                )
+
+                for ep_idx in batch_episodes:
+                    if ep_idx in batch_annotations and batch_annotations[ep_idx]:
+                        skills = batch_annotations[ep_idx]
+                        annotations[ep_idx] = EpisodeSkills(
+                            episode_index=ep_idx,
+                            description=coarse_goal,
+                            skills=skills,
+                        )
+                        print(f" Episode {ep_idx}: {len(skills)} skills identified")
+                    else:
+                        failed_episodes[ep_idx] = "Empty or missing skills from batch processing"
+                        print(f"⚠ Episode {ep_idx}: No skills extracted, will retry")
+            except Exception as e:
+                print(f"✗ Batch failed: {e}. Falling back to single-episode processing...")
+                # Fallback: process episodes one by one
+                for ep_idx in batch_episodes:
+                    try:
+                        skills = self._annotate_episode(
+                            dataset, ep_idx, video_key, coarse_goal, subtask_labels
+                        )
+                        if skills:
+                            annotations[ep_idx] = EpisodeSkills(
+                                episode_index=ep_idx,
+                                description=coarse_goal,
+                                skills=skills,
+                            )
+                            print(f" Episode {ep_idx}: {len(skills)} skills identified")
+                        else:
+                            failed_episodes[ep_idx] = "Empty skills list from single-episode processing"
+                            print(f"⚠ Episode {ep_idx}: No skills extracted, will retry")
+                    except Exception as ep_error:
+                        failed_episodes[ep_idx] = str(ep_error)
+                        print(f"⚠ Episode {ep_idx} failed: {ep_error}, will retry")
+
+        # Retry failed episodes one more time
+        if failed_episodes:
+            print(f"\nRetrying {len(failed_episodes)} failed episodes...")
+            retry_count = 0
+            for ep_idx, error_msg in list(failed_episodes.items()):
+                print(f"Retry attempt for episode {ep_idx} (previous error: {error_msg})")
+                try:
+                    skills = self._annotate_episode(dataset, ep_idx, video_key, coarse_goal, subtask_labels)
+                    if skills:
+                        annotations[ep_idx] = EpisodeSkills(
+                            episode_index=ep_idx,
+                            description=coarse_goal,
+                            skills=skills,
+                        )
+                        print(f" Episode {ep_idx} (retry): {len(skills)} skills identified")
+                        del failed_episodes[ep_idx]
+                        retry_count += 1
+                    else:
+                        print(f"✗ Episode {ep_idx} (retry): Still no skills extracted")
+                except Exception as retry_error:
+                    failed_episodes[ep_idx] = str(retry_error)
+                    print(f"✗ Episode {ep_idx} (retry) failed: {retry_error}")
+
+            if retry_count > 0:
+                print(f"Successfully recovered {retry_count} episodes on retry")
+
+            if failed_episodes:
+                print(f"\n⚠ Warning: {len(failed_episodes)} episodes still failed after retry:")
+                for ep_idx, error_msg in failed_episodes.items():
+                    print(f"  Episode {ep_idx}: {error_msg}")
+
+        return annotations
+
+    def _get_coarse_goal(self, dataset: LeRobotDataset) -> str:
+        """Extract or generate the coarse task description."""
+        # Try to get from existing task metadata
+        if dataset.meta.tasks is not None and len(dataset.meta.tasks) > 0:
+            # Get the first task description
+            first_task = dataset.meta.tasks.index[0]
+            if first_task:
+                return str(first_task)
+
+        return "Perform the demonstrated manipulation task."
+
+    def _annotate_episodes_batch(
+        self,
+        dataset: LeRobotDataset,
+        episode_indices: list[int],
+        video_key: str,
+        coarse_goal: str,
+        subtask_labels: list[str] | None = None,
+    ) -> dict[int, list[Skill]]:
+        """Annotate multiple episodes with skill labels in a batch."""
+        # Extract all videos for this batch
+        extracted_paths = []
+        timer_paths = []
+        paths_for_vlm = []
+        durations = []
+        valid_episode_indices = []
+
+        for ep_idx in episode_indices:
+            try:
+                # Get video path and timestamps
+                video_path = dataset.root / dataset.meta.get_video_file_path(ep_idx, video_key)
+
+                if not video_path.exists():
+                    print(f"Warning: Video not found for episode {ep_idx}")
+                    continue
+
+                # Get episode timestamps from metadata
+                ep = dataset.meta.episodes[ep_idx]
+                start_ts = float(ep[f"videos/{video_key}/from_timestamp"])
+                end_ts = float(ep[f"videos/{video_key}/to_timestamp"])
+                duration = end_ts - start_ts
+
+                # Extract episode segment to temporary file
+                extracted_path = self.video_extractor.extract_episode_video(
+                    video_path, start_ts, end_ts, target_fps=dataset.meta.fps
+                )
+
+                if self.add_timer_overlay:
+                    video_for_vlm = self.video_extractor.add_timer_overlay(extracted_path)
+                    extracted_paths.append(extracted_path)
+                    timer_paths.append(video_for_vlm)
+                else:
+                    video_for_vlm = extracted_path
+                    extracted_paths.append(extracted_path)
+                    timer_paths.append(None)
+
+                paths_for_vlm.append(video_for_vlm)
+                durations.append(duration)
+                valid_episode_indices.append(ep_idx)
+
+            except Exception as e:
+                print(f"Warning: Failed to extract video for episode {ep_idx}: {e}")
+                continue
+
+        if not paths_for_vlm:
+            return {}
+
+        try:
+            # Run VLM skill segmentation in batch
+            all_skills = self.vlm.segment_skills_batch(paths_for_vlm, durations, coarse_goal, subtask_labels)
+
+            # Map results back to episode indices
+            results = {}
+            for ep_idx, skills in zip(valid_episode_indices, all_skills, strict=True):
+                results[ep_idx] = skills
+
+            return results
+
+        finally:
+            # Clean up all temporary files (extracted and timer-overlay)
+            for path in extracted_paths:
+                if path.exists():
+                    path.unlink()
+            for path in timer_paths:
+                if path is not None and path.exists():
+                    path.unlink()
+
+    def _annotate_episode(
+        self,
+        dataset: LeRobotDataset,
+        episode_index: int,
+        video_key: str,
+        coarse_goal: str,
+        subtask_labels: list[str] | None = None,
+    ) -> list[Skill]:
+        """Annotate a single episode with skill labels."""
+        # Get video path and timestamps for this episode
+        video_path = dataset.root / dataset.meta.get_video_file_path(episode_index, video_key)
+
+        if not video_path.exists():
+            raise FileNotFoundError(f"Video not found: {video_path}")
+
+        # Get episode timestamps from metadata
+        ep = dataset.meta.episodes[episode_index]
+        start_ts = float(ep[f"videos/{video_key}/from_timestamp"])
+        end_ts = float(ep[f"videos/{video_key}/to_timestamp"])
+        duration = end_ts - start_ts
+
+        # Extract episode segment to temporary file
+        extracted_path = self.video_extractor.extract_episode_video(
+            video_path, start_ts, end_ts, target_fps=1
+        )
+        if self.add_timer_overlay:
+            video_for_vlm = self.video_extractor.add_timer_overlay(extracted_path)
+        else:
+            video_for_vlm = extracted_path
+
+        try:
+            # Run VLM skill segmentation
+            skills = self.vlm.segment_skills(video_for_vlm, duration, coarse_goal, subtask_labels)
+            return skills
+        finally:
+            # Clean up temporary files (extracted and optionally timer-overlay)
+            if extracted_path.exists():
+                extracted_path.unlink()
+            if self.add_timer_overlay and video_for_vlm != extracted_path and video_for_vlm.exists():
+                video_for_vlm.unlink()
+
+
+# Metadata Writer - Updates per-frame task_index based on skills
+
+
+def get_skill_for_timestamp(skills: list[Skill], timestamp: float) -> Skill | None:
+    """
+    Find which skill covers a given timestamp.
+
+    Args:
+        skills: List of skills with start/end times
+        timestamp: Frame timestamp in seconds
+
+    Returns:
+        The Skill that covers this timestamp, or None if not found
+    """
+    for skill in skills:
+        if skill.start <= timestamp < skill.end:
+            return skill
+        # Handle the last frame (end boundary)
+        if timestamp >= skill.end and skill == skills[-1]:
+            return skill
+    return skills[-1] if skills else None  # Fallback to last skill
+
+
+def save_skill_annotations(
+    dataset: LeRobotDataset,
+    annotations: dict[int, EpisodeSkills],
+    output_dir: Path | None = None,
+    repo_id: str | None = None,
+) -> LeRobotDataset:
+    """
+    Save skill annotations to the dataset by:
+    1. Creating a subtasks.parquet file with unique subtasks
+    2. Adding a subtask_index feature to the dataset
+    3. Saving raw skill annotations as JSON for reference
+
+    This function does NOT modify tasks.parquet - it keeps the original tasks intact
+    and creates a separate subtask hierarchy.
+
+    Args:
+        dataset: The LeRobot dataset to annotate
+        annotations: Dictionary of episode skills
+        output_dir: Optional directory to save the modified dataset
+        repo_id: Optional repository ID for the new dataset
+
+    Returns:
+        New dataset with subtask_index feature added
+    """
+    if not annotations:
+        print("No annotations to save")
+        return dataset
+
+    # Step 1: Create subtasks DataFrame
+    print("Creating subtasks DataFrame...")
+    subtasks_df, skill_to_subtask_idx = create_subtasks_dataframe(annotations)
+
+    # Step 2: Create subtask_index array for all frames
+    print("Creating subtask_index array...")
+    subtask_indices = create_subtask_index_array(dataset, annotations, skill_to_subtask_idx)
+
+    # Step 3: Save subtasks.parquet to the original dataset root
+    save_subtasks(subtasks_df, dataset.root)
+
+    # Step 4: Save the raw skill annotations as JSON for reference
+    skills_path = dataset.root / "meta" / "skills.json"
+    skills_path.parent.mkdir(parents=True, exist_ok=True)
+
+    # Load existing skills data if it exists and is not empty
+    existing_skills_data = None
+    if skills_path.exists():
+        try:
+            with open(skills_path) as f:
+                existing_skills_data = json.load(f)
+                if existing_skills_data and len(existing_skills_data.get("episodes", {})) > 0:
+                    print(
+                        f"Found existing skills.json with {len(existing_skills_data.get('episodes', {}))} episodes, merging..."
+                    )
+        except (OSError, json.JSONDecodeError):
+            print("Warning: Could not load existing skills.json, will create new file")
+            existing_skills_data = None
+
+    # Prepare new annotations
+    new_episodes = {str(ep_idx): ann.to_dict() for ep_idx, ann in annotations.items()}
+
+    # Merge with existing data if available
+    if existing_skills_data:
+        # Preserve existing episodes that are not being updated
+        merged_episodes = existing_skills_data.get("episodes", {}).copy()
+        merged_episodes.update(new_episodes)
+
+        # Merge skill_to_subtask_index mappings
+        merged_skill_to_subtask = existing_skills_data.get("skill_to_subtask_index", {}).copy()
+        merged_skill_to_subtask.update(skill_to_subtask_idx)
+
+        # Use existing coarse_description if available, otherwise use new one
+        coarse_desc = existing_skills_data.get(
+            "coarse_description", annotations[next(iter(annotations))].description
+        )
+
+        skills_data = {
+            "coarse_description": coarse_desc,
+            "skill_to_subtask_index": merged_skill_to_subtask,
+            "episodes": merged_episodes,
+        }
+        print(
+            f"Updated {len(new_episodes)} episode(s), total episodes in skills.json: {len(merged_episodes)}"
+        )
+    else:
+        # No existing data, create new
+        skills_data = {
+            "coarse_description": annotations[next(iter(annotations))].description,
+            "skill_to_subtask_index": skill_to_subtask_idx,
+            "episodes": new_episodes,
+        }
+
+    with open(skills_path, "w") as f:
+        json.dump(skills_data, f, indent=2)
+
+    print(f" Saved skill annotations to {skills_path}")
+
+    # Step 5: Add subtask_index feature to dataset using add_features
+    print("Adding subtask_index feature to dataset...")
+
+    # Determine output directory and repo_id
+    output_dir = dataset.root.parent / f"{dataset.root.name}" if output_dir is None else Path(output_dir)
+
+    if repo_id is None:
+        repo_id = f"{dataset.repo_id}"
+
+    # Add feature using dataset_tools
+    feature_info = {
+        "dtype": "int64",
+        "shape": (1,),
+        "names": None,
+    }
+    new_dataset = add_features(
+        dataset=dataset,
+        features={
+            "subtask_index": (subtask_indices, feature_info),
+        },
+        output_dir=output_dir,
+        repo_id=repo_id,
+    )
+
+    # Copy subtasks.parquet to new output directory
+    import shutil
+
+    shutil.copy(dataset.root / "meta" / "subtasks.parquet", output_dir / "meta" / "subtasks.parquet")
+    shutil.copy(dataset.root / "meta" / "skills.json", output_dir / "meta" / "skills.json")
+
+    print(" Successfully added subtask_index feature!")
+    print(f"  New dataset saved to: {new_dataset.root}")
+    print(f"  Total subtasks: {len(subtasks_df)}")
+
+    return new_dataset
+
+
+def load_skill_annotations(dataset_root: Path) -> dict | None:
+    """Load existing skill annotations from a dataset."""
+    skills_path = dataset_root / "meta" / "skills.json"
+    if skills_path.exists():
+        with open(skills_path) as f:
+            return json.load(f)
+    return None

src/lerobot/data_processing/data_annotations/vlm_annotations.py

@@ -0,0 +1,271 @@
+# Copyright 2025 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.
+
+import json
+import logging
+import re
+from abc import ABC, abstractmethod
+from pathlib import Path
+
+import torch
+
+from lerobot.data_processing.data_annotations.subtask_annotations import Skill
+from lerobot.utils.constants import (
+    SKILL_SEGMENTATION_PROMPT_TEMPLATE,
+    format_subtask_labels_section,
+)
+
+logger = logging.getLogger(__name__)
+
+DEFAULT_MODEL = "Qwen/Qwen3.5-27B"
+
+
+def create_skill_segmentation_prompt(
+    coarse_goal: str | None = None,
+    subtask_labels: list[str] | None = None,
+    duration_seconds: float | None = None,
+) -> str:
+    """Create the prompt for skill segmentation using the template from constants."""
+    if duration_seconds is None:
+        raise ValueError("duration_seconds is required for skill segmentation prompt")
+    goal_context = f'The overall goal is: "{coarse_goal}"\n\n' if coarse_goal else ""
+    subtask_labels_section = format_subtask_labels_section(subtask_labels) if subtask_labels else ""
+    video_duration_mm_ss = f"{int(duration_seconds // 60):02d}:{int(duration_seconds % 60):02d}"
+    return SKILL_SEGMENTATION_PROMPT_TEMPLATE.format(
+        goal_context=goal_context,
+        subtask_labels_section=subtask_labels_section,
+        video_duration_seconds=duration_seconds,
+        video_duration_mm_ss=video_duration_mm_ss,
+    )
+
+
+class BaseVLM(ABC):
+    """
+    Abstract base class for Vision-Language Models used in skill segmentation.
+
+    To add a new VLM family:
+    1. Subclass BaseVLM
+    2. Implement __init__, segment_skills, and segment_skills_batch
+    3. Register it in get_vlm()
+    """
+
+    @abstractmethod
+    def __init__(self, model_name: str, device: str = "cuda", torch_dtype: torch.dtype = torch.bfloat16):
+        pass
+
+    @abstractmethod
+    def segment_skills(
+        self,
+        video_path: Path,
+        episode_duration: float,
+        coarse_goal: str | None = None,
+        subtask_labels: list[str] | None = None,
+    ) -> list[Skill]:
+        """Segment a single video into atomic skills."""
+        pass
+
+    @abstractmethod
+    def segment_skills_batch(
+        self,
+        video_paths: list[Path],
+        episode_durations: list[float],
+        coarse_goal: str | None = None,
+        subtask_labels: list[str] | None = None,
+    ) -> list[list[Skill]]:
+        """Segment multiple videos into atomic skills in a single batch."""
+        pass
+
+    def _parse_skills_response(self, response: str) -> list[Skill]:
+        """Parse JSON skill list from VLM response text."""
+        if "```json" in response:
+            response = response.split("```json")[1].split("```")[0]
+        elif "```" in response:
+            response = response.split("```")[1].split("```")[0]
+
+        try:
+            data = json.loads(response)
+            skills_data = data.get("skills", data)
+            if isinstance(skills_data, list):
+                return [Skill.from_dict(s) for s in skills_data]
+        except json.JSONDecodeError:
+            match = re.search(r"\{.*\}", response, re.DOTALL)
+            if match:
+                try:
+                    data = json.loads(match.group())
+                    skills_data = data.get("skills", [])
+                    return [Skill.from_dict(s) for s in skills_data]
+                except json.JSONDecodeError as e:
+                    raise ValueError(f"Could not parse JSON from VLM response: {response[:200]}...") from e
+
+        raise ValueError(f"Could not parse skills from response: {response[:200]}...")
+
+
+class QwenVL(BaseVLM):
+    """Qwen VL model for skill segmentation (default: Qwen3.5 series).
+
+    Uses qwen-vl-utils for video processing and the HuggingFace transformers
+    Qwen3VLProcessor pipeline. Requires transformers >= 5.4.0 for correct
+    video position embeddings.
+    """
+
+    def __init__(self, model_name: str, device: str = "cuda", torch_dtype: torch.dtype = torch.bfloat16):
+        from qwen_vl_utils import process_vision_info
+        from transformers import AutoModelForImageTextToText, AutoProcessor
+
+        self.device = device
+        self.model_name = model_name
+        self.process_vision_info = process_vision_info
+
+        logger.info(f"Loading model: {model_name}...")
+
+        self.model = AutoModelForImageTextToText.from_pretrained(
+            model_name, torch_dtype=torch_dtype, device_map=device, trust_remote_code=True
+        )
+        self.processor = AutoProcessor.from_pretrained(model_name, trust_remote_code=True)
+        self.processor.tokenizer.padding_side = "left"
+
+        logger.info(f"Model loaded on {device}")
+
+    def _build_messages(self, video_path: Path, episode_duration: float, prompt: str) -> list[dict]:
+        duration_str = f"{int(episode_duration // 60):02d}:{int(episode_duration % 60):02d}"
+        return [
+            {"role": "system", "content": [{"type": "text", "text": prompt}]},
+            {
+                "role": "user",
+                "content": [
+                    {"type": "video", "video": str(video_path), "fps": 1.0},
+                    {
+                        "type": "text",
+                        "text": (
+                            f"Video duration: {duration_str} (exactly {episode_duration:.1f} seconds). "
+                            f"Segment into atomic skills. Last skill must end at {episode_duration:.1f}."
+                        ),
+                    },
+                ],
+            },
+        ]
+
+    def _prepare_inputs(self, messages: list[dict]) -> dict:
+        """Tokenize a single message and return processor inputs on device."""
+        text = self.processor.apply_chat_template(
+            messages, tokenize=False, add_generation_prompt=True, enable_thinking=False
+        )
+        image_inputs, video_inputs = self.process_vision_info(messages, return_video_metadata=True)
+
+        videos, video_metadata = None, None
+        if video_inputs:
+            videos = [v[0] for v in video_inputs]
+            video_metadata = [v[1] for v in video_inputs]
+
+        return self.processor(
+            text=[text],
+            images=image_inputs,
+            videos=videos,
+            videos_kwargs={
+                "video_metadata": video_metadata,
+                "do_sample_frames": False,
+            },
+            padding=True,
+            return_tensors="pt",
+        ).to(self.device)
+
+    def _decode(self, inputs, generated_ids) -> list[str]:
+        return self.processor.batch_decode(
+            [out[len(inp) :] for inp, out in zip(inputs.input_ids, generated_ids, strict=True)],
+            skip_special_tokens=True,
+            clean_up_tokenization_spaces=False,
+        )
+
+    def segment_skills(
+        self,
+        video_path: Path,
+        episode_duration: float,
+        coarse_goal: str | None = None,
+        subtask_labels: list[str] | None = None,
+    ) -> list[Skill]:
+        prompt = create_skill_segmentation_prompt(
+            coarse_goal, subtask_labels, duration_seconds=episode_duration
+        )
+        messages = self._build_messages(video_path, episode_duration, prompt)
+        inputs = self._prepare_inputs(messages)
+
+        with torch.no_grad():
+            generated_ids = self.model.generate(
+                **inputs, max_new_tokens=1024, do_sample=True, temperature=0.7
+            )
+
+        response = self._decode(inputs, generated_ids)[0].strip()
+        return self._parse_skills_response(response)
+
+    def segment_skills_batch(
+        self,
+        video_paths: list[Path],
+        episode_durations: list[float],
+        coarse_goal: str | None = None,
+        subtask_labels: list[str] | None = None,
+    ) -> list[list[Skill]]:
+        all_texts = []
+        all_video_tuples: list[tuple] = []
+
+        for video_path, duration in zip(video_paths, episode_durations, strict=True):
+            prompt = create_skill_segmentation_prompt(coarse_goal, subtask_labels, duration_seconds=duration)
+            messages = self._build_messages(video_path, duration, prompt)
+
+            text = self.processor.apply_chat_template(
+                messages, tokenize=False, add_generation_prompt=True, enable_thinking=False
+            )
+            _image_inputs, video_inputs = self.process_vision_info(messages, return_video_metadata=True)
+            all_texts.append(text)
+            all_video_tuples.extend(video_inputs or [])
+
+        videos, video_metadata = None, None
+        if all_video_tuples:
+            videos = [v[0] for v in all_video_tuples]
+            video_metadata = [v[1] for v in all_video_tuples]
+
+        inputs = self.processor(
+            text=all_texts,
+            videos=videos,
+            videos_kwargs={
+                "video_metadata": video_metadata,
+                "do_sample_frames": False,
+            },
+            padding=True,
+            return_tensors="pt",
+        ).to(self.device)
+
+        with torch.no_grad():
+            generated_ids = self.model.generate(
+                **inputs, max_new_tokens=1024, do_sample=True, temperature=0.7
+            )
+
+        responses = self._decode(inputs, generated_ids)
+
+        all_skills = []
+        for idx, response in enumerate(responses):
+            try:
+                skills = self._parse_skills_response(response.strip())
+                if not skills:
+                    logger.warning(f"No skills parsed for video {idx}")
+                all_skills.append(skills)
+            except Exception as e:
+                logger.warning(f"Failed to parse response for video {idx}: {e}")
+                all_skills.append([])
+
+        return all_skills
+
+
+def get_vlm(model_name: str, device: str = "cuda", torch_dtype: torch.dtype = torch.bfloat16) -> BaseVLM:
+    """Create a VLM instance. Defaults to QwenVL which supports the Qwen3.5 series."""
+    return QwenVL(model_name, device, torch_dtype)

src/lerobot/data_processing/sarm_annotations/subtask_annotation.py

@@ -746,8 +746,7 @@ def save_annotations_to_dataset(
     dataset_path: Path, annotations: dict[int, SubtaskAnnotation], fps: int, prefix: str = "sparse"
 ):
     """Save annotations to LeRobot dataset parquet format."""
-    from lerobot.datasets.io_utils import load_episodes
-    from lerobot.datasets.utils import DEFAULT_EPISODES_PATH
+    from lerobot.datasets.utils import DEFAULT_EPISODES_PATH, load_episodes
 
     episodes_dataset = load_episodes(dataset_path)
     if not episodes_dataset or len(episodes_dataset) == 0:
@@ -841,7 +840,7 @@ def generate_auto_sparse_annotations(
 
 def load_annotations_from_dataset(dataset_path: Path, prefix: str = "sparse") -> dict[int, SubtaskAnnotation]:
     """Load annotations from LeRobot dataset parquet files."""
-    from lerobot.datasets.io_utils import load_episodes
+    from lerobot.datasets.utils import load_episodes
 
     episodes_dataset = load_episodes(dataset_path)
     if not episodes_dataset or len(episodes_dataset) == 0:

src/lerobot/datasets/__init__.py

@@ -1,33 +0,0 @@
-#!/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 lerobot.datasets.dataset_metadata import LeRobotDatasetMetadata
-from lerobot.datasets.lerobot_dataset import LeRobotDataset
-from lerobot.datasets.multi_dataset import MultiLeRobotDataset
-from lerobot.datasets.sampler import EpisodeAwareSampler
-from lerobot.datasets.streaming_dataset import StreamingLeRobotDataset
-from lerobot.datasets.transforms import ImageTransforms, ImageTransformsConfig
-
-__all__ = [
-    "EpisodeAwareSampler",
-    "ImageTransforms",
-    "ImageTransformsConfig",
-    "LeRobotDataset",
-    "LeRobotDatasetMetadata",
-    "MultiLeRobotDataset",
-    "StreamingLeRobotDataset",
-]

src/lerobot/datasets/aggregate.py

@@ -24,16 +24,7 @@ import pandas as pd
 import tqdm
 
 from lerobot.datasets.compute_stats import aggregate_stats
-from lerobot.datasets.dataset_metadata import LeRobotDatasetMetadata
-from lerobot.datasets.feature_utils import get_hf_features_from_features
-from lerobot.datasets.io_utils import (
-    get_file_size_in_mb,
-    get_parquet_file_size_in_mb,
-    to_parquet_with_hf_images,
-    write_info,
-    write_stats,
-    write_tasks,
-)
+from lerobot.datasets.lerobot_dataset import LeRobotDatasetMetadata
 from lerobot.datasets.utils import (
     DEFAULT_CHUNK_SIZE,
     DEFAULT_DATA_FILE_SIZE_IN_MB,
@@ -41,7 +32,14 @@ from lerobot.datasets.utils import (
     DEFAULT_EPISODES_PATH,
     DEFAULT_VIDEO_FILE_SIZE_IN_MB,
     DEFAULT_VIDEO_PATH,
+    get_file_size_in_mb,
+    get_hf_features_from_features,
+    get_parquet_file_size_in_mb,
+    to_parquet_with_hf_images,
     update_chunk_file_indices,
+    write_info,
+    write_stats,
+    write_tasks,
 )
 from lerobot.datasets.video_utils import concatenate_video_files, get_video_duration_in_s
 

src/lerobot/datasets/backward_compatibility.py

@@ -0,0 +1,56 @@
+# Copyright 2024 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.
+
+import packaging.version
+
+V30_MESSAGE = """
+The dataset you requested ({repo_id}) is in {version} format.
+
+We introduced a new format since v3.0 which is not backward compatible with v2.1.
+Please, update your dataset to the new format using this command:
+```
+python -m lerobot.datasets.v30.convert_dataset_v21_to_v30 --repo-id={repo_id}
+```
+
+If you already have a converted version uploaded to the hub, then this error might be because of
+an older version in your local cache. Consider deleting the cached version and retrying.
+
+If you encounter a problem, contact LeRobot maintainers on [Discord](https://discord.com/invite/s3KuuzsPFb)
+or open an [issue on GitHub](https://github.com/huggingface/lerobot/issues/new/choose).
+"""
+
+FUTURE_MESSAGE = """
+The dataset you requested ({repo_id}) is only available in {version} format.
+As we cannot ensure forward compatibility with it, please update your current version of lerobot.
+"""
+
+
+class CompatibilityError(Exception): ...
+
+
+class BackwardCompatibilityError(CompatibilityError):
+    def __init__(self, repo_id: str, version: packaging.version.Version):
+        if version.major == 2 and version.minor == 1:
+            message = V30_MESSAGE.format(repo_id=repo_id, version=version)
+        else:
+            raise NotImplementedError(
+                "Contact the maintainer on [Discord](https://discord.com/invite/s3KuuzsPFb)."
+            )
+        super().__init__(message)
+
+
+class ForwardCompatibilityError(CompatibilityError):
+    def __init__(self, repo_id: str, version: packaging.version.Version):
+        message = FUTURE_MESSAGE.format(repo_id=repo_id, version=version)
+        super().__init__(message)

src/lerobot/datasets/compute_stats.py

@@ -13,14 +13,9 @@
 # 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
-
-import logging
-
 import numpy as np
 
-from lerobot.datasets.io_utils import load_image_as_numpy
-from lerobot.utils.constants import ACTION, OBS_STATE
+from lerobot.datasets.utils import load_image_as_numpy
 
 DEFAULT_QUANTILES = [0.01, 0.10, 0.50, 0.90, 0.99]
 
@@ -629,232 +624,3 @@ def aggregate_stats(stats_list: list[dict[str, dict]]) -> dict[str, dict[str, np
         aggregated_stats[key] = aggregate_feature_stats(stats_with_key)
 
     return aggregated_stats
-
-
-def _get_valid_chunk_starts(episode_indices: np.ndarray, chunk_size: int) -> np.ndarray:
-    """Return all start indices where a chunk of ``chunk_size`` stays within one episode."""
-    total = len(episode_indices)
-    if total < chunk_size:
-        return np.array([], dtype=np.int64)
-    max_start = total - chunk_size
-    starts = np.arange(max_start + 1)
-    valid = episode_indices[starts] == episode_indices[starts + chunk_size - 1]
-    return starts[valid]
-
-
-def _compute_relative_chunk_batch(
-    start_indices: np.ndarray,
-    all_actions: np.ndarray,
-    all_states: np.ndarray,
-    chunk_size: int,
-    relative_mask: np.ndarray,
-) -> np.ndarray:
-    """Vectorised relative-action computation for a batch of start indices.
-
-    Returns an ``(N * chunk_size, action_dim)`` float32 array.
-    """
-    if len(start_indices) == 0:
-        return np.empty((0, all_actions.shape[1]), dtype=np.float32)
-    offsets = np.arange(chunk_size)
-    frame_idx = start_indices[:, None] + offsets[None, :]
-    chunks = all_actions[frame_idx].copy()
-    states = all_states[start_indices]
-    mask_dim = len(relative_mask)
-    chunks[:, :, :mask_dim] -= states[:, None, :mask_dim] * relative_mask[None, None, :]
-    return chunks.reshape(-1, all_actions.shape[1])
-
-
-def compute_relative_action_stats(
-    hf_dataset,
-    features: dict,
-    chunk_size: int,
-    exclude_joints: list[str] | None = None,
-    num_workers: int = 0,
-) -> dict[str, np.ndarray]:
-    """Compute normalization statistics for relative actions over the full dataset.
-
-    Iterates *all* valid action chunks (within single episodes), converts them to
-    relative actions (action − current_state), and computes per-dimension
-    statistics suitable for normalization.
-
-    Args:
-        hf_dataset: The underlying HuggingFace dataset with "action",
-            "observation.state", and "episode_index" columns.
-        features: Dataset feature metadata (must contain "action" with "shape"
-            and optionally "names").
-        chunk_size: Number of consecutive frames per action chunk.
-        exclude_joints: Joint names whose dimensions should remain absolute
-            (not converted to relative actions).
-        num_workers: Number of parallel threads for computation. Values ≤1
-            mean single-threaded. Numpy releases the GIL so threads give
-            real parallelism here.
-
-    Returns:
-        Statistics dict with keys "mean", "std", "min", "max", "q01", …, "q99".
-
-    Raises:
-        ValueError: If the dataset has fewer frames than ``chunk_size``.
-        RuntimeError: If no valid (single-episode) chunks are found.
-    """
-    from lerobot.processor.relative_action_processor import RelativeActionsProcessorStep
-
-    if exclude_joints is None:
-        exclude_joints = []
-
-    action_dim = features[ACTION]["shape"][0]
-    action_names = features.get(ACTION, {}).get("names")
-    mask_step = RelativeActionsProcessorStep(
-        enabled=True,
-        exclude_joints=exclude_joints,
-        action_names=action_names,
-    )
-    relative_mask = np.array(mask_step._build_mask(action_dim), dtype=np.float32)
-
-    logging.info("Loading action/state data for relative action stats...")
-    all_actions = np.array(hf_dataset[ACTION], dtype=np.float32)
-    all_states = np.array(hf_dataset[OBS_STATE], dtype=np.float32)
-    episode_indices = np.array(hf_dataset["episode_index"])
-
-    valid_starts = _get_valid_chunk_starts(episode_indices, chunk_size)
-    if len(valid_starts) == 0:
-        raise RuntimeError(
-            f"No valid chunks found (total_frames={len(episode_indices)}, chunk_size={chunk_size})"
-        )
-
-    effective_workers = max(num_workers, 1)
-    logging.info(
-        f"Computing relative action stats from {len(valid_starts)} chunks "
-        f"(chunk_size={chunk_size}, workers={effective_workers})"
-    )
-
-    batch_size = 50_000
-    batches = [valid_starts[i : i + batch_size] for i in range(0, len(valid_starts), batch_size)]
-
-    running_stats = RunningQuantileStats()
-
-    if num_workers > 1:
-        from concurrent.futures import ThreadPoolExecutor, as_completed
-
-        with ThreadPoolExecutor(max_workers=num_workers) as pool:
-            futures = [
-                pool.submit(
-                    _compute_relative_chunk_batch,
-                    batch,
-                    all_actions,
-                    all_states,
-                    chunk_size,
-                    relative_mask,
-                )
-                for batch in batches
-            ]
-            for future in as_completed(futures):
-                running_stats.update(future.result())
-    else:
-        for batch in batches:
-            running_stats.update(
-                _compute_relative_chunk_batch(batch, all_actions, all_states, chunk_size, relative_mask)
-            )
-
-    stats = running_stats.get_statistics()
-
-    excluded_dims = int(len(relative_mask) - relative_mask.sum())
-    total_frames = len(valid_starts) * chunk_size
-    logging.info(
-        f"Relative action stats ({len(valid_starts)} chunks, {total_frames} frames): "
-        f"relative_dims={int(relative_mask.sum())}/{len(relative_mask)} (excluded={excluded_dims}), "
-        f"mean={np.abs(stats['mean']).mean():.4f}, std={stats['std'].mean():.4f}, "
-        f"q01={stats['q01'].mean():.4f}, q99={stats['q99'].mean():.4f}"
-    )
-
-    return stats
-
-
-def compute_relative_state_stats(
-    hf_dataset,
-    features: dict,
-    state_obs_steps: int = 2,
-    exclude_joints: list[str] | None = None,
-    source_key: str = OBS_STATE,
-) -> dict[str, np.ndarray]:
-    """Compute normalization statistics for observation.state after relative conversion.
-
-    For UMI-style relative proprioception with ``state_obs_steps`` timesteps,
-    each state observation becomes a stack of offsets from the current timestep:
-    ``state[t-k] - state[t]`` for k in ``range(state_obs_steps-1, -1, -1)``.
-
-    The stats are computed over the flattened ``[state_obs_steps * state_dim]``
-    vector that the model actually sees after ``prepare_state`` flattening.
-
-    Args:
-        hf_dataset: The HuggingFace dataset with the source column and
-            "episode_index" columns.
-        features: Dataset feature metadata.
-        state_obs_steps: Number of observation timesteps (must be >= 2).
-        exclude_joints: State dimension names to keep absolute.
-        source_key: Column to read data from. Defaults to "observation.state".
-            When ``derive_state_from_action=True``, pass ``ACTION`` to read
-            from the action column instead.
-
-    Returns:
-        Statistics dict with keys "mean", "std", "min", "max", "q01", …, "q99".
-    """
-    from lerobot.processor.relative_action_processor import RelativeStateProcessorStep
-
-    if exclude_joints is None:
-        exclude_joints = []
-
-    state_dim = features[source_key]["shape"][0]
-    state_names = features.get(source_key, {}).get("names")
-    mask_step = RelativeStateProcessorStep(
-        enabled=True,
-        exclude_joints=exclude_joints,
-        state_names=state_names,
-    )
-    relative_mask = np.array(mask_step._build_mask(state_dim), dtype=np.float32)
-
-    logging.info(f"Loading data from '{source_key}' for relative state stats...")
-    all_states = np.array(hf_dataset[source_key], dtype=np.float32)
-    episode_indices = np.array(hf_dataset["episode_index"])
-
-    # Build all valid windows of length state_obs_steps within each episode
-    n = len(all_states)
-    if n < state_obs_steps:
-        raise ValueError(f"Dataset has {n} frames but state_obs_steps={state_obs_steps}")
-
-    max_start = n - state_obs_steps
-    starts = np.arange(max_start + 1)
-    valid = episode_indices[starts] == episode_indices[starts + state_obs_steps - 1]
-    valid_starts = starts[valid]
-
-    if len(valid_starts) == 0:
-        raise RuntimeError("No valid state windows found within single episodes")
-
-    offsets = np.arange(state_obs_steps)
-    mask_dim = len(relative_mask)
-
-    running_stats = RunningQuantileStats()
-
-    batch_size = 50_000
-    for i in range(0, len(valid_starts), batch_size):
-        batch_starts = valid_starts[i : i + batch_size]
-        frame_idx = batch_starts[:, None] + offsets[None, :]  # [N, state_obs_steps]
-        windows = all_states[frame_idx].copy()  # [N, state_obs_steps, state_dim]
-
-        # Subtract current (last) timestep from all timesteps for masked dims
-        current = windows[:, -1:, :]  # [N, 1, state_dim]
-        windows[:, :, :mask_dim] -= current[:, :, :mask_dim] * relative_mask[None, None, :]
-
-        # Flatten to [N, state_obs_steps * state_dim] (same as prepare_state)
-        flattened = windows.reshape(len(batch_starts), -1)
-        running_stats.update(flattened)
-
-    stats = running_stats.get_statistics()
-
-    excluded_dims = int(mask_dim - relative_mask.sum())
-    logging.info(
-        f"Relative state stats ({len(valid_starts)} windows, obs_steps={state_obs_steps}): "
-        f"relative_dims={int(relative_mask.sum())}/{mask_dim} (excluded={excluded_dims}), "
-        f"mean={np.abs(stats['mean']).mean():.4f}, std={stats['std'].mean():.4f}"
-    )
-
-    return stats

src/lerobot/datasets/dataset_metadata.py

@@ -1,652 +0,0 @@
-#!/usr/bin/env python
-
-# Copyright 2024 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.
-import contextlib
-from pathlib import Path
-
-import numpy as np
-import packaging.version
-import pandas as pd
-import pyarrow as pa
-import pyarrow.parquet as pq
-from huggingface_hub import snapshot_download
-
-from lerobot.datasets.compute_stats import aggregate_stats
-from lerobot.datasets.feature_utils import _validate_feature_names, create_empty_dataset_info
-from lerobot.datasets.io_utils import (
-    get_file_size_in_mb,
-    load_episodes,
-    load_info,
-    load_stats,
-    load_subtasks,
-    load_tasks,
-    write_info,
-    write_json,
-    write_stats,
-    write_tasks,
-)
-from lerobot.datasets.utils import (
-    DEFAULT_EPISODES_PATH,
-    DEFAULT_FEATURES,
-    INFO_PATH,
-    check_version_compatibility,
-    flatten_dict,
-    get_safe_version,
-    has_legacy_hub_download_metadata,
-    is_valid_version,
-    update_chunk_file_indices,
-)
-from lerobot.datasets.video_utils import get_video_info
-from lerobot.utils.constants import HF_LEROBOT_HOME, HF_LEROBOT_HUB_CACHE
-
-CODEBASE_VERSION = "v3.0"
-
-
-class LeRobotDatasetMetadata:
-    """Metadata container for a LeRobot dataset.
-
-    Manages the ``info.json``, ``stats.json``, ``tasks.parquet``, and
-    ``episodes/`` parquet files that describe a dataset's structure, content,
-    and statistics.
-    """
-
-    def __init__(
-        self,
-        repo_id: str,
-        root: str | Path | None = None,
-        revision: str | None = None,
-        force_cache_sync: bool = False,
-        metadata_buffer_size: int = 10,
-    ):
-        """Load or download metadata for an existing LeRobot dataset.
-
-        Attempts to load metadata from local disk. If files are missing or
-        ``force_cache_sync`` is ``True``, downloads the ``meta/`` directory from
-        the Hub.
-
-        Args:
-            repo_id: Repository identifier (e.g. ``'lerobot/aloha_sim'``).
-            root: Local directory for the dataset. When provided, Hub downloads
-                are materialized directly into this directory. When omitted,
-                existing local datasets are still looked up under
-                ``$HF_LEROBOT_HOME/{repo_id}``, but Hub downloads use a
-                revision-safe snapshot cache under
-                ``$HF_LEROBOT_HOME/hub``.
-            revision: Git revision (branch, tag, or commit hash). Defaults to
-                the current codebase version.
-            force_cache_sync: If ``True``, re-download metadata from the Hub
-                even when local files exist.
-            metadata_buffer_size: Number of episode metadata records to buffer
-                in memory before flushing to parquet.
-        """
-        self.repo_id = repo_id
-        self.revision = revision if revision else CODEBASE_VERSION
-        self._requested_root = Path(root) if root is not None else None
-        self.root = self._requested_root if self._requested_root is not None else HF_LEROBOT_HOME / repo_id
-        self._pq_writer = None
-        self.latest_episode = None
-        self._metadata_buffer: list[dict] = []
-        self._metadata_buffer_size = metadata_buffer_size
-        self._finalized = False
-
-        try:
-            if force_cache_sync or (
-                self._requested_root is None and has_legacy_hub_download_metadata(self.root)
-            ):
-                raise FileNotFoundError
-            self._load_metadata()
-        except (FileNotFoundError, NotADirectoryError):
-            if is_valid_version(self.revision):
-                self.revision = get_safe_version(self.repo_id, self.revision)
-
-            self._pull_from_repo(allow_patterns="meta/")
-            self._load_metadata()
-
-    def _flush_metadata_buffer(self) -> None:
-        """Write all buffered episode metadata to parquet file."""
-        if not hasattr(self, "_metadata_buffer") or len(self._metadata_buffer) == 0:
-            return
-
-        combined_dict = {}
-        for episode_dict in self._metadata_buffer:
-            for key, value in episode_dict.items():
-                if key not in combined_dict:
-                    combined_dict[key] = []
-                # Extract value and serialize numpy arrays
-                # because PyArrow's from_pydict function doesn't support numpy arrays
-                val = value[0] if isinstance(value, list) else value
-                combined_dict[key].append(val.tolist() if isinstance(val, np.ndarray) else val)
-
-        first_ep = self._metadata_buffer[0]
-        chunk_idx = first_ep["meta/episodes/chunk_index"][0]
-        file_idx = first_ep["meta/episodes/file_index"][0]
-
-        table = pa.Table.from_pydict(combined_dict)
-
-        if not self._pq_writer:
-            path = Path(self.root / DEFAULT_EPISODES_PATH.format(chunk_index=chunk_idx, file_index=file_idx))
-            path.parent.mkdir(parents=True, exist_ok=True)
-            self._pq_writer = pq.ParquetWriter(
-                path, schema=table.schema, compression="snappy", use_dictionary=True
-            )
-
-        self._pq_writer.write_table(table)
-
-        self.latest_episode = self._metadata_buffer[-1]
-        self._metadata_buffer.clear()
-
-    def _close_writer(self) -> None:
-        """Close and cleanup the parquet writer if it exists."""
-        self._flush_metadata_buffer()
-
-        writer = getattr(self, "_pq_writer", None)
-        if writer is not None:
-            writer.close()
-            self._pq_writer = None
-
-    def finalize(self) -> None:
-        """Flush metadata buffer and close the parquet writer.
-
-        Idempotent — safe to call multiple times.
-        """
-        if getattr(self, "_finalized", False):
-            return
-        self._close_writer()
-        self._finalized = True
-
-    def __del__(self):
-        """Safety net: flush and close parquet writer on garbage collection."""
-        # During interpreter shutdown, referenced objects may already be collected.
-        with contextlib.suppress(Exception):
-            self.finalize()
-
-    def _load_metadata(self):
-        self.info = load_info(self.root)
-        check_version_compatibility(self.repo_id, self._version, CODEBASE_VERSION)
-        self.tasks = load_tasks(self.root)
-        self.subtasks = load_subtasks(self.root)
-        self.episodes = load_episodes(self.root)
-        self.stats = load_stats(self.root)
-
-    def _pull_from_repo(
-        self,
-        allow_patterns: list[str] | str | None = None,
-        ignore_patterns: list[str] | str | None = None,
-    ) -> None:
-        if self._requested_root is None:
-            self.root = Path(
-                snapshot_download(
-                    self.repo_id,
-                    repo_type="dataset",
-                    revision=self.revision,
-                    cache_dir=HF_LEROBOT_HUB_CACHE,
-                    allow_patterns=allow_patterns,
-                    ignore_patterns=ignore_patterns,
-                )
-            )
-            return
-
-        self._requested_root.mkdir(exist_ok=True, parents=True)
-        snapshot_download(
-            self.repo_id,
-            repo_type="dataset",
-            revision=self.revision,
-            local_dir=self._requested_root,
-            allow_patterns=allow_patterns,
-            ignore_patterns=ignore_patterns,
-        )
-        self.root = self._requested_root
-
-    @property
-    def url_root(self) -> str:
-        """Hugging Face Hub URL root for this dataset."""
-        return f"hf://datasets/{self.repo_id}"
-
-    @property
-    def _version(self) -> packaging.version.Version:
-        """Codebase version used to create this dataset."""
-        return packaging.version.parse(self.info["codebase_version"])
-
-    def get_data_file_path(self, ep_index: int) -> Path:
-        """Return the relative parquet file path for the given episode index.
-
-        Args:
-            ep_index: Zero-based episode index.
-
-        Returns:
-            Path to the parquet file containing this episode's data.
-
-        Raises:
-            IndexError: If ``ep_index`` is out of range.
-        """
-        if self.episodes is None:
-            self.episodes = load_episodes(self.root)
-        if ep_index >= len(self.episodes):
-            raise IndexError(
-                f"Episode index {ep_index} out of range. Episodes: {len(self.episodes) if self.episodes else 0}"
-            )
-        ep = self.episodes[ep_index]
-        chunk_idx = ep["data/chunk_index"]
-        file_idx = ep["data/file_index"]
-        fpath = self.data_path.format(chunk_index=chunk_idx, file_index=file_idx)
-        return Path(fpath)
-
-    def get_video_file_path(self, ep_index: int, vid_key: str) -> Path:
-        """Return the relative video file path for the given episode and video key.
-
-        Args:
-            ep_index: Zero-based episode index.
-            vid_key: Feature key identifying the video stream
-                (e.g. ``'observation.images.laptop'``).
-
-        Returns:
-            Path to the video file containing this episode's frames.
-
-        Raises:
-            IndexError: If ``ep_index`` is out of range.
-        """
-        if self.episodes is None:
-            self.episodes = load_episodes(self.root)
-        if ep_index >= len(self.episodes):
-            raise IndexError(
-                f"Episode index {ep_index} out of range. Episodes: {len(self.episodes) if self.episodes else 0}"
-            )
-        ep = self.episodes[ep_index]
-        chunk_idx = ep[f"videos/{vid_key}/chunk_index"]
-        file_idx = ep[f"videos/{vid_key}/file_index"]
-        fpath = self.video_path.format(video_key=vid_key, chunk_index=chunk_idx, file_index=file_idx)
-        return Path(fpath)
-
-    @property
-    def data_path(self) -> str:
-        """Formattable string for the parquet files."""
-        return self.info["data_path"]
-
-    @property
-    def video_path(self) -> str | None:
-        """Formattable string for the video files."""
-        return self.info["video_path"]
-
-    @property
-    def robot_type(self) -> str | None:
-        """Robot type used in recording this dataset."""
-        return self.info["robot_type"]
-
-    @property
-    def fps(self) -> int:
-        """Frames per second used during data collection."""
-        return self.info["fps"]
-
-    @property
-    def features(self) -> dict[str, dict]:
-        """All features contained in the dataset."""
-        return self.info["features"]
-
-    @property
-    def image_keys(self) -> list[str]:
-        """Keys to access visual modalities stored as images."""
-        return [key for key, ft in self.features.items() if ft["dtype"] == "image"]
-
-    @property
-    def video_keys(self) -> list[str]:
-        """Keys to access visual modalities stored as videos."""
-        return [key for key, ft in self.features.items() if ft["dtype"] == "video"]
-
-    @property
-    def camera_keys(self) -> list[str]:
-        """Keys to access visual modalities (regardless of their storage method)."""
-        return [key for key, ft in self.features.items() if ft["dtype"] in ["video", "image"]]
-
-    @property
-    def names(self) -> dict[str, list | dict]:
-        """Names of the various dimensions of vector modalities."""
-        return {key: ft["names"] for key, ft in self.features.items()}
-
-    @property
-    def shapes(self) -> dict:
-        """Shapes for the different features."""
-        return {key: tuple(ft["shape"]) for key, ft in self.features.items()}
-
-    @property
-    def total_episodes(self) -> int:
-        """Total number of episodes available."""
-        return self.info["total_episodes"]
-
-    @property
-    def total_frames(self) -> int:
-        """Total number of frames saved in this dataset."""
-        return self.info["total_frames"]
-
-    @property
-    def total_tasks(self) -> int:
-        """Total number of different tasks performed in this dataset."""
-        return self.info["total_tasks"]
-
-    @property
-    def chunks_size(self) -> int:
-        """Max number of files per chunk."""
-        return self.info["chunks_size"]
-
-    @property
-    def data_files_size_in_mb(self) -> int:
-        """Max size of data file in mega bytes."""
-        return self.info["data_files_size_in_mb"]
-
-    @property
-    def video_files_size_in_mb(self) -> int:
-        """Max size of video file in mega bytes."""
-        return self.info["video_files_size_in_mb"]
-
-    def get_task_index(self, task: str) -> int | None:
-        """
-        Given a task in natural language, returns its task_index if the task already exists in the dataset,
-        otherwise return None.
-        """
-        if task in self.tasks.index:
-            return int(self.tasks.loc[task].task_index)
-        else:
-            return None
-
-    def save_episode_tasks(self, tasks: list[str]):
-        """Register tasks for the current episode and persist to disk.
-
-        New tasks that do not already exist in the dataset are assigned
-        sequential task indices and appended to the tasks parquet file.
-
-        Args:
-            tasks: List of unique task descriptions in natural language.
-
-        Raises:
-            ValueError: If ``tasks`` contains duplicates.
-        """
-        if len(set(tasks)) != len(tasks):
-            raise ValueError(f"Tasks are not unique: {tasks}")
-
-        if self.tasks is None:
-            new_tasks = tasks
-            task_indices = range(len(tasks))
-            self.tasks = pd.DataFrame({"task_index": task_indices}, index=pd.Index(tasks, name="task"))
-        else:
-            new_tasks = [task for task in tasks if task not in self.tasks.index]
-            new_task_indices = range(len(self.tasks), len(self.tasks) + len(new_tasks))
-            for task_idx, task in zip(new_task_indices, new_tasks, strict=False):
-                self.tasks.loc[task] = task_idx
-
-        if len(new_tasks) > 0:
-            # Update on disk
-            write_tasks(self.tasks, self.root)
-
-    def _save_episode_metadata(self, episode_dict: dict) -> None:
-        """Buffer episode metadata and write to parquet in batches for efficiency.
-
-        This function accumulates episode metadata in a buffer and flushes it when the buffer
-        reaches the configured size. This reduces I/O overhead by writing multiple episodes
-        at once instead of one row at a time.
-
-        Notes: We both need to update parquet files and HF dataset:
-        - `pandas` loads parquet file in RAM
-        - `datasets` relies on a memory mapping from pyarrow (no RAM). It either converts parquet files to a pyarrow cache on disk,
-          or loads directly from pyarrow cache.
-        """
-        # Convert to list format for each value
-        episode_dict = {key: [value] for key, value in episode_dict.items()}
-        num_frames = episode_dict["length"][0]
-
-        if self.latest_episode is None:
-            # Initialize indices and frame count for a new dataset made of the first episode data
-            chunk_idx, file_idx = 0, 0
-            if self.episodes is not None and len(self.episodes) > 0:
-                # It means we are resuming recording, so we need to load the latest episode
-                # Update the indices to avoid overwriting the latest episode
-                chunk_idx = self.episodes[-1]["meta/episodes/chunk_index"]
-                file_idx = self.episodes[-1]["meta/episodes/file_index"]
-                latest_num_frames = self.episodes[-1]["dataset_to_index"]
-                episode_dict["dataset_from_index"] = [latest_num_frames]
-                episode_dict["dataset_to_index"] = [latest_num_frames + num_frames]
-
-                # When resuming, move to the next file
-                chunk_idx, file_idx = update_chunk_file_indices(chunk_idx, file_idx, self.chunks_size)
-            else:
-                episode_dict["dataset_from_index"] = [0]
-                episode_dict["dataset_to_index"] = [num_frames]
-
-            episode_dict["meta/episodes/chunk_index"] = [chunk_idx]
-            episode_dict["meta/episodes/file_index"] = [file_idx]
-        else:
-            chunk_idx = self.latest_episode["meta/episodes/chunk_index"][0]
-            file_idx = self.latest_episode["meta/episodes/file_index"][0]
-
-            latest_path = (
-                self.root / DEFAULT_EPISODES_PATH.format(chunk_index=chunk_idx, file_index=file_idx)
-                if self._pq_writer is None
-                else self._pq_writer.where
-            )
-
-            if Path(latest_path).exists():
-                latest_size_in_mb = get_file_size_in_mb(Path(latest_path))
-                latest_num_frames = self.latest_episode["episode_index"][0]
-
-                av_size_per_frame = latest_size_in_mb / latest_num_frames if latest_num_frames > 0 else 0.0
-
-                if latest_size_in_mb + av_size_per_frame * num_frames >= self.data_files_size_in_mb:
-                    # Size limit is reached, flush buffer and prepare new parquet file
-                    self._flush_metadata_buffer()
-                    chunk_idx, file_idx = update_chunk_file_indices(chunk_idx, file_idx, self.chunks_size)
-                    self._close_writer()
-
-            # Update the existing pandas dataframe with new row
-            episode_dict["meta/episodes/chunk_index"] = [chunk_idx]
-            episode_dict["meta/episodes/file_index"] = [file_idx]
-            episode_dict["dataset_from_index"] = [self.latest_episode["dataset_to_index"][0]]
-            episode_dict["dataset_to_index"] = [self.latest_episode["dataset_to_index"][0] + num_frames]
-
-        # Add to buffer
-        self._metadata_buffer.append(episode_dict)
-        self.latest_episode = episode_dict
-
-        if len(self._metadata_buffer) >= self._metadata_buffer_size:
-            self._flush_metadata_buffer()
-
-    def save_episode(
-        self,
-        episode_index: int,
-        episode_length: int,
-        episode_tasks: list[str],
-        episode_stats: dict[str, dict],
-        episode_metadata: dict,
-    ) -> None:
-        """Persist episode metadata, update dataset info, and aggregate stats.
-
-        Writes the episode's metadata to the buffered parquet writer, increments
-        the total episode/frame counters in ``info.json``, and merges the
-        episode's statistics into the running dataset statistics.
-
-        Args:
-            episode_index: Zero-based index of the episode being saved.
-            episode_length: Number of frames in this episode.
-            episode_tasks: List of task descriptions for this episode.
-            episode_stats: Per-feature statistics for this episode.
-            episode_metadata: Additional metadata (chunk/file indices, frame
-                ranges, video timestamps, etc.).
-        """
-        episode_dict = {
-            "episode_index": episode_index,
-            "tasks": episode_tasks,
-            "length": episode_length,
-        }
-        episode_dict.update(episode_metadata)
-        episode_dict.update(flatten_dict({"stats": episode_stats}))
-        self._save_episode_metadata(episode_dict)
-
-        # Update info
-        self.info["total_episodes"] += 1
-        self.info["total_frames"] += episode_length
-        self.info["total_tasks"] = len(self.tasks)
-        self.info["splits"] = {"train": f"0:{self.info['total_episodes']}"}
-
-        write_info(self.info, self.root)
-
-        self.stats = aggregate_stats([self.stats, episode_stats]) if self.stats is not None else episode_stats
-        write_stats(self.stats, self.root)
-
-    def update_video_info(self, video_key: str | None = None) -> None:
-        """
-        Warning: this function writes info from first episode videos, implicitly assuming that all videos have
-        been encoded the same way. Also, this means it assumes the first episode exists.
-        """
-        if video_key is not None and video_key not in self.video_keys:
-            raise ValueError(f"Video key {video_key} not found in dataset")
-
-        video_keys = [video_key] if video_key is not None else self.video_keys
-        for key in video_keys:
-            if not self.features[key].get("info", None):
-                video_path = self.root / self.video_path.format(video_key=key, chunk_index=0, file_index=0)
-                self.info["features"][key]["info"] = get_video_info(video_path)
-
-    def update_chunk_settings(
-        self,
-        chunks_size: int | None = None,
-        data_files_size_in_mb: int | None = None,
-        video_files_size_in_mb: int | None = None,
-    ) -> None:
-        """Update chunk and file size settings after dataset creation.
-
-        This allows users to customize storage organization without modifying the constructor.
-        These settings control how episodes are chunked and how large files can grow before
-        creating new ones.
-
-        Args:
-            chunks_size: Maximum number of files per chunk directory. If None, keeps current value.
-            data_files_size_in_mb: Maximum size for data parquet files in MB. If None, keeps current value.
-            video_files_size_in_mb: Maximum size for video files in MB. If None, keeps current value.
-        """
-        if chunks_size is not None:
-            if chunks_size <= 0:
-                raise ValueError(f"chunks_size must be positive, got {chunks_size}")
-            self.info["chunks_size"] = chunks_size
-
-        if data_files_size_in_mb is not None:
-            if data_files_size_in_mb <= 0:
-                raise ValueError(f"data_files_size_in_mb must be positive, got {data_files_size_in_mb}")
-            self.info["data_files_size_in_mb"] = data_files_size_in_mb
-
-        if video_files_size_in_mb is not None:
-            if video_files_size_in_mb <= 0:
-                raise ValueError(f"video_files_size_in_mb must be positive, got {video_files_size_in_mb}")
-            self.info["video_files_size_in_mb"] = video_files_size_in_mb
-
-        # Update the info file on disk
-        write_info(self.info, self.root)
-
-    def get_chunk_settings(self) -> dict[str, int]:
-        """Get current chunk and file size settings.
-
-        Returns:
-            Dict containing chunks_size, data_files_size_in_mb, and video_files_size_in_mb.
-        """
-        return {
-            "chunks_size": self.chunks_size,
-            "data_files_size_in_mb": self.data_files_size_in_mb,
-            "video_files_size_in_mb": self.video_files_size_in_mb,
-        }
-
-    def __repr__(self):
-        feature_keys = list(self.features)
-        return (
-            f"{self.__class__.__name__}({{\n"
-            f"    Repository ID: '{self.repo_id}',\n"
-            f"    Total episodes: '{self.total_episodes}',\n"
-            f"    Total frames: '{self.total_frames}',\n"
-            f"    Features: '{feature_keys}',\n"
-            "})',\n"
-        )
-
-    @classmethod
-    def create(
-        cls,
-        repo_id: str,
-        fps: int,
-        features: dict,
-        robot_type: str | None = None,
-        root: str | Path | None = None,
-        use_videos: bool = True,
-        metadata_buffer_size: int = 10,
-        chunks_size: int | None = None,
-        data_files_size_in_mb: int | None = None,
-        video_files_size_in_mb: int | None = None,
-    ) -> "LeRobotDatasetMetadata":
-        """Create metadata for a new LeRobot dataset from scratch.
-
-        Initializes the ``info.json`` file on disk with the provided feature
-        schema and dataset settings. No episode data is written yet.
-
-        Args:
-            repo_id: Repository identifier (e.g. ``'user/my_dataset'``).
-            fps: Frames per second used during data collection.
-            features: Feature specification dict mapping feature names to their
-                type/shape metadata.
-            robot_type: Optional robot type string stored in metadata.
-            root: Local directory for the dataset. Defaults to
-                ``$HF_LEROBOT_HOME/{repo_id}``. Must not already exist.
-            use_videos: If ``True``, visual modalities are encoded as MP4 videos.
-            metadata_buffer_size: Number of episode metadata records to buffer
-                before flushing to parquet.
-            chunks_size: Max number of files per chunk directory. ``None`` uses
-                the default.
-            data_files_size_in_mb: Max parquet file size in MB. ``None`` uses the
-                default.
-            video_files_size_in_mb: Max video file size in MB. ``None`` uses the
-                default.
-
-        Returns:
-            A new :class:`LeRobotDatasetMetadata` instance.
-        """
-        obj = cls.__new__(cls)
-        obj.repo_id = repo_id
-        obj._requested_root = Path(root) if root is not None else None
-        obj.root = obj._requested_root if obj._requested_root is not None else HF_LEROBOT_HOME / repo_id
-
-        obj.root.mkdir(parents=True, exist_ok=False)
-
-        features = {**features, **DEFAULT_FEATURES}
-        _validate_feature_names(features)
-
-        obj.tasks = None
-        obj.subtasks = None
-        obj.episodes = None
-        obj.stats = None
-        obj.info = create_empty_dataset_info(
-            CODEBASE_VERSION,
-            fps,
-            features,
-            use_videos,
-            robot_type,
-            chunks_size,
-            data_files_size_in_mb,
-            video_files_size_in_mb,
-        )
-        if len(obj.video_keys) > 0 and not use_videos:
-            raise ValueError(
-                f"Features contain video keys {obj.video_keys}, but 'use_videos' is set to False. "
-                "Either remove video features from the features dict, or set 'use_videos=True'."
-            )
-        write_json(obj.info, obj.root / INFO_PATH)
-        obj.revision = None
-        obj._pq_writer = None
-        obj.latest_episode = None
-        obj._metadata_buffer = []
-        obj._metadata_buffer_size = metadata_buffer_size
-        obj._finalized = False
-        return obj

src/lerobot/datasets/dataset_reader.py

@@ -1,288 +0,0 @@
-#!/usr/bin/env python
-
-# Copyright 2024 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.
-"""Private reader component for LeRobotDataset. Handles random-access reading (HF dataset, delta indices, video decoding)."""
-
-from collections.abc import Callable
-from pathlib import Path
-
-import datasets
-import torch
-
-from lerobot.datasets.dataset_metadata import LeRobotDatasetMetadata
-from lerobot.datasets.feature_utils import (
-    check_delta_timestamps,
-    get_delta_indices,
-    get_hf_features_from_features,
-)
-from lerobot.datasets.io_utils import (
-    hf_transform_to_torch,
-    load_nested_dataset,
-)
-from lerobot.datasets.video_utils import decode_video_frames
-
-
-class DatasetReader:
-    """Encapsulates read-side state and methods for LeRobotDataset.
-
-    Owns: hf_dataset, _absolute_to_relative_idx, delta_indices.
-    """
-
-    def __init__(
-        self,
-        meta: LeRobotDatasetMetadata,
-        root: Path,
-        episodes: list[int] | None,
-        tolerance_s: float,
-        video_backend: str,
-        delta_timestamps: dict[str, list[float]] | None,
-        image_transforms: Callable | None,
-    ):
-        """Initialize the reader with metadata, filtering, and transform config.
-
-        The HF dataset is not loaded here — call :meth:`try_load` or
-        :meth:`load_and_activate` afterward.
-
-        Args:
-            meta: Dataset metadata instance.
-            root: Local dataset root directory.
-            episodes: Optional list of episode indices to select. ``None``
-                means all episodes.
-            tolerance_s: Timestamp synchronization tolerance in seconds.
-            video_backend: Video decoding backend identifier.
-            delta_timestamps: Optional dict mapping feature keys to lists of
-                relative timestamp offsets for temporal context windows.
-            image_transforms: Optional torchvision v2 transform applied to
-                visual features.
-        """
-        self._meta = meta
-        self.root = root
-        self.episodes = episodes
-        self._tolerance_s = tolerance_s
-        self._video_backend = video_backend
-        self._image_transforms = image_transforms
-
-        self.hf_dataset: datasets.Dataset | None = None
-        self._absolute_to_relative_idx: dict[int, int] | None = None
-
-        # Setup delta_indices (doesn't depend on hf_dataset)
-        self.delta_indices = None
-        if delta_timestamps is not None:
-            check_delta_timestamps(delta_timestamps, meta.fps, tolerance_s)
-            self.delta_indices = get_delta_indices(delta_timestamps, meta.fps)
-
-    def try_load(self) -> bool:
-        """Attempt to load from local cache. Returns True if data is sufficient."""
-        try:
-            self.hf_dataset = self._load_hf_dataset()
-        except (FileNotFoundError, NotADirectoryError):
-            self.hf_dataset = None
-            return False
-        if not self._check_cached_episodes_sufficient():
-            self.hf_dataset = None
-            return False
-        self._build_index_mapping()
-        return True
-
-    def load_and_activate(self) -> None:
-        """Load HF dataset from disk and build index mapping. Call after data is on disk."""
-        self.hf_dataset = self._load_hf_dataset()
-        self._build_index_mapping()
-
-    def _build_index_mapping(self) -> None:
-        """Build absolute-to-relative index mapping from loaded hf_dataset."""
-        self._absolute_to_relative_idx = None
-        if self.episodes is not None and self.hf_dataset is not None:
-            self._absolute_to_relative_idx = {
-                abs_idx.item() if isinstance(abs_idx, torch.Tensor) else abs_idx: rel_idx
-                for rel_idx, abs_idx in enumerate(self.hf_dataset["index"])
-            }
-
-    @property
-    def num_frames(self) -> int:
-        """Number of frames in selected episodes."""
-        if self.episodes is not None and self.hf_dataset is not None:
-            return len(self.hf_dataset)
-        return self._meta.total_frames
-
-    @property
-    def num_episodes(self) -> int:
-        """Number of episodes selected."""
-        return len(self.episodes) if self.episodes is not None else self._meta.total_episodes
-
-    def _load_hf_dataset(self) -> datasets.Dataset:
-        """hf_dataset contains all the observations, states, actions, rewards, etc."""
-        features = get_hf_features_from_features(self._meta.features)
-        hf_dataset = load_nested_dataset(self.root / "data", features=features, episodes=self.episodes)
-        hf_dataset.set_transform(hf_transform_to_torch)
-        return hf_dataset
-
-    def _check_cached_episodes_sufficient(self) -> bool:
-        """Check if the cached dataset contains all requested episodes and their video files."""
-        if self.hf_dataset is None or len(self.hf_dataset) == 0:
-            return False
-
-        available_episodes = {
-            ep_idx.item() if isinstance(ep_idx, torch.Tensor) else ep_idx
-            for ep_idx in self.hf_dataset.unique("episode_index")
-        }
-
-        if self.episodes is None:
-            requested_episodes = set(range(self._meta.total_episodes))
-        else:
-            requested_episodes = set(self.episodes)
-
-        if not requested_episodes.issubset(available_episodes):
-            return False
-
-        if len(self._meta.video_keys) > 0:
-            for ep_idx in requested_episodes:
-                for vid_key in self._meta.video_keys:
-                    video_path = self.root / self._meta.get_video_file_path(ep_idx, vid_key)
-                    if not video_path.exists():
-                        return False
-
-        return True
-
-    def get_episodes_file_paths(self) -> list[Path]:
-        """Return deduplicated file paths (data + video) for selected episodes.
-
-        Used to build the ``allow_patterns`` list for ``snapshot_download``.
-        """
-        episodes = self.episodes if self.episodes is not None else list(range(self._meta.total_episodes))
-        fpaths = [str(self._meta.get_data_file_path(ep_idx)) for ep_idx in episodes]
-        if len(self._meta.video_keys) > 0:
-            video_files = [
-                str(self._meta.get_video_file_path(ep_idx, vid_key))
-                for vid_key in self._meta.video_keys
-                for ep_idx in episodes
-            ]
-            fpaths += video_files
-        # episodes are stored in the same files, so we return unique paths only
-        fpaths = list(set(fpaths))
-        return fpaths
-
-    def _get_query_indices(
-        self, abs_idx: int, ep_idx: int
-    ) -> tuple[dict[str, list[int]], dict[str, torch.Tensor]]:
-        """Compute query indices for delta timestamps."""
-        ep = self._meta.episodes[ep_idx]
-        ep_start = ep["dataset_from_index"]
-        ep_end = ep["dataset_to_index"]
-        query_indices = {
-            key: [max(ep_start, min(ep_end - 1, abs_idx + delta)) for delta in delta_idx]
-            for key, delta_idx in self.delta_indices.items()
-        }
-        padding = {
-            f"{key}_is_pad": torch.BoolTensor(
-                [(abs_idx + delta < ep_start) | (abs_idx + delta >= ep_end) for delta in delta_idx]
-            )
-            for key, delta_idx in self.delta_indices.items()
-        }
-        return query_indices, padding
-
-    def _get_query_timestamps(
-        self,
-        current_ts: float,
-        query_indices: dict[str, list[int]] | None = None,
-    ) -> dict[str, list[float]]:
-        query_timestamps = {}
-        for key in self._meta.video_keys:
-            if query_indices is not None and key in query_indices:
-                if self._absolute_to_relative_idx is not None:
-                    relative_indices = [self._absolute_to_relative_idx[idx] for idx in query_indices[key]]
-                    timestamps = self.hf_dataset[relative_indices]["timestamp"]
-                else:
-                    timestamps = self.hf_dataset[query_indices[key]]["timestamp"]
-                query_timestamps[key] = torch.stack(timestamps).tolist()
-            else:
-                query_timestamps[key] = [current_ts]
-
-        return query_timestamps
-
-    def _query_hf_dataset(self, query_indices: dict[str, list[int]]) -> dict:
-        """Query dataset for indices across keys, skipping video keys."""
-        result: dict = {}
-        for key, q_idx in query_indices.items():
-            if key in self._meta.video_keys:
-                continue
-            relative_indices = (
-                q_idx
-                if self._absolute_to_relative_idx is None
-                else [self._absolute_to_relative_idx[idx] for idx in q_idx]
-            )
-            try:
-                result[key] = torch.stack(self.hf_dataset[key][relative_indices])
-            except (KeyError, TypeError, IndexError):
-                result[key] = torch.stack(self.hf_dataset[relative_indices][key])
-        return result
-
-    def _query_videos(self, query_timestamps: dict[str, list[float]], ep_idx: int) -> dict[str, torch.Tensor]:
-        """Note: When using data workers (e.g. DataLoader with num_workers>0), do not call this function
-        in the main process (e.g. by using a second Dataloader with num_workers=0). It will result in a
-        Segmentation Fault.
-        """
-        ep = self._meta.episodes[ep_idx]
-        item = {}
-        for vid_key, query_ts in query_timestamps.items():
-            from_timestamp = ep[f"videos/{vid_key}/from_timestamp"]
-            shifted_query_ts = [from_timestamp + ts for ts in query_ts]
-
-            video_path = self.root / self._meta.get_video_file_path(ep_idx, vid_key)
-            frames = decode_video_frames(video_path, shifted_query_ts, self._tolerance_s, self._video_backend)
-            item[vid_key] = frames.squeeze(0)
-
-        return item
-
-    def get_item(self, idx) -> dict:
-        """Core __getitem__ logic. Assumes hf_dataset is loaded.
-
-        ``idx`` is a *relative* index into the (possibly episode-filtered)
-        HF dataset, **not** the absolute frame index stored in the ``index``
-        column.  The absolute index is retrieved from the row itself.
-        """
-        item = self.hf_dataset[idx]
-        ep_idx = item["episode_index"].item()
-        abs_idx = item["index"].item()
-
-        query_indices = None
-        if self.delta_indices is not None:
-            query_indices, padding = self._get_query_indices(abs_idx, ep_idx)
-            query_result = self._query_hf_dataset(query_indices)
-            item = {**item, **padding}
-            for key, val in query_result.items():
-                item[key] = val
-
-        if len(self._meta.video_keys) > 0:
-            current_ts = item["timestamp"].item()
-            query_timestamps = self._get_query_timestamps(current_ts, query_indices)
-            video_frames = self._query_videos(query_timestamps, ep_idx)
-            item = {**video_frames, **item}
-
-        if self._image_transforms is not None:
-            image_keys = self._meta.camera_keys
-            for cam in image_keys:
-                item[cam] = self._image_transforms(item[cam])
-
-        # Add task as a string
-        task_idx = item["task_index"].item()
-        item["task"] = self._meta.tasks.iloc[task_idx].name
-
-        # add subtask information if available
-        if "subtask_index" in self._meta.features and self._meta.subtasks is not None:
-            subtask_idx = item["subtask_index"].item()
-            item["subtask"] = self._meta.subtasks.iloc[subtask_idx].name
-
-        return item

src/lerobot/datasets/dataset_tools.py

@@ -37,31 +37,23 @@ import torch
 from tqdm import tqdm
 
 from lerobot.datasets.aggregate import aggregate_datasets
-from lerobot.datasets.compute_stats import (
-    aggregate_stats,
-    compute_episode_stats,
-    compute_relative_action_stats,
-    compute_relative_state_stats,
-)
-from lerobot.datasets.dataset_metadata import LeRobotDatasetMetadata
-from lerobot.datasets.io_utils import (
-    get_parquet_file_size_in_mb,
-    load_episodes,
-    write_info,
-    write_stats,
-    write_tasks,
-)
-from lerobot.datasets.lerobot_dataset import LeRobotDataset
+from lerobot.datasets.compute_stats import aggregate_stats
+from lerobot.datasets.lerobot_dataset import LeRobotDataset, LeRobotDatasetMetadata
 from lerobot.datasets.utils import (
     DATA_DIR,
     DEFAULT_CHUNK_SIZE,
     DEFAULT_DATA_FILE_SIZE_IN_MB,
     DEFAULT_DATA_PATH,
     DEFAULT_EPISODES_PATH,
+    get_parquet_file_size_in_mb,
+    load_episodes,
     update_chunk_file_indices,
+    write_info,
+    write_stats,
+    write_tasks,
 )
 from lerobot.datasets.video_utils import encode_video_frames, get_video_info
-from lerobot.utils.constants import ACTION, HF_LEROBOT_HOME, OBS_IMAGE, OBS_STATE
+from lerobot.utils.constants import HF_LEROBOT_HOME, OBS_IMAGE
 
 
 def _load_episode_with_stats(src_dataset: LeRobotDataset, episode_idx: int) -> dict:
@@ -896,7 +888,7 @@ def _copy_and_reindex_episodes_metadata(
 
         total_frames += src_episode["length"]
 
-    dst_meta.finalize()
+    dst_meta._close_writer()
 
     dst_meta.info.update(
         {
@@ -923,8 +915,7 @@ def _write_parquet(df: pd.DataFrame, path: Path, meta: LeRobotDatasetMetadata) -
 
     This ensures images are properly embedded and the file can be loaded correctly by HF datasets.
     """
-    from lerobot.datasets.feature_utils import get_hf_features_from_features
-    from lerobot.datasets.io_utils import embed_images
+    from lerobot.datasets.utils import embed_images, get_hf_features_from_features
 
     hf_features = get_hf_features_from_features(meta.features)
     ep_dataset = datasets.Dataset.from_dict(df.to_dict(orient="list"), features=hf_features, split="train")
@@ -1538,147 +1529,6 @@ def modify_tasks(
     return dataset
 
 
-def recompute_stats(
-    dataset: LeRobotDataset,
-    skip_image_video: bool = True,
-    relative_action: bool = False,
-    relative_exclude_joints: list[str] | None = None,
-    chunk_size: int = 50,
-    num_workers: int = 0,
-    relative_state: bool = False,
-    relative_exclude_state_joints: list[str] | None = None,
-    state_obs_steps: int = 2,
-    derive_state_from_action: bool = False,
-) -> LeRobotDataset:
-    """Recompute stats.json from scratch by iterating all episodes.
-
-    Args:
-        dataset: The LeRobotDataset to recompute stats for.
-        skip_image_video: If True (default), only recompute stats for numeric features
-            (action, state, etc.) and keep existing image/video stats unchanged.
-        relative_action: If True, compute action stats in relative space by
-            iterating all valid action chunks and subtracting the current state.
-            This matches the normalization distribution the model sees during
-            training with ``use_relative_actions=True``.
-        relative_exclude_joints: Joint names to exclude from relative conversion when
-            relative_action=True. These dims keep absolute stats.
-        chunk_size: Action chunk size used for relative stats computation. Should match
-            ``policy.chunk_size``. Only used when ``relative_action=True``.
-        num_workers: Number of parallel threads for relative action stats computation.
-            Values ≤1 mean single-threaded. Only used when ``relative_action=True``.
-        relative_state: If True, compute observation.state stats in relative space
-            (multi-timestep offsets from current). This matches the normalization
-            the model sees during training with ``use_relative_state=True``.
-        relative_exclude_state_joints: State dim names to exclude from relative conversion.
-        state_obs_steps: Number of observation timesteps for relative state stats.
-            Should match ``policy.state_obs_steps``. Only used when ``relative_state=True``.
-        derive_state_from_action: If True, compute relative state stats from the
-            action column instead of observation.state. Implies ``relative_state=True``
-            and ``state_obs_steps=2``.
-
-    Returns:
-        The same dataset with updated stats.
-    """
-    if derive_state_from_action:
-        relative_state = True
-        state_obs_steps = 2
-    features = dataset.meta.features
-    meta_keys = {"index", "episode_index", "task_index", "frame_index", "timestamp"}
-    numeric_features = {
-        k: v
-        for k, v in features.items()
-        if v["dtype"] not in ["image", "video", "string"] and k not in meta_keys
-    }
-
-    if skip_image_video:
-        features_to_compute = numeric_features
-    else:
-        features_to_compute = {
-            k: v for k, v in features.items() if v["dtype"] != "string" and k not in meta_keys
-        }
-
-    # When relative_action is enabled, compute action stats via chunk-based sampling
-    # (matching what the model sees during training) and skip action in the
-    # per-episode pass below.
-    relative_action_stats = None
-    if relative_action and ACTION in features and OBS_STATE in features:
-        if relative_exclude_joints is None:
-            relative_exclude_joints = ["gripper"]
-        relative_action_stats = compute_relative_action_stats(
-            hf_dataset=dataset.hf_dataset,
-            features=features,
-            chunk_size=chunk_size,
-            exclude_joints=relative_exclude_joints,
-            num_workers=num_workers,
-        )
-        features_to_compute.pop(ACTION, None)
-
-    # When relative_state is enabled, compute state stats over the flattened
-    # multi-timestep relative representation (matching what the model sees).
-    relative_state_stats = None
-    if relative_state and (OBS_STATE in features or derive_state_from_action):
-        source_key = ACTION if derive_state_from_action else OBS_STATE
-        relative_state_stats = compute_relative_state_stats(
-            hf_dataset=dataset.hf_dataset,
-            features=features,
-            state_obs_steps=state_obs_steps,
-            exclude_joints=relative_exclude_state_joints,
-            source_key=source_key,
-        )
-        features_to_compute.pop(OBS_STATE, None)
-
-    logging.info(f"Recomputing stats for features: {list(features_to_compute.keys())}")
-
-    data_dir = dataset.root / DATA_DIR
-    parquet_files = sorted(data_dir.glob("*/*.parquet"))
-    if not parquet_files:
-        raise ValueError(f"No parquet files found in {data_dir}")
-
-    all_episode_stats = []
-    numeric_keys = [k for k, v in features_to_compute.items() if v["dtype"] not in ["image", "video"]]
-
-    for parquet_path in tqdm(parquet_files, desc="Computing stats from data files"):
-        df = pd.read_parquet(parquet_path)
-
-        for ep_idx in sorted(df["episode_index"].unique()):
-            ep_df = df[df["episode_index"] == ep_idx]
-            episode_data = {}
-            for key in numeric_keys:
-                if key in ep_df.columns:
-                    values = ep_df[key].values
-                    if hasattr(values[0], "__len__"):
-                        episode_data[key] = np.stack(values)
-                    else:
-                        episode_data[key] = np.array(values)
-
-            ep_stats = compute_episode_stats(episode_data, features_to_compute)
-            all_episode_stats.append(ep_stats)
-
-    if features_to_compute and not all_episode_stats:
-        logging.warning("No episode stats computed")
-        return dataset
-
-    new_stats = aggregate_stats(all_episode_stats) if all_episode_stats else {}
-
-    if relative_action_stats is not None:
-        new_stats[ACTION] = relative_action_stats
-
-    if relative_state_stats is not None:
-        new_stats[OBS_STATE] = relative_state_stats
-
-    # Merge: keep existing stats for features we didn't recompute
-    if dataset.meta.stats:
-        for key, value in dataset.meta.stats.items():
-            if key not in new_stats:
-                new_stats[key] = value
-
-    write_stats(new_stats, dataset.root)
-    dataset.meta.stats = new_stats
-
-    logging.info("Stats recomputed successfully")
-    return dataset
-
-
 def convert_image_to_video_dataset(
     dataset: LeRobotDataset,
     output_dir: Path | None = None,

src/lerobot/datasets/dataset_writer.py

@@ -1,634 +0,0 @@
-#!/usr/bin/env python
-
-# Copyright 2024 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.
-"""Private writer component for LeRobotDataset. Handles sequential recording (episode buffer, ParquetWriter, image writer, video encoding)."""
-
-from __future__ import annotations
-
-import concurrent.futures
-import contextlib
-import logging
-import shutil
-import tempfile
-from pathlib import Path
-
-import datasets
-import numpy as np
-import pandas as pd
-import PIL.Image
-import pyarrow.parquet as pq
-import torch
-
-from lerobot.datasets.compute_stats import compute_episode_stats
-from lerobot.datasets.dataset_metadata import LeRobotDatasetMetadata
-from lerobot.datasets.feature_utils import (
-    get_hf_features_from_features,
-    validate_episode_buffer,
-    validate_frame,
-)
-from lerobot.datasets.image_writer import AsyncImageWriter, write_image
-from lerobot.datasets.io_utils import (
-    embed_images,
-    get_file_size_in_mb,
-    load_episodes,
-    write_info,
-)
-from lerobot.datasets.utils import (
-    DEFAULT_EPISODES_PATH,
-    DEFAULT_IMAGE_PATH,
-    update_chunk_file_indices,
-)
-from lerobot.datasets.video_utils import (
-    StreamingVideoEncoder,
-    concatenate_video_files,
-    encode_video_frames,
-    get_video_duration_in_s,
-)
-
-logger = logging.getLogger(__name__)
-
-
-def _encode_video_worker(
-    video_key: str,
-    episode_index: int,
-    root: Path,
-    fps: int,
-    vcodec: str = "libsvtav1",
-    encoder_threads: int | None = None,
-) -> Path:
-    temp_path = Path(tempfile.mkdtemp(dir=root)) / f"{video_key}_{episode_index:03d}.mp4"
-    fpath = DEFAULT_IMAGE_PATH.format(image_key=video_key, episode_index=episode_index, frame_index=0)
-    img_dir = (root / fpath).parent
-    encode_video_frames(
-        img_dir, temp_path, fps, vcodec=vcodec, overwrite=True, encoder_threads=encoder_threads
-    )
-    shutil.rmtree(img_dir)
-    return temp_path
-
-
-class DatasetWriter:
-    """Encapsulates write-side state and methods for LeRobotDataset.
-
-    Owns: episode_buffer, image_writer, _pq_writer (ParquetWriter), _latest_episode,
-    _current_file_start_frame, _streaming_encoder, _episodes_since_last_encoding, _recorded_frames.
-    """
-
-    def __init__(
-        self,
-        meta: LeRobotDatasetMetadata,
-        root: Path,
-        vcodec: str,
-        encoder_threads: int | None,
-        batch_encoding_size: int,
-        streaming_encoder: StreamingVideoEncoder | None = None,
-        initial_frames: int = 0,
-    ):
-        """Initialize the writer with metadata, codec, and encoding config.
-
-        Args:
-            meta: Dataset metadata instance (used for feature schema, chunk
-                settings, and episode persistence).
-            root: Local dataset root directory.
-            vcodec: Video codec for encoding (e.g. ``'libsvtav1'``, ``'h264'``).
-            encoder_threads: Threads per encoder instance. ``None`` for auto.
-            batch_encoding_size: Number of episodes to accumulate before
-                batch-encoding videos.
-            streaming_encoder: Optional pre-built :class:`StreamingVideoEncoder`
-                for real-time encoding. ``None`` disables streaming mode.
-            initial_frames: Starting frame count (non-zero when resuming).
-        """
-        self._meta = meta
-        self._root = root
-        self._vcodec = vcodec
-        self._encoder_threads = encoder_threads
-        self._batch_encoding_size = batch_encoding_size
-        self._streaming_encoder = streaming_encoder
-
-        # Writer state
-        self.image_writer: AsyncImageWriter | None = None
-        self.episode_buffer: dict = self._create_episode_buffer()
-        self._pq_writer: pq.ParquetWriter | None = None
-        self._latest_episode: dict | None = None
-        self._current_file_start_frame: int | None = None
-        self._episodes_since_last_encoding: int = 0
-        self._recorded_frames: int = initial_frames
-        self._finalized = False
-
-    def _create_episode_buffer(self, episode_index: int | None = None) -> dict:
-        current_ep_idx = self._meta.total_episodes if episode_index is None else episode_index
-        ep_buffer = {}
-        ep_buffer["size"] = 0
-        ep_buffer["task"] = []
-        for key in self._meta.features:
-            ep_buffer[key] = current_ep_idx if key == "episode_index" else []
-        return ep_buffer
-
-    def _get_image_file_path(self, episode_index: int, image_key: str, frame_index: int) -> Path:
-        fpath = DEFAULT_IMAGE_PATH.format(
-            image_key=image_key, episode_index=episode_index, frame_index=frame_index
-        )
-        return self._root / fpath
-
-    def _get_image_file_dir(self, episode_index: int, image_key: str) -> Path:
-        return self._get_image_file_path(episode_index, image_key, frame_index=0).parent
-
-    def _save_image(
-        self, image: torch.Tensor | np.ndarray | PIL.Image.Image, fpath: Path, compress_level: int = 1
-    ) -> None:
-        if self.image_writer is None:
-            if isinstance(image, torch.Tensor):
-                image = image.cpu().numpy()
-            write_image(image, fpath, compress_level=compress_level)
-        else:
-            self.image_writer.save_image(image=image, fpath=fpath, compress_level=compress_level)
-
-    def add_frame(self, frame: dict) -> None:
-        """
-        Add a single frame to the current episode buffer.
-
-        Apart from images written to a temporary directory, nothing is written to disk
-        until ``save_episode()`` is called.
-
-        The caller must provide all user-defined features plus ``"task"``, and must
-        not provide ``"timestamp"`` or ``"frame_index"``; those are computed
-        automatically.
-        """
-        # Convert torch to numpy if needed
-        for name in frame:
-            if isinstance(frame[name], torch.Tensor):
-                frame[name] = frame[name].numpy()
-
-        validate_frame(frame, self._meta.features)
-
-        if self.episode_buffer is None:
-            self.episode_buffer = self._create_episode_buffer()
-
-        # Automatically add frame_index and timestamp to episode buffer
-        frame_index = self.episode_buffer["size"]
-        timestamp = frame_index / self._meta.fps
-        self.episode_buffer["frame_index"].append(frame_index)
-        self.episode_buffer["timestamp"].append(timestamp)
-        self.episode_buffer["task"].append(frame.pop("task"))
-
-        # Start streaming encoder on first frame of episode
-        if frame_index == 0 and self._streaming_encoder is not None:
-            self._streaming_encoder.start_episode(
-                video_keys=list(self._meta.video_keys),
-                temp_dir=self._root,
-            )
-
-        # Add frame features to episode_buffer
-        for key in frame:
-            if key not in self._meta.features:
-                raise ValueError(
-                    f"An element of the frame is not in the features. '{key}' not in '{self._meta.features.keys()}'."
-                )
-
-            if self._meta.features[key]["dtype"] == "video" and self._streaming_encoder is not None:
-                self._streaming_encoder.feed_frame(key, frame[key])
-                self.episode_buffer[key].append(None)
-            elif self._meta.features[key]["dtype"] in ["image", "video"]:
-                img_path = self._get_image_file_path(
-                    episode_index=self.episode_buffer["episode_index"], image_key=key, frame_index=frame_index
-                )
-                if frame_index == 0:
-                    img_path.parent.mkdir(parents=True, exist_ok=True)
-                compress_level = 1 if self._meta.features[key]["dtype"] == "video" else 6
-                self._save_image(frame[key], img_path, compress_level)
-                self.episode_buffer[key].append(str(img_path))
-            else:
-                self.episode_buffer[key].append(frame[key])
-
-        self.episode_buffer["size"] += 1
-
-    def save_episode(
-        self,
-        episode_data: dict | None = None,
-        parallel_encoding: bool = True,
-    ) -> None:
-        """Save the current episode in self.episode_buffer to disk."""
-        episode_buffer = episode_data if episode_data is not None else self.episode_buffer
-
-        validate_episode_buffer(episode_buffer, self._meta.total_episodes, self._meta.features)
-
-        # size and task are special cases that won't be added to hf_dataset
-        episode_length = episode_buffer.pop("size")
-        tasks = episode_buffer.pop("task")
-        episode_tasks = list(set(tasks))
-        episode_index = episode_buffer["episode_index"]
-
-        episode_buffer["index"] = np.arange(self._meta.total_frames, self._meta.total_frames + episode_length)
-        episode_buffer["episode_index"] = np.full((episode_length,), episode_index)
-
-        # Update tasks and task indices with new tasks if any
-        self._meta.save_episode_tasks(episode_tasks)
-
-        # Given tasks in natural language, find their corresponding task indices
-        episode_buffer["task_index"] = np.array([self._meta.get_task_index(task) for task in tasks])
-
-        for key, ft in self._meta.features.items():
-            if key in ["index", "episode_index", "task_index"] or ft["dtype"] in ["image", "video"]:
-                continue
-            episode_buffer[key] = np.stack(episode_buffer[key])
-
-        # Wait for image writer to end, so that episode stats over images can be computed
-        self._wait_image_writer()
-
-        has_video_keys = len(self._meta.video_keys) > 0
-        use_streaming = self._streaming_encoder is not None and has_video_keys
-        use_batched_encoding = self._batch_encoding_size > 1
-
-        if use_streaming:
-            non_video_buffer = {
-                k: v
-                for k, v in episode_buffer.items()
-                if self._meta.features.get(k, {}).get("dtype") not in ("video",)
-            }
-            non_video_features = {k: v for k, v in self._meta.features.items() if v["dtype"] != "video"}
-            ep_stats = compute_episode_stats(non_video_buffer, non_video_features)
-        else:
-            ep_stats = compute_episode_stats(episode_buffer, self._meta.features)
-
-        ep_metadata = self._save_episode_data(episode_buffer)
-
-        if use_streaming:
-            streaming_results = self._streaming_encoder.finish_episode()
-            for video_key in self._meta.video_keys:
-                temp_path, video_stats = streaming_results[video_key]
-                if video_stats is not None:
-                    ep_stats[video_key] = {
-                        k: v if k == "count" else np.squeeze(v.reshape(1, -1, 1, 1) / 255.0, axis=0)
-                        for k, v in video_stats.items()
-                    }
-                ep_metadata.update(self._save_episode_video(video_key, episode_index, temp_path=temp_path))
-        elif has_video_keys and not use_batched_encoding:
-            num_cameras = len(self._meta.video_keys)
-            if parallel_encoding and num_cameras > 1:
-                with concurrent.futures.ProcessPoolExecutor(max_workers=num_cameras) as executor:
-                    future_to_key = {
-                        executor.submit(
-                            _encode_video_worker,
-                            video_key,
-                            episode_index,
-                            self._root,
-                            self._meta.fps,
-                            self._vcodec,
-                            self._encoder_threads,
-                        ): video_key
-                        for video_key in self._meta.video_keys
-                    }
-
-                    results = {}
-                    for future in concurrent.futures.as_completed(future_to_key):
-                        video_key = future_to_key[future]
-                        try:
-                            temp_path = future.result()
-                            results[video_key] = temp_path
-                        except Exception as exc:
-                            logger.error(f"Video encoding failed for {video_key}: {exc}")
-                            raise exc
-
-                for video_key in self._meta.video_keys:
-                    temp_path = results[video_key]
-                    ep_metadata.update(
-                        self._save_episode_video(video_key, episode_index, temp_path=temp_path)
-                    )
-            else:
-                for video_key in self._meta.video_keys:
-                    ep_metadata.update(self._save_episode_video(video_key, episode_index))
-
-        # `meta.save_episode` need to be executed after encoding the videos
-        self._meta.save_episode(episode_index, episode_length, episode_tasks, ep_stats, ep_metadata)
-
-        if has_video_keys and use_batched_encoding:
-            self._episodes_since_last_encoding += 1
-            if self._episodes_since_last_encoding == self._batch_encoding_size:
-                start_ep = self._meta.total_episodes - self._batch_encoding_size
-                end_ep = self._meta.total_episodes
-                self._batch_save_episode_video(start_ep, end_ep)
-                self._episodes_since_last_encoding = 0
-
-        if episode_data is None:
-            self.clear_episode_buffer(delete_images=len(self._meta.image_keys) > 0)
-
-    def _batch_save_episode_video(self, start_episode: int, end_episode: int | None = None) -> None:
-        """Batch save videos for multiple episodes."""
-        if end_episode is None:
-            end_episode = self._meta.total_episodes
-
-        logger.info(
-            f"Batch encoding {self._batch_encoding_size} videos for episodes {start_episode} to {end_episode - 1}"
-        )
-
-        chunk_idx = self._meta.episodes[start_episode]["data/chunk_index"]
-        file_idx = self._meta.episodes[start_episode]["data/file_index"]
-        episode_df_path = self._root / DEFAULT_EPISODES_PATH.format(
-            chunk_index=chunk_idx, file_index=file_idx
-        )
-        episode_df = pd.read_parquet(episode_df_path)
-
-        for ep_idx in range(start_episode, end_episode):
-            logger.info(f"Encoding videos for episode {ep_idx}")
-
-            if (
-                self._meta.episodes[ep_idx]["data/chunk_index"] != chunk_idx
-                or self._meta.episodes[ep_idx]["data/file_index"] != file_idx
-            ):
-                episode_df.to_parquet(episode_df_path)
-                self._meta.episodes = load_episodes(self._root)
-
-                chunk_idx = self._meta.episodes[ep_idx]["data/chunk_index"]
-                file_idx = self._meta.episodes[ep_idx]["data/file_index"]
-                episode_df_path = self._root / DEFAULT_EPISODES_PATH.format(
-                    chunk_index=chunk_idx, file_index=file_idx
-                )
-                episode_df = pd.read_parquet(episode_df_path)
-
-            video_ep_metadata = {}
-            for video_key in self._meta.video_keys:
-                video_ep_metadata.update(self._save_episode_video(video_key, ep_idx))
-            video_ep_metadata.pop("episode_index")
-            video_ep_df = pd.DataFrame(video_ep_metadata, index=[ep_idx]).convert_dtypes(
-                dtype_backend="pyarrow"
-            )
-
-            episode_df = episode_df.combine_first(video_ep_df)
-            episode_df.to_parquet(episode_df_path)
-            self._meta.episodes = load_episodes(self._root)
-
-    def _save_episode_data(self, episode_buffer: dict) -> dict:
-        """Save episode data to a parquet file."""
-        # Use metadata features as the authoritative schema
-        hf_features = get_hf_features_from_features(self._meta.features)
-        ep_dict = {key: episode_buffer[key] for key in hf_features}
-        ep_dataset = datasets.Dataset.from_dict(ep_dict, features=hf_features, split="train")
-        ep_dataset = embed_images(ep_dataset)
-        ep_num_frames = len(ep_dataset)
-
-        if self._latest_episode is None:
-            chunk_idx, file_idx = 0, 0
-            global_frame_index = 0
-            self._current_file_start_frame = 0
-            if self._meta.episodes is not None and len(self._meta.episodes) > 0:
-                latest_ep = self._meta.episodes[-1]
-                global_frame_index = latest_ep["dataset_to_index"]
-                chunk_idx = latest_ep["data/chunk_index"]
-                file_idx = latest_ep["data/file_index"]
-
-                chunk_idx, file_idx = update_chunk_file_indices(chunk_idx, file_idx, self._meta.chunks_size)
-                self._current_file_start_frame = global_frame_index
-        else:
-            latest_ep = self._latest_episode
-            chunk_idx = latest_ep["data/chunk_index"]
-            file_idx = latest_ep["data/file_index"]
-            global_frame_index = latest_ep["index"][-1] + 1
-
-            latest_path = self._root / self._meta.data_path.format(chunk_index=chunk_idx, file_index=file_idx)
-            latest_size_in_mb = get_file_size_in_mb(latest_path)
-
-            frames_in_current_file = global_frame_index - self._current_file_start_frame
-            av_size_per_frame = (
-                latest_size_in_mb / frames_in_current_file if frames_in_current_file > 0 else 0
-            )
-
-            if latest_size_in_mb + av_size_per_frame * ep_num_frames >= self._meta.data_files_size_in_mb:
-                chunk_idx, file_idx = update_chunk_file_indices(chunk_idx, file_idx, self._meta.chunks_size)
-                self.close_writer()
-                self._current_file_start_frame = global_frame_index
-
-        ep_dict["data/chunk_index"] = chunk_idx
-        ep_dict["data/file_index"] = file_idx
-
-        path = self._root / self._meta.data_path.format(chunk_index=chunk_idx, file_index=file_idx)
-        path.parent.mkdir(parents=True, exist_ok=True)
-
-        table = ep_dataset.with_format("arrow")[:]
-        if not self._pq_writer:
-            self._pq_writer = pq.ParquetWriter(
-                path, schema=table.schema, compression="snappy", use_dictionary=True
-            )
-        self._pq_writer.write_table(table)
-
-        metadata = {
-            "data/chunk_index": chunk_idx,
-            "data/file_index": file_idx,
-            "dataset_from_index": global_frame_index,
-            "dataset_to_index": global_frame_index + ep_num_frames,
-        }
-
-        self._latest_episode = {**ep_dict, **metadata}
-        self._recorded_frames += ep_num_frames
-
-        return metadata
-
-    def _save_episode_video(
-        self,
-        video_key: str,
-        episode_index: int,
-        temp_path: Path | None = None,
-    ) -> dict:
-        if temp_path is None:
-            ep_path = self._encode_temporary_episode_video(video_key, episode_index)
-        else:
-            ep_path = temp_path
-
-        ep_size_in_mb = get_file_size_in_mb(ep_path)
-        ep_duration_in_s = get_video_duration_in_s(ep_path)
-
-        if (
-            episode_index == 0
-            or self._meta.latest_episode is None
-            or f"videos/{video_key}/chunk_index" not in self._meta.latest_episode
-        ):
-            chunk_idx, file_idx = 0, 0
-            if self._meta.episodes is not None and len(self._meta.episodes) > 0:
-                old_chunk_idx = self._meta.episodes[-1][f"videos/{video_key}/chunk_index"]
-                old_file_idx = self._meta.episodes[-1][f"videos/{video_key}/file_index"]
-                chunk_idx, file_idx = update_chunk_file_indices(
-                    old_chunk_idx, old_file_idx, self._meta.chunks_size
-                )
-            latest_duration_in_s = 0.0
-            new_path = self._root / self._meta.video_path.format(
-                video_key=video_key, chunk_index=chunk_idx, file_index=file_idx
-            )
-            new_path.parent.mkdir(parents=True, exist_ok=True)
-            shutil.move(str(ep_path), str(new_path))
-        else:
-            latest_ep = self._meta.latest_episode
-            chunk_idx = latest_ep[f"videos/{video_key}/chunk_index"][0]
-            file_idx = latest_ep[f"videos/{video_key}/file_index"][0]
-
-            latest_path = self._root / self._meta.video_path.format(
-                video_key=video_key, chunk_index=chunk_idx, file_index=file_idx
-            )
-            latest_size_in_mb = get_file_size_in_mb(latest_path)
-            latest_duration_in_s = latest_ep[f"videos/{video_key}/to_timestamp"][0]
-
-            if latest_size_in_mb + ep_size_in_mb >= self._meta.video_files_size_in_mb:
-                chunk_idx, file_idx = update_chunk_file_indices(chunk_idx, file_idx, self._meta.chunks_size)
-                new_path = self._root / self._meta.video_path.format(
-                    video_key=video_key, chunk_index=chunk_idx, file_index=file_idx
-                )
-                new_path.parent.mkdir(parents=True, exist_ok=True)
-                shutil.move(str(ep_path), str(new_path))
-                latest_duration_in_s = 0.0
-            else:
-                concatenate_video_files(
-                    [latest_path, ep_path],
-                    latest_path,
-                )
-
-        # Remove temporary directory
-        shutil.rmtree(str(ep_path.parent))
-
-        # Update video info (only needed when first episode is encoded)
-        if episode_index == 0:
-            self._meta.update_video_info(video_key)
-            write_info(self._meta.info, self._meta.root)
-
-        metadata = {
-            "episode_index": episode_index,
-            f"videos/{video_key}/chunk_index": chunk_idx,
-            f"videos/{video_key}/file_index": file_idx,
-            f"videos/{video_key}/from_timestamp": latest_duration_in_s,
-            f"videos/{video_key}/to_timestamp": latest_duration_in_s + ep_duration_in_s,
-        }
-        return metadata
-
-    def clear_episode_buffer(self, delete_images: bool = True) -> None:
-        """Discard the current episode buffer and optionally delete temp images.
-
-        Args:
-            delete_images: If ``True``, remove temporary image directories
-                written for the current episode.
-        """
-        # Cancel streaming encoder if active
-        if self._streaming_encoder is not None:
-            self._streaming_encoder.cancel_episode()
-
-        if delete_images:
-            if self.image_writer is not None:
-                self._wait_image_writer()
-            episode_index = self.episode_buffer["episode_index"]
-            # episode_index is `int` when freshly created, but becomes `np.ndarray` after
-            # save_episode() mutates the buffer. Handle both types here.
-            if isinstance(episode_index, np.ndarray):
-                episode_index = episode_index.item() if episode_index.size == 1 else episode_index[0]
-            for cam_key in self._meta.image_keys:
-                img_dir = self._get_image_file_dir(episode_index, cam_key)
-                if img_dir.is_dir():
-                    shutil.rmtree(img_dir)
-
-        self.episode_buffer = self._create_episode_buffer()
-
-    def start_image_writer(self, num_processes: int = 0, num_threads: int = 4) -> None:
-        """Start an :class:`AsyncImageWriter` for background image persistence.
-
-        Args:
-            num_processes: Number of subprocesses. ``0`` means threads only.
-            num_threads: Number of threads per process.
-        """
-        if isinstance(self.image_writer, AsyncImageWriter):
-            logger.warning(
-                "You are starting a new AsyncImageWriter that is replacing an already existing one in the dataset."
-            )
-
-        self.image_writer = AsyncImageWriter(
-            num_processes=num_processes,
-            num_threads=num_threads,
-        )
-
-    def stop_image_writer(self) -> None:
-        """Stop the image writer (needed before pickling the dataset for DataLoader)."""
-        if self.image_writer is not None:
-            self.image_writer.stop()
-            self.image_writer = None
-
-    def _wait_image_writer(self) -> None:
-        """Wait for asynchronous image writer to finish."""
-        if self.image_writer is not None:
-            self.image_writer.wait_until_done()
-
-    def _encode_temporary_episode_video(self, video_key: str, episode_index: int) -> Path:
-        """Use ffmpeg to convert frames stored as png into mp4 videos."""
-        return _encode_video_worker(
-            video_key, episode_index, self._root, self._meta.fps, self._vcodec, self._encoder_threads
-        )
-
-    def close_writer(self) -> None:
-        """Close and cleanup the parquet writer if it exists."""
-        if self._pq_writer is not None:
-            self._pq_writer.close()
-            self._pq_writer = None
-
-    def flush_pending_videos(self) -> None:
-        """Flush any pending video encoding (streaming or batch).
-
-        For streaming encoding: closes the encoder.
-        For batch encoding: encodes any remaining episodes that haven't been batch-encoded yet.
-        """
-        if self._streaming_encoder is not None:
-            self._streaming_encoder.close()
-        elif self._episodes_since_last_encoding > 0:
-            start_ep = self._meta.total_episodes - self._episodes_since_last_encoding
-            end_ep = self._meta.total_episodes
-            logger.info(
-                f"Encoding remaining {self._episodes_since_last_encoding} episodes, "
-                f"from episode {start_ep} to {end_ep - 1}"
-            )
-            self._batch_save_episode_video(start_ep, end_ep)
-
-    def cancel_pending_videos(self) -> None:
-        """Cancel any in-progress streaming encoding without flushing."""
-        if self._streaming_encoder is not None:
-            self._streaming_encoder.cancel_episode()
-
-    def cleanup_interrupted_episode(self, episode_index: int) -> None:
-        """Remove temporary image directories for an interrupted episode."""
-        for key in self._meta.video_keys:
-            img_dir = self._get_image_file_path(
-                episode_index=episode_index, image_key=key, frame_index=0
-            ).parent
-            if img_dir.exists():
-                logger.debug(
-                    f"Cleaning up interrupted episode images for episode {episode_index}, camera {key}"
-                )
-                shutil.rmtree(img_dir)
-
-    def finalize(self) -> None:
-        """Flush all pending work and release all resources.
-
-        Idempotent — safe to call multiple times.
-        """
-        if getattr(self, "_finalized", False):
-            return
-        # 1. Wait for async image writes to complete, then stop
-        if self.image_writer is not None:
-            self.image_writer.wait_until_done()
-            self.image_writer.stop()
-            self.image_writer = None
-        # 2. Flush pending video encoding (streaming or batch)
-        self.flush_pending_videos()
-        # 3. Close own parquet writer
-        self.close_writer()
-        # 4. Finalize metadata (idempotent)
-        self._meta.finalize()
-        self._finalized = True
-
-    def __del__(self):
-        """Safety net: release resources on garbage collection."""
-        # During interpreter shutdown, referenced objects may already be collected.
-        with contextlib.suppress(Exception):
-            self.finalize()

src/lerobot/datasets/factory.py

@@ -20,12 +20,14 @@ import torch
 
 from lerobot.configs.policies import PreTrainedConfig
 from lerobot.configs.train import TrainPipelineConfig
-from lerobot.datasets.dataset_metadata import LeRobotDatasetMetadata
-from lerobot.datasets.lerobot_dataset import LeRobotDataset
-from lerobot.datasets.multi_dataset import MultiLeRobotDataset
+from lerobot.datasets.lerobot_dataset import (
+    LeRobotDataset,
+    LeRobotDatasetMetadata,
+    MultiLeRobotDataset,
+)
 from lerobot.datasets.streaming_dataset import StreamingLeRobotDataset
 from lerobot.datasets.transforms import ImageTransforms
-from lerobot.utils.constants import ACTION, OBS_PREFIX, OBS_STATE, REWARD
+from lerobot.utils.constants import ACTION, OBS_PREFIX, REWARD
 
 IMAGENET_STATS = {
     "mean": [[[0.485]], [[0.456]], [[0.406]]],  # (c,1,1)
@@ -52,15 +54,12 @@ def resolve_delta_timestamps(
             returns `None` if the resulting dict is empty.
     """
     delta_timestamps = {}
-    state_delta = getattr(cfg, "state_delta_indices", None)
     for key in ds_meta.features:
         if key == REWARD and cfg.reward_delta_indices is not None:
             delta_timestamps[key] = [i / ds_meta.fps for i in cfg.reward_delta_indices]
         if key == ACTION and cfg.action_delta_indices is not None:
             delta_timestamps[key] = [i / ds_meta.fps for i in cfg.action_delta_indices]
-        if key == OBS_STATE and state_delta is not None:
-            delta_timestamps[key] = [i / ds_meta.fps for i in state_delta]
-        elif key.startswith(OBS_PREFIX) and cfg.observation_delta_indices is not None:
+        if key.startswith(OBS_PREFIX) and cfg.observation_delta_indices is not None:
             delta_timestamps[key] = [i / ds_meta.fps for i in cfg.observation_delta_indices]
 
     if len(delta_timestamps) == 0:

src/lerobot/datasets/feature_utils.py

@@ -1,556 +0,0 @@
-#!/usr/bin/env python
-
-# Copyright 2024 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 pprint import pformat
-from typing import Any
-
-import datasets
-import numpy as np
-from PIL import Image as PILImage
-
-from lerobot.configs.types import FeatureType, PolicyFeature
-from lerobot.datasets.utils import (
-    DEFAULT_CHUNK_SIZE,
-    DEFAULT_DATA_FILE_SIZE_IN_MB,
-    DEFAULT_DATA_PATH,
-    DEFAULT_FEATURES,
-    DEFAULT_VIDEO_FILE_SIZE_IN_MB,
-    DEFAULT_VIDEO_PATH,
-)
-from lerobot.utils.constants import ACTION, OBS_ENV_STATE, OBS_STR
-from lerobot.utils.utils import is_valid_numpy_dtype_string
-
-
-def get_hf_features_from_features(features: dict) -> datasets.Features:
-    """Convert a LeRobot features dictionary to a `datasets.Features` object.
-
-    Args:
-        features (dict): A LeRobot-style feature dictionary.
-
-    Returns:
-        datasets.Features: The corresponding Hugging Face `datasets.Features` object.
-
-    Raises:
-        ValueError: If a feature has an unsupported shape.
-    """
-    hf_features = {}
-    for key, ft in features.items():
-        if ft["dtype"] == "video":
-            continue
-        elif ft["dtype"] == "image":
-            hf_features[key] = datasets.Image()
-        elif ft["shape"] == (1,):
-            hf_features[key] = datasets.Value(dtype=ft["dtype"])
-        elif len(ft["shape"]) == 1:
-            hf_features[key] = datasets.Sequence(
-                length=ft["shape"][0], feature=datasets.Value(dtype=ft["dtype"])
-            )
-        elif len(ft["shape"]) == 2:
-            hf_features[key] = datasets.Array2D(shape=ft["shape"], dtype=ft["dtype"])
-        elif len(ft["shape"]) == 3:
-            hf_features[key] = datasets.Array3D(shape=ft["shape"], dtype=ft["dtype"])
-        elif len(ft["shape"]) == 4:
-            hf_features[key] = datasets.Array4D(shape=ft["shape"], dtype=ft["dtype"])
-        elif len(ft["shape"]) == 5:
-            hf_features[key] = datasets.Array5D(shape=ft["shape"], dtype=ft["dtype"])
-        else:
-            raise ValueError(f"Corresponding feature is not valid: {ft}")
-
-    return datasets.Features(hf_features)
-
-
-def _validate_feature_names(features: dict[str, dict]) -> None:
-    """Validate that feature names do not contain invalid characters.
-
-    Args:
-        features (dict): The LeRobot features dictionary.
-
-    Raises:
-        ValueError: If any feature name contains '/'.
-    """
-    invalid_features = {name: ft for name, ft in features.items() if "/" in name}
-    if invalid_features:
-        raise ValueError(f"Feature names should not contain '/'. Found '/' in '{invalid_features}'.")
-
-
-def hw_to_dataset_features(
-    hw_features: dict[str, type | tuple], prefix: str, use_video: bool = True
-) -> dict[str, dict]:
-    """Convert hardware-specific features to a LeRobot dataset feature dictionary.
-
-    This function takes a dictionary describing hardware outputs (like joint states
-    or camera image shapes) and formats it into the standard LeRobot feature
-    specification.
-
-    Args:
-        hw_features (dict): Dictionary mapping feature names to their type (float for
-            joints) or shape (tuple for images).
-        prefix (str): The prefix to add to the feature keys (e.g., "observation"
-            or "action").
-        use_video (bool): If True, image features are marked as "video", otherwise "image".
-
-    Returns:
-        dict: A LeRobot features dictionary.
-    """
-    features = {}
-    joint_fts = {
-        key: ftype
-        for key, ftype in hw_features.items()
-        if ftype is float or (isinstance(ftype, PolicyFeature) and ftype.type != FeatureType.VISUAL)
-    }
-    cam_fts = {key: shape for key, shape in hw_features.items() if isinstance(shape, tuple)}
-
-    if joint_fts and prefix == ACTION:
-        features[prefix] = {
-            "dtype": "float32",
-            "shape": (len(joint_fts),),
-            "names": list(joint_fts),
-        }
-
-    if joint_fts and prefix == OBS_STR:
-        features[f"{prefix}.state"] = {
-            "dtype": "float32",
-            "shape": (len(joint_fts),),
-            "names": list(joint_fts),
-        }
-
-    for key, shape in cam_fts.items():
-        features[f"{prefix}.images.{key}"] = {
-            "dtype": "video" if use_video else "image",
-            "shape": shape,
-            "names": ["height", "width", "channels"],
-        }
-
-    _validate_feature_names(features)
-    return features
-
-
-def build_dataset_frame(
-    ds_features: dict[str, dict], values: dict[str, Any], prefix: str
-) -> dict[str, np.ndarray]:
-    """Construct a single data frame from raw values based on dataset features.
-
-    A "frame" is a dictionary containing all the data for a single timestep,
-    formatted as numpy arrays according to the feature specification.
-
-    Args:
-        ds_features (dict): The LeRobot dataset features dictionary.
-        values (dict): A dictionary of raw values from the hardware/environment.
-        prefix (str): The prefix to filter features by (e.g., "observation"
-            or "action").
-
-    Returns:
-        dict: A dictionary representing a single frame of data.
-    """
-    frame = {}
-    for key, ft in ds_features.items():
-        if key in DEFAULT_FEATURES or not key.startswith(prefix):
-            continue
-        elif ft["dtype"] == "float32" and len(ft["shape"]) == 1:
-            frame[key] = np.array([values[name] for name in ft["names"]], dtype=np.float32)
-        elif ft["dtype"] in ["image", "video"]:
-            frame[key] = values[key.removeprefix(f"{prefix}.images.")]
-
-    return frame
-
-
-def dataset_to_policy_features(features: dict[str, dict]) -> dict[str, PolicyFeature]:
-    """Convert dataset features to policy features.
-
-    This function transforms the dataset's feature specification into a format
-    that a policy can use, classifying features by type (e.g., visual, state,
-    action) and ensuring correct shapes (e.g., channel-first for images).
-
-    Args:
-        features (dict): The LeRobot dataset features dictionary.
-
-    Returns:
-        dict: A dictionary mapping feature keys to `PolicyFeature` objects.
-
-    Raises:
-        ValueError: If an image feature does not have a 3D shape.
-    """
-    # TODO(aliberts): Implement "type" in dataset features and simplify this
-    policy_features = {}
-    for key, ft in features.items():
-        shape = ft["shape"]
-        if ft["dtype"] in ["image", "video"]:
-            type = FeatureType.VISUAL
-            if len(shape) != 3:
-                raise ValueError(f"Number of dimensions of {key} != 3 (shape={shape})")
-
-            names = ft["names"]
-            # Backward compatibility for "channel" which is an error introduced in LeRobotDataset v2.0 for ported datasets.
-            if names[2] in ["channel", "channels"]:  # (h, w, c) -> (c, h, w)
-                shape = (shape[2], shape[0], shape[1])
-        elif key == OBS_ENV_STATE:
-            type = FeatureType.ENV
-        elif key.startswith(OBS_STR):
-            type = FeatureType.STATE
-        elif key.startswith(ACTION):
-            type = FeatureType.ACTION
-        else:
-            continue
-
-        policy_features[key] = PolicyFeature(
-            type=type,
-            shape=shape,
-        )
-
-    return policy_features
-
-
-def combine_feature_dicts(*dicts: dict) -> dict:
-    """Merge LeRobot grouped feature dicts.
-
-    - For 1D numeric specs (dtype not image/video/string) with "names": we merge the names and recompute the shape.
-    - For others (e.g. `observation.images.*`), the last one wins (if they are identical).
-
-    Args:
-        *dicts: A variable number of LeRobot feature dictionaries to merge.
-
-    Returns:
-        dict: A single merged feature dictionary.
-
-    Raises:
-        ValueError: If there's a dtype mismatch for a feature being merged.
-    """
-    out: dict = {}
-    for d in dicts:
-        for key, value in d.items():
-            if not isinstance(value, dict):
-                out[key] = value
-                continue
-
-            dtype = value.get("dtype")
-            shape = value.get("shape")
-            is_vector = (
-                dtype not in ("image", "video", "string")
-                and isinstance(shape, tuple)
-                and len(shape) == 1
-                and "names" in value
-            )
-
-            if is_vector:
-                # Initialize or retrieve the accumulating dict for this feature key
-                target = out.setdefault(key, {"dtype": dtype, "names": [], "shape": (0,)})
-                # Ensure consistent data types across merged entries
-                if "dtype" in target and dtype != target["dtype"]:
-                    raise ValueError(f"dtype mismatch for '{key}': {target['dtype']} vs {dtype}")
-
-                # Merge feature names: append only new ones to preserve order without duplicates
-                seen = set(target["names"])
-                for n in value["names"]:
-                    if n not in seen:
-                        target["names"].append(n)
-                        seen.add(n)
-                # Recompute the shape to reflect the updated number of features
-                target["shape"] = (len(target["names"]),)
-            else:
-                # For images/videos and non-1D entries: override with the latest definition
-                out[key] = value
-    return out
-
-
-def create_empty_dataset_info(
-    codebase_version: str,
-    fps: int,
-    features: dict,
-    use_videos: bool,
-    robot_type: str | None = None,
-    chunks_size: int | None = None,
-    data_files_size_in_mb: int | None = None,
-    video_files_size_in_mb: int | None = None,
-) -> dict:
-    """Create a template dictionary for a new dataset's `info.json`.
-
-    Args:
-        codebase_version (str): The version of the LeRobot codebase.
-        fps (int): The frames per second of the data.
-        features (dict): The LeRobot features dictionary for the dataset.
-        use_videos (bool): Whether the dataset will store videos.
-        robot_type (str | None): The type of robot used, if any.
-
-    Returns:
-        dict: A dictionary with the initial dataset metadata.
-    """
-    return {
-        "codebase_version": codebase_version,
-        "robot_type": robot_type,
-        "total_episodes": 0,
-        "total_frames": 0,
-        "total_tasks": 0,
-        "chunks_size": chunks_size or DEFAULT_CHUNK_SIZE,
-        "data_files_size_in_mb": data_files_size_in_mb or DEFAULT_DATA_FILE_SIZE_IN_MB,
-        "video_files_size_in_mb": video_files_size_in_mb or DEFAULT_VIDEO_FILE_SIZE_IN_MB,
-        "fps": fps,
-        "splits": {},
-        "data_path": DEFAULT_DATA_PATH,
-        "video_path": DEFAULT_VIDEO_PATH if use_videos else None,
-        "features": features,
-    }
-
-
-def check_delta_timestamps(
-    delta_timestamps: dict[str, list[float]], fps: int, tolerance_s: float, raise_value_error: bool = True
-) -> bool:
-    """Check if delta timestamps are multiples of 1/fps +/- tolerance.
-
-    This ensures that adding these delta timestamps to any existing timestamp in
-    the dataset will result in a value that aligns with the dataset's frame rate.
-
-    Args:
-        delta_timestamps (dict): A dictionary where values are lists of time
-            deltas in seconds.
-        fps (int): The frames per second of the dataset.
-        tolerance_s (float): The allowed tolerance in seconds.
-        raise_value_error (bool): If True, raises an error on failure.
-
-    Returns:
-        bool: True if all deltas are valid, False otherwise.
-
-    Raises:
-        ValueError: If any delta is outside the tolerance and `raise_value_error` is True.
-    """
-    outside_tolerance = {}
-    for key, delta_ts in delta_timestamps.items():
-        within_tolerance = [abs(ts * fps - round(ts * fps)) / fps <= tolerance_s for ts in delta_ts]
-        if not all(within_tolerance):
-            outside_tolerance[key] = [
-                ts for ts, is_within in zip(delta_ts, within_tolerance, strict=True) if not is_within
-            ]
-
-    if len(outside_tolerance) > 0:
-        if raise_value_error:
-            raise ValueError(
-                f"""
-                The following delta_timestamps are found outside of tolerance range.
-                Please make sure they are multiples of 1/{fps} +/- tolerance and adjust
-                their values accordingly.
-                \n{pformat(outside_tolerance)}
-                """
-            )
-        return False
-
-    return True
-
-
-def get_delta_indices(delta_timestamps: dict[str, list[float]], fps: int) -> dict[str, list[int]]:
-    """Convert delta timestamps in seconds to delta indices in frames.
-
-    Args:
-        delta_timestamps (dict): A dictionary of time deltas in seconds.
-        fps (int): The frames per second of the dataset.
-
-    Returns:
-        dict: A dictionary of frame delta indices.
-    """
-    delta_indices = {}
-    for key, delta_ts in delta_timestamps.items():
-        delta_indices[key] = [round(d * fps) for d in delta_ts]
-
-    return delta_indices
-
-
-def validate_frame(frame: dict, features: dict) -> None:
-    # DEFAULT_FEATURES (timestamp, frame_index, episode_index, index, task_index) are
-    # auto-populated by the recording pipeline (add_frame / save_episode) and must not
-    # be supplied by the caller. Excluding them here means any frame dict that contains
-    # these keys will be rejected as extra features.
-    expected_features = set(features) - set(DEFAULT_FEATURES)
-    actual_features = set(frame)
-
-    # task is a special required field that's not part of regular features
-    if "task" not in actual_features:
-        raise ValueError("Feature mismatch in `frame` dictionary:\nMissing features: {'task'}\n")
-
-    # Remove task from actual_features for regular feature validation
-    actual_features_for_validation = actual_features - {"task"}
-
-    error_message = validate_features_presence(actual_features_for_validation, expected_features)
-
-    common_features = actual_features_for_validation & expected_features
-    for name in common_features:
-        error_message += validate_feature_dtype_and_shape(name, features[name], frame[name])
-
-    if error_message:
-        raise ValueError(error_message)
-
-
-def validate_features_presence(actual_features: set[str], expected_features: set[str]) -> str:
-    """Check for missing or extra features in a frame.
-
-    Args:
-        actual_features (set[str]): The set of feature names present in the frame.
-        expected_features (set[str]): The set of feature names expected in the frame.
-
-    Returns:
-        str: An error message string if there's a mismatch, otherwise an empty string.
-    """
-    error_message = ""
-    missing_features = expected_features - actual_features
-    extra_features = actual_features - expected_features
-
-    if missing_features or extra_features:
-        error_message += "Feature mismatch in `frame` dictionary:\n"
-        if missing_features:
-            error_message += f"Missing features: {missing_features}\n"
-        if extra_features:
-            error_message += f"Extra features: {extra_features}\n"
-
-    return error_message
-
-
-def validate_feature_dtype_and_shape(
-    name: str, feature: dict, value: np.ndarray | PILImage.Image | str
-) -> str:
-    """Validate the dtype and shape of a single feature's value.
-
-    Args:
-        name (str): The name of the feature.
-        feature (dict): The feature specification from the LeRobot features dictionary.
-        value: The value of the feature to validate.
-
-    Returns:
-        str: An error message if validation fails, otherwise an empty string.
-
-    Raises:
-        NotImplementedError: If the feature dtype is not supported for validation.
-    """
-    expected_dtype = feature["dtype"]
-    expected_shape = feature["shape"]
-    if is_valid_numpy_dtype_string(expected_dtype):
-        return validate_feature_numpy_array(name, expected_dtype, expected_shape, value)
-    elif expected_dtype in ["image", "video"]:
-        return validate_feature_image_or_video(name, expected_shape, value)
-    elif expected_dtype == "string":
-        return validate_feature_string(name, value)
-    else:
-        raise NotImplementedError(f"The feature dtype '{expected_dtype}' is not implemented yet.")
-
-
-def validate_feature_numpy_array(
-    name: str, expected_dtype: str, expected_shape: list[int], value: np.ndarray
-) -> str:
-    """Validate a feature that is expected to be a numpy array.
-
-    Args:
-        name (str): The name of the feature.
-        expected_dtype (str): The expected numpy dtype as a string.
-        expected_shape (list[int]): The expected shape.
-        value (np.ndarray): The numpy array to validate.
-
-    Returns:
-        str: An error message if validation fails, otherwise an empty string.
-    """
-    error_message = ""
-    if isinstance(value, np.ndarray):
-        actual_dtype = value.dtype
-        actual_shape = value.shape
-
-        if actual_dtype != np.dtype(expected_dtype):
-            error_message += f"The feature '{name}' of dtype '{actual_dtype}' is not of the expected dtype '{expected_dtype}'.\n"
-
-        if actual_shape != expected_shape:
-            error_message += f"The feature '{name}' of shape '{actual_shape}' does not have the expected shape '{expected_shape}'.\n"
-    else:
-        error_message += f"The feature '{name}' is not a 'np.ndarray'. Expected type is '{expected_dtype}', but type '{type(value)}' provided instead.\n"
-
-    return error_message
-
-
-def validate_feature_image_or_video(
-    name: str, expected_shape: list[str], value: np.ndarray | PILImage.Image
-) -> str:
-    """Validate a feature that is expected to be an image or video frame.
-
-    Accepts `np.ndarray` (channel-first or channel-last) or `PIL.Image.Image`.
-
-    Args:
-        name (str): The name of the feature.
-        expected_shape (list[str]): The expected shape (C, H, W).
-        value: The image data to validate.
-
-    Returns:
-        str: An error message if validation fails, otherwise an empty string.
-    """
-    # Note: The check of pixels range ([0,1] for float and [0,255] for uint8) is done by the image writer threads.
-    error_message = ""
-    if isinstance(value, np.ndarray):
-        actual_shape = value.shape
-        c, h, w = expected_shape
-        if len(actual_shape) != 3 or (actual_shape != (c, h, w) and actual_shape != (h, w, c)):
-            error_message += f"The feature '{name}' of shape '{actual_shape}' does not have the expected shape '{(c, h, w)}' or '{(h, w, c)}'.\n"
-    elif isinstance(value, PILImage.Image):
-        pass
-    else:
-        error_message += f"The feature '{name}' is expected to be of type 'PIL.Image' or 'np.ndarray' channel first or channel last, but type '{type(value)}' provided instead.\n"
-
-    return error_message
-
-
-def validate_feature_string(name: str, value: str) -> str:
-    """Validate a feature that is expected to be a string.
-
-    Args:
-        name (str): The name of the feature.
-        value (str): The value to validate.
-
-    Returns:
-        str: An error message if validation fails, otherwise an empty string.
-    """
-    if not isinstance(value, str):
-        return f"The feature '{name}' is expected to be of type 'str', but type '{type(value)}' provided instead.\n"
-    return ""
-
-
-def validate_episode_buffer(episode_buffer: dict, total_episodes: int, features: dict) -> None:
-    """Validate the episode buffer before it's written to disk.
-
-    Ensures the buffer has the required keys, contains at least one frame, and
-    has features consistent with the dataset's specification.
-
-    Args:
-        episode_buffer (dict): The buffer containing data for a single episode.
-        total_episodes (int): The current total number of episodes in the dataset.
-        features (dict): The LeRobot features dictionary for the dataset.
-
-    Raises:
-        ValueError: If the buffer is invalid.
-        NotImplementedError: If the episode index is manually set and doesn't match.
-    """
-    if "size" not in episode_buffer:
-        raise ValueError("size key not found in episode_buffer")
-
-    if "task" not in episode_buffer:
-        raise ValueError("task key not found in episode_buffer")
-
-    if episode_buffer["episode_index"] != total_episodes:
-        # TODO(aliberts): Add option to use existing episode_index
-        raise NotImplementedError(
-            "You might have manually provided the episode_buffer with an episode_index that doesn't "
-            "match the total number of episodes already in the dataset. This is not supported for now."
-        )
-
-    if episode_buffer["size"] == 0:
-        raise ValueError("You must add one or several frames with `add_frame` before calling `add_episode`.")
-
-    buffer_keys = set(episode_buffer.keys()) - {"task", "size"}
-    if not buffer_keys == set(features):
-        raise ValueError(
-            f"Features from `episode_buffer` don't match the ones in `features`."
-            f"In episode_buffer not in features: {buffer_keys - set(features)}"
-            f"In features not in episode_buffer: {set(features) - buffer_keys}"
-        )

src/lerobot/datasets/image_writer.py

@@ -13,7 +13,6 @@
 # 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.
-import logging
 import multiprocessing
 import queue
 import threading
@@ -23,8 +22,6 @@ import numpy as np
 import PIL.Image
 import torch
 
-logger = logging.getLogger(__name__)
-
 
 def safe_stop_image_writer(func):
     def wrapper(*args, **kwargs):
@@ -32,10 +29,10 @@ def safe_stop_image_writer(func):
             return func(*args, **kwargs)
         except Exception as e:
             dataset = kwargs.get("dataset")
-            writer = getattr(dataset, "writer", None) if dataset else None
-            if writer is not None and writer.image_writer is not None:
-                logger.warning("Waiting for image writer to terminate...")
-                writer.image_writer.stop()
+            image_writer = getattr(dataset, "image_writer", None) if dataset else None
+            if image_writer is not None:
+                print("Waiting for image writer to terminate...")
+                image_writer.stop()
             raise e
 
     return wrapper
@@ -92,7 +89,8 @@ def write_image(image: np.ndarray | PIL.Image.Image, fpath: Path, compress_level
             PIL.Image.Image object.
 
     Side Effects:
-        Logs an error message if the image writing process fails for any reason.
+        Prints an error message to the console if the image writing process
+        fails for any reason.
     """
     try:
         if isinstance(image, np.ndarray):
@@ -103,7 +101,7 @@ def write_image(image: np.ndarray | PIL.Image.Image, fpath: Path, compress_level
             raise TypeError(f"Unsupported image type: {type(image)}")
         img.save(fpath, compress_level=compress_level)
     except Exception as e:
-        logger.error("Error writing image %s: %s", fpath, e)
+        print(f"Error writing image {fpath}: {e}")
 
 
 def worker_thread_loop(queue: queue.Queue):

src/lerobot/datasets/io_utils.py

@@ -1,342 +0,0 @@
-#!/usr/bin/env python
-
-# Copyright 2024 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.
-import json
-from pathlib import Path
-from typing import Any
-
-import datasets
-import numpy as np
-import pandas
-import pandas as pd
-import pyarrow.dataset as pa_ds
-import pyarrow.parquet as pq
-import torch
-from datasets import Dataset
-from datasets.table import embed_table_storage
-from PIL import Image as PILImage
-from torchvision import transforms
-
-from lerobot.datasets.utils import (
-    DEFAULT_DATA_FILE_SIZE_IN_MB,
-    DEFAULT_EPISODES_PATH,
-    DEFAULT_SUBTASKS_PATH,
-    DEFAULT_TASKS_PATH,
-    EPISODES_DIR,
-    INFO_PATH,
-    STATS_PATH,
-    flatten_dict,
-    serialize_dict,
-    unflatten_dict,
-)
-from lerobot.utils.utils import SuppressProgressBars
-
-
-def get_parquet_file_size_in_mb(parquet_path: str | Path) -> float:
-    metadata = pq.read_metadata(parquet_path)
-    total_uncompressed_size = 0
-    for row_group in range(metadata.num_row_groups):
-        rg_metadata = metadata.row_group(row_group)
-        for column in range(rg_metadata.num_columns):
-            col_metadata = rg_metadata.column(column)
-            total_uncompressed_size += col_metadata.total_uncompressed_size
-    return total_uncompressed_size / (1024**2)
-
-
-def get_hf_dataset_size_in_mb(hf_ds: Dataset) -> int:
-    return hf_ds.data.nbytes // (1024**2)
-
-
-def load_nested_dataset(
-    pq_dir: Path, features: datasets.Features | None = None, episodes: list[int] | None = None
-) -> Dataset:
-    """Find parquet files in provided directory {pq_dir}/chunk-xxx/file-xxx.parquet
-    Convert parquet files to pyarrow memory mapped in a cache folder for efficient RAM usage
-    Concatenate all pyarrow references to return HF Dataset format
-
-    Args:
-        pq_dir: Directory containing parquet files
-        features: Optional features schema to ensure consistent loading of complex types like images
-        episodes: Optional list of episode indices to filter. Uses PyArrow predicate pushdown for efficiency.
-    """
-    paths = sorted(pq_dir.glob("*/*.parquet"))
-    if len(paths) == 0:
-        raise FileNotFoundError(f"Provided directory does not contain any parquet file: {pq_dir}")
-
-    with SuppressProgressBars():
-        # We use .from_parquet() memory-mapped loading for efficiency
-        filters = pa_ds.field("episode_index").isin(episodes) if episodes is not None else None
-        return Dataset.from_parquet([str(path) for path in paths], filters=filters, features=features)
-
-
-def get_parquet_num_frames(parquet_path: str | Path) -> int:
-    metadata = pq.read_metadata(parquet_path)
-    return metadata.num_rows
-
-
-def get_file_size_in_mb(file_path: Path) -> float:
-    """Get file size on disk in megabytes.
-
-    Args:
-        file_path (Path): Path to the file.
-    """
-    file_size_bytes = file_path.stat().st_size
-    return file_size_bytes / (1024**2)
-
-
-def embed_images(dataset: datasets.Dataset) -> datasets.Dataset:
-    """Embed image bytes into the dataset table before saving to Parquet.
-
-    This function prepares a Hugging Face dataset for serialization by converting
-    image objects into an embedded format that can be stored in Arrow/Parquet.
-
-    Args:
-        dataset (datasets.Dataset): The input dataset, possibly containing image features.
-
-    Returns:
-        datasets.Dataset: The dataset with images embedded in the table storage.
-    """
-    # Embed image bytes into the table before saving to parquet
-    format = dataset.format
-    dataset = dataset.with_format("arrow")
-    dataset = dataset.map(embed_table_storage, batched=False)
-    dataset = dataset.with_format(**format)
-    return dataset
-
-
-def load_json(fpath: Path) -> Any:
-    """Load data from a JSON file.
-
-    Args:
-        fpath (Path): Path to the JSON file.
-
-    Returns:
-        Any: The data loaded from the JSON file.
-    """
-    with open(fpath) as f:
-        return json.load(f)
-
-
-def write_json(data: dict, fpath: Path) -> None:
-    """Write data to a JSON file.
-
-    Creates parent directories if they don't exist.
-
-    Args:
-        data (dict): The dictionary to write.
-        fpath (Path): The path to the output JSON file.
-    """
-    fpath.parent.mkdir(exist_ok=True, parents=True)
-    with open(fpath, "w") as f:
-        json.dump(data, f, indent=4, ensure_ascii=False)
-
-
-def write_info(info: dict, local_dir: Path) -> None:
-    write_json(info, local_dir / INFO_PATH)
-
-
-def load_info(local_dir: Path) -> dict:
-    """Load dataset info metadata from its standard file path.
-
-    Also converts shape lists to tuples for consistency.
-
-    Args:
-        local_dir (Path): The root directory of the dataset.
-
-    Returns:
-        dict: The dataset information dictionary.
-    """
-    info = load_json(local_dir / INFO_PATH)
-    for ft in info["features"].values():
-        ft["shape"] = tuple(ft["shape"])
-    return info
-
-
-def write_stats(stats: dict, local_dir: Path) -> None:
-    """Serialize and write dataset statistics to their standard file path.
-
-    Args:
-        stats (dict): The statistics dictionary (can contain tensors/numpy arrays).
-        local_dir (Path): The root directory of the dataset.
-    """
-    serialized_stats = serialize_dict(stats)
-    write_json(serialized_stats, local_dir / STATS_PATH)
-
-
-def cast_stats_to_numpy(stats: dict) -> dict[str, dict[str, np.ndarray]]:
-    """Recursively cast numerical values in a stats dictionary to numpy arrays.
-
-    Args:
-        stats (dict): The statistics dictionary.
-
-    Returns:
-        dict: The statistics dictionary with values cast to numpy arrays.
-    """
-    stats = {key: np.array(value) for key, value in flatten_dict(stats).items()}
-    return unflatten_dict(stats)
-
-
-def load_stats(local_dir: Path) -> dict[str, dict[str, np.ndarray]] | None:
-    """Load dataset statistics and cast numerical values to numpy arrays.
-
-    Returns None if the stats file doesn't exist.
-
-    Args:
-        local_dir (Path): The root directory of the dataset.
-
-    Returns:
-        A dictionary of statistics or None if the file is not found.
-    """
-    if not (local_dir / STATS_PATH).exists():
-        return None
-    stats = load_json(local_dir / STATS_PATH)
-    return cast_stats_to_numpy(stats)
-
-
-def write_tasks(tasks: pandas.DataFrame, local_dir: Path) -> None:
-    path = local_dir / DEFAULT_TASKS_PATH
-    path.parent.mkdir(parents=True, exist_ok=True)
-    tasks.to_parquet(path)
-
-
-def load_tasks(local_dir: Path) -> pandas.DataFrame:
-    tasks = pd.read_parquet(local_dir / DEFAULT_TASKS_PATH)
-    tasks.index.name = "task"
-    return tasks
-
-
-def load_subtasks(local_dir: Path) -> pandas.DataFrame | None:
-    """Load subtasks from subtasks.parquet if it exists."""
-    subtasks_path = local_dir / DEFAULT_SUBTASKS_PATH
-    if subtasks_path.exists():
-        return pd.read_parquet(subtasks_path)
-    return None
-
-
-def write_episodes(episodes: Dataset, local_dir: Path) -> None:
-    """Write episode metadata to a parquet file in the LeRobot v3.0 format.
-    This function writes episode-level metadata to a single parquet file.
-    Used primarily during dataset conversion (v2.1 → v3.0) and in test fixtures.
-
-    Args:
-        episodes: HuggingFace Dataset containing episode metadata
-        local_dir: Root directory where the dataset will be stored
-    """
-    episode_size_mb = get_hf_dataset_size_in_mb(episodes)
-    if episode_size_mb > DEFAULT_DATA_FILE_SIZE_IN_MB:
-        raise NotImplementedError(
-            f"Episodes dataset is too large ({episode_size_mb} MB) to write to a single file. "
-            f"The current limit is {DEFAULT_DATA_FILE_SIZE_IN_MB} MB. "
-            "This function only supports single-file episode metadata. "
-        )
-
-    fpath = local_dir / DEFAULT_EPISODES_PATH.format(chunk_index=0, file_index=0)
-    fpath.parent.mkdir(parents=True, exist_ok=True)
-    episodes.to_parquet(fpath)
-
-
-def load_episodes(local_dir: Path) -> datasets.Dataset:
-    episodes = load_nested_dataset(local_dir / EPISODES_DIR)
-    # Select episode features/columns containing references to episode data and videos
-    # (e.g. tasks, dataset_from_index, dataset_to_index, data/chunk_index, data/file_index, etc.)
-    # This is to speedup access to these data, instead of having to load episode stats.
-    episodes = episodes.select_columns([key for key in episodes.features if not key.startswith("stats/")])
-    return episodes
-
-
-def load_image_as_numpy(
-    fpath: str | Path, dtype: np.dtype = np.float32, channel_first: bool = True
-) -> np.ndarray:
-    """Load an image from a file into a numpy array.
-
-    Args:
-        fpath (str | Path): Path to the image file.
-        dtype (np.dtype): The desired data type of the output array. If floating,
-            pixels are scaled to [0, 1].
-        channel_first (bool): If True, converts the image to (C, H, W) format.
-            Otherwise, it remains in (H, W, C) format.
-
-    Returns:
-        np.ndarray: The image as a numpy array.
-    """
-    img = PILImage.open(fpath).convert("RGB")
-    img_array = np.array(img, dtype=dtype)
-    if channel_first:  # (H, W, C) -> (C, H, W)
-        img_array = np.transpose(img_array, (2, 0, 1))
-    if np.issubdtype(dtype, np.floating):
-        img_array /= 255.0
-    return img_array
-
-
-def hf_transform_to_torch(items_dict: dict[str, list[Any]]) -> dict[str, list[torch.Tensor | str]]:
-    """Convert a batch from a Hugging Face dataset to torch tensors.
-
-    This transform function converts items from Hugging Face dataset format (pyarrow)
-    to torch tensors. Importantly, images are converted from PIL objects (H, W, C, uint8)
-    to a torch image representation (C, H, W, float32) in the range [0, 1]. Other
-    types are converted to torch.tensor.
-
-    Args:
-        items_dict (dict): A dictionary representing a batch of data from a
-            Hugging Face dataset.
-
-    Returns:
-        dict: The batch with items converted to torch tensors.
-    """
-    for key in items_dict:
-        first_item = items_dict[key][0]
-        if isinstance(first_item, PILImage.Image):
-            to_tensor = transforms.ToTensor()
-            items_dict[key] = [to_tensor(img) for img in items_dict[key]]
-        elif first_item is None:
-            pass
-        else:
-            items_dict[key] = [x if isinstance(x, str) else torch.tensor(x) for x in items_dict[key]]
-    return items_dict
-
-
-def to_parquet_with_hf_images(
-    df: pandas.DataFrame, path: Path, features: datasets.Features | None = None
-) -> None:
-    """This function correctly writes to parquet a panda DataFrame that contains images encoded by HF dataset.
-    This way, it can be loaded by HF dataset and correctly formatted images are returned.
-
-    Args:
-        df: DataFrame to write to parquet.
-        path: Path to write the parquet file.
-        features: Optional HuggingFace Features schema. If provided, ensures image columns
-                  are properly typed as Image() in the parquet schema.
-    """
-    # TODO(qlhoest): replace this weird synthax by `df.to_parquet(path)` only
-    ds = datasets.Dataset.from_dict(df.to_dict(orient="list"), features=features)
-    ds.to_parquet(path)
-
-
-def item_to_torch(item: dict) -> dict:
-    """Convert all items in a dictionary to PyTorch tensors where appropriate.
-
-    This function is used to convert an item from a streaming dataset to PyTorch tensors.
-
-    Args:
-        item (dict): Dictionary of items from a dataset.
-
-    Returns:
-        dict: Dictionary with all tensor-like items converted to torch.Tensor.
-    """
-    for key, val in item.items():
-        if isinstance(val, (np.ndarray | list)) and key not in ["task"]:
-            # Convert numpy arrays and lists to torch tensors
-            item[key] = torch.tensor(val)
-    return item

src/lerobot/datasets/multi_dataset.py

@@ -1,217 +0,0 @@
-#!/usr/bin/env python
-
-# Copyright 2024 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.
-import logging
-from collections.abc import Callable
-from pathlib import Path
-
-import datasets
-import torch
-import torch.utils
-
-from lerobot.datasets.compute_stats import aggregate_stats
-from lerobot.datasets.feature_utils import get_hf_features_from_features
-from lerobot.datasets.lerobot_dataset import LeRobotDataset
-from lerobot.datasets.video_utils import VideoFrame
-from lerobot.utils.constants import HF_LEROBOT_HOME
-
-logger = logging.getLogger(__name__)
-
-
-class MultiLeRobotDataset(torch.utils.data.Dataset):
-    """A dataset consisting of multiple underlying `LeRobotDataset`s.
-
-    The underlying `LeRobotDataset`s are effectively concatenated, and this class adopts much of the API
-    structure of `LeRobotDataset`.
-    """
-
-    def __init__(
-        self,
-        repo_ids: list[str],
-        root: str | Path | None = None,
-        episodes: dict | None = None,
-        image_transforms: Callable | None = None,
-        delta_timestamps: dict[str, list[float]] | None = None,
-        tolerances_s: dict | None = None,
-        download_videos: bool = True,
-        video_backend: str | None = None,
-    ):
-        super().__init__()
-        self.repo_ids = repo_ids
-        self.root = Path(root) if root else HF_LEROBOT_HOME
-        self.tolerances_s = tolerances_s if tolerances_s else dict.fromkeys(repo_ids, 0.0001)
-        # Construct the underlying datasets passing everything but `transform` and `delta_timestamps` which
-        # are handled by this class.
-        self._datasets = [
-            LeRobotDataset(
-                repo_id,
-                root=self.root / repo_id,
-                episodes=episodes[repo_id] if episodes else None,
-                image_transforms=image_transforms,
-                delta_timestamps=delta_timestamps,
-                tolerance_s=self.tolerances_s[repo_id],
-                download_videos=download_videos,
-                video_backend=video_backend,
-            )
-            for repo_id in repo_ids
-        ]
-
-        # Disable any data keys that are not common across all of the datasets. Note: we may relax this
-        # restriction in future iterations of this class. For now, this is necessary at least for being able
-        # to use PyTorch's default DataLoader collate function.
-        self.disabled_features = set()
-        intersection_features = set(self._datasets[0].features)
-        for ds in self._datasets:
-            intersection_features.intersection_update(ds.features)
-        if len(intersection_features) == 0:
-            raise RuntimeError(
-                "Multiple datasets were provided but they had no keys common to all of them. "
-                "The multi-dataset functionality currently only keeps common keys."
-            )
-        for repo_id, ds in zip(self.repo_ids, self._datasets, strict=True):
-            extra_keys = set(ds.features).difference(intersection_features)
-            if extra_keys:
-                logger.warning(
-                    f"keys {extra_keys} of {repo_id} were disabled as they are not contained in all the "
-                    "other datasets."
-                )
-                self.disabled_features.update(extra_keys)
-
-        self.image_transforms = image_transforms
-        self.delta_timestamps = delta_timestamps
-        # TODO(rcadene, aliberts): We should not perform this aggregation for datasets
-        # with multiple robots of different ranges. Instead we should have one normalization
-        # per robot.
-        self.stats = aggregate_stats([dataset.meta.stats for dataset in self._datasets])
-
-    @property
-    def repo_id_to_index(self):
-        """Return a mapping from dataset repo_id to a dataset index automatically created by this class.
-
-        This index is incorporated as a data key in the dictionary returned by `__getitem__`.
-        """
-        return {repo_id: i for i, repo_id in enumerate(self.repo_ids)}
-
-    @property
-    def fps(self) -> int:
-        """Frames per second used during data collection.
-
-        NOTE: Fow now, this relies on a check in __init__ to make sure all sub-datasets have the same info.
-        """
-        return self._datasets[0].meta.info["fps"]
-
-    @property
-    def video(self) -> bool:
-        """Returns True if this dataset loads video frames from mp4 files.
-
-        Returns False if it only loads images from png files.
-
-        NOTE: Fow now, this relies on a check in __init__ to make sure all sub-datasets have the same info.
-        """
-        return self._datasets[0].meta.info.get("video", False)
-
-    @property
-    def features(self) -> datasets.Features:
-        features = {}
-        for dataset in self._datasets:
-            features.update(
-                {
-                    k: v
-                    for k, v in get_hf_features_from_features(dataset.features).items()
-                    if k not in self.disabled_features
-                }
-            )
-        return features
-
-    @property
-    def camera_keys(self) -> list[str]:
-        """Keys to access image and video stream from cameras."""
-        keys = []
-        for key, feats in self.features.items():
-            if isinstance(feats, (datasets.Image | VideoFrame)):
-                keys.append(key)
-        return keys
-
-    @property
-    def video_frame_keys(self) -> list[str]:
-        """Keys to access video frames that requires to be decoded into images.
-
-        Note: It is empty if the dataset contains images only,
-        or equal to `self.cameras` if the dataset contains videos only,
-        or can even be a subset of `self.cameras` in a case of a mixed image/video dataset.
-        """
-        video_frame_keys = []
-        for key, feats in self.features.items():
-            if isinstance(feats, VideoFrame):
-                video_frame_keys.append(key)
-        return video_frame_keys
-
-    @property
-    def num_frames(self) -> int:
-        """Number of samples/frames."""
-        return sum(d.num_frames for d in self._datasets)
-
-    @property
-    def num_episodes(self) -> int:
-        """Number of episodes."""
-        return sum(d.num_episodes for d in self._datasets)
-
-    @property
-    def tolerance_s(self) -> float:
-        """Tolerance in seconds used to discard loaded frames when their timestamps
-        are not close enough from the requested frames. It is only used when `delta_timestamps`
-        is provided or when loading video frames from mp4 files.
-        """
-        # 1e-4 to account for possible numerical error
-        return 1 / self.fps - 1e-4
-
-    def __len__(self):
-        return self.num_frames
-
-    def __getitem__(self, idx: int) -> dict[str, torch.Tensor]:
-        if idx >= len(self):
-            raise IndexError(f"Index {idx} out of bounds.")
-        # Determine which dataset to get an item from based on the index.
-        start_idx = 0
-        dataset_idx = 0
-        for dataset in self._datasets:
-            if idx >= start_idx + dataset.num_frames:
-                start_idx += dataset.num_frames
-                dataset_idx += 1
-                continue
-            break
-        else:
-            raise AssertionError("We expect the loop to break out as long as the index is within bounds.")
-        item = self._datasets[dataset_idx][idx - start_idx]
-        item["dataset_index"] = torch.tensor(dataset_idx)
-        for data_key in self.disabled_features:
-            if data_key in item:
-                del item[data_key]
-
-        return item
-
-    def __repr__(self):
-        return (
-            f"{self.__class__.__name__}(\n"
-            f"  Repository IDs: '{self.repo_ids}',\n"
-            f"  Number of Samples: {self.num_frames},\n"
-            f"  Number of Episodes: {self.num_episodes},\n"
-            f"  Type: {'video (.mp4)' if self.video else 'image (.png)'},\n"
-            f"  Recorded Frames per Second: {self.fps},\n"
-            f"  Camera Keys: {self.camera_keys},\n"
-            f"  Video Frame Keys: {self.video_frame_keys if self.video else 'N/A'},\n"
-            f"  Transformations: {self.image_transforms},\n"
-            f")"
-        )

src/lerobot/datasets/online_buffer.py

@@ -0,0 +1,382 @@
+#!/usr/bin/env python
+
+# Copyright 2024 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.
+"""An online buffer for the online training loop in train.py
+
+Note to maintainers: This duplicates some logic from LeRobotDataset and EpisodeAwareSampler. We should
+consider converging to one approach. Here we have opted to use numpy.memmap to back the data buffer. It's much
+faster than using HuggingFace Datasets as there's no conversion to an intermediate non-python object. Also it
+supports in-place slicing and mutation which is very handy for a dynamic buffer.
+"""
+
+import os
+from pathlib import Path
+from typing import Any
+
+import numpy as np
+import torch
+
+from lerobot.datasets.lerobot_dataset import LeRobotDataset
+
+
+def _make_memmap_safe(**kwargs) -> np.memmap:
+    """Make a numpy memmap with checks on available disk space first.
+
+    Expected kwargs are: "filename", "dtype" (must by np.dtype), "mode" and "shape"
+
+    For information on dtypes:
+    https://numpy.org/doc/stable/reference/arrays.dtypes.html#arrays-dtypes-constructing
+    """
+    if kwargs["mode"].startswith("w"):
+        required_space = kwargs["dtype"].itemsize * np.prod(kwargs["shape"])  # bytes
+        stats = os.statvfs(Path(kwargs["filename"]).parent)
+        available_space = stats.f_bavail * stats.f_frsize  # bytes
+        if required_space >= available_space * 0.8:
+            raise RuntimeError(
+                f"You're about to take up {required_space} of {available_space} bytes available."
+            )
+    return np.memmap(**kwargs)
+
+
+class OnlineBuffer(torch.utils.data.Dataset):
+    """FIFO data buffer for the online training loop in train.py.
+
+    Follows the protocol of LeRobotDataset as much as is required to have it be used by the online training
+    loop in the same way that a LeRobotDataset would be used.
+
+    The underlying data structure will have data inserted in a circular fashion. Always insert after the
+    last index, and when you reach the end, wrap around to the start.
+
+    The data is stored in a numpy memmap.
+    """
+
+    NEXT_INDEX_KEY = "_next_index"
+    OCCUPANCY_MASK_KEY = "_occupancy_mask"
+    INDEX_KEY = "index"
+    FRAME_INDEX_KEY = "frame_index"
+    EPISODE_INDEX_KEY = "episode_index"
+    TIMESTAMP_KEY = "timestamp"
+    IS_PAD_POSTFIX = "_is_pad"
+
+    def __init__(
+        self,
+        write_dir: str | Path,
+        data_spec: dict[str, Any] | None,
+        buffer_capacity: int | None,
+        fps: float | None = None,
+        delta_timestamps: dict[str, list[float]] | dict[str, np.ndarray] | None = None,
+    ):
+        """
+        The online buffer can be provided from scratch or you can load an existing online buffer by passing
+        a `write_dir` associated with an existing buffer.
+
+        Args:
+            write_dir: Where to keep the numpy memmap files. One memmap file will be stored for each data key.
+                Note that if the files already exist, they are opened in read-write mode (used for training
+                resumption.)
+            data_spec: A mapping from data key to data specification, like {data_key: {"shape": tuple[int],
+                "dtype": np.dtype}}. This should include all the data that you wish to record into the buffer,
+                but note that "index", "frame_index" and "episode_index" are already accounted for by this
+                class, so you don't need to include them.
+            buffer_capacity: How many frames should be stored in the buffer as a maximum. Be aware of your
+                system's available disk space when choosing this.
+            fps: Same as the fps concept in LeRobot dataset. Here it needs to be provided for the
+                 delta_timestamps logic. You can pass None if you are not using delta_timestamps.
+            delta_timestamps: Same as the delta_timestamps concept in LeRobotDataset. This is internally
+                converted to dict[str, np.ndarray] for optimization purposes.
+
+        """
+        self.set_delta_timestamps(delta_timestamps)
+        self._fps = fps
+        # Tolerance in seconds used to discard loaded frames when their timestamps are not close enough from
+        # the requested frames. It is only used when `delta_timestamps` is provided.
+        # minus 1e-4 to account for possible numerical error
+        self.tolerance_s = 1 / self.fps - 1e-4 if fps is not None else None
+        self._buffer_capacity = buffer_capacity
+        data_spec = self._make_data_spec(data_spec, buffer_capacity)
+        Path(write_dir).mkdir(parents=True, exist_ok=True)
+        self._data = {}
+        for k, v in data_spec.items():
+            self._data[k] = _make_memmap_safe(
+                filename=Path(write_dir) / k,
+                dtype=v["dtype"] if v is not None else None,
+                mode="r+" if (Path(write_dir) / k).exists() else "w+",
+                shape=tuple(v["shape"]) if v is not None else None,
+            )
+
+    @property
+    def delta_timestamps(self) -> dict[str, np.ndarray] | None:
+        return self._delta_timestamps
+
+    def set_delta_timestamps(self, value: dict[str, list[float]] | None):
+        """Set delta_timestamps converting the values to numpy arrays.
+
+        The conversion is for an optimization in the __getitem__. The loop is much slower if the arrays
+        need to be converted into numpy arrays.
+        """
+        if value is not None:
+            self._delta_timestamps = {k: np.array(v) for k, v in value.items()}
+        else:
+            self._delta_timestamps = None
+
+    def _make_data_spec(self, data_spec: dict[str, Any], buffer_capacity: int) -> dict[str, dict[str, Any]]:
+        """Makes the data spec for np.memmap."""
+        if any(k.startswith("_") for k in data_spec):
+            raise ValueError(
+                "data_spec keys should not start with '_'. This prefix is reserved for internal logic."
+            )
+        preset_keys = {
+            OnlineBuffer.INDEX_KEY,
+            OnlineBuffer.FRAME_INDEX_KEY,
+            OnlineBuffer.EPISODE_INDEX_KEY,
+            OnlineBuffer.TIMESTAMP_KEY,
+        }
+        if len(intersection := set(data_spec).intersection(preset_keys)) > 0:
+            raise ValueError(
+                f"data_spec should not contain any of {preset_keys} as these are handled internally. "
+                f"The provided data_spec has {intersection}."
+            )
+        complete_data_spec = {
+            # _next_index will be a pointer to the next index that we should start filling from when we add
+            # more data.
+            OnlineBuffer.NEXT_INDEX_KEY: {"dtype": np.dtype("int64"), "shape": ()},
+            # Since the memmap is initialized with all-zeros, this keeps track of which indices are occupied
+            # with real data rather than the dummy initialization.
+            OnlineBuffer.OCCUPANCY_MASK_KEY: {"dtype": np.dtype("?"), "shape": (buffer_capacity,)},
+            OnlineBuffer.INDEX_KEY: {"dtype": np.dtype("int64"), "shape": (buffer_capacity,)},
+            OnlineBuffer.FRAME_INDEX_KEY: {"dtype": np.dtype("int64"), "shape": (buffer_capacity,)},
+            OnlineBuffer.EPISODE_INDEX_KEY: {"dtype": np.dtype("int64"), "shape": (buffer_capacity,)},
+            OnlineBuffer.TIMESTAMP_KEY: {"dtype": np.dtype("float64"), "shape": (buffer_capacity,)},
+        }
+        for k, v in data_spec.items():
+            complete_data_spec[k] = {"dtype": v["dtype"], "shape": (buffer_capacity, *v["shape"])}
+        return complete_data_spec
+
+    def add_data(self, data: dict[str, np.ndarray]):
+        """Add new data to the buffer, which could potentially mean shifting old data out.
+
+        The new data should contain all the frames (in order) of any number of episodes. The indices should
+        start from 0 (note to the developer: this can easily be generalized). See the `rollout` and
+        `eval_policy` functions in `eval.py` for more information on how the data is constructed.
+
+        Shift the incoming data index and episode_index to continue on from the last frame. Note that this
+        will be done in place!
+        """
+        if len(missing_keys := (set(self.data_keys).difference(set(data)))) > 0:
+            raise ValueError(f"Missing data keys: {missing_keys}")
+        new_data_length = len(data[self.data_keys[0]])
+        if not all(len(data[k]) == new_data_length for k in self.data_keys):
+            raise ValueError("All data items should have the same length")
+
+        next_index = self._data[OnlineBuffer.NEXT_INDEX_KEY]
+
+        # Sanity check to make sure that the new data indices start from 0.
+        assert data[OnlineBuffer.EPISODE_INDEX_KEY][0].item() == 0
+        assert data[OnlineBuffer.INDEX_KEY][0].item() == 0
+
+        # Shift the incoming indices if necessary.
+        if self.num_frames > 0:
+            last_episode_index = self._data[OnlineBuffer.EPISODE_INDEX_KEY][next_index - 1]
+            last_data_index = self._data[OnlineBuffer.INDEX_KEY][next_index - 1]
+            data[OnlineBuffer.EPISODE_INDEX_KEY] += last_episode_index + 1
+            data[OnlineBuffer.INDEX_KEY] += last_data_index + 1
+
+        # Insert the new data starting from next_index. It may be necessary to wrap around to the start.
+        n_surplus = max(0, new_data_length - (self._buffer_capacity - next_index))
+        for k in self.data_keys:
+            if n_surplus == 0:
+                slc = slice(next_index, next_index + new_data_length)
+                self._data[k][slc] = data[k]
+                self._data[OnlineBuffer.OCCUPANCY_MASK_KEY][slc] = True
+            else:
+                self._data[k][next_index:] = data[k][:-n_surplus]
+                self._data[OnlineBuffer.OCCUPANCY_MASK_KEY][next_index:] = True
+                self._data[k][:n_surplus] = data[k][-n_surplus:]
+        if n_surplus == 0:
+            self._data[OnlineBuffer.NEXT_INDEX_KEY] = next_index + new_data_length
+        else:
+            self._data[OnlineBuffer.NEXT_INDEX_KEY] = n_surplus
+
+    @property
+    def data_keys(self) -> list[str]:
+        keys = set(self._data)
+        keys.remove(OnlineBuffer.OCCUPANCY_MASK_KEY)
+        keys.remove(OnlineBuffer.NEXT_INDEX_KEY)
+        return sorted(keys)
+
+    @property
+    def fps(self) -> float | None:
+        return self._fps
+
+    @property
+    def num_episodes(self) -> int:
+        return len(
+            np.unique(self._data[OnlineBuffer.EPISODE_INDEX_KEY][self._data[OnlineBuffer.OCCUPANCY_MASK_KEY]])
+        )
+
+    @property
+    def num_frames(self) -> int:
+        return np.count_nonzero(self._data[OnlineBuffer.OCCUPANCY_MASK_KEY])
+
+    def __len__(self):
+        return self.num_frames
+
+    def _item_to_tensors(self, item: dict) -> dict:
+        item_ = {}
+        for k, v in item.items():
+            if isinstance(v, torch.Tensor):
+                item_[k] = v
+            elif isinstance(v, np.ndarray):
+                item_[k] = torch.from_numpy(v)
+            else:
+                item_[k] = torch.tensor(v)
+        return item_
+
+    def __getitem__(self, idx: int) -> dict[str, torch.Tensor]:
+        if idx >= len(self) or idx < -len(self):
+            raise IndexError
+
+        item = {k: v[idx] for k, v in self._data.items() if not k.startswith("_")}
+
+        if self.delta_timestamps is None:
+            return self._item_to_tensors(item)
+
+        episode_index = item[OnlineBuffer.EPISODE_INDEX_KEY]
+        current_ts = item[OnlineBuffer.TIMESTAMP_KEY]
+        episode_data_indices = np.where(
+            np.bitwise_and(
+                self._data[OnlineBuffer.EPISODE_INDEX_KEY] == episode_index,
+                self._data[OnlineBuffer.OCCUPANCY_MASK_KEY],
+            )
+        )[0]
+        episode_timestamps = self._data[OnlineBuffer.TIMESTAMP_KEY][episode_data_indices]
+
+        for data_key in self.delta_timestamps:
+            # Note: The logic in this loop is copied from `load_previous_and_future_frames`.
+            # Get timestamps used as query to retrieve data of previous/future frames.
+            query_ts = current_ts + self.delta_timestamps[data_key]
+
+            # Compute distances between each query timestamp and all timestamps of all the frames belonging to
+            # the episode.
+            dist = np.abs(query_ts[:, None] - episode_timestamps[None, :])
+            argmin_ = np.argmin(dist, axis=1)
+            min_ = dist[np.arange(dist.shape[0]), argmin_]
+
+            is_pad = min_ > self.tolerance_s
+
+            # Check violated query timestamps are all outside the episode range.
+            assert (
+                (query_ts[is_pad] < episode_timestamps[0]) | (episode_timestamps[-1] < query_ts[is_pad])
+            ).all(), (
+                f"One or several timestamps unexpectedly violate the tolerance ({min_} > {self.tolerance_s=}"
+                ") inside the episode range."
+            )
+
+            # Load frames for this data key.
+            item[data_key] = self._data[data_key][episode_data_indices[argmin_]]
+
+            item[f"{data_key}{OnlineBuffer.IS_PAD_POSTFIX}"] = is_pad
+
+        return self._item_to_tensors(item)
+
+    def get_data_by_key(self, key: str) -> torch.Tensor:
+        """Returns all data for a given data key as a Tensor."""
+        return torch.from_numpy(self._data[key][self._data[OnlineBuffer.OCCUPANCY_MASK_KEY]])
+
+
+def compute_sampler_weights(
+    offline_dataset: LeRobotDataset,
+    offline_drop_n_last_frames: int = 0,
+    online_dataset: OnlineBuffer | None = None,
+    online_sampling_ratio: float | None = None,
+    online_drop_n_last_frames: int = 0,
+) -> torch.Tensor:
+    """Compute the sampling weights for the online training dataloader in train.py.
+
+    Args:
+        offline_dataset: The LeRobotDataset used for offline pre-training.
+        online_drop_n_last_frames: Number of frames to drop from the end of each offline dataset episode.
+        online_dataset: The OnlineBuffer used in online training.
+        online_sampling_ratio: The proportion of data that should be sampled from the online dataset. If an
+            online dataset is provided, this value must also be provided.
+        online_drop_n_first_frames: See `offline_drop_n_last_frames`. This is the same, but for the online
+            dataset.
+    Returns:
+        Tensor of weights for [offline_dataset; online_dataset], normalized to 1.
+
+    Notes to maintainers:
+        - This duplicates some logic from EpisodeAwareSampler. We should consider converging to one approach.
+        - When used with `torch.utils.data.WeightedRandomSampler`, it could completely replace
+          `EpisodeAwareSampler` as the online dataset related arguments are optional. The only missing feature
+          is the ability to turn shuffling off.
+        - Options `drop_first_n_frames` and `episode_indices_to_use` can be added easily. They were not
+          included here to avoid adding complexity.
+    """
+    if len(offline_dataset) == 0 and (online_dataset is None or len(online_dataset) == 0):
+        raise ValueError("At least one of `offline_dataset` or `online_dataset` should be contain data.")
+    if (online_dataset is None) ^ (online_sampling_ratio is None):
+        raise ValueError(
+            "`online_dataset` and `online_sampling_ratio` must be provided together or not at all."
+        )
+    offline_sampling_ratio = 0 if online_sampling_ratio is None else 1 - online_sampling_ratio
+
+    weights = []
+
+    if len(offline_dataset) > 0:
+        offline_data_mask_indices = []
+        for start_index, end_index in zip(
+            offline_dataset.meta.episodes["dataset_from_index"],
+            offline_dataset.meta.episodes["dataset_to_index"],
+            strict=True,
+        ):
+            offline_data_mask_indices.extend(range(start_index, end_index - offline_drop_n_last_frames))
+        offline_data_mask = torch.zeros(len(offline_dataset), dtype=torch.bool)
+        offline_data_mask[torch.tensor(offline_data_mask_indices)] = True
+        weights.append(
+            torch.full(
+                size=(len(offline_dataset),),
+                fill_value=offline_sampling_ratio / offline_data_mask.sum(),
+            )
+            * offline_data_mask
+        )
+
+    if online_dataset is not None and len(online_dataset) > 0:
+        online_data_mask_indices = []
+        episode_indices = online_dataset.get_data_by_key("episode_index")
+        for episode_idx in torch.unique(episode_indices):
+            where_episode = torch.where(episode_indices == episode_idx)
+            start_index = where_episode[0][0]
+            end_index = where_episode[0][-1] + 1
+            online_data_mask_indices.extend(
+                range(start_index.item(), end_index.item() - online_drop_n_last_frames)
+            )
+        online_data_mask = torch.zeros(len(online_dataset), dtype=torch.bool)
+        online_data_mask[torch.tensor(online_data_mask_indices)] = True
+        weights.append(
+            torch.full(
+                size=(len(online_dataset),),
+                fill_value=online_sampling_ratio / online_data_mask.sum(),
+            )
+            * online_data_mask
+        )
+
+    weights = torch.cat(weights)
+
+    if weights.sum() == 0:
+        weights += 1 / len(weights)
+    else:
+        weights /= weights.sum()
+
+    return weights

src/lerobot/datasets/pipeline_features.py

@@ -17,9 +17,8 @@ from collections.abc import Sequence
 from typing import Any
 
 from lerobot.configs.types import PipelineFeatureType
-from lerobot.datasets.feature_utils import hw_to_dataset_features
-from lerobot.processor import DataProcessorPipeline
-from lerobot.types import RobotAction, RobotObservation
+from lerobot.datasets.utils import hw_to_dataset_features
+from lerobot.processor import DataProcessorPipeline, RobotAction, RobotObservation
 from lerobot.utils.constants import ACTION, OBS_IMAGES, OBS_STATE, OBS_STR
 
 
@@ -44,11 +43,11 @@ def create_initial_features(
     return features
 
 
-# Helper to filter state/action keys based on compiled regex patterns.
-def should_keep(key: str, patterns: tuple[re.Pattern] | None) -> bool:
+# Helper to filter state/action keys based on regex patterns.
+def should_keep(key: str, patterns: tuple[str]) -> bool:
     if patterns is None:
         return True
-    return any(pat.search(key) for pat in patterns)
+    return any(re.search(pat, key) for pat in patterns)
 
 
 def strip_prefix(key: str, prefixes_to_strip: tuple[str]) -> str:
@@ -89,8 +88,6 @@ def aggregate_pipeline_dataset_features(
     Returns:
         A dictionary of features formatted for a Hugging Face LeRobot Dataset.
     """
-    compiled_patterns = tuple(re.compile(p) for p in patterns) if patterns is not None else None
-
     all_features = pipeline.transform_features(initial_features)
 
     # Intermediate storage for categorized and filtered features.
@@ -122,7 +119,7 @@ def aggregate_pipeline_dataset_features(
             # 2. Apply filtering rules.
             if is_image and not use_videos:
                 continue
-            if not is_image and not should_keep(key, compiled_patterns):
+            if not is_image and not should_keep(key, patterns):
                 continue
 
             # 3. Add the feature to the appropriate group with a clean name.

src/lerobot/datasets/push_dataset_to_hub/utils.py

@@ -0,0 +1,73 @@
+#!/usr/bin/env python
+
+# Copyright 2024 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.
+
+import datasets
+import torch
+
+
+# TODO(aliberts): remove
+def calculate_episode_data_index(hf_dataset: datasets.Dataset) -> dict[str, torch.Tensor]:
+    """
+    Calculate episode data index for the provided HuggingFace Dataset. Relies on episode_index column of hf_dataset.
+
+    Parameters:
+    - hf_dataset (datasets.Dataset): A HuggingFace dataset containing the episode index.
+
+    Returns:
+    - episode_data_index: A dictionary containing the data index for each episode. The dictionary has two keys:
+        - "from": A tensor containing the starting index of each episode.
+        - "to": A tensor containing the ending index of each episode.
+    """
+    episode_data_index = {"from": [], "to": []}
+
+    current_episode = None
+    """
+    The episode_index is a list of integers, each representing the episode index of the corresponding example.
+    For instance, the following is a valid episode_index:
+      [0, 0, 0, 1, 1, 1, 1, 2, 2, 2, 2, 2]
+
+    Below, we iterate through the episode_index and populate the episode_data_index dictionary with the starting and
+    ending index of each episode. For the episode_index above, the episode_data_index dictionary will look like this:
+        {
+            "from": [0, 3, 7],
+            "to": [3, 7, 12]
+        }
+    """
+    if len(hf_dataset) == 0:
+        episode_data_index = {
+            "from": torch.tensor([]),
+            "to": torch.tensor([]),
+        }
+        return episode_data_index
+    for idx, episode_idx in enumerate(hf_dataset["episode_index"]):
+        if episode_idx != current_episode:
+            # We encountered a new episode, so we append its starting location to the "from" list
+            episode_data_index["from"].append(idx)
+            # If this is not the first episode, we append the ending location of the previous episode to the "to" list
+            if current_episode is not None:
+                episode_data_index["to"].append(idx)
+            # Let's keep track of the current episode index
+            current_episode = episode_idx
+        else:
+            # We are still in the same episode, so there is nothing for us to do here
+            pass
+    # We have reached the end of the dataset, so we append the ending location of the last episode to the "to" list
+    episode_data_index["to"].append(idx + 1)
+
+    for k in ["from", "to"]:
+        episode_data_index[k] = torch.tensor(episode_data_index[k])
+
+    return episode_data_index

src/lerobot/datasets/sampler.py

@@ -13,13 +13,10 @@
 # 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.
-import logging
 from collections.abc import Iterator
 
 import torch
 
-logger = logging.getLogger(__name__)
-
 
 class EpisodeAwareSampler:
     def __init__(
@@ -42,35 +39,13 @@ class EpisodeAwareSampler:
             drop_n_last_frames: Number of frames to drop from the end of each episode.
             shuffle: Whether to shuffle the indices.
         """
-        if drop_n_first_frames < 0:
-            raise ValueError(f"drop_n_first_frames must be >= 0, got {drop_n_first_frames}")
-        if drop_n_last_frames < 0:
-            raise ValueError(f"drop_n_last_frames must be >= 0, got {drop_n_last_frames}")
-
         indices = []
         for episode_idx, (start_index, end_index) in enumerate(
             zip(dataset_from_indices, dataset_to_indices, strict=True)
         ):
             if episode_indices_to_use is None or episode_idx in episode_indices_to_use:
-                ep_length = end_index - start_index
-                if drop_n_first_frames + drop_n_last_frames >= ep_length:
-                    logger.warning(
-                        "Episode %d has %d frames but drop_n_first_frames=%d and "
-                        "drop_n_last_frames=%d removes all frames. Skipping.",
-                        episode_idx,
-                        ep_length,
-                        drop_n_first_frames,
-                        drop_n_last_frames,
-                    )
-                    continue
                 indices.extend(range(start_index + drop_n_first_frames, end_index - drop_n_last_frames))
 
-        if not indices:
-            raise ValueError(
-                "No valid frames remain after applying drop_n_first_frames and drop_n_last_frames. "
-                "All episodes were either filtered out or had too few frames."
-            )
-
         self.indices = indices
         self.shuffle = shuffle
 

src/lerobot/datasets/streaming_dataset.py

@@ -13,8 +13,7 @@
 # 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 collections import deque
-from collections.abc import Callable, Generator, Iterable, Iterator
+from collections.abc import Callable, Generator, Iterator
 from pathlib import Path
 
 import datasets
@@ -22,13 +21,16 @@ import numpy as np
 import torch
 from datasets import load_dataset
 
-from lerobot.datasets.dataset_metadata import CODEBASE_VERSION, LeRobotDatasetMetadata
-from lerobot.datasets.feature_utils import get_delta_indices
-from lerobot.datasets.io_utils import item_to_torch
+from lerobot.datasets.lerobot_dataset import CODEBASE_VERSION, LeRobotDatasetMetadata
 from lerobot.datasets.utils import (
+    Backtrackable,
+    LookAheadError,
+    LookBackError,
     check_version_compatibility,
     find_float_index,
+    get_delta_indices,
     is_float_in_list,
+    item_to_torch,
     safe_shard,
 )
 from lerobot.datasets.video_utils import (
@@ -38,164 +40,6 @@ from lerobot.datasets.video_utils import (
 from lerobot.utils.constants import HF_LEROBOT_HOME, LOOKAHEAD_BACKTRACKTABLE, LOOKBACK_BACKTRACKTABLE
 
 
-class LookBackError(Exception):
-    """
-    Exception raised when trying to look back in the history of a Backtrackable object.
-    """
-
-    pass
-
-
-class LookAheadError(Exception):
-    """
-    Exception raised when trying to look ahead in the future of a Backtrackable object.
-    """
-
-    pass
-
-
-class Backtrackable[T]:
-    """
-    Wrap any iterator/iterable so you can step back up to `history` items
-    and look ahead up to `lookahead` items.
-
-    This is useful for streaming datasets where you need to access previous and future items
-    but can't load the entire dataset into memory.
-
-    Example:
-    -------
-    ```python
-    ds = load_dataset("c4", "en", streaming=True, split="train")
-    rev = Backtrackable(ds, history=3, lookahead=2)
-
-    x0 = next(rev)  # forward
-    x1 = next(rev)
-    x2 = next(rev)
-
-    # Look ahead
-    x3_peek = rev.peek_ahead(1)  # next item without moving cursor
-    x4_peek = rev.peek_ahead(2)  # two items ahead
-
-    # Look back
-    x1_again = rev.peek_back(1)  # previous item without moving cursor
-    x0_again = rev.peek_back(2)  # two items back
-
-    # Move backward
-    x1_back = rev.prev()  # back one step
-    next(rev)  # returns x2, continues forward from where we were
-    ```
-    """
-
-    __slots__ = ("_source", "_back_buf", "_ahead_buf", "_cursor", "_history", "_lookahead")
-
-    def __init__(self, iterable: Iterable[T], *, history: int = 1, lookahead: int = 0):
-        if history < 1:
-            raise ValueError("history must be >= 1")
-        if lookahead <= 0:
-            raise ValueError("lookahead must be > 0")
-
-        self._source: Iterator[T] = iter(iterable)
-        self._back_buf: deque[T] = deque(maxlen=history)
-        self._ahead_buf: deque[T] = deque(maxlen=lookahead) if lookahead > 0 else deque()
-        self._cursor: int = 0
-        self._history = history
-        self._lookahead = lookahead
-
-    def __iter__(self) -> "Backtrackable[T]":
-        return self
-
-    def __next__(self) -> T:
-        # If we've stepped back, consume from back buffer first
-        if self._cursor < 0:  # -1 means "last item", etc.
-            self._cursor += 1
-            return self._back_buf[self._cursor]
-
-        # If we have items in the ahead buffer, use them first
-        item = self._ahead_buf.popleft() if self._ahead_buf else next(self._source)
-
-        # Add current item to back buffer and reset cursor
-        self._back_buf.append(item)
-        self._cursor = 0
-        return item
-
-    def prev(self) -> T:
-        """
-        Step one item back in history and return it.
-        Raises IndexError if already at the oldest buffered item.
-        """
-        if len(self._back_buf) + self._cursor <= 1:
-            raise LookBackError("At start of history")
-
-        self._cursor -= 1
-        return self._back_buf[self._cursor]
-
-    def peek_back(self, n: int = 1) -> T:
-        """
-        Look `n` items back (n=1 == previous item) without moving the cursor.
-        """
-        if n < 0 or n + 1 > len(self._back_buf) + self._cursor:
-            raise LookBackError("peek_back distance out of range")
-
-        return self._back_buf[self._cursor - (n + 1)]
-
-    def peek_ahead(self, n: int = 1) -> T:
-        """
-        Look `n` items ahead (n=1 == next item) without moving the cursor.
-        Fills the ahead buffer if necessary.
-        """
-        if n < 1:
-            raise LookAheadError("peek_ahead distance must be 1 or more")
-        elif n > self._lookahead:
-            raise LookAheadError("peek_ahead distance exceeds lookahead limit")
-
-        # Fill ahead buffer if we don't have enough items
-        while len(self._ahead_buf) < n:
-            try:
-                item = next(self._source)
-                self._ahead_buf.append(item)
-
-            except StopIteration as err:
-                raise LookAheadError("peek_ahead: not enough items in source") from err
-
-        return self._ahead_buf[n - 1]
-
-    def history(self) -> list[T]:
-        """
-        Return a copy of the buffered history (most recent last).
-        The list length ≤ `history` argument passed at construction.
-        """
-        if self._cursor == 0:
-            return list(self._back_buf)
-
-        # When cursor<0, slice so the order remains chronological
-        return list(self._back_buf)[: self._cursor or None]
-
-    def can_peek_back(self, steps: int = 1) -> bool:
-        """
-        Check if we can go back `steps` items without raising an IndexError.
-        """
-        return steps <= len(self._back_buf) + self._cursor
-
-    def can_peek_ahead(self, steps: int = 1) -> bool:
-        """
-        Check if we can peek ahead `steps` items.
-        This may involve trying to fill the ahead buffer.
-        """
-        if self._lookahead > 0 and steps > self._lookahead:
-            return False
-
-        # Try to fill ahead buffer to check if we can peek that far
-        try:
-            while len(self._ahead_buf) < steps:
-                if self._lookahead > 0 and len(self._ahead_buf) >= self._lookahead:
-                    return False
-                item = next(self._source)
-                self._ahead_buf.append(item)
-            return True
-        except StopIteration:
-            return False
-
-
 class StreamingLeRobotDataset(torch.utils.data.IterableDataset):
     """LeRobotDataset with streaming capabilities.
 
@@ -255,9 +99,7 @@ class StreamingLeRobotDataset(torch.utils.data.IterableDataset):
 
         Args:
             repo_id (str): This is the repo id that will be used to fetch the dataset.
-            root (Path | None, optional): Local directory to use for local datasets. When omitted, Hub
-                metadata is resolved through a revision-safe snapshot cache under
-                ``$HF_LEROBOT_HOME/hub``.
+            root (Path | None, optional): Local directory to use for downloading/writing files.
             episodes (list[int] | None, optional): If specified, this will only load episodes specified by
                 their episode_index in this list.
             image_transforms (Callable | None, optional): Transform to apply to image data.
@@ -273,8 +115,7 @@ class StreamingLeRobotDataset(torch.utils.data.IterableDataset):
         """
         super().__init__()
         self.repo_id = repo_id
-        self._requested_root = Path(root) if root else None
-        self.root = self._requested_root if self._requested_root is not None else HF_LEROBOT_HOME / repo_id
+        self.root = Path(root) if root else HF_LEROBOT_HOME / repo_id
         self.streaming_from_local = root is not None
 
         self.image_transforms = image_transforms
@@ -291,15 +132,12 @@ class StreamingLeRobotDataset(torch.utils.data.IterableDataset):
         # We cache the video decoders to avoid re-initializing them at each frame (avoiding a ~10x slowdown)
         self.video_decoder_cache = None
 
-        if self._requested_root is not None:
-            self.root.mkdir(exist_ok=True, parents=True)
+        self.root.mkdir(exist_ok=True, parents=True)
 
         # Load metadata
         self.meta = LeRobotDatasetMetadata(
-            self.repo_id, self._requested_root, self.revision, force_cache_sync=force_cache_sync
+            self.repo_id, self.root, self.revision, force_cache_sync=force_cache_sync
         )
-        self.root = self.meta.root
-        self.revision = self.meta.revision
         # Check version
         check_version_compatibility(self.repo_id, self.meta._version, CODEBASE_VERSION)
 

src/lerobot/datasets/v30/augment_dataset_quantile_stats.py

@@ -28,7 +28,7 @@ quantile statistics (q01, q10, q50, q90, q99) in their metadata. This script:
 Usage:
 
 ```bash
-python src/lerobot/scripts/augment_dataset_quantile_stats.py \
+python src/lerobot/datasets/v30/augment_dataset_quantile_stats.py \
     --repo-id=lerobot/pusht \
 ```
 """
@@ -45,9 +45,8 @@ from requests import HTTPError
 from tqdm import tqdm
 
 from lerobot.datasets.compute_stats import DEFAULT_QUANTILES, aggregate_stats, get_feature_stats
-from lerobot.datasets.dataset_metadata import CODEBASE_VERSION
-from lerobot.datasets.io_utils import write_stats
-from lerobot.datasets.lerobot_dataset import LeRobotDataset
+from lerobot.datasets.lerobot_dataset import CODEBASE_VERSION, LeRobotDataset
+from lerobot.datasets.utils import write_stats
 from lerobot.utils.utils import init_logging
 
 

src/lerobot/datasets/v30/convert_dataset_v21_to_v30.py

@@ -28,13 +28,13 @@ Usage:
 
 Convert a dataset from the hub:
 ```bash
-python src/lerobot/scripts/convert_dataset_v21_to_v30.py \
+python src/lerobot/datasets/v30/convert_dataset_v21_to_v30.py \
     --repo-id=lerobot/pusht
 ```
 
 Convert a local dataset (works in place):
 ```bash
-python src/lerobot/scripts/convert_dataset_v21_to_v30.py \
+python src/lerobot/datasets/v30/convert_dataset_v21_to_v30.py \
     --repo-id=lerobot/pusht \
     --root=/path/to/local/dataset/directory \
     --push-to-hub=false
@@ -60,19 +60,7 @@ from huggingface_hub import HfApi, snapshot_download
 from requests import HTTPError
 
 from lerobot.datasets.compute_stats import aggregate_stats
-from lerobot.datasets.dataset_metadata import CODEBASE_VERSION
-from lerobot.datasets.io_utils import (
-    cast_stats_to_numpy,
-    get_file_size_in_mb,
-    get_parquet_file_size_in_mb,
-    get_parquet_num_frames,
-    load_info,
-    write_episodes,
-    write_info,
-    write_stats,
-    write_tasks,
-)
-from lerobot.datasets.lerobot_dataset import LeRobotDataset
+from lerobot.datasets.lerobot_dataset import CODEBASE_VERSION, LeRobotDataset
 from lerobot.datasets.utils import (
     DEFAULT_CHUNK_SIZE,
     DEFAULT_DATA_FILE_SIZE_IN_MB,
@@ -82,8 +70,17 @@ from lerobot.datasets.utils import (
     LEGACY_EPISODES_PATH,
     LEGACY_EPISODES_STATS_PATH,
     LEGACY_TASKS_PATH,
+    cast_stats_to_numpy,
     flatten_dict,
+    get_file_size_in_mb,
+    get_parquet_file_size_in_mb,
+    get_parquet_num_frames,
+    load_info,
     update_chunk_file_indices,
+    write_episodes,
+    write_info,
+    write_stats,
+    write_tasks,
 )
 from lerobot.datasets.video_utils import concatenate_video_files, get_video_duration_in_s
 from lerobot.utils.constants import HF_LEROBOT_HOME

src/lerobot/datasets/video_utils.py

@@ -37,8 +37,6 @@ import torchvision
 from datasets.features.features import register_feature
 from PIL import Image
 
-logger = logging.getLogger(__name__)
-
 # List of hardware encoders to probe for auto-selection. Availability depends on the platform and FFmpeg build.
 # Determines the order of preference for auto-selection when vcodec="auto" is used.
 HW_ENCODERS = [
@@ -96,7 +94,7 @@ def detect_available_hw_encoders() -> list[str]:
             av.codec.Codec(codec_name, "w")
             available.append(codec_name)
         except Exception:  # nosec B110
-            logger.debug("HW encoder '%s' not available", codec_name)  # nosec B110
+            pass  # nosec B110
     return available
 
 
@@ -105,14 +103,14 @@ def resolve_vcodec(vcodec: str) -> str:
     if vcodec not in VALID_VIDEO_CODECS:
         raise ValueError(f"Invalid vcodec '{vcodec}'. Must be one of: {sorted(VALID_VIDEO_CODECS)}")
     if vcodec != "auto":
-        logger.info(f"Using video codec: {vcodec}")
+        logging.info(f"Using video codec: {vcodec}")
         return vcodec
     available = detect_available_hw_encoders()
     for encoder in HW_ENCODERS:
         if encoder in available:
-            logger.info(f"Auto-selected video codec: {encoder}")
+            logging.info(f"Auto-selected video codec: {encoder}")
             return encoder
-    logger.info("No hardware encoder available, falling back to software encoder 'libsvtav1'")
+    logging.info("No hardware encoder available, falling back to software encoder 'libsvtav1'")
     return "libsvtav1"
 
 
@@ -120,7 +118,7 @@ def get_safe_default_codec():
     if importlib.util.find_spec("torchcodec"):
         return "torchcodec"
     else:
-        logger.warning(
+        logging.warning(
             "'torchcodec' is not available in your platform, falling back to 'pyav' as a default decoder"
         )
         return "pyav"
@@ -210,7 +208,7 @@ def decode_video_frames_torchvision(
     for frame in reader:
         current_ts = frame["pts"]
         if log_loaded_timestamps:
-            logger.info(f"frame loaded at timestamp={current_ts:.4f}")
+            logging.info(f"frame loaded at timestamp={current_ts:.4f}")
         loaded_frames.append(frame["data"])
         loaded_ts.append(current_ts)
         if current_ts >= last_ts:
@@ -246,7 +244,7 @@ def decode_video_frames_torchvision(
     closest_ts = loaded_ts[argmin_]
 
     if log_loaded_timestamps:
-        logger.info(f"{closest_ts=}")
+        logging.info(f"{closest_ts=}")
 
     # convert to the pytorch format which is float32 in [0,1] range (and channel first)
     closest_frames = closest_frames.type(torch.float32) / 255
@@ -350,7 +348,7 @@ def decode_video_frames_torchcodec(
         loaded_frames.append(frame)
         loaded_ts.append(pts.item())
         if log_loaded_timestamps:
-            logger.info(f"Frame loaded at timestamp={pts:.4f}")
+            logging.info(f"Frame loaded at timestamp={pts:.4f}")
 
     query_ts = torch.tensor(timestamps)
     loaded_ts = torch.tensor(loaded_ts)
@@ -376,7 +374,7 @@ def decode_video_frames_torchcodec(
     closest_ts = loaded_ts[argmin_]
 
     if log_loaded_timestamps:
-        logger.info(f"{closest_ts=}")
+        logging.info(f"{closest_ts=}")
 
     # convert to float32 in [0,1] range
     closest_frames = (closest_frames / 255.0).type(torch.float32)
@@ -410,14 +408,14 @@ def encode_video_frames(
     imgs_dir = Path(imgs_dir)
 
     if video_path.exists() and not overwrite:
-        logger.warning(f"Video file already exists: {video_path}. Skipping encoding.")
+        logging.warning(f"Video file already exists: {video_path}. Skipping encoding.")
         return
 
     video_path.parent.mkdir(parents=True, exist_ok=True)
 
     # Encoders/pixel formats incompatibility check
     if (vcodec == "libsvtav1" or vcodec == "hevc") and pix_fmt == "yuv444p":
-        logger.warning(
+        logging.warning(
             f"Incompatible pixel format 'yuv444p' for codec {vcodec}, auto-selecting format 'yuv420p'"
         )
         pix_fmt = "yuv420p"
@@ -510,7 +508,7 @@ def concatenate_video_files(
     output_video_path = Path(output_video_path)
 
     if output_video_path.exists() and not overwrite:
-        logger.warning(f"Video file already exists: {output_video_path}. Skipping concatenation.")
+        logging.warning(f"Video file already exists: {output_video_path}. Skipping concatenation.")
         return
 
     output_video_path.parent.mkdir(parents=True, exist_ok=True)
@@ -695,7 +693,7 @@ class _CameraEncoderThread(threading.Thread):
                 self.result_queue.put(("ok", None))
 
         except Exception as e:
-            logger.error(f"Encoder thread error: {e}")
+            logging.error(f"Encoder thread error: {e}")
             if container is not None:
                 with contextlib.suppress(Exception):
                     container.close()
@@ -741,7 +739,6 @@ class StreamingVideoEncoder:
         self._video_paths: dict[str, Path] = {}
         self._dropped_frames: dict[str, int] = {}
         self._episode_active = False
-        self._closed = False
 
     def start_episode(self, video_keys: list[str], temp_dir: Path) -> None:
         """Start encoder threads for a new episode.
@@ -822,7 +819,7 @@ class StreamingVideoEncoder:
             count = self._dropped_frames[video_key]
             # Log periodically to avoid spam (1st, then every 10th)
             if count == 1 or count % 10 == 0:
-                logger.warning(
+                logging.warning(
                     f"Encoder queue full for {video_key}, dropped {count} frame(s). "
                     f"Consider using vcodec='auto' for hardware encoding or increasing encoder_queue_maxsize."
                 )
@@ -844,7 +841,7 @@ class StreamingVideoEncoder:
         # Report dropped frames
         for video_key, count in self._dropped_frames.items():
             if count > 0:
-                logger.warning(f"Episode finished with {count} dropped frame(s) for {video_key}.")
+                logging.warning(f"Episode finished with {count} dropped frame(s) for {video_key}.")
 
         # Send sentinel to all queues
         for video_key in self._frame_queues:
@@ -854,7 +851,7 @@ class StreamingVideoEncoder:
         for video_key in self._threads:
             self._threads[video_key].join(timeout=120)
             if self._threads[video_key].is_alive():
-                logger.error(f"Encoder thread for {video_key} did not finish in time")
+                logging.error(f"Encoder thread for {video_key} did not finish in time")
                 self._stop_events[video_key].set()
                 self._threads[video_key].join(timeout=5)
                 results[video_key] = (self._video_paths[video_key], None)
@@ -866,7 +863,7 @@ class StreamingVideoEncoder:
                     raise RuntimeError(f"Encoder thread for {video_key} failed: {data}")
                 results[video_key] = (self._video_paths[video_key], data)
             except queue.Empty:
-                logger.error(f"No result from encoder thread for {video_key}")
+                logging.error(f"No result from encoder thread for {video_key}")
                 results[video_key] = (self._video_paths[video_key], None)
 
         self._cleanup()
@@ -896,11 +893,8 @@ class StreamingVideoEncoder:
 
     def close(self) -> None:
         """Close the encoder, canceling any in-progress episode."""
-        if self._closed:
-            return
         if self._episode_active:
             self.cancel_episode()
-        self._closed = True
 
     def _cleanup(self) -> None:
         """Clean up queues and thread tracking dicts."""
@@ -1067,19 +1061,43 @@ class VideoEncodingManager:
         return self
 
     def __exit__(self, exc_type, exc_val, exc_tb):
-        writer = self.dataset.writer
-        if writer is not None:
-            if exc_type is not None and writer._streaming_encoder is not None:
-                writer.cancel_pending_videos()
+        streaming_encoder = getattr(self.dataset, "_streaming_encoder", None)
 
-            # finalize() handles flush_pending_videos + parquet + metadata
-            self.dataset.finalize()
+        if streaming_encoder is not None:
+            # Handle streaming encoder cleanup
+            if exc_type is not None:
+                streaming_encoder.cancel_episode()
+            streaming_encoder.close()
+        elif self.dataset.episodes_since_last_encoding > 0:
+            # Handle any remaining episodes that haven't been batch encoded
+            if exc_type is not None:
+                logging.info("Exception occurred. Encoding remaining episodes before exit...")
+            else:
+                logging.info("Recording stopped. Encoding remaining episodes...")
 
-            # Clean up episode images if recording was interrupted (only for non-streaming mode)
-            if exc_type is not None and writer._streaming_encoder is None:
-                writer.cleanup_interrupted_episode(self.dataset.num_episodes)
-        else:
-            self.dataset.finalize()
+            start_ep = self.dataset.num_episodes - self.dataset.episodes_since_last_encoding
+            end_ep = self.dataset.num_episodes
+            logging.info(
+                f"Encoding remaining {self.dataset.episodes_since_last_encoding} episodes, "
+                f"from episode {start_ep} to {end_ep - 1}"
+            )
+            self.dataset._batch_save_episode_video(start_ep, end_ep)
+
+        # Finalize the dataset to properly close all writers
+        self.dataset.finalize()
+
+        # Clean up episode images if recording was interrupted (only for non-streaming mode)
+        if exc_type is not None and streaming_encoder is None:
+            interrupted_episode_index = self.dataset.num_episodes
+            for key in self.dataset.meta.video_keys:
+                img_dir = self.dataset._get_image_file_path(
+                    episode_index=interrupted_episode_index, image_key=key, frame_index=0
+                ).parent
+                if img_dir.exists():
+                    logging.debug(
+                        f"Cleaning up interrupted episode images for episode {interrupted_episode_index}, camera {key}"
+                    )
+                    shutil.rmtree(img_dir)
 
         # Clean up any remaining images directory if it's empty
         img_dir = self.dataset.root / "images"
@@ -1087,8 +1105,8 @@ class VideoEncodingManager:
             png_files = list(img_dir.rglob("*.png"))
             if len(png_files) == 0:
                 shutil.rmtree(img_dir)
-                logger.debug("Cleaned up empty images directory")
+                logging.debug("Cleaned up empty images directory")
             else:
-                logger.debug(f"Images directory is not empty, containing {len(png_files)} PNG files")
+                logging.debug(f"Images directory is not empty, containing {len(png_files)} PNG files")
 
         return False  # Don't suppress the original exception

src/lerobot/envs/libero.py

@@ -29,7 +29,7 @@ from gymnasium import spaces
 from libero.libero import benchmark, get_libero_path
 from libero.libero.envs import OffScreenRenderEnv
 
-from lerobot.types import RobotObservation
+from lerobot.processor import RobotObservation
 
 
 def _parse_camera_names(camera_name: str | Sequence[str]) -> list[str]:

src/lerobot/envs/metaworld.py

@@ -25,7 +25,7 @@ import metaworld.policies as policies
 import numpy as np
 from gymnasium import spaces
 
-from lerobot.types import RobotObservation
+from lerobot.processor import RobotObservation
 
 # ---- Load configuration data from the external JSON file ----
 CONFIG_PATH = Path(__file__).parent / "metaworld_config.json"

src/lerobot/envs/utils.py

@@ -29,7 +29,7 @@ from torch import Tensor
 
 from lerobot.configs.types import FeatureType, PolicyFeature
 from lerobot.envs.configs import EnvConfig
-from lerobot.types import RobotObservation
+from lerobot.processor import RobotObservation
 from lerobot.utils.constants import OBS_ENV_STATE, OBS_IMAGE, OBS_IMAGES, OBS_STATE, OBS_STR
 from lerobot.utils.utils import get_channel_first_image_shape
 

src/lerobot/optim/optimizers.py

@@ -23,8 +23,7 @@ import draccus
 import torch
 from safetensors.torch import load_file, save_file
 
-from lerobot.datasets.io_utils import write_json
-from lerobot.datasets.utils import flatten_dict, unflatten_dict
+from lerobot.datasets.utils import flatten_dict, unflatten_dict, write_json
 from lerobot.utils.constants import (
     OPTIMIZER_PARAM_GROUPS,
     OPTIMIZER_STATE,

src/lerobot/optim/schedulers.py

@@ -23,7 +23,7 @@ import draccus
 from torch.optim import Optimizer
 from torch.optim.lr_scheduler import LambdaLR, LRScheduler
 
-from lerobot.datasets.io_utils import write_json
+from lerobot.datasets.utils import write_json
 from lerobot.utils.constants import SCHEDULER_STATE
 from lerobot.utils.io_utils import deserialize_json_into_object
 

src/lerobot/policies/__init__.py

@@ -15,7 +15,6 @@
 from .act.configuration_act import ACTConfig as ACTConfig
 from .diffusion.configuration_diffusion import DiffusionConfig as DiffusionConfig
 from .groot.configuration_groot import GrootConfig as GrootConfig
-from .multi_task_dit.configuration_multi_task_dit import MultiTaskDiTConfig as MultiTaskDiTConfig
 from .pi0.configuration_pi0 import PI0Config as PI0Config
 from .pi0_fast.configuration_pi0_fast import PI0FastConfig as PI0FastConfig
 from .pi05.configuration_pi05 import PI05Config as PI05Config
@@ -29,7 +28,6 @@ from .xvla.configuration_xvla import XVLAConfig as XVLAConfig
 __all__ = [
     "ACTConfig",
     "DiffusionConfig",
-    "MultiTaskDiTConfig",
     "PI0Config",
     "PI05Config",
     "PI0FastConfig",

src/lerobot/policies/factory.py

@@ -24,14 +24,13 @@ import torch
 
 from lerobot.configs.policies import PreTrainedConfig
 from lerobot.configs.types import FeatureType
-from lerobot.datasets.dataset_metadata import LeRobotDatasetMetadata
-from lerobot.datasets.feature_utils import dataset_to_policy_features
+from lerobot.datasets.lerobot_dataset import LeRobotDatasetMetadata
+from lerobot.datasets.utils import dataset_to_policy_features
 from lerobot.envs.configs import EnvConfig
 from lerobot.envs.utils import env_to_policy_features
 from lerobot.policies.act.configuration_act import ACTConfig
 from lerobot.policies.diffusion.configuration_diffusion import DiffusionConfig
 from lerobot.policies.groot.configuration_groot import GrootConfig
-from lerobot.policies.multi_task_dit.configuration_multi_task_dit import MultiTaskDiTConfig
 from lerobot.policies.pi0.configuration_pi0 import PI0Config
 from lerobot.policies.pi05.configuration_pi05 import PI05Config
 from lerobot.policies.pretrained import PreTrainedPolicy
@@ -44,14 +43,13 @@ from lerobot.policies.utils import validate_visual_features_consistency
 from lerobot.policies.vqbet.configuration_vqbet import VQBeTConfig
 from lerobot.policies.wall_x.configuration_wall_x import WallXConfig
 from lerobot.policies.xvla.configuration_xvla import XVLAConfig
-from lerobot.processor import PolicyProcessorPipeline
+from lerobot.processor import PolicyAction, PolicyProcessorPipeline
 from lerobot.processor.converters import (
     batch_to_transition,
     policy_action_to_transition,
     transition_to_batch,
     transition_to_policy_action,
 )
-from lerobot.types import PolicyAction
 from lerobot.utils.constants import (
     ACTION,
     POLICY_POSTPROCESSOR_DEFAULT_NAME,
@@ -59,29 +57,6 @@ from lerobot.utils.constants import (
 )
 
 
-def _reconnect_relative_absolute_steps(
-    preprocessor: PolicyProcessorPipeline, postprocessor: PolicyProcessorPipeline
-) -> None:
-    """Wire AbsoluteActionsProcessorStep.relative_step to the RelativeActionsProcessorStep after deserialization.
-
-    After a policy is loaded from disk, the preprocessor and postprocessor are reconstructed
-    independently from their configs. AbsoluteActionsProcessorStep needs a live reference to
-    the RelativeActionsProcessorStep so it can read the cached state at inference time.
-    That reference is not serializable, so we re-establish it here after loading.
-    """
-    from lerobot.processor.relative_action_processor import (
-        AbsoluteActionsProcessorStep,
-        RelativeActionsProcessorStep,
-    )
-
-    relative_step = next((s for s in preprocessor.steps if isinstance(s, RelativeActionsProcessorStep)), None)
-    if relative_step is None:
-        return
-    for step in postprocessor.steps:
-        if isinstance(step, AbsoluteActionsProcessorStep) and step.relative_step is None:
-            step.relative_step = relative_step
-
-
 def get_policy_class(name: str) -> type[PreTrainedPolicy]:
     """
     Retrieves a policy class by its registered name.
@@ -91,7 +66,8 @@ def get_policy_class(name: str) -> type[PreTrainedPolicy]:
 
     Args:
         name: The name of the policy. Supported names are "tdmpc", "diffusion", "act",
-            "multi_task_dit", "vqbet", "pi0", "pi05", "sac", "reward_classifier", "smolvla", "wall_x".
+              "vqbet", "pi0", "pi05", "sac", "reward_classifier", "smolvla", "wall_x".
+
     Returns:
         The policy class corresponding to the given name.
 
@@ -110,10 +86,6 @@ def get_policy_class(name: str) -> type[PreTrainedPolicy]:
         from lerobot.policies.act.modeling_act import ACTPolicy
 
         return ACTPolicy
-    elif name == "multi_task_dit":
-        from lerobot.policies.multi_task_dit.modeling_multi_task_dit import MultiTaskDiTPolicy
-
-        return MultiTaskDiTPolicy
     elif name == "vqbet":
         from lerobot.policies.vqbet.modeling_vqbet import VQBeTPolicy
 
@@ -174,8 +146,8 @@ def make_policy_config(policy_type: str, **kwargs) -> PreTrainedConfig:
 
     Args:
         policy_type: The type of the policy. Supported types include "tdmpc",
-                     "multi_task_dit", "diffusion", "act", "vqbet", "pi0", "pi05", "sac",
-                     "smolvla", "reward_classifier", "wall_x".
+                     "diffusion", "act", "vqbet", "pi0", "pi05", "sac", "smolvla",
+                     "reward_classifier", "wall_x".
         **kwargs: Keyword arguments to be passed to the configuration class constructor.
 
     Returns:
@@ -190,8 +162,6 @@ def make_policy_config(policy_type: str, **kwargs) -> PreTrainedConfig:
         return DiffusionConfig(**kwargs)
     elif policy_type == "act":
         return ACTConfig(**kwargs)
-    elif policy_type == "multi_task_dit":
-        return MultiTaskDiTConfig(**kwargs)
     elif policy_type == "vqbet":
         return VQBeTConfig(**kwargs)
     elif policy_type == "pi0":
@@ -292,26 +262,26 @@ def make_pre_post_processors(
             kwargs["preprocessor_overrides"] = preprocessor_overrides
             kwargs["postprocessor_overrides"] = postprocessor_overrides
 
-        preprocessor = PolicyProcessorPipeline.from_pretrained(
-            pretrained_model_name_or_path=pretrained_path,
-            config_filename=kwargs.get(
-                "preprocessor_config_filename", f"{POLICY_PREPROCESSOR_DEFAULT_NAME}.json"
+        return (
+            PolicyProcessorPipeline.from_pretrained(
+                pretrained_model_name_or_path=pretrained_path,
+                config_filename=kwargs.get(
+                    "preprocessor_config_filename", f"{POLICY_PREPROCESSOR_DEFAULT_NAME}.json"
+                ),
+                overrides=kwargs.get("preprocessor_overrides", {}),
+                to_transition=batch_to_transition,
+                to_output=transition_to_batch,
             ),
-            overrides=kwargs.get("preprocessor_overrides", {}),
-            to_transition=batch_to_transition,
-            to_output=transition_to_batch,
-        )
-        postprocessor = PolicyProcessorPipeline.from_pretrained(
-            pretrained_model_name_or_path=pretrained_path,
-            config_filename=kwargs.get(
-                "postprocessor_config_filename", f"{POLICY_POSTPROCESSOR_DEFAULT_NAME}.json"
+            PolicyProcessorPipeline.from_pretrained(
+                pretrained_model_name_or_path=pretrained_path,
+                config_filename=kwargs.get(
+                    "postprocessor_config_filename", f"{POLICY_POSTPROCESSOR_DEFAULT_NAME}.json"
+                ),
+                overrides=kwargs.get("postprocessor_overrides", {}),
+                to_transition=policy_action_to_transition,
+                to_output=transition_to_policy_action,
             ),
-            overrides=kwargs.get("postprocessor_overrides", {}),
-            to_transition=policy_action_to_transition,
-            to_output=transition_to_policy_action,
         )
-        _reconnect_relative_absolute_steps(preprocessor, postprocessor)
-        return preprocessor, postprocessor
 
     # Create a new processor based on policy type
     if isinstance(policy_cfg, TDMPCConfig):
@@ -338,16 +308,6 @@ def make_pre_post_processors(
             dataset_stats=kwargs.get("dataset_stats"),
         )
 
-    elif isinstance(policy_cfg, MultiTaskDiTConfig):
-        from lerobot.policies.multi_task_dit.processor_multi_task_dit import (
-            make_multi_task_dit_pre_post_processors,
-        )
-
-        processors = make_multi_task_dit_pre_post_processors(
-            config=policy_cfg,
-            dataset_stats=kwargs.get("dataset_stats"),
-        )
-
     elif isinstance(policy_cfg, VQBeTConfig):
         from lerobot.policies.vqbet.processor_vqbet import make_vqbet_pre_post_processors
 
@@ -509,13 +469,6 @@ def make_policy(
     cfg.output_features = {key: ft for key, ft in features.items() if ft.type is FeatureType.ACTION}
     if not cfg.input_features:
         cfg.input_features = {key: ft for key, ft in features.items() if key not in cfg.output_features}
-
-    # Store action feature names for relative_exclude_joints support
-    if ds_meta is not None and hasattr(cfg, "action_feature_names"):
-        action_names = ds_meta.features.get(ACTION, {}).get("names")
-        if action_names is not None:
-            cfg.action_feature_names = list(action_names)
-
     kwargs["config"] = cfg
 
     # Pass dataset_stats to the policy if available (needed for some policies like SARM)

src/lerobot/policies/groot/processor_groot.py

@@ -49,7 +49,7 @@ from lerobot.processor.converters import (
     policy_action_to_transition,
     transition_to_policy_action,
 )
-from lerobot.types import EnvTransition, TransitionKey
+from lerobot.processor.core import EnvTransition, TransitionKey
 from lerobot.utils.constants import (
     ACTION,
     HF_LEROBOT_HOME,

src/lerobot/policies/multi_task_dit/README.md

@@ -1,37 +0,0 @@
-# Multitask DiT Policy
-
-## Citation
-
-If you use this work, please cite the following works:
-
-```bibtex
-@misc{jones2025multitaskditpolicy,
-  author = {Bryson Jones},
-  title = {Dissecting and Open-Sourcing Multitask Diffusion Transformer Policy},
-  year = {2025},
-  url = {https://brysonkjones.substack.com/p/dissecting-and-open-sourcing-multitask-diffusion-transformer-policy},
-  note = {Blog post}
-}
-```
-
-```bibtex
-@misc{trilbmteam2025carefulexaminationlargebehaviormodels,
-  author       = {TRI LBM Team},
-  title        = {A Careful Examination of Large Behavior Models for Multitask Dexterous Manipulation},
-  year         = {2025},
-  eprint       = {arXiv:2507.05331},
-  archivePrefix = {arXiv},
-  primaryClass = {cs.RO},
-  url          = {https://arxiv.org/abs/2507.05331}
-}
-```
-
-```bibtex
-@misc{bostondynamics2025largebehaviormodelsatlas,
-  author       = {Boston Dynamics and TRI Research Team},
-  title        = {Large Behavior Models and Atlas Find New Footing},
-  year         = {2025},
-  url          = {https://bostondynamics.com/blog/large-behavior-models-atlas-find-new-footing/},
-  note         = {Blog post}
-}
-```

src/lerobot/policies/multi_task_dit/__init__.py

@@ -1,21 +0,0 @@
-#!/usr/bin/env python
-
-# Copyright 2025 Bryson Jones 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.
-
-from .configuration_multi_task_dit import MultiTaskDiTConfig
-from .modeling_multi_task_dit import MultiTaskDiTPolicy
-from .processor_multi_task_dit import make_multi_task_dit_pre_post_processors
-
-__all__ = ["MultiTaskDiTConfig", "MultiTaskDiTPolicy", "make_multi_task_dit_pre_post_processors"]

src/lerobot/policies/multi_task_dit/configuration_multi_task_dit.py

@@ -1,256 +0,0 @@
-#!/usr/bin/env python
-
-# Copyright 2025 Bryson Jones 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.
-
-import logging
-from dataclasses import dataclass, field
-
-from lerobot.configs.policies import PreTrainedConfig
-from lerobot.configs.types import NormalizationMode
-from lerobot.optim.optimizers import AdamConfig
-from lerobot.optim.schedulers import DiffuserSchedulerConfig
-
-
-@PreTrainedConfig.register_subclass("multi_task_dit")
-@dataclass
-class MultiTaskDiTConfig(PreTrainedConfig):
-    """Configuration for the Multi-Task Diffusion Transformer (DiT) policy.
-
-    A transformer-based policy that supports both diffusion and flow matching objectives
-    for multi-task robot learning with text and vision conditioning.
-    """
-
-    n_obs_steps: int = 2  # Number of observation steps for temporal context
-    horizon: int = 32  # Number of action steps to predict
-    n_action_steps: int = 24  # Actions executed per policy call (~0.8s at 30Hz)
-
-    # Objective Selection
-    objective: str = "diffusion"  # "diffusion" or "flow_matching"
-
-    # --- Diffusion-specific (used when objective="diffusion") ---
-    noise_scheduler_type: str = "DDPM"  # "DDPM" or "DDIM"
-    num_train_timesteps: int = 100  # Number of diffusion timesteps
-    beta_schedule: str = "squaredcos_cap_v2"  # Noise schedule type
-    beta_start: float = 0.0001  # Starting noise level
-    beta_end: float = 0.02  # Ending noise level
-    prediction_type: str = "epsilon"  # "epsilon" (predict noise) or "sample" (predict clean)
-    clip_sample: bool = True  # Clip samples during denoising
-    clip_sample_range: float = 1.0  # Clipping range [-x, x]
-    num_inference_steps: int | None = None  # Denoising steps at inference (defaults to num_train_timesteps)
-
-    # --- Flow Matching-specific (used when objective="flow_matching") ---
-    sigma_min: float = 0.0  # Minimum noise in flow interpolation path
-    num_integration_steps: int = 100  # ODE integration steps at inference
-    integration_method: str = "euler"  # ODE solver: "euler" or "rk4"
-    timestep_sampling_strategy: str = "beta"  # "uniform" or "beta"
-
-    timestep_sampling_s: float = 0.999  # (beta only) Max timestep threshold
-    timestep_sampling_alpha: float = 1.5  # (beta only) Beta distribution alpha
-    timestep_sampling_beta: float = 1.0  # (beta only) Beta distribution beta
-
-    # Transformer Architecture
-    hidden_dim: int = 512  # Transformer hidden dimension
-    num_layers: int = 6  # Number of transformer layers
-    num_heads: int = 8  # Number of attention heads
-    dropout: float = 0.1  # Dropout rate
-    use_positional_encoding: bool = False  # Use absolute positional encoding
-    timestep_embed_dim: int = 256  # Timestep embedding dimension
-    use_rope: bool = True  # Use Rotary Position Embedding
-    rope_base: float = 10000.0  # RoPE base frequency
-
-    # Vision Encoder (CLIP)
-    vision_encoder_name: str = "openai/clip-vit-base-patch16"  # HuggingFace CLIP model
-    use_separate_rgb_encoder_per_camera: bool = False  # Separate encoder per camera view
-    vision_encoder_lr_multiplier: float = 0.1  # LR multiplier for vision encoder
-    image_resize_shape: tuple[int, int] | None = None  # Resize images before crop
-    image_crop_shape: tuple[int, int] | None = (224, 224)  # Crop shape (CLIP default)
-    image_crop_is_random: bool = True  # Random crop during training, center at inference
-
-    # Text Encoder (CLIP)
-    text_encoder_name: str = "openai/clip-vit-base-patch16"  # HuggingFace CLIP model
-    tokenizer_max_length: int = 77  # Max length for tokenized text (CLIP default is 77)
-    tokenizer_padding: str = "max_length"  # Padding strategy: "max_length" or "longest"
-    tokenizer_padding_side: str = "right"  # Padding side: "left" or "right"
-    tokenizer_truncation: bool = True  # Whether to truncate sequences longer than max_length
-
-    # Normalization
-    normalization_mapping: dict[str, NormalizationMode] = field(
-        default_factory=lambda: {
-            "VISUAL": NormalizationMode.MEAN_STD,
-            "STATE": NormalizationMode.MIN_MAX,
-            "ACTION": NormalizationMode.MIN_MAX,
-        }
-    )
-
-    # Training/Optimizer
-    optimizer_lr: float = 2e-5
-    optimizer_betas: tuple = (0.95, 0.999)
-    optimizer_eps: float = 1e-8
-    optimizer_weight_decay: float = 0.0
-    scheduler_name: str = "cosine"
-    scheduler_warmup_steps: int = 0
-    do_mask_loss_for_padding: bool = False
-
-    # Auto-calculated
-    drop_n_last_frames: int | None = None
-
-    def __post_init__(self):
-        super().__post_init__()
-
-        if self.drop_n_last_frames is None:
-            self.drop_n_last_frames = self.horizon - self.n_action_steps - self.n_obs_steps + 1
-
-        self._validate()
-
-    def _validate(self):
-        """Validate configuration parameters."""
-        # Objective validation
-        if self.objective not in ["diffusion", "flow_matching"]:
-            raise ValueError(f"objective must be 'diffusion' or 'flow_matching', got '{self.objective}'")
-
-        # Transformer validation
-        if self.hidden_dim <= 0:
-            raise ValueError("hidden_dim must be positive")
-        if self.num_layers <= 0:
-            raise ValueError("num_layers must be positive")
-        if self.num_heads <= 0:
-            raise ValueError("num_heads must be positive")
-        if self.hidden_dim % self.num_heads != 0:
-            raise ValueError("hidden_dim must be divisible by num_heads")
-        if not (0.0 <= self.dropout <= 1.0):
-            raise ValueError("dropout must be between 0.0 and 1.0")
-
-        # Vision encoder validation
-        if "clip" not in self.vision_encoder_name.lower():
-            raise ValueError(
-                f"vision_encoder_name must be a CLIP model (contain 'clip'), got '{self.vision_encoder_name}'"
-            )
-        if (
-            self.image_resize_shape
-            and self.image_crop_shape
-            and (
-                self.image_crop_shape[0] > self.image_resize_shape[0]
-                or self.image_crop_shape[1] > self.image_resize_shape[1]
-            )
-        ):
-            logging.warning(
-                "image_crop_shape %s must be <= image_resize_shape %s; disabling cropping.",
-                self.image_crop_shape,
-                self.image_resize_shape,
-            )
-            self.image_crop_shape = None
-
-        # Text encoder validation
-        if "clip" not in self.text_encoder_name.lower():
-            raise ValueError(
-                f"text_encoder_name must be a CLIP model (contain 'clip'), got '{self.text_encoder_name}'"
-            )
-
-        # Objective-specific validation
-        if self.objective == "diffusion":
-            if self.noise_scheduler_type not in ["DDPM", "DDIM"]:
-                raise ValueError(
-                    f"noise_scheduler_type must be 'DDPM' or 'DDIM', got {self.noise_scheduler_type}"
-                )
-            if self.prediction_type not in ["epsilon", "sample"]:
-                raise ValueError(f"prediction_type must be 'epsilon' or 'sample', got {self.prediction_type}")
-            if self.num_train_timesteps <= 0:
-                raise ValueError(f"num_train_timesteps must be positive, got {self.num_train_timesteps}")
-            if not (0.0 <= self.beta_start <= self.beta_end <= 1.0):
-                raise ValueError(f"Invalid beta values: {self.beta_start}, {self.beta_end}")
-
-        elif self.objective == "flow_matching":
-            if not (0.0 <= self.sigma_min <= 1.0):
-                raise ValueError(f"sigma_min must be in [0, 1], got {self.sigma_min}")
-            if self.num_integration_steps <= 0:
-                raise ValueError(f"num_integration_steps must be positive, got {self.num_integration_steps}")
-            if self.integration_method not in ["euler", "rk4"]:
-                raise ValueError(
-                    f"integration_method must be 'euler' or 'rk4', got {self.integration_method}"
-                )
-            if self.timestep_sampling_strategy not in ["uniform", "beta"]:
-                raise ValueError("timestep_sampling_strategy must be 'uniform' or 'beta'")
-            if self.timestep_sampling_strategy == "beta":
-                if not (0.0 < self.timestep_sampling_s <= 1.0):
-                    raise ValueError(f"timestep_sampling_s must be in (0, 1], got {self.timestep_sampling_s}")
-                if self.timestep_sampling_alpha <= 0:
-                    raise ValueError("timestep_sampling_alpha must be positive")
-                if self.timestep_sampling_beta <= 0:
-                    raise ValueError("timestep_sampling_beta must be positive")
-
-    def get_optimizer_preset(self) -> AdamConfig:
-        return AdamConfig(
-            lr=self.optimizer_lr,
-            betas=self.optimizer_betas,
-            eps=self.optimizer_eps,
-            weight_decay=self.optimizer_weight_decay,
-        )
-
-    def get_scheduler_preset(self) -> DiffuserSchedulerConfig:
-        return DiffuserSchedulerConfig(
-            name=self.scheduler_name,
-            num_warmup_steps=self.scheduler_warmup_steps,
-        )
-
-    def validate_features(self) -> None:
-        """Validate that required input features are present and properly configured."""
-        # If the configured crop doesn't fit, disable cropping instead of erroring.
-        # Note: if image_resize_shape is set, cropping is applied *after* resizing.
-        if self.image_crop_shape is not None:
-            for key, image_ft in self.image_features.items():
-                # image_ft.shape is (C, H, W)
-                effective_h, effective_w = (
-                    self.image_resize_shape
-                    if self.image_resize_shape is not None
-                    else (image_ft.shape[1], image_ft.shape[2])
-                )
-                if self.image_crop_shape[0] > effective_h or self.image_crop_shape[1] > effective_w:
-                    logging.warning(
-                        "image_crop_shape %s doesn't fit within effective image shape (%s, %s) for '%s'; disabling cropping.",
-                        self.image_crop_shape,
-                        effective_h,
-                        effective_w,
-                        key,
-                    )
-                    self.image_crop_shape = None
-                    break
-
-        if len(self.image_features) > 0:
-            first_key, first_ft = next(iter(self.image_features.items()))
-            for key, image_ft in self.image_features.items():
-                if image_ft.shape != first_ft.shape:
-                    raise ValueError(
-                        f"Image '{key}' shape {image_ft.shape} != '{first_key}' shape {first_ft.shape}"
-                    )
-
-    @property
-    def is_diffusion(self) -> bool:
-        return self.objective == "diffusion"
-
-    @property
-    def is_flow_matching(self) -> bool:
-        return self.objective == "flow_matching"
-
-    @property
-    def observation_delta_indices(self) -> list:
-        return list(range(1 - self.n_obs_steps, 1))
-
-    @property
-    def action_delta_indices(self) -> list:
-        return list(range(1 - self.n_obs_steps, 1 - self.n_obs_steps + self.horizon))
-
-    @property
-    def reward_delta_indices(self) -> None:
-        return None

src/lerobot/policies/multi_task_dit/modeling_multi_task_dit.py

@@ -1,803 +0,0 @@
-#!/usr/bin/env python
-
-# Copyright 2025 Bryson Jones 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.
-
-"""Multi-Task Diffusion Transformer (DiT) Policy
-
-Transformer-based diffusion policy for multi-task robot learning with text and vision conditioning.
-Supports both diffusion and flow matching objectives for action generation.
-
-References:
-- https://arxiv.org/abs/2507.05331
-- https://bostondynamics.com/blog/large-behavior-models-atlas-find-new-footing/
-- https://brysonkjones.substack.com/p/dissecting-and-open-sourcing-multitask-diffusion-transformer-policy
-"""
-
-import math
-from collections import deque
-from typing import TYPE_CHECKING
-
-import einops
-import torch
-import torch.nn as nn
-import torch.nn.functional as F  # noqa: N812
-import torchvision
-from diffusers.schedulers.scheduling_ddim import DDIMScheduler
-from diffusers.schedulers.scheduling_ddpm import DDPMScheduler
-from torch import Tensor
-
-from lerobot.policies.multi_task_dit.configuration_multi_task_dit import MultiTaskDiTConfig
-from lerobot.utils.import_utils import _transformers_available
-
-# Conditional import for type checking and lazy loading
-if TYPE_CHECKING or _transformers_available:
-    from transformers import CLIPTextModel, CLIPVisionModel
-else:
-    CLIPTextModel = None
-    CLIPVisionModel = None
-from lerobot.policies.pretrained import PreTrainedPolicy
-from lerobot.policies.utils import populate_queues
-from lerobot.utils.constants import (
-    ACTION,
-    OBS_IMAGES,
-    OBS_LANGUAGE_ATTENTION_MASK,
-    OBS_LANGUAGE_TOKENS,
-    OBS_STATE,
-)
-
-# -- Policy --
-
-
-class MultiTaskDiTPolicy(PreTrainedPolicy):
-    config_class = MultiTaskDiTConfig
-    name = "multi_task_dit"
-
-    def __init__(self, config: MultiTaskDiTConfig, **kwargs):
-        super().__init__(config)
-        config.validate_features()
-        self.config = config
-
-        self._queues = None
-
-        self.observation_encoder = ObservationEncoder(config)
-        conditioning_dim = self.observation_encoder.conditioning_dim
-        self.noise_predictor = DiffusionTransformer(config, conditioning_dim=conditioning_dim)
-
-        action_dim = config.action_feature.shape[0]
-        horizon = config.horizon
-
-        if config.is_diffusion:
-            self.objective = DiffusionObjective(
-                config,
-                action_dim=action_dim,
-                horizon=horizon,
-                do_mask_loss_for_padding=config.do_mask_loss_for_padding,
-            )
-        elif config.is_flow_matching:
-            self.objective = FlowMatchingObjective(
-                config,
-                action_dim=action_dim,
-                horizon=horizon,
-                do_mask_loss_for_padding=config.do_mask_loss_for_padding,
-            )
-        else:
-            raise ValueError(f"Unsupported objective: {config.objective}")
-
-        self.reset()
-
-    def get_optim_params(self) -> list:
-        """Returns parameter groups with different learning rates for vision vs non-vision parameters"""
-        non_vision_params = []
-        vision_encoder_params = []
-
-        for name, param in self.named_parameters():
-            if not param.requires_grad:
-                continue
-
-            if "observation_encoder.vision_encoder" in name:
-                vision_encoder_params.append(param)
-            else:
-                non_vision_params.append(param)
-
-        return [
-            {"params": non_vision_params},
-            {
-                "params": vision_encoder_params,
-                "lr": self.config.optimizer_lr * self.config.vision_encoder_lr_multiplier,
-            },
-        ]
-
-    def _generate_actions(self, batch: dict[str, Tensor]) -> Tensor:
-        batch_size, n_obs_steps = batch[OBS_STATE].shape[:2]
-        assert n_obs_steps == self.config.n_obs_steps
-
-        conditioning_vec = self.observation_encoder.encode(batch)
-        actions = self.objective.conditional_sample(self.noise_predictor, batch_size, conditioning_vec)
-
-        start = n_obs_steps - 1
-        end = start + self.config.n_action_steps
-        actions = actions[:, start:end]
-        return actions
-
-    def reset(self):
-        """Clear observation and action queues. Should be called on `env.reset()`"""
-        self._queues = {
-            OBS_STATE: deque(maxlen=self.config.n_obs_steps),
-            ACTION: deque(maxlen=self.config.n_action_steps),
-        }
-
-        if self.config.image_features:
-            self._queues[OBS_IMAGES] = deque(maxlen=self.config.n_obs_steps)
-
-    @torch.no_grad()
-    def predict_action_chunk(self, batch: dict[str, Tensor]) -> Tensor:
-        """Predict a chunk of actions given environment observations"""
-        self.eval()
-
-        for k in batch:
-            if k in self._queues:
-                batch[k] = torch.stack(list(self._queues[k]), dim=1)
-
-        actions = self._generate_actions(batch)
-        return actions
-
-    def _prepare_batch(self, batch: dict[str, Tensor]) -> dict[str, Tensor]:
-        """Prepare batch by stacking image features if needed."""
-        if self.config.image_features:
-            batch = dict(batch)  # shallow copy to avoid modifying original
-            batch[OBS_IMAGES] = torch.stack([batch[key] for key in self.config.image_features], dim=-4)
-
-        return batch
-
-    @torch.no_grad()
-    def select_action(self, batch: dict[str, Tensor]) -> Tensor:
-        """Select a single action given environment observations"""
-        if ACTION in batch:
-            batch = dict(batch)  # shallow copy to avoid modifying original
-            batch.pop(ACTION)
-
-        batch = self._prepare_batch(batch)
-
-        self._queues = populate_queues(self._queues, batch)
-
-        if len(self._queues[ACTION]) == 0:
-            actions = self.predict_action_chunk(batch)
-            self._queues[ACTION].extend(actions.transpose(0, 1))
-
-        action = self._queues[ACTION].popleft()
-        return action
-
-    def forward(self, batch: dict[str, Tensor]) -> tuple[Tensor, dict | None]:
-        """Run the batch through the model and compute the loss for training"""
-        batch = self._prepare_batch(batch)
-
-        conditioning_vec = self.observation_encoder.encode(batch)
-        loss = self.objective.compute_loss(self.noise_predictor, batch, conditioning_vec)
-
-        return loss, None
-
-
-# -- Observation Encoders --
-
-
-class CLIPVisionEncoder(nn.Module):
-    """CLIP vision encoder using the CLS token for global image representation."""
-
-    def __init__(self, model_name: str):
-        super().__init__()
-        self.model_name = model_name
-        self.model = CLIPVisionModel.from_pretrained(self.model_name)
-        self.num_non_spatial_tokens = 1
-        self.embed_dim = self.model.config.hidden_size
-
-    def forward(self, x: Tensor) -> Tensor:
-        """Encode RGB image to CLS token."""
-        outputs = self.model(pixel_values=x, output_hidden_states=False)
-        cls_token = outputs.last_hidden_state[:, 0]
-        b, embed_dim = cls_token.shape
-        return cls_token.reshape(b, embed_dim, 1, 1)
-
-    def get_output_shape(self) -> tuple:
-        return (self.embed_dim, 1, 1)
-
-
-class CLIPTextEncoder(nn.Module):
-    """CLIP text encoder with frozen weights and a learnable projection layer.
-
-    Accepts pre-tokenized inputs (input_ids and attention_mask) from the processor pipeline. See the processor
-    pipeline to see how the tokenization is handled.
-    """
-
-    def __init__(self, model_name: str = "openai/clip-vit-base-patch16", projection_dim: int = 512):
-        super().__init__()
-        self.model_name = model_name
-        self.projection_dim = projection_dim
-        self.text_encoder = CLIPTextModel.from_pretrained(model_name)
-
-        for param in self.text_encoder.parameters():
-            param.requires_grad = False
-
-        self.text_embed_dim = self.text_encoder.config.hidden_size
-        self.projection = nn.Linear(self.text_embed_dim, projection_dim)
-
-    def forward(self, input_ids: Tensor, attention_mask: Tensor) -> Tensor:
-        """Encode pre-tokenized text to feature vectors."""
-        # Ensure inputs are on the same device as the model
-        device = next(self.parameters()).device
-        input_ids = input_ids.to(device)
-        attention_mask = attention_mask.to(device)
-
-        with torch.no_grad():
-            outputs = self.text_encoder(input_ids=input_ids, attention_mask=attention_mask)
-            clip_features = outputs.pooler_output
-
-        return self.projection(clip_features)
-
-
-class ObservationEncoder(nn.Module):
-    """Handles all observation processing for the conditioning vector."""
-
-    def __init__(self, config):
-        super().__init__()
-        self.config = config
-        self._setup_preprocessing(config)
-
-        if config.image_features:
-            self.num_cameras = len(config.image_features)
-            self.camera_names = list(config.image_features.keys())
-
-            if config.use_separate_rgb_encoder_per_camera:
-                self.vision_encoders = nn.ModuleList(
-                    [CLIPVisionEncoder(model_name=config.vision_encoder_name) for _ in self.camera_names]
-                )
-                self.vision_encoder = None
-            else:
-                self.vision_encoder = CLIPVisionEncoder(model_name=config.vision_encoder_name)
-                self.vision_encoders = None
-        else:
-            self.vision_encoder = None
-            self.vision_encoders = None
-            self.camera_names = []
-            self.num_cameras = 0
-
-        if hasattr(config, "robot_state_feature") and config.robot_state_feature:
-            self.robot_state_dim = config.robot_state_feature.shape[0]
-        else:
-            self.robot_state_dim = 0
-
-        self.text_dim = config.hidden_dim
-        self.text_encoder = CLIPTextEncoder(model_name=config.text_encoder_name, projection_dim=self.text_dim)
-
-        self._setup_vector_output()
-
-    def _apply_preprocessing(self, images: Tensor) -> Tensor:
-        if self.do_resize:
-            images = self.resize(images)
-        if self.do_crop:
-            images = self.maybe_random_crop(images) if self.training else self.center_crop(images)
-        return images
-
-    def _setup_preprocessing(self, config):
-        if config.image_resize_shape is not None:
-            self.do_resize = True
-            self.resize = torchvision.transforms.Resize(
-                size=config.image_resize_shape,
-                interpolation=torchvision.transforms.InterpolationMode.BILINEAR,
-                antialias=True,
-            )
-        else:
-            self.do_resize = False
-
-        if config.image_crop_shape is not None:
-            self.do_crop = True
-            self.center_crop = torchvision.transforms.CenterCrop(config.image_crop_shape)
-            if config.image_crop_is_random:
-                self.maybe_random_crop = torchvision.transforms.RandomCrop(config.image_crop_shape)
-            else:
-                self.maybe_random_crop = self.center_crop
-        else:
-            self.do_crop = False
-
-    def _setup_vector_output(self):
-        total_dim = 0
-
-        if self.vision_encoder is not None or self.vision_encoders is not None:
-            encoder_to_check = self.vision_encoder or next(iter(self.vision_encoders))
-            feature_map_shape = encoder_to_check.get_output_shape()
-            c, h, w = feature_map_shape
-            spatial_feature_dim = c * h * w
-            total_dim += spatial_feature_dim * self.num_cameras
-
-        total_dim += self.robot_state_dim
-        total_dim += self.text_dim
-
-        self.conditioning_dim = total_dim * self.config.n_obs_steps
-
-    def encode(self, batch: dict) -> Tensor:
-        """Encode observations to vector format."""
-        batch_size, n_obs_steps = batch[OBS_STATE].shape[:2]
-        conditioning_feats = []
-
-        conditioning_feats.append(batch[OBS_STATE])
-
-        if self.vision_encoder is not None or self.vision_encoders is not None:
-            images = batch[OBS_IMAGES]
-
-            if len(images.shape) == 5:
-                images = images.unsqueeze(1)
-
-            if self.config.use_separate_rgb_encoder_per_camera:
-                camera_features = []
-                for cam_idx in range(self.num_cameras):
-                    cam_images = images[:, :, cam_idx]
-                    cam_images_flat = einops.rearrange(cam_images, "b s c h w -> (b s) c h w")
-                    cam_images_flat = self._apply_preprocessing(cam_images_flat)
-                    cam_features = self.vision_encoders[cam_idx](cam_images_flat)
-                    cam_visual_features = cam_features.flatten(start_dim=1)
-                    cam_features_reshaped = einops.rearrange(
-                        cam_visual_features, "(b s) f -> b s f", b=batch_size, s=n_obs_steps
-                    )
-                    camera_features.append(cam_features_reshaped)
-                img_features = torch.cat(camera_features, dim=-1)
-                conditioning_feats.append(img_features)
-            else:
-                images_flat = einops.rearrange(images, "b s n c h w -> (b s n) c h w")
-                images_flat = self._apply_preprocessing(images_flat)
-                visual_features = self.vision_encoder(images_flat).flatten(start_dim=1)
-                img_features = einops.rearrange(
-                    visual_features, "(b s n) f -> b s (n f)", b=batch_size, s=n_obs_steps, n=self.num_cameras
-                )
-                conditioning_feats.append(img_features)
-
-        if self.text_encoder is not None and OBS_LANGUAGE_TOKENS in batch:
-            input_ids = batch[OBS_LANGUAGE_TOKENS]  # [batch_size, seq_length]
-            attention_mask = batch[OBS_LANGUAGE_ATTENTION_MASK]  # [batch_size, seq_length]
-
-            text_features = self.text_encoder(input_ids, attention_mask)
-
-            text_features = text_features.unsqueeze(1).expand(-1, n_obs_steps, -1)
-            conditioning_feats.append(text_features)
-
-        combined_features = torch.cat(conditioning_feats, dim=-1)
-        return combined_features.flatten(start_dim=1)
-
-
-# -- Transformer Components --
-
-
-def modulate(x: Tensor, shift: Tensor, scale: Tensor) -> Tensor:
-    """Modulate input with shift and scale for AdaLN-Zero."""
-    return x * (1 + scale) + shift
-
-
-class SinusoidalPosEmb(nn.Module):
-    """Sinusoidal positional embeddings for timesteps."""
-
-    def __init__(self, dim: int):
-        super().__init__()
-        self.dim = dim
-
-    def forward(self, x: Tensor) -> Tensor:
-        device = x.device
-        half_dim = self.dim // 2
-        emb = math.log(10000) / (half_dim - 1)
-        emb = torch.exp(torch.arange(half_dim, device=device) * -emb)
-        emb = x[:, None] * emb[None, :]
-        emb = torch.cat((emb.sin(), emb.cos()), dim=-1)
-        return emb
-
-
-class RotaryPositionalEmbedding(nn.Module):
-    """Rotary Position Embedding (RoPE) for transformers."""
-
-    def __init__(self, head_dim: int, max_seq_len: int = 512, base: float = 10000.0):
-        super().__init__()
-        assert head_dim % 2 == 0, "head_dim must be even for RoPE"
-
-        self.head_dim = head_dim
-        self.max_seq_len = max_seq_len
-        self.base = base
-
-        inv_freq = 1.0 / (base ** (torch.arange(0, head_dim, 2).float() / head_dim))
-        self.register_buffer("inv_freq", inv_freq, persistent=False)
-        self._precompute_cache(max_seq_len)
-
-    def _precompute_cache(self, seq_len: int):
-        t = torch.arange(seq_len, dtype=self.inv_freq.dtype)
-        freqs = torch.outer(t, self.inv_freq)
-        emb = torch.cat((freqs, freqs), dim=-1)
-        self.register_buffer("_cos_cached", emb.cos()[None, None, :, :], persistent=False)
-        self.register_buffer("_sin_cached", emb.sin()[None, None, :, :], persistent=False)
-
-    def _rotate_half(self, x: Tensor) -> Tensor:
-        x1 = x[..., : x.shape[-1] // 2]
-        x2 = x[..., x.shape[-1] // 2 :]
-        return torch.cat((-x2, x1), dim=-1)
-
-    def forward(self, q: Tensor, k: Tensor) -> tuple[Tensor, Tensor]:
-        seq_len = q.shape[2]
-        if seq_len > self.max_seq_len:
-            raise ValueError(f"Sequence length {seq_len} exceeds max_seq_len {self.max_seq_len}.")
-
-        cos = self._cos_cached[:, :, :seq_len, :].to(q.dtype)
-        sin = self._sin_cached[:, :, :seq_len, :].to(q.dtype)
-
-        q_rotated = (q * cos) + (self._rotate_half(q) * sin)
-        k_rotated = (k * cos) + (self._rotate_half(k) * sin)
-        return q_rotated, k_rotated
-
-
-class RoPEAttention(nn.Module):
-    """Multi-head self-attention with Rotary Position Embedding (RoPE)."""
-
-    def __init__(
-        self,
-        hidden_size: int,
-        num_heads: int,
-        dropout: float = 0.0,
-        max_seq_len: int = 512,
-        rope_base: float = 10000.0,
-    ):
-        super().__init__()
-        assert hidden_size % num_heads == 0, "hidden_size must be divisible by num_heads"
-
-        self.hidden_size = hidden_size
-        self.num_heads = num_heads
-        self.head_dim = hidden_size // num_heads
-        self.scale = self.head_dim**-0.5
-
-        self.qkv_proj = nn.Linear(hidden_size, 3 * hidden_size, bias=True)
-        self.out_proj = nn.Linear(hidden_size, hidden_size, bias=True)
-        self.dropout = nn.Dropout(dropout) if dropout > 0 else nn.Identity()
-        self.rope = RotaryPositionalEmbedding(head_dim=self.head_dim, max_seq_len=max_seq_len, base=rope_base)
-
-    def forward(self, x: Tensor) -> Tensor:
-        B, T, _ = x.shape  # noqa: N806
-
-        qkv = self.qkv_proj(x)
-        qkv = qkv.reshape(B, T, 3, self.num_heads, self.head_dim)
-        qkv = qkv.permute(2, 0, 3, 1, 4)
-        q, k, v = qkv[0], qkv[1], qkv[2]
-
-        q, k = self.rope(q, k)
-
-        attn_out = torch.nn.functional.scaled_dot_product_attention(
-            q,
-            k,
-            v,
-            dropout_p=self.dropout.p if isinstance(self.dropout, nn.Dropout) and self.training else 0.0,
-        )
-
-        attn_out = attn_out.transpose(1, 2).reshape(B, T, self.hidden_size)
-        return self.out_proj(attn_out)
-
-
-class TransformerBlock(nn.Module):
-    """DiT-style transformer block with AdaLN-Zero."""
-
-    def __init__(
-        self,
-        hidden_size: int = 128,
-        num_heads: int = 4,
-        num_features: int = 128,
-        dropout: float = 0.0,
-        use_rope: bool = False,
-        max_seq_len: int = 512,
-        rope_base: float = 10000.0,
-    ):
-        super().__init__()
-        self.use_rope = use_rope
-
-        if use_rope:
-            self.attn = RoPEAttention(
-                hidden_size=hidden_size,
-                num_heads=num_heads,
-                dropout=dropout,
-                max_seq_len=max_seq_len,
-                rope_base=rope_base,
-            )
-        else:
-            self.multihead_attn = nn.MultiheadAttention(
-                hidden_size, num_heads=num_heads, batch_first=True, dropout=dropout
-            )
-
-        self.norm1 = nn.LayerNorm(hidden_size, elementwise_affine=False, eps=1e-6)
-        self.norm2 = nn.LayerNorm(hidden_size, elementwise_affine=False, eps=1e-6)
-
-        self.mlp = nn.Sequential(
-            nn.Linear(hidden_size, hidden_size * 4),
-            nn.GELU(approximate="tanh"),
-            nn.Linear(hidden_size * 4, hidden_size),
-        )
-
-        self.adaLN_modulation = nn.Sequential(nn.SiLU(), nn.Linear(num_features, 6 * hidden_size, bias=True))
-
-    def forward(self, x: Tensor, features: Tensor) -> Tensor:
-        shift_msa, scale_msa, gate_msa, shift_mlp, scale_mlp, gate_mlp = self.adaLN_modulation(
-            features
-        ).chunk(6, dim=1)
-
-        attn_input = modulate(self.norm1(x), shift_msa.unsqueeze(1), scale_msa.unsqueeze(1))
-
-        if self.use_rope:
-            attn_out = self.attn(attn_input)
-        else:
-            attn_out, _ = self.multihead_attn(attn_input, attn_input, attn_input)
-
-        x = x + gate_msa.unsqueeze(1) * attn_out
-
-        mlp_input = modulate(self.norm2(x), shift_mlp.unsqueeze(1), scale_mlp.unsqueeze(1))
-        mlp_out = self.mlp(mlp_input)
-        x = x + gate_mlp.unsqueeze(1) * mlp_out
-
-        return x
-
-
-class DiffusionTransformer(nn.Module):
-    """Transformer-based diffusion noise prediction model."""
-
-    def __init__(self, config, conditioning_dim: int):
-        super().__init__()
-        self.config = config
-        self.conditioning_dim = conditioning_dim
-
-        self.action_dim = config.action_feature.shape[0]
-        self.horizon = config.horizon
-        self.hidden_size = config.hidden_dim
-        self.num_layers = config.num_layers
-        self.num_heads = config.num_heads
-        self.dropout = config.dropout
-        self.use_rope = config.use_rope
-
-        self.timestep_embed_dim = config.timestep_embed_dim
-        self.time_mlp = nn.Sequential(
-            SinusoidalPosEmb(self.timestep_embed_dim),
-            nn.Linear(self.timestep_embed_dim, 2 * self.timestep_embed_dim),
-            nn.GELU(),
-            nn.Linear(2 * self.timestep_embed_dim, self.timestep_embed_dim),
-            nn.GELU(),
-        )
-
-        self.cond_dim = self.timestep_embed_dim + conditioning_dim
-        self.input_proj = nn.Linear(self.action_dim, self.hidden_size)
-
-        if config.use_positional_encoding:
-            self.pos_embedding = nn.Parameter(
-                torch.empty(1, self.horizon, self.hidden_size).normal_(std=0.02)
-            )
-        else:
-            self.pos_embedding = None
-
-        self.transformer_blocks = nn.ModuleList(
-            [
-                TransformerBlock(
-                    hidden_size=self.hidden_size,
-                    num_heads=self.num_heads,
-                    num_features=self.cond_dim,
-                    dropout=self.dropout,
-                    use_rope=self.use_rope,
-                    max_seq_len=self.horizon,
-                    rope_base=config.rope_base,
-                )
-                for _ in range(self.num_layers)
-            ]
-        )
-
-        self.output_proj = nn.Linear(self.hidden_size, self.action_dim)
-        self._initialize_weights()
-
-    def _initialize_weights(self):
-        for block in self.transformer_blocks:
-            nn.init.constant_(block.adaLN_modulation[-1].weight, 0)
-            nn.init.constant_(block.adaLN_modulation[-1].bias, 0)
-
-    def forward(self, x: Tensor, timestep: Tensor, conditioning_vec: Tensor) -> Tensor:
-        _, seq_len, _ = x.shape
-
-        timestep_features = self.time_mlp(timestep)
-        cond_features = torch.cat([timestep_features, conditioning_vec], dim=-1)
-
-        hidden_seq = self.input_proj(x)
-
-        if self.pos_embedding is not None:
-            hidden_seq = hidden_seq + self.pos_embedding[:, :seq_len, :]
-
-        for block in self.transformer_blocks:
-            hidden_seq = block(hidden_seq, cond_features)
-
-        return self.output_proj(hidden_seq)
-
-
-# -- Objectives --
-
-
-class DiffusionObjective(nn.Module):
-    """Standard diffusion (DDPM/DDIM) objective implementation."""
-
-    def __init__(self, config, action_dim: int, horizon: int, do_mask_loss_for_padding: bool = False):
-        super().__init__()
-        self.config = config
-        self.action_dim = action_dim
-        self.horizon = horizon
-        self.do_mask_loss_for_padding = do_mask_loss_for_padding
-
-        scheduler_kwargs = {
-            "num_train_timesteps": config.num_train_timesteps,
-            "beta_start": config.beta_start,
-            "beta_end": config.beta_end,
-            "beta_schedule": config.beta_schedule,
-            "clip_sample": config.clip_sample,
-            "clip_sample_range": config.clip_sample_range,
-            "prediction_type": config.prediction_type,
-        }
-
-        if config.noise_scheduler_type == "DDPM":
-            self.noise_scheduler: DDPMScheduler | DDIMScheduler = DDPMScheduler(**scheduler_kwargs)
-        elif config.noise_scheduler_type == "DDIM":
-            self.noise_scheduler = DDIMScheduler(**scheduler_kwargs)
-        else:
-            raise ValueError(f"Unsupported noise scheduler type {config.noise_scheduler_type}")
-
-        self.num_inference_steps = (
-            config.num_inference_steps
-            if config.num_inference_steps is not None
-            else self.noise_scheduler.config.num_train_timesteps
-        )
-
-    def compute_loss(self, model: nn.Module, batch: dict[str, Tensor], conditioning_vec: Tensor) -> Tensor:
-        clean_actions = batch[ACTION]
-        noise = torch.randn_like(clean_actions)
-        timesteps = torch.randint(
-            low=0,
-            high=self.noise_scheduler.config.num_train_timesteps,
-            size=(clean_actions.shape[0],),
-            device=clean_actions.device,
-        ).long()
-        noisy_actions = self.noise_scheduler.add_noise(clean_actions, noise, timesteps)
-
-        prediction_type = self.noise_scheduler.config.prediction_type
-        if prediction_type == "epsilon":
-            target = noise
-        elif prediction_type == "sample":
-            target = clean_actions
-        else:
-            raise ValueError(f"Unsupported prediction type: {prediction_type}")
-
-        predicted = model(noisy_actions, timesteps, conditioning_vec=conditioning_vec)
-        loss = F.mse_loss(predicted, target, reduction="none")
-
-        if self.do_mask_loss_for_padding and "action_is_pad" in batch:
-            valid_actions = ~batch["action_is_pad"]
-            loss = loss * valid_actions.unsqueeze(-1)
-
-        return loss.mean()
-
-    def conditional_sample(self, model: nn.Module, batch_size: int, conditioning_vec: Tensor) -> Tensor:
-        device = next(model.parameters()).device
-        dtype = next(model.parameters()).dtype
-
-        sample = torch.randn(
-            size=(batch_size, self.horizon, self.action_dim),
-            dtype=dtype,
-            device=device,
-        )
-
-        self.noise_scheduler.set_timesteps(self.num_inference_steps)
-        for t in self.noise_scheduler.timesteps:
-            model_output = model(
-                sample,
-                torch.full(sample.shape[:1], t, dtype=torch.long, device=sample.device),
-                conditioning_vec=conditioning_vec,
-            )
-            sample = self.noise_scheduler.step(model_output, t, sample).prev_sample
-
-        return sample
-
-
-class FlowMatchingObjective(nn.Module):
-    """Flow matching objective: trains a model to predict velocity fields."""
-
-    def __init__(self, config, action_dim: int, horizon: int, do_mask_loss_for_padding: bool = False):
-        super().__init__()
-        self.config = config
-        self.action_dim = action_dim
-        self.horizon = horizon
-        self.do_mask_loss_for_padding = do_mask_loss_for_padding
-
-    def _sample_timesteps(self, batch_size: int, device: torch.device) -> Tensor:
-        if self.config.timestep_sampling_strategy == "uniform":
-            return torch.rand(batch_size, device=device)
-        elif self.config.timestep_sampling_strategy == "beta":
-            beta_dist = torch.distributions.Beta(
-                self.config.timestep_sampling_alpha, self.config.timestep_sampling_beta
-            )
-            u = beta_dist.sample((batch_size,)).to(device)
-            return self.config.timestep_sampling_s * (1.0 - u)
-        else:
-            raise ValueError(f"Unknown timestep strategy: {self.config.timestep_sampling_strategy}")
-
-    def compute_loss(self, model: nn.Module, batch: dict[str, Tensor], conditioning_vec: Tensor) -> Tensor:
-        data = batch[ACTION]
-        batch_size = data.shape[0]
-        device = data.device
-
-        noise = torch.randn_like(data)
-        t = self._sample_timesteps(batch_size, device)
-        t_expanded = t.view(-1, 1, 1)
-        x_t = t_expanded * data + (1 - (1 - self.config.sigma_min) * t_expanded) * noise
-
-        target_velocity = data - (1 - self.config.sigma_min) * noise
-        predicted_velocity = model(x_t, t, conditioning_vec=conditioning_vec)
-        loss = F.mse_loss(predicted_velocity, target_velocity, reduction="none")
-
-        if self.do_mask_loss_for_padding and "action_is_pad" in batch:
-            valid_mask = ~batch["action_is_pad"]
-            loss = loss * valid_mask.unsqueeze(-1)
-
-        return loss.mean()
-
-    def conditional_sample(self, model: nn.Module, batch_size: int, conditioning_vec: Tensor) -> Tensor:
-        device = next(model.parameters()).device
-        dtype = next(model.parameters()).dtype
-
-        x = torch.randn((batch_size, self.horizon, self.action_dim), dtype=dtype, device=device)
-
-        num_steps = self.config.num_integration_steps
-        time_grid = torch.linspace(0, 1, num_steps + 1, device=device)
-
-        if self.config.integration_method == "euler":
-            x = self._euler_integrate(model, x, time_grid, conditioning_vec)
-        elif self.config.integration_method == "rk4":
-            x = self._rk4_integrate(model, x, time_grid, conditioning_vec)
-        else:
-            raise ValueError(f"Unknown integration method: {self.config.integration_method}")
-
-        return x
-
-    def _euler_integrate(
-        self, model: nn.Module, x_init: Tensor, time_grid: Tensor, conditioning_vec: Tensor
-    ) -> Tensor:
-        x = x_init
-        for i in range(len(time_grid) - 1):
-            t_scalar = time_grid[i].item()
-            dt = (time_grid[i + 1] - time_grid[i]).item()
-            t_batch = torch.full((x.shape[0],), t_scalar, dtype=x.dtype, device=x.device)
-            with torch.no_grad():
-                velocity = model(x, t_batch, conditioning_vec=conditioning_vec)
-            x = x + dt * velocity
-        return x
-
-    def _rk4_integrate(
-        self, model: nn.Module, x_init: Tensor, time_grid: Tensor, conditioning_vec: Tensor
-    ) -> Tensor:
-        x = x_init
-
-        def dynamics(x_val: Tensor, t_scalar: float) -> Tensor:
-            t_batch = torch.full((x_val.shape[0],), t_scalar, dtype=x_val.dtype, device=x_val.device)
-            with torch.no_grad():
-                return model(x_val, t_batch, conditioning_vec=conditioning_vec)
-
-        for i in range(len(time_grid) - 1):
-            t = time_grid[i].item()
-            dt = (time_grid[i + 1] - time_grid[i]).item()
-
-            k1 = dynamics(x, t)
-            k2 = dynamics(x + dt * k1 / 2, t + dt / 2)
-            k3 = dynamics(x + dt * k2 / 2, t + dt / 2)
-            k4 = dynamics(x + dt * k3, t + dt)
-
-            x = x + dt / 6 * (k1 + 2 * k2 + 2 * k3 + k4)
-
-        return x

src/lerobot/policies/multi_task_dit/processor_multi_task_dit.py

@@ -1,105 +0,0 @@
-#!/usr/bin/env python
-
-# Copyright 2025 Bryson Jones 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.
-
-from typing import Any
-
-import torch
-
-from lerobot.policies.multi_task_dit.configuration_multi_task_dit import MultiTaskDiTConfig
-from lerobot.processor import (
-    AddBatchDimensionProcessorStep,
-    DeviceProcessorStep,
-    NormalizerProcessorStep,
-    PolicyAction,
-    PolicyProcessorPipeline,
-    RenameObservationsProcessorStep,
-    TokenizerProcessorStep,
-    UnnormalizerProcessorStep,
-)
-from lerobot.processor.converters import policy_action_to_transition, transition_to_policy_action
-from lerobot.utils.constants import POLICY_POSTPROCESSOR_DEFAULT_NAME, POLICY_PREPROCESSOR_DEFAULT_NAME
-
-
-def make_multi_task_dit_pre_post_processors(
-    config: MultiTaskDiTConfig,
-    dataset_stats: dict[str, dict[str, torch.Tensor]] | None = None,
-) -> tuple[
-    PolicyProcessorPipeline[dict[str, Any], dict[str, Any]],
-    PolicyProcessorPipeline[PolicyAction, PolicyAction],
-]:
-    """
-    Constructs pre-processor and post-processor pipelines for a Multi-Task DiT policy.
-
-    The pre-processing pipeline prepares the input data for the model by:
-    1. Renaming features.
-    2. Adding a batch dimension.
-    3. Tokenizing the language task description (if present).
-    4. Moving the data to the specified device.
-    5. Normalizing the input and output features based on dataset statistics.
-
-    The post-processing pipeline handles the model's output by:
-    1. Unnormalizing the output features to their original scale.
-    2. Moving the data to the CPU.
-
-    Args:
-        config: The configuration object for the Multi-Task DiT policy,
-            containing feature definitions, normalization mappings, and device information.
-        dataset_stats: A dictionary of statistics used for normalization.
-            Defaults to None.
-
-    Returns:
-        A tuple containing the configured pre-processor and post-processor pipelines.
-    """
-
-    input_steps = [
-        RenameObservationsProcessorStep(rename_map={}),
-        AddBatchDimensionProcessorStep(),
-        TokenizerProcessorStep(
-            tokenizer_name=config.text_encoder_name,
-            padding=config.tokenizer_padding,
-            padding_side=config.tokenizer_padding_side,
-            max_length=config.tokenizer_max_length,
-            truncation=config.tokenizer_truncation,
-        ),
-        DeviceProcessorStep(device=config.device),
-        NormalizerProcessorStep(
-            features={**config.input_features, **config.output_features},
-            norm_map=config.normalization_mapping,
-            stats=dataset_stats,
-            device=config.device,
-        ),
-    ]
-    output_steps = [
-        UnnormalizerProcessorStep(
-            features=config.output_features,
-            norm_map=config.normalization_mapping,
-            stats=dataset_stats,
-        ),
-        DeviceProcessorStep(device="cpu"),
-    ]
-
-    return (
-        PolicyProcessorPipeline[dict[str, Any], dict[str, Any]](
-            steps=input_steps,
-            name=POLICY_PREPROCESSOR_DEFAULT_NAME,
-        ),
-        PolicyProcessorPipeline[PolicyAction, PolicyAction](
-            steps=output_steps,
-            name=POLICY_POSTPROCESSOR_DEFAULT_NAME,
-            to_transition=policy_action_to_transition,
-            to_output=transition_to_policy_action,
-        ),
-    )

src/lerobot/policies/pi0/README.md

@@ -17,65 +17,6 @@ It is designed as a **Vision-Language-Action model for general robot control**.
 
 ---
 
-## Relative Actions
-
-π₀ supports training with **relative actions**, where the model learns relative offsets
-from the current robot state instead of absolute joint positions. This mirrors the
-relative-action transform in OpenPI (`DeltaActions`) and can improve performance.
-
-### How it works
-
-1. **During preprocessing**, absolute actions are converted to relative offsets:
-   `relative = action - state` (for selected joints).
-2. The relative actions are normalized using statistics computed from the relative distribution.
-3. **During postprocessing**, predicted relative actions are converted back to absolute:
-   `absolute = relative + state`.
-
-Joints listed in `relative_exclude_joints` (e.g., gripper) are kept absolute.
-
-### Configuration
-
-| Parameter                 | Type        | Default       | Description                                                      |
-| ------------------------- | ----------- | ------------- | ---------------------------------------------------------------- |
-| `use_relative_actions`    | `bool`      | `False`       | Enable relative-action training                                  |
-| `relative_exclude_joints` | `list[str]` | `["gripper"]` | Joint names to keep absolute (matched by substring)              |
-| `action_feature_names`    | `list[str]` | `None`        | Auto-populated from dataset metadata at runtime by `make_policy` |
-
-### Training example
-
-```bash
-python -m lerobot.scripts.lerobot_train \
-  --policy.type=pi0 \
-  --dataset.repo_id=your_org/your_dataset \
-  --policy.use_relative_actions=true \
-  --policy.relative_exclude_joints='["gripper"]'
-```
-
-When `use_relative_actions=true`, the training script automatically:
-
-- Computes relative action statistics from the dataset (sampled chunk-level relative actions)
-- Replaces the standard action stats with relative stats for normalization
-- Broadcasts these stats across all ranks in distributed training
-
-### Recomputing stats for an existing dataset
-
-If you want to precompute relative action stats offline, use `recompute_stats` from
-`lerobot.datasets.dataset_tools`:
-
-```python
-from lerobot.datasets.lerobot_dataset import LeRobotDataset
-from lerobot.datasets.dataset_tools import recompute_stats
-
-dataset = LeRobotDataset("your_org/your_dataset")
-dataset = recompute_stats(
-    dataset,
-    relative_action=True,
-    relative_exclude_joints=["gripper"],
-)
-```
-
----
-
 ## Citation
 
 If you use this work, please cite both **OpenPI** and the π₀ paper:

src/lerobot/policies/pi0/configuration_pi0.py

@@ -50,35 +50,6 @@ class PI0Config(PreTrainedConfig):
     min_period: float = 4e-3
     max_period: float = 4.0
 
-    # Relative actions: converts absolute actions to relative (relative to state).
-    use_relative_actions: bool = False
-    # Joint names to exclude from relative (kept absolute). Empty list = all dims relative.
-    relative_exclude_joints: list[str] = field(default_factory=lambda: ["gripper"])
-    # Populated at runtime from dataset metadata by make_policy.
-    action_feature_names: list[str] | None = None
-
-    # Relative state (UMI-style relative proprioception): converts multi-timestep
-    # observation.state to offsets from the current timestep, providing velocity info.
-    # Requires state_obs_steps >= 2. The flattened multi-timestep state is padded to
-    # max_state_dim, so ensure state_obs_steps * state_dim <= max_state_dim.
-    use_relative_state: bool = False
-    state_obs_steps: int = 1
-    relative_exclude_state_joints: list[str] = field(default_factory=list)
-    # Populated at runtime from dataset metadata by make_policy.
-    state_feature_names: list[str] | None = None
-
-    # Derive observation.state from the action column (UMI-style).
-    # When True, action_delta_indices loads one extra leading timestep [-1, 0, ..., chunk_size-1],
-    # DeriveStateFromActionStep extracts [action[t-1], action[t]] as a 2-step state,
-    # and strips the extra timestep from the action chunk.
-    # Implies use_relative_state=True and state_obs_steps=2.
-    derive_state_from_action: bool = False
-
-    # Latency compensation: skip this many steps from the start of each predicted
-    # action chunk during inference. E.g. at 10Hz with ~200ms total latency,
-    # latency_skip_steps=2 compensates for the delay.
-    latency_skip_steps: int = 0
-
     # Real-Time Chunking (RTC) configuration
     rtc_config: RTCConfig | None = None
 
@@ -128,10 +99,6 @@ class PI0Config(PreTrainedConfig):
     def __post_init__(self):
         super().__post_init__()
 
-        if self.derive_state_from_action:
-            self.use_relative_state = True
-            self.state_obs_steps = 2
-
         # Validate configuration
         if self.n_action_steps > self.chunk_size:
             raise ValueError(
@@ -147,13 +114,6 @@ class PI0Config(PreTrainedConfig):
         if self.dtype not in ["bfloat16", "float32"]:
             raise ValueError(f"Invalid dtype: {self.dtype}")
 
-        if self.use_relative_state and self.state_obs_steps < 2:
-            raise ValueError(
-                "use_relative_state requires state_obs_steps >= 2 "
-                f"(got {self.state_obs_steps}). Set state_obs_steps=2 for "
-                "UMI-style relative proprioception."
-            )
-
     def validate_features(self) -> None:
         """Validate and set up input/output features."""
         for i in range(self.empty_cameras):
@@ -199,16 +159,8 @@ class PI0Config(PreTrainedConfig):
     def observation_delta_indices(self) -> None:
         return None
 
-    @property
-    def state_delta_indices(self) -> list[int] | None:
-        if self.state_obs_steps >= 2:
-            return list(range(-(self.state_obs_steps - 1), 1))
-        return None
-
     @property
     def action_delta_indices(self) -> list:
-        if self.derive_state_from_action:
-            return [-1] + list(range(self.chunk_size))
         return list(range(self.chunk_size))
 
     @property

src/lerobot/policies/pi0/modeling_pi0.py

@@ -1230,11 +1230,8 @@ class PI0Policy(PreTrainedPolicy):
         return images, img_masks
 
     def prepare_state(self, batch):
-        """Flatten multi-timestep state and pad to max_state_dim."""
-        state = batch[OBS_STATE]
-        if state.ndim == 3:
-            state = state.flatten(start_dim=1)
-        state = pad_vector(state, self.config.max_state_dim)
+        """Pad state"""
+        state = pad_vector(batch[OBS_STATE], self.config.max_state_dim)
         return state
 
     def prepare_action(self, batch):
@@ -1253,8 +1250,7 @@ class PI0Policy(PreTrainedPolicy):
 
         # Action queue logic for n_action_steps > 1
         if len(self._action_queue) == 0:
-            skip = self.config.latency_skip_steps
-            actions = self.predict_action_chunk(batch)[:, skip : skip + self.config.n_action_steps]
+            actions = self.predict_action_chunk(batch)[:, : self.config.n_action_steps]
             # Transpose to get shape (n_action_steps, batch_size, action_dim)
             self._action_queue.extend(actions.transpose(0, 1))
 

src/lerobot/policies/pi0/processor_pi0.py

@@ -21,18 +21,14 @@ import torch
 from lerobot.configs.types import PipelineFeatureType, PolicyFeature
 from lerobot.policies.pi0.configuration_pi0 import PI0Config
 from lerobot.processor import (
-    AbsoluteActionsProcessorStep,
     AddBatchDimensionProcessorStep,
     ComplementaryDataProcessorStep,
-    DeriveStateFromActionStep,
     DeviceProcessorStep,
     NormalizerProcessorStep,
     PolicyAction,
     PolicyProcessorPipeline,
     ProcessorStep,
     ProcessorStepRegistry,
-    RelativeActionsProcessorStep,
-    RelativeStateProcessorStep,
     RenameObservationsProcessorStep,
     TokenizerProcessorStep,
     UnnormalizerProcessorStep,
@@ -130,25 +126,7 @@ def make_pi0_pre_post_processors(
         A tuple containing the configured pre-processor and post-processor pipelines.
     """
 
-    derive_state_step = DeriveStateFromActionStep(
-        enabled=getattr(config, "derive_state_from_action", False),
-    )
-
-    relative_step = RelativeActionsProcessorStep(
-        enabled=config.use_relative_actions,
-        exclude_joints=getattr(config, "relative_exclude_joints", []),
-        action_names=getattr(config, "action_feature_names", None),
-    )
-
-    relative_state_step = RelativeStateProcessorStep(
-        enabled=getattr(config, "use_relative_state", False),
-        exclude_joints=getattr(config, "relative_exclude_state_joints", []),
-        state_names=getattr(config, "state_feature_names", None),
-    )
-
-    # Order: DeriveStateFromAction extracts state from the extended action chunk,
-    # then relative_action uses current state[t] for subtraction,
-    # then relative_state converts the multi-timestep state to offsets.
+    # Add remaining processors
     input_steps: list[ProcessorStep] = [
         RenameObservationsProcessorStep(rename_map={}),  # To mimic the same processor as pretrained one
         AddBatchDimensionProcessorStep(),
@@ -160,9 +138,6 @@ def make_pi0_pre_post_processors(
             padding="max_length",
         ),
         DeviceProcessorStep(device=config.device),
-        derive_state_step,
-        relative_step,
-        relative_state_step,
         NormalizerProcessorStep(
             features={**config.input_features, **config.output_features},
             norm_map=config.normalization_mapping,
@@ -174,7 +149,6 @@ def make_pi0_pre_post_processors(
         UnnormalizerProcessorStep(
             features=config.output_features, norm_map=config.normalization_mapping, stats=dataset_stats
         ),
-        AbsoluteActionsProcessorStep(enabled=config.use_relative_actions, relative_step=relative_step),
         DeviceProcessorStep(device="cpu"),
     ]
 

src/lerobot/policies/pi05/README.md

@@ -17,48 +17,6 @@ It is designed as a **Vision-Language-Action model with open-world generalizatio
 
 ---
 
-## Relative Actions
-
-π₀.₅ supports training with **relative actions**, where the model learns relative offsets
-from the current robot state instead of absolute joint positions. This mirrors the
-relative-action transform in OpenPI (`DeltaActions`) and can improve performance.
-
-### How it works
-
-1. **During preprocessing**, absolute actions are converted to relative offsets:
-   `relative = action - state` (for selected joints).
-2. The relative actions are normalized using statistics computed from the relative distribution.
-3. **During postprocessing**, predicted relative actions are converted back to absolute:
-   `absolute = relative + state`.
-
-Joints listed in `relative_exclude_joints` (e.g., gripper) are kept absolute.
-
-### Configuration
-
-| Parameter                 | Type        | Default       | Description                                                      |
-| ------------------------- | ----------- | ------------- | ---------------------------------------------------------------- |
-| `use_relative_actions`    | `bool`      | `False`       | Enable relative-action training                                  |
-| `relative_exclude_joints` | `list[str]` | `["gripper"]` | Joint names to keep absolute (matched by substring)              |
-| `action_feature_names`    | `list[str]` | `None`        | Auto-populated from dataset metadata at runtime by `make_policy` |
-
-### Training example
-
-```bash
-python -m lerobot.scripts.lerobot_train \
-  --policy.type=pi05 \
-  --dataset.repo_id=your_org/your_dataset \
-  --policy.use_relative_actions=true \
-  --policy.relative_exclude_joints='["gripper"]'
-```
-
-When `use_relative_actions=true`, the training script automatically:
-
-- Computes relative action statistics from the dataset (sampled chunk-level relative actions)
-- Replaces the standard action stats with relative stats for normalization
-- Broadcasts these stats across all ranks in distributed training
-
----
-
 ## Citation
 
 If you use this work, please cite both **OpenPI** and the π₀.₅ paper:

src/lerobot/policies/pi05/configuration_pi05.py

@@ -50,13 +50,6 @@ class PI05Config(PreTrainedConfig):
     min_period: float = 4e-3
     max_period: float = 4.0
 
-    # Relative actions: converts absolute actions to relative (relative to state).
-    use_relative_actions: bool = False
-    # Joint names to exclude from relative (kept absolute). Empty list = all dims relative.
-    relative_exclude_joints: list[str] = field(default_factory=lambda: ["gripper"])
-    # Populated at runtime from dataset metadata by make_policy.
-    action_feature_names: list[str] | None = None
-
     # Real-Time Chunking (RTC) configuration
     rtc_config: RTCConfig | None = None
 

src/lerobot/policies/pi05/processor_pi05.py

@@ -24,7 +24,6 @@ import torch
 from lerobot.configs.types import PipelineFeatureType, PolicyFeature
 from lerobot.policies.pi05.configuration_pi05 import PI05Config
 from lerobot.processor import (
-    AbsoluteActionsProcessorStep,
     AddBatchDimensionProcessorStep,
     DeviceProcessorStep,
     NormalizerProcessorStep,
@@ -32,13 +31,12 @@ from lerobot.processor import (
     PolicyProcessorPipeline,
     ProcessorStep,
     ProcessorStepRegistry,
-    RelativeActionsProcessorStep,
     RenameObservationsProcessorStep,
     TokenizerProcessorStep,
     UnnormalizerProcessorStep,
 )
 from lerobot.processor.converters import policy_action_to_transition, transition_to_policy_action
-from lerobot.types import EnvTransition, TransitionKey
+from lerobot.processor.core import EnvTransition, TransitionKey
 from lerobot.utils.constants import (
     OBS_STATE,
     POLICY_POSTPROCESSOR_DEFAULT_NAME,
@@ -127,17 +125,10 @@ def make_pi05_pre_post_processors(
         A tuple containing the configured pre-processor and post-processor pipelines.
     """
 
-    relative_step = RelativeActionsProcessorStep(
-        enabled=config.use_relative_actions,
-        exclude_joints=getattr(config, "relative_exclude_joints", []),
-        action_names=getattr(config, "action_feature_names", None),
-    )
-
-    # OpenPI order: raw → relative → normalize → model → unnormalize → absolute
+    # Add remaining processors
     input_steps: list[ProcessorStep] = [
         RenameObservationsProcessorStep(rename_map={}),  # To mimic the same processor as pretrained one
         AddBatchDimensionProcessorStep(),
-        relative_step,
         # NOTE: NormalizerProcessorStep MUST come before Pi05PrepareStateTokenizerProcessorStep
         # because the tokenizer step expects normalized state in [-1, 1] range for discretization
         NormalizerProcessorStep(
@@ -159,7 +150,6 @@ def make_pi05_pre_post_processors(
         UnnormalizerProcessorStep(
             features=config.output_features, norm_map=config.normalization_mapping, stats=dataset_stats
         ),
-        AbsoluteActionsProcessorStep(enabled=config.use_relative_actions, relative_step=relative_step),
         DeviceProcessorStep(device="cpu"),
     ]
 

src/lerobot/policies/pi0_fast/configuration_pi0_fast.py

@@ -41,13 +41,6 @@ class PI0FastConfig(PreTrainedConfig):
     max_action_dim: int = 32
     max_action_tokens: int = 256
 
-    # Relative actions: converts absolute actions to relative (relative to state).
-    use_relative_actions: bool = False
-    # Joint names to exclude from relative (kept absolute). Empty list = all dims relative.
-    relative_exclude_joints: list[str] = field(default_factory=lambda: ["gripper"])
-    # Populated at runtime from dataset metadata by make_policy.
-    action_feature_names: list[str] | None = None
-
     # Real-Time Chunking (RTC) configuration
     rtc_config: RTCConfig | None = None
 

src/lerobot/policies/pi0_fast/processor_pi0_fast.py

@@ -24,7 +24,6 @@ import torch
 from lerobot.configs.types import PipelineFeatureType, PolicyFeature
 from lerobot.policies.pi0_fast.configuration_pi0_fast import PI0FastConfig
 from lerobot.processor import (
-    AbsoluteActionsProcessorStep,
     ActionTokenizerProcessorStep,
     AddBatchDimensionProcessorStep,
     DeviceProcessorStep,
@@ -33,13 +32,12 @@ from lerobot.processor import (
     PolicyProcessorPipeline,
     ProcessorStep,
     ProcessorStepRegistry,
-    RelativeActionsProcessorStep,
     RenameObservationsProcessorStep,
     TokenizerProcessorStep,
     UnnormalizerProcessorStep,
 )
 from lerobot.processor.converters import policy_action_to_transition, transition_to_policy_action
-from lerobot.types import EnvTransition, TransitionKey
+from lerobot.processor.core import EnvTransition, TransitionKey
 from lerobot.utils.constants import (
     OBS_STATE,
     POLICY_POSTPROCESSOR_DEFAULT_NAME,
@@ -127,24 +125,12 @@ def make_pi0_fast_pre_post_processors(
     Returns:
         A tuple containing the configured pre-processor and post-processor pipelines.
     """
-    relative_step = RelativeActionsProcessorStep(
-        enabled=config.use_relative_actions,
-        exclude_joints=getattr(config, "relative_exclude_joints", []),
-        action_names=getattr(config, "action_feature_names", None),
-    )
-
-    # Pi0Fast order: relative → normalize → tokenize → model → unnormalize → absolute
-    # This matches pi0/pi0.5: RelativeActionsProcessorStep runs first on raw absolute actions,
-    # caching the raw state. NormalizerProcessorStep then normalizes the raw relative actions,
-    # so the normalizer (and action tokenizer) sees delta values, relative stats are required.
-    # NOTE: RelativeActionsProcessorStep only modifies the action in the transition; it reads
-    # state from the observation but does not change it. NormalizerProcessorStep still runs
-    # before Pi0FastPrepareStateAndLanguageTokenizerProcessorStep, so the state tokenizer
-    # continues to receive normalized state in [-1, 1] as expected.
+    # Add remaining processors
     input_steps: list[ProcessorStep] = [
         RenameObservationsProcessorStep(rename_map={}),  # To mimic the same processor as pretrained one
         AddBatchDimensionProcessorStep(),
-        relative_step,
+        # NOTE: NormalizerProcessorStep MUST come before Pi0FastPrepareStateAndLanguageTokenizerProcessorStep
+        # because the tokenizer step expects normalized state in [-1, 1] range for discretization
         NormalizerProcessorStep(
             features={**config.input_features, **config.output_features},
             norm_map=config.normalization_mapping,
@@ -170,7 +156,6 @@ def make_pi0_fast_pre_post_processors(
         UnnormalizerProcessorStep(
             features=config.output_features, norm_map=config.normalization_mapping, stats=dataset_stats
         ),
-        AbsoluteActionsProcessorStep(enabled=config.use_relative_actions, relative_step=relative_step),
         DeviceProcessorStep(device="cpu"),
     ]