refactor(groot): N1.7 style cleanup (utils, imports, flash-attn, config)

Mechanical refactor of the GR00T N1.7 policy to match the repo's architecture and
style standards. No change to policy algorithm/numerics; only UX/CLI and packaging
changes. Tests are intentionally left untouched (out of scope) and need updating
for the removed `model_version` field.

Cleanup & consolidation:
- Add `groot/utils.py` holding the pure, side-effect-free helpers (JSON I/O, value
  coercion, stat flattening, rot6d/SE3 math, language/batch prep) shared by the
  config and processor layers.
- Remove dead code: the unused `resolve_groot_n1_7_backbone_model` cache-resolver
  cluster, `GR00TN17Config.to_filtered_dict/json`, and the `_copy_default` wrapper.

Imports & execution guards:
- Hoist nested imports to module top; relative imports within the package, absolute
  for external modules. The version-gated Qwen3-VL classes import under the single
  `_transformers_available` guard (transformers is pinned >=5.4, which ships them).
- No import-time side effects: `_register_with_transformers()` now runs in
  `GR00TN17.__init__` (idempotent via `register(exist_ok=True)`), and the N1.5 step
  stubs register lazily before pipeline deserialization (idempotent via the
  registry, no run-once globals).
- Gate optional deps at the point of use with `require_package(..., extra="groot")`.

Dependencies & docs:
- Drop `flash-attn` (and its build-only dep `ninja`) from the `groot` extra; default
  to SDPA (numerically equivalent) with opt-in via `--policy.use_flash_attention`.
  Un-comment `lerobot[groot]` in the `all` extra and regenerate `uv.lock`.
- Rewrite the `groot.mdx` install section: flash-attn is a purely optional,
  user-managed optimization that LeRobot neither installs nor requires.

Config & CLI:
- Surface previously-frozen knobs on `GrootConfig` (plumbed into `GR00TN17Config`;
  no-ops at their defaults): inference — `num_inference_timesteps`, `rtc_ramp_rate`,
  `use_flash_attention`; fine-tuning — `tune_top_llm_layers` (partial-LLM tuning)
  and `tune_vlln` (previously hardwired to True).
- Convert the single-valued `model_version` and `n1_7_backbone_model` fields to
  internal constants.
- Keep `base_model_path`: it is NOT equivalent to `pretrained_path` (raw NVIDIA
  checkpoints have no LeRobot `type` field and load only via `base_model_path`) and
  is genuinely user-tunable.
- Keep the deprecated Isaac-GR00T/N1.5 fields (and the dead LoRA fields) as a
  back-compat block so a v0.5.1 N1.5 `config.json` still parses under draccus and is
  rejected with the friendly N1.5 removal message instead of an opaque decode error.

README.md

@@ -105,7 +105,7 @@ lerobot-train \
 | -------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | **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)            |
+| **VLAs Models**            | [Pi0Fast](./docs/source/pi0fast.mdx), [Pi0.5](./docs/source/pi05.mdx), [GR00T N1.7](./docs/source/policy_groot_README.md), [SmolVLA](./docs/source/policy_smolvla_README.md), [XVLA](./docs/source/xvla.mdx)            |
 
 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
 

docs/source/_toctree.yml

@@ -68,7 +68,7 @@
   - local: eo1
     title: EO-1
   - local: groot
-    title: NVIDIA GR00T N1.5
+    title: NVIDIA GR00T
   - local: xvla
     title: X-VLA
   - local: multi_task_dit

docs/source/envhub_isaaclab_arena.mdx

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

docs/source/groot.mdx

@@ -1,16 +1,19 @@
-# GR00T N1.5 Policy
+# GR00T Policy
 
-GR00T N1.5 is an open foundation model from NVIDIA designed for generalized humanoid robot reasoning and skills. It is a cross-embodiment model that accepts multimodal input, including language and images, to perform manipulation tasks in diverse environments.
+GR00T is an NVIDIA foundation model family for generalized humanoid robot reasoning and skills. It is a cross-embodiment policy that accepts multimodal input, including language, images, and proprioception, to perform manipulation tasks in diverse environments.
 
-This document outlines the specifics of its integration and usage within the LeRobot framework.
+LeRobot integrates GR00T N1.7 through the `groot` policy type.
+
+> [!WARNING]
+> **Breaking change:** GR00T N1.5 support was removed from LeRobot, and current releases support GR00T N1.7 only. N1.5 checkpoints and configs are rejected with a migration note. To keep using an N1.5 checkpoint, pin the last release that supports it: `pip install 'lerobot==0.5.1'`. To use the current release, migrate to GR00T N1.7 (base model [`nvidia/GR00T-N1.7-3B`](https://huggingface.co/nvidia/GR00T-N1.7-3B)).
 
 ## Model Overview
 
-NVIDIA Isaac GR00T N1.5 is an upgraded version of the GR00T N1 foundation model. It is built to improve generalization and language-following abilities for humanoid robots.
+GR00T N1.7 uses a Cosmos-Reason2/Qwen3-VL backbone and provides checkpoints for SimplerEnv, DROID, and LIBERO.
 
-Developers and researchers can post-train GR00T N1.5 with their own real or synthetic data to adapt it for specific humanoid robots or tasks.
+Developers and researchers can post-train GR00T with their own real or synthetic data to adapt it for specific humanoid robots or tasks.
 
-GR00T N1.5 (specifically the GR00T-N1.5-3B model) is built using pre-trained vision and language encoders. It utilizes a flow matching action transformer to model a chunk of actions, conditioned on vision, language, and proprioception.
+GR00T uses pre-trained vision and language encoders with a flow matching action transformer to model a chunk of actions conditioned on vision, language, and proprioception.
 
 <img
   src="https://huggingface.co/datasets/huggingface/documentation-images/resolve/main/lerobot/lerobot-groot-paper1%20(1).png"
@@ -28,33 +31,43 @@ This approach allows the model to be highly adaptable through post-training for
 
 ## Installation Requirements
 
-As of today, GR00T N1.5 requires flash attention for it's internal working.
-
-We are working on making this optional, but in the meantime that means that we require an extra installation step and it can only be used in CUDA enabled devices.
-
-1. Following the Environment Setup of our [Installation Guide](./installation). **Attention** don't install `lerobot` in this step.
-2. Install [Flash Attention](https://github.com/Dao-AILab/flash-attention) by running:
+GR00T is intended for NVIDIA GPU-accelerated systems. Install LeRobot with the GR00T extra:
 
 ```bash
-# Check https://pytorch.org/get-started/locally/ for your system
-pip install "torch>=2.2.1,<2.8.0" "torchvision>=0.21.0,<0.23.0" # --index-url https://download.pytorch.org/whl/cu1XX
-pip install ninja "packaging>=24.2,<26.0" # flash attention dependencies
+pip install "lerobot[groot]"
+```
+
+For a source checkout:
+
+```bash
+pip install -e ".[groot]"
+```
+
+### Optional: Flash Attention acceleration
+
+Flash Attention is a purely optional performance optimization. **LeRobot neither installs nor requires it**, and setting it up is up to the user as it has environment-specific build requirements (a matching PyTorch/CUDA toolchain). To enable it:
+
+1. Install a `flash-attn` build matching your PyTorch/CUDA environment (see the [Flash Attention project](https://github.com/Dao-AILab/flash-attention)):
+
+```bash
+# Check https://pytorch.org/get-started/locally/ for the right CUDA wheel index for your system.
+pip install "torch>=2.7,<2.12.0" "torchvision>=0.22.0,<0.27.0" \
+  --index-url https://download.pytorch.org/whl/cu128
+pip install "ninja>=1.11.1,<2.0.0" "packaging>=24.2,<26.0"
 pip install "flash-attn>=2.5.9,<3.0.0" --no-build-isolation
 python -c "import flash_attn; print(f'Flash Attention {flash_attn.__version__} imported successfully')"
 ```
 
-3. Install LeRobot by running:
+2. Install lerobot with the groot extra.
 
-```bash
-pip install lerobot[groot]
-```
+3. Opt in by passing `--policy.use_flash_attention=true` when training/evaluating GR00T. If the kernel is missing or fails to import, the backbone transparently falls back to SDPA.
 
 ## Usage
 
-To use GR00T in your LeRobot configuration, specify the policy type as:
+To use GR00T N1.7:
 
-```python
-policy.type=groot
+```bash
+--policy.type=groot
 ```
 
 ## Training
@@ -87,21 +100,53 @@ accelerate launch \
 
 ## Performance Results
 
-### Libero Benchmark Results
+### LIBERO Benchmark Results
 
 > [!NOTE]
-> Follow our instructions for Libero usage: [Libero](./libero)
+> Follow the [LIBERO](./libero) setup instructions before running `lerobot-eval`.
 
-GR00T has demonstrated strong performance on the Libero benchmark suite. To compare and test its LeRobot implementation, we finetuned the GR00T N1.5 model for 30k steps on the Libero dataset and compared the results to the GR00T reference results.
+GR00T N1.7 has demonstrated strong performance on the LIBERO benchmark suite. To reproduce LeRobot results, follow the instructions in the [LIBERO](./libero) section.
 
-| Benchmark          | LeRobot Implementation | GR00T Reference |
-| ------------------ | ---------------------- | --------------- |
-| **Libero Spatial** | 82.0%                  | 92.0%           |
-| **Libero Object**  | 99.0%                  | 92.0%           |
-| **Libero Long**    | 82.0%                  | 76.0%           |
-| **Average**        | 87.0%                  | 87.0%           |
+### GR00T N1.7 LIBERO Checkpoints
 
-These results demonstrate GR00T's strong generalization capabilities across diverse robotic manipulation tasks. To reproduce these results, you can follow the instructions in the [Libero](https://huggingface.co/docs/lerobot/libero) section.
+NVIDIA publishes GR00T N1.7 LIBERO checkpoints at [`nvidia/GR00T-N1.7-LIBERO`](https://huggingface.co/nvidia/GR00T-N1.7-LIBERO), with one subdirectory per LIBERO suite:
+
+| Suite          | Checkpoint subdirectory |
+| -------------- | ----------------------- |
+| LIBERO Spatial | `libero_spatial`        |
+| LIBERO Object  | `libero_object`         |
+| LIBERO Goal    | `libero_goal`           |
+| LIBERO 10      | `libero_10`             |
+
+Preliminary LeRobot integration results:
+
+| Suite          | Status | Success rate | n_episodes |
+| -------------- | ------ | -----------: | ---------: |
+| LIBERO Spatial | ✓      |         ~95% |         XX |
+| LIBERO Object  | ✓      |          XX% |         XX |
+| LIBERO Goal    | ✓      |          XX% |         XX |
+| LIBERO 10      | ✓      |          XX% |         XX |
+| **Average**    | ✓      |      **XX%** |     **XX** |
+
+Replace the `XX` placeholders with final eval artifacts before merge.
+
+Download the suite checkpoint locally, then point `--policy.base_model_path` at the downloaded subdirectory. `--policy.path` is reserved for LeRobot checkpoints that contain a LeRobot `config.json` with a `type` field.
+
+```bash
+hf download nvidia/GR00T-N1.7-LIBERO \
+  --include "libero_spatial/*" \
+  --local-dir ./GR00T-N1.7-LIBERO
+
+lerobot-eval \
+  --policy.type=groot \
+  --policy.base_model_path=./GR00T-N1.7-LIBERO/libero_spatial \
+  --policy.embodiment_tag=libero_sim \
+  --env.type=libero \
+  --env.task=libero_spatial \
+  --eval.n_episodes=50
+```
+
+Use `eval.n_episodes >= 50` per suite when reporting success rates.
 
 ### Evaluate in your hardware setup
 
@@ -131,4 +176,4 @@ lerobot-rollout\
 
 ## License
 
-This model follows NVIDIA's proprietary license, consistent with the original [GR00T repository](https://github.com/NVIDIA/Isaac-GR00T). Future versions (starting from N1.7) will follow **Apache 2.0 License**.
+GR00T N1.7 is released under the [NVIDIA Open Model License Agreement](https://www.nvidia.com/en-us/agreements/enterprise-software/nvidia-open-model-license/).

docs/source/il_robots.mdx

@@ -647,6 +647,5 @@ The `--strategy.type` flag selects the execution mode:
 - `sentry`: Continuous recording with auto-upload (useful for large-scale evaluation)
 - `highlight`: Ring buffer recording with keystroke save (useful for capturing interesting events)
 - `dagger`: Human-in-the-loop data collection (see [HIL Data Collection](./hil_data_collection))
-- `episodic`: Episode-oriented policy recording with reset phases between episodes
 
 All strategies support `--inference.type=rtc` for smooth execution with slow VLA models (Pi0, Pi0.5, SmolVLA).

docs/source/inference.mdx

@@ -157,44 +157,6 @@ Foot pedal input is also supported via `--strategy.input_device=pedal`. Configur
 | `--strategy.input_device`            | Input device: `keyboard` or `pedal` (default: keyboard) |
 | `--teleop.type`                      | **Required.** Teleoperator type                         |
 
-### Episodic (`--strategy.type=episodic`)
-
-Episode-oriented recording that mirrors the behavior of `lerobot-record`. The policy drives the robot for each episode; an optional teleoperator can drive the robot during the reset phase between episodes.
-
-```bash
-lerobot-rollout \
-    --strategy.type=episodic \
-    --policy.path=${HF_USER}/my_policy \
-    --robot.type=so100_follower \
-    --robot.port=/dev/ttyACM0 \
-    --teleop.type=so100_leader \
-    --teleop.port=/dev/ttyACM1 \
-    --dataset.repo_id=${HF_USER}/my_eval_data \
-    --dataset.num_episodes=20 \
-    --dataset.episode_time_s=30 \
-    --dataset.reset_time_s=10 \
-    --dataset.single_task="Pick up the red cube"
-```
-
-Teleop is optional — if omitted the robot holds its position during the reset phase.
-
-**Keyboard controls:**
-
-| Key         | Action                           |
-| ----------- | -------------------------------- |
-| `→` (right) | End the current episode early    |
-| `←` (left)  | Discard episode and re-record it |
-| `ESC`       | Stop the recording session       |
-
-| Flag                                            | Description                                                                |
-| ----------------------------------------------- | -------------------------------------------------------------------------- |
-| `--dataset.num_episodes`                        | Number of episodes to record                                               |
-| `--dataset.episode_time_s`                      | Duration of each recording episode in seconds                              |
-| `--dataset.reset_time_s`                        | Duration of the reset phase between episodes in seconds                    |
-| `--teleop.type`                                 | Optional. Teleoperator to drive the robot during resets                    |
-| `--strategy.reset_to_initial_position`          | Whether to reset the robot to its initial position between episodes        |
-| `--strategy.smooth_leader_to_follower_handover` | Whether to turn on or off the leader -> follower smooth handover behavior. |
-
 ---
 
 ## Inference Backends

docs/source/policy_groot_README.md

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

examples/scaling/benchmark_dataloading.py

@@ -1,547 +0,0 @@
-# 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.
-
-"""Single-image dataloading benchmark across the LeRobot loaders, MADE TO RUN ON A COMPUTE CLUSTER (SLURM).
-
-This one file is both the orchestrator and the worker:
-
-  * Run it with no ``--scenario`` (from a login node) and it submits a SERIAL sbatch chain of all
-    scenarios below (no two network-bound jobs overlap, so CDN numbers stay clean).
-  * Run it with ``--scenario <name>`` and it executes that single benchmark (this is what each sbatch
-    job calls). The 2-node scenario is launched with ``srun`` and reads ``RANK``/``WORLD_SIZE`` so the
-    streaming dataset splits shards per node.
-
-Scenarios (all single-frame / non-SARM):
-  1. ``mmap_local``             map-style LeRobotDataset over a LOCAL copy (``--local_root``, no network).
-  2. ``mmap_local_maxworkers``  same, but workers scaled to saturate the node's cores (decode-bound).
-  3. ``stream_hub``             StreamingLeRobotDataset from the Hub (allenai/MolmoAct2-BimanualYAM-Dataset).
-  4. ``stream_bucket``          StreamingLeRobotDataset from a warmed storage bucket (1 node).
-  5. ``stream_bucket_2node``    same warmed bucket, 2 nodes (split_dataset_by_node, per-rank results).
-
-Reported per run: peak process-tree RSS (max memory), parallel throughput (samples/s, where a sample
-is one timestep, plus decoded_frames/s = samples/s x num_cameras),
-single-process throughput, shuffle randomness fraction (distinct episodes per batch / batch size),
-fetch vs decode split (% of single-process per-sample time), first-batch latency, and p50/p95/p99
-sample latency. Results are written as JSON + CSV under ``--out_dir``.
-
-Submit the whole chain (from a login node, inside the repo). Point the scheduler env vars at your own
-cluster's account/partition/qos, and ``--local_root`` at a local copy of the map-style dataset:
-    ACCOUNT=<account> PARTITION=<partition> QOS=<qos> \\
-        python examples/scaling/benchmark_dataloading.py --local_root /path/to/local/dataset
-"""
-
-import argparse
-import csv
-import json
-import os
-import random
-import statistics
-import subprocess
-import sys
-import threading
-import time
-from pathlib import Path
-
-import torch
-from torch.utils.data import DataLoader
-
-from lerobot.datasets import LeRobotDataset, LeRobotDatasetMetadata, StreamingLeRobotDataset
-from lerobot.datasets.partition import group_episodes_by_files, partition_episodes
-
-ROBOCASA_REPO = "pepijn223/robocasa_pretrain_human300_v4"
-MOLMO_REPO = "allenai/MolmoAct2-BimanualYAM-Dataset"
-MOLMO_BUCKET = "hf://buckets/pepijn223/MolmoAct2-BimanualYAM-Dataset-bucket"
-# MolmoAct2 is published without a codebase-version git tag, so the version-safe loader would refuse
-# it; "main" pins the branch directly and skips that check.
-MOLMO_REVISION = "main"
-
-# Per-scenario sbatch shape. mem is generous for the streaming legs (32k-episode, 3-camera, 2.35 TB
-# dataset keeps many AV1 decoders open); the local map-style leg is light. Optional ``num_workers`` /
-# ``cpus`` override the CLI defaults for that leg.
-# ``mmap_local_maxworkers``: map-style decode is CPU-bound and each worker decodes its cameras on
-# parallel threads, so the saturation point is ~num_cpus / num_cameras workers (~90 concurrent decode
-# threads). The 96-core H100 nodes here schedule at most 92 cpus/task, so we take 92 cpus / 30 workers.
-SCENARIOS = {
-    "mmap_local": {"kind": "map", "nodes": 1, "mem": "64G", "time": "01:00:00"},
-    "mmap_local_maxworkers": {
-        "kind": "map",
-        "nodes": 1,
-        "mem": "128G",
-        "time": "01:00:00",
-        "num_workers": 30,
-        "cpus": 92,
-    },
-    "stream_hub": {"kind": "stream", "nodes": 1, "mem": "250G", "time": "03:00:00"},
-    "stream_bucket": {"kind": "stream", "nodes": 1, "mem": "250G", "time": "03:00:00"},
-    "stream_bucket_2node": {"kind": "stream", "nodes": 2, "mem": "250G", "time": "03:00:00"},
-}
-
-
-def _tree_rss_bytes() -> int:
-    """Sum RSS of this process and all descendants via /proc (DataLoader workers are separate procs)."""
-    try:
-        children: dict[int, list[int]] = {}
-        for entry in os.listdir("/proc"):
-            if not entry.isdigit():
-                continue
-            try:
-                with open(f"/proc/{entry}/stat") as f:
-                    ppid = int(f.read().split(") ", 1)[1].split()[1])
-                children.setdefault(ppid, []).append(int(entry))
-            except (OSError, ValueError, IndexError):
-                pass
-        total, stack = 0, [os.getpid()]
-        while stack:
-            cur = stack.pop()
-            try:
-                with open(f"/proc/{cur}/statm") as f:
-                    total += int(f.read().split()[1]) * os.sysconf("SC_PAGE_SIZE")
-            except (OSError, ValueError, IndexError):
-                pass
-            stack.extend(children.get(cur, []))
-        return total
-    except OSError:
-        return 0
-
-
-class PeakRSSSampler:
-    """Background thread tracking peak process-tree RSS for the duration of the ``with`` block."""
-
-    def __init__(self, interval_s: float = 0.5):
-        self.interval_s = interval_s
-        self.peak_bytes = 0
-        self._stop = threading.Event()
-        self._thread = threading.Thread(target=self._run, daemon=True)
-
-    def _run(self) -> None:
-        while not self._stop.is_set():
-            self.peak_bytes = max(self.peak_bytes, _tree_rss_bytes())
-            self._stop.wait(self.interval_s)
-
-    def __enter__(self) -> "PeakRSSSampler":
-        self._thread.start()
-        return self
-
-    def __exit__(self, *exc) -> None:
-        self._stop.set()
-        self._thread.join(timeout=2)
-
-
-def percentile(values: list[float], pct: float) -> float:
-    if not values:
-        return float("nan")
-    ordered = sorted(values)
-    k = max(0, min(len(ordered) - 1, int(round((pct / 100.0) * (len(ordered) - 1)))))
-    return ordered[k]
-
-
-class _TimedStreaming(StreamingLeRobotDataset):
-    """StreamingLeRobotDataset that times the fetch stage (parquet/network row) separately from the
-    decode stage (video decode + torch conversion in ``_finalize_sample``), so a single-process pass
-    can attribute per-sample cost to fetch vs decode. Timing lives here in the benchmark, not in the
-    library, to keep the dataset itself instrumentation-free."""
-
-    def __init__(self, *args, **kwargs):
-        super().__init__(*args, **kwargs)
-        self.fetch_s = 0.0
-        self.decode_s = 0.0
-
-    def __iter__(self):
-        self._in_flight_epoch = self._epoch
-        self._pipeline.set_epoch(self._in_flight_epoch)
-        self._epoch += 1
-        self.video_decoder_cache = self._make_video_decoder_cache()
-        iterator = iter(self._pipeline)
-        while True:
-            t0 = time.perf_counter()
-            try:
-                row = next(iterator)
-            except StopIteration:
-                return
-            t1 = time.perf_counter()
-            sample = self._finalize_sample(row)
-            t2 = time.perf_counter()
-            self.fetch_s += t1 - t0
-            self.decode_s += t2 - t1
-            yield sample
-
-
-def select_node_episodes(
-    meta: LeRobotDatasetMetadata, num_partitions: int, index: int, cap: int
-) -> list[int]:
-    """This node's episode share, mirroring lerobot_train ``--data_partition=node``: group episodes by
-    shared video files, LPT-balance the groups by frame count, take this node's bin (capped)."""
-    episodes = list(range(meta.total_episodes))
-    from_idx = meta.episodes["dataset_from_index"]
-    to_idx = meta.episodes["dataset_to_index"]
-    lengths = [int(to_idx[ep] - from_idx[ep]) for ep in episodes]
-    if meta.video_keys:
-        file_columns = {
-            key: (meta.episodes[f"videos/{key}/chunk_index"], meta.episodes[f"videos/{key}/file_index"])
-            for key in meta.video_keys
-        }
-    else:
-        file_columns = {"data": (meta.episodes["data/chunk_index"], meta.episodes["data/file_index"])}
-    episode_file_ids = [
-        [(key, chunks[ep], files[ep]) for key, (chunks, files) in file_columns.items()] for ep in episodes
-    ]
-    groups = group_episodes_by_files(episode_file_ids)
-    if len(groups) < num_partitions:
-        groups = [[i] for i in range(len(episodes))]
-    group_lengths = [sum(lengths[i] for i in g) for g in groups]
-    bins = partition_episodes(group_lengths, num_partitions)
-    chosen = sorted(episodes[i] for g in bins[index] for i in groups[g])
-    return chosen[:cap] if cap and len(chosen) > cap else chosen
-
-
-def build_dataset(scenario: str, args: argparse.Namespace):
-    """Return (dataset, meta, is_map_style, info) for the scenario; single-frame (no delta windows)."""
-    if scenario.startswith("mmap_local"):
-        if not args.local_root:
-            raise SystemExit("mmap_local needs --local_root pointing at a local LeRobotDataset copy.")
-        meta = LeRobotDatasetMetadata(ROBOCASA_REPO, root=args.local_root)
-        episodes = select_node_episodes(meta, args.num_partitions, args.partition_index, args.max_episodes)
-        dataset = LeRobotDataset(ROBOCASA_REPO, root=args.local_root, episodes=episodes, tolerance_s=1e-3)
-        return dataset, meta, True, {"loaded_episodes": len(episodes)}
-
-    data_files_root = MOLMO_BUCKET if scenario.startswith("stream_bucket") else None
-    meta = LeRobotDatasetMetadata(MOLMO_REPO, revision=MOLMO_REVISION)
-    dataset = _TimedStreaming(
-        MOLMO_REPO,
-        revision=MOLMO_REVISION,
-        data_files_root=data_files_root,
-        episode_pool_size=args.episode_pool_size,
-        max_buffer_input_shards=args.max_buffer_input_shards,
-        video_decoder_cache_size=args.video_decoder_cache_size,
-        tolerance_s=1e-3,
-        # Throughput benchmark: don't gate on the one-row-group-per-episode invariant (a public
-        # dataset may be collapsed); reshard() still yields per-episode shards where it holds.
-        validate_row_groups=False,
-    )
-    return dataset, meta, False, {"num_shards": dataset.num_shards, "data_files_root": data_files_root}
-
-
-def _split(fetch_s: float, decode_s: float, getitem_s: float, n_probe: int) -> dict:
-    stage = fetch_s + decode_s
-    return {
-        "single_proc_samples_per_s": round(n_probe / getitem_s, 2) if getitem_s else None,
-        "fetch_pct": round(100 * fetch_s / stage, 1) if stage else None,
-        "decode_pct": round(100 * decode_s / stage, 1) if stage else None,
-    }
-
-
-def measure_fetch_decode_stream(dataset: _TimedStreaming, n_probe: int, warmup: int) -> dict:
-    """Single-process pass attributing per-sample time to fetch (parquet/network row) vs decode (video)."""
-    it = iter(dataset)
-    for _ in range(warmup):  # exclude the cold shuffle-buffer fill from the ratio
-        next(it)
-    dataset.fetch_s = dataset.decode_s = 0.0
-    t0 = time.perf_counter()
-    for _ in range(n_probe):
-        next(it)
-    return _split(dataset.fetch_s, dataset.decode_s, time.perf_counter() - t0, n_probe)
-
-
-def measure_fetch_decode_map(dataset: LeRobotDataset, n_probe: int, warmup: int) -> dict:
-    """Same split for the map-style loader: fetch = raw tabular row (``get_raw_item``), decode = the rest
-    of ``__getitem__`` (video decode + transforms). Local reads make fetch tiny and decode dominant.
-
-    Random frames are resampled past any that torchcodec fails to decode, so a single flaky frame can't
-    abort the whole benchmark (the parallel DataLoader pass draws its own fresh random frames)."""
-    rng = random.Random(0)
-    n = len(dataset)
-    fetch_s = getitem_s = 0.0
-    warmed = measured = skipped = attempts = 0
-    while measured < n_probe and attempts < (warmup + n_probe) * 10:
-        attempts += 1
-        i = rng.randrange(n)
-        try:
-            t0 = time.perf_counter()
-            dataset.get_raw_item(i)
-            t1 = time.perf_counter()
-            dataset[i]
-            t2 = time.perf_counter()
-        except Exception:
-            skipped += 1
-            continue
-        if warmed < warmup:
-            warmed += 1
-            continue
-        fetch_s += t1 - t0
-        getitem_s += t2 - t1
-        measured += 1
-    if skipped:
-        print(f"map fetch/decode probe skipped {skipped} undecodable frame(s)", flush=True)
-    return _split(fetch_s, max(0.0, getitem_s - fetch_s), getitem_s, measured)
-
-
-def run_scenario(scenario: str, args: argparse.Namespace) -> None:
-    rank = int(os.environ.get("RANK", "0"))
-    world_size = int(os.environ.get("WORLD_SIZE", "1"))
-    device = torch.device(args.device)
-
-    dataset, meta, is_map_style, info = build_dataset(scenario, args)
-
-    loader = DataLoader(
-        dataset,
-        batch_size=args.batch_size,
-        num_workers=args.num_workers,
-        shuffle=is_map_style,  # map-style: global random shuffle; streaming: shuffled inside the dataset
-        pin_memory=device.type == "cuda",
-        drop_last=True,
-        prefetch_factor=args.prefetch_factor if args.num_workers > 0 else None,
-        persistent_workers=args.num_workers > 0,
-    )
-
-    sample_latencies_ms: list[float] = []
-    episodes_per_batch: list[int] = []
-    samples = 0
-    first_batch_latency_s = None
-    steady_start = None
-
-    t_start = time.perf_counter()
-    t_prev = t_start
-    with PeakRSSSampler() as rss:
-        for i, batch in enumerate(loader):
-            for value in batch.values():
-                if torch.is_tensor(value):
-                    value.to(device, non_blocking=device.type == "cuda")
-            now = time.perf_counter()
-            if first_batch_latency_s is None:
-                first_batch_latency_s = now - t_start
-            if i == args.warmup_batches:
-                steady_start = now
-            elif i > args.warmup_batches:
-                sample_latencies_ms.append((now - t_prev) / args.batch_size * 1000.0)
-                samples += args.batch_size
-                ep = batch.get("episode_index")
-                if torch.is_tensor(ep):
-                    episodes_per_batch.append(int(torch.unique(ep).numel()))
-            t_prev = now
-            # Measure throughput over a fixed wall-clock window (after warmup) so every scenario is
-            # compared over the same duration regardless of its speed; num_batches is only a safety cap.
-            if steady_start is not None and (now - steady_start) >= args.duration_s:
-                break
-            if i + 1 >= args.num_batches:
-                break
-    peak_rss_gb = round(rss.peak_bytes / 1e9, 2) if rss.peak_bytes else None
-
-    now = time.perf_counter()
-    elapsed = now - t_start
-    steady_elapsed_s = (now - steady_start) if steady_start is not None else elapsed
-
-    if samples == 0:
-        raise SystemExit(
-            f"FAILED: 0 samples in {args.duration_s}s for scenario={scenario} "
-            "(inspect worker logs; try --num_workers 0 to surface the exception)."
-        )
-
-    # Single-process fetch/decode split + single-proc throughput. Run AFTER the DataLoader pass: this
-    # decodes video in the main process, which must stay decode-clean until the workers have forked
-    # (decoding before fork corrupts the workers' torchcodec state).
-    del loader
-    if is_map_style:
-        fetch_decode = measure_fetch_decode_map(dataset, args.probe_samples, args.probe_warmup)
-    else:
-        fetch_decode = measure_fetch_decode_stream(dataset, args.probe_samples, args.probe_warmup)
-
-    image_shape = list(meta.features[meta.video_keys[0]]["shape"]) if meta.video_keys else None
-    num_cameras = len(meta.video_keys)
-    results = {
-        "scenario": scenario,
-        "rank": rank,
-        "world_size": world_size,
-        "loader": "map_style" if is_map_style else "streaming",
-        "batch_size": args.batch_size,
-        "num_workers": args.num_workers,
-        "episode_pool_size": None if is_map_style else args.episode_pool_size,
-        "max_buffer_input_shards": None
-        if is_map_style
-        else (args.max_buffer_input_shards or args.episode_pool_size),
-        **info,
-        "num_cameras": num_cameras,
-        "image_shape": image_shape,
-        "fps": meta.fps,
-        "peak_rss_gb": peak_rss_gb,
-        "samples_measured": samples,
-        "steady_window_s": round(steady_elapsed_s, 2),
-        "first_batch_latency_s": round(first_batch_latency_s or float("nan"), 3),
-        # Parallel throughput over the steady window (excludes warmup + the prefetch queue it filled).
-        # A sample is one timestep (one dataset item); it decodes num_cameras video frames.
-        "samples_per_s": round(samples / steady_elapsed_s, 2) if steady_elapsed_s else 0.0,
-        "decoded_frames_per_s": round(samples / steady_elapsed_s * num_cameras, 2)
-        if steady_elapsed_s
-        else 0.0,
-        **fetch_decode,
-        # Distinct episodes per batch / batch size: ~1.0 ≈ map-style uniform, low ≈ correlated samples.
-        "shuffle_randomness_frac": round(statistics.mean(episodes_per_batch) / args.batch_size, 3)
-        if episodes_per_batch
-        else None,
-        "p50_sample_latency_ms": round(statistics.median(sample_latencies_ms), 3)
-        if sample_latencies_ms
-        else None,
-        "p95_sample_latency_ms": round(percentile(sample_latencies_ms, 95), 3),
-        "p99_sample_latency_ms": round(percentile(sample_latencies_ms, 99), 3),
-        "total_time_s": round(elapsed, 2),
-    }
-
-    out_dir = Path(args.out_dir)
-    out_dir.mkdir(parents=True, exist_ok=True)
-    tag = f"{scenario}_bs{args.batch_size}_w{args.num_workers}_r{rank}of{world_size}"
-    (out_dir / f"{tag}.json").write_text(json.dumps(results, indent=2))
-    flat = {k: (json.dumps(v) if isinstance(v, (dict, list)) else v) for k, v in results.items()}
-    with open(out_dir / f"{tag}.csv", "w", newline="") as f:
-        writer = csv.DictWriter(f, fieldnames=list(flat))
-        writer.writeheader()
-        writer.writerow(flat)
-    print(json.dumps(results, indent=2), flush=True)
-    print(f"Wrote {out_dir / tag}.json and .csv", flush=True)
-
-
-def submit_chain(args: argparse.Namespace) -> None:
-    """Submit every scenario as a serial sbatch chain (one network-bound job at a time).
-
-    Bodies are passed to ``sbatch --wrap`` as a single argv (no outer shell), so ``$SLURM_PROCID`` /
-    ``$SLURM_NTASKS`` stay literal and expand at job runtime, not at submit time.
-    """
-    this_file = Path(__file__).resolve()
-    repo_dir = str(this_file.parents[2])  # <repo>/examples/scaling/<this file>
-    logs = Path(repo_dir) / "logs"
-    logs.mkdir(exist_ok=True)
-    run = f"conda run --no-capture-output -n {args.conda_env} python"
-    common = (
-        f"--batch_size {args.batch_size} "
-        f"--prefetch_factor {args.prefetch_factor} --episode_pool_size {args.episode_pool_size} "
-        f"--video_decoder_cache_size {args.video_decoder_cache_size} --duration_s {args.duration_s} "
-        f"--num_batches {args.num_batches} --out_dir {args.out_dir}"
-    )
-    if args.max_buffer_input_shards is not None:
-        common += f" --max_buffer_input_shards {args.max_buffer_input_shards}"
-    if args.local_root:
-        common += f" --local_root {args.local_root}"
-    env_prefix = "export TOKENIZERS_PARALLELISM=false"
-    sched = []
-    for opt, env in (("--account", "ACCOUNT"), ("--partition", "PARTITION"), ("--qos", "QOS")):
-        if os.environ.get(env):
-            sched.append(f"{opt}={os.environ[env]}")
-
-    selected = args.scenarios.split(",") if args.scenarios else list(SCENARIOS)
-    prev = ""
-    for scenario in selected:
-        cfg = SCENARIOS[scenario]
-        nw = cfg.get("num_workers", args.num_workers)
-        cpus = cfg.get("cpus", nw + 4)
-        worker = f"{run} {this_file} --scenario {scenario} --num_workers {nw} {common}"
-        if cfg["nodes"] > 1:
-            # One task per node; each exports RANK/WORLD_SIZE so the stream splits shards per node.
-            inner = f"export RANK=$SLURM_PROCID WORLD_SIZE=$SLURM_NTASKS && cd {repo_dir} && {env_prefix} && {worker}"
-            body = f"srun --export=ALL bash -c '{inner}'"
-            node_flags = [f"--nodes={cfg['nodes']}", "--ntasks-per-node=1", "--gpus-per-node=1"]
-        else:
-            body = f"cd {repo_dir} && {env_prefix} && {worker}"
-            node_flags = ["--nodes=1", "--ntasks=1", "--gpus=1"]
-        cmd = [
-            "sbatch",
-            "--parsable",
-            f"--job-name=dlbench_{scenario}",
-            *node_flags,
-            f"--cpus-per-task={cpus}",
-            f"--mem={cfg['mem']}",
-            f"--time={cfg['time']}",
-            f"--output={logs}/%x-%j.out",
-            *sched,
-        ]
-        if prev:
-            cmd.append(f"--dependency=afterany:{prev}")
-        cmd += ["--wrap", body]
-        jid = subprocess.check_output(cmd, text=True).strip().split(";")[0]
-        print(f"submitted {jid}  dlbench_{scenario}{f'  (after {prev})' if prev else ''}", flush=True)
-        prev = jid
-
-    print(f"\nSubmitted {len(selected)} jobs as a serial chain. Results: {args.out_dir}/*.json", flush=True)
-
-
-def parse_args() -> argparse.Namespace:
-    p = argparse.ArgumentParser(description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter)
-    p.add_argument(
-        "--scenario",
-        choices=list(SCENARIOS),
-        default=None,
-        help="Run ONE scenario (worker mode). Omit to submit the whole chain (orchestrator mode).",
-    )
-    p.add_argument(
-        "--scenarios",
-        type=str,
-        default=None,
-        help="Orchestrator only: comma-separated subset of scenarios to submit (default: all).",
-    )
-    p.add_argument("--local_root", type=str, default=None, help="Local LeRobotDataset copy for mmap_local.")
-    p.add_argument(
-        "--num_partitions", type=int, default=8, help="Node count for mmap_local episode partition."
-    )
-    p.add_argument("--partition_index", type=int, default=0)
-    p.add_argument(
-        "--max_episodes", type=int, default=512, help="Cap mmap_local episodes to the local share."
-    )
-    p.add_argument("--batch_size", type=int, default=64)
-    p.add_argument("--num_workers", type=int, default=8)
-    p.add_argument("--prefetch_factor", type=int, default=2)
-    p.add_argument(
-        "--episode_pool_size", type=int, default=1024, help="Streaming shuffle pool (randomness knob)."
-    )
-    p.add_argument(
-        "--max_buffer_input_shards",
-        type=int,
-        default=None,
-        help="Concurrently-live random episodes feeding the pool after reshard() "
-        "(default: episode_pool_size). The frac knob; set >= batch_size for frac->1.",
-    )
-    p.add_argument(
-        "--video_decoder_cache_size", type=int, default=32, help="Max open video decoders (bounds RAM)."
-    )
-    p.add_argument(
-        "--duration_s", type=float, default=60.0, help="Steady-state measurement window (seconds)."
-    )
-    p.add_argument(
-        "--num_batches", type=int, default=1_000_000, help="Safety cap; duration_s governs the window."
-    )
-    p.add_argument("--warmup_batches", type=int, default=5, help="Excluded from steady-state throughput.")
-    p.add_argument(
-        "--probe_samples", type=int, default=100, help="Single-process samples for fetch/decode split."
-    )
-    p.add_argument(
-        "--probe_warmup", type=int, default=10, help="Samples skipped before the fetch/decode probe."
-    )
-    p.add_argument("--device", type=str, default="cuda" if torch.cuda.is_available() else "cpu")
-    p.add_argument("--conda_env", type=str, default="lerobot", help="Conda env the chained jobs run in.")
-    p.add_argument("--out_dir", type=str, default="benchmarks/streaming/results_dataloading")
-    return p.parse_args()
-
-
-def main() -> None:
-    args = parse_args()
-    if args.scenario is None:
-        if torch.cuda.is_available():
-            print(
-                "NOTE: no --scenario given, submitting the SLURM chain. This benchmark is meant to run on a "
-                "compute cluster; run from a login node with ACCOUNT/PARTITION/QOS set.",
-                file=sys.stderr,
-            )
-        submit_chain(args)
-    else:
-        run_scenario(args.scenario, args)
-
-
-if __name__ == "__main__":
-    main()

pyproject.toml

@@ -95,7 +95,7 @@ dependencies = [
 
 # ── Feature-scoped extras ──────────────────────────────────
 dataset = [
-    "datasets>=5.0.0,<6.0.0", # StreamingLeRobotDataset needs reshard() + shuffle(max_buffer_input_shards=...)
+    "datasets>=4.7.0,<5.0.0",
     "pandas>=2.0.0,<3.0.0", # NOTE: Transitive dependency of datasets
     "pyarrow>=21.0.0,<30.0.0", # NOTE: Transitive dependency of datasets
     "lerobot[av-dep]",
@@ -208,15 +208,13 @@ groot = [
     "dm-tree>=0.1.8,<1.0.0",
     "timm>=1.0.0,<1.1.0",
     "decord>=0.6.0,<1.0.0; (platform_machine == 'AMD64' or platform_machine == 'x86_64')",
-    "ninja>=1.11.1,<2.0.0",
-    "flash-attn>=2.5.9,<3.0.0 ; sys_platform != 'darwin'"
 ]
 sarm = ["lerobot[transformers-dep]", "pydantic>=2.0.0,<3.0.0", "faker>=33.0.0,<35.0.0", "lerobot[matplotlib-dep]", "lerobot[qwen-vl-utils-dep]"]
 robometer = ["lerobot[transformers-dep]", "lerobot[qwen-vl-utils-dep]", "lerobot[peft-dep]"]
 topreward = ["lerobot[transformers-dep]"]
 xvla = ["lerobot[transformers-dep]"]
 eo1 = ["lerobot[transformers-dep]", "lerobot[qwen-vl-utils-dep]"]
-hilserl = ["lerobot[transformers-dep]", "lerobot[dataset]", "gym-hil>=0.1.14,<0.2.0", "lerobot[grpcio-dep]", "lerobot[placo-dep]"]
+hilserl = ["lerobot[transformers-dep]", "lerobot[dataset]", "gym-hil>=0.1.13,<0.2.0", "lerobot[grpcio-dep]", "lerobot[placo-dep]"]
 vla_jepa = ["lerobot[transformers-dep]", "lerobot[diffusers-dep]", "lerobot[qwen-vl-utils-dep]"]
 
 # Features
@@ -231,9 +229,9 @@ video_benchmark = ["scikit-image>=0.23.2,<0.26.0", "pandas>=2.2.2,<2.4.0"]
 
 # Simulation
 # NOTE: Explicitly listing scipy helps flatten the dependecy tree.
-aloha = ["lerobot[dataset]", "gym-aloha>=0.1.4,<0.2.0", "lerobot[scipy-dep]"]
+aloha = ["lerobot[dataset]", "gym-aloha>=0.1.2,<0.2.0", "lerobot[scipy-dep]"]
 pusht = ["lerobot[dataset]", "gym-pusht>=0.1.5,<0.2.0", "pymunk>=6.6.0,<7.0.0"] # TODO: Fix pymunk version in gym-pusht instead
-libero = ["lerobot[dataset]", "lerobot[transformers-dep]", "hf-libero>=0.1.4,<0.2.0; sys_platform == 'linux'", "lerobot[scipy-dep]"]
+libero = ["lerobot[dataset]", "lerobot[transformers-dep]", "hf-libero>=0.1.3,<0.2.0; sys_platform == 'linux'", "lerobot[scipy-dep]"]
 metaworld = ["lerobot[dataset]", "metaworld==3.0.0", "lerobot[scipy-dep]"]
 # NOTE: vlabench is NOT exposed as a `lerobot` extra. Its only distribution
 # is the OpenMOSS/VLABench GitHub repo (package name `VLABench`, no PyPI
@@ -280,7 +278,7 @@ all = [
     "lerobot[pi]",
     "lerobot[molmoact2]",
     "lerobot[smolvla]",
-    # "lerobot[groot]", TODO(Steven): Gr00t requires specific installation instructions for flash-attn
+    "lerobot[groot]",
     "lerobot[xvla]",
     "lerobot[hilserl]",
     "lerobot[vla_jepa]",
@@ -333,16 +331,6 @@ explicit = true
 [tool.uv.sources]
 torch = [{ index = "pytorch-cu128", marker = "sys_platform == 'linux'" }]
 torchvision = [{ index = "pytorch-cu128", marker = "sys_platform == 'linux'" }]
-# Temporary: the native streaming pipeline needs batch(by_column=...) to survive shard/shuffle
-# re-creation (datasets#8259), reshard() per row group (#8193), and shuffle(max_buffer_input_shards=...)
-# (#8194) — all merged, not yet in a tagged 5.0 release. Track main until the next datasets release ships
-# them, then drop this and rely on the `datasets>=5.0.0` floor in `dependencies`.
-datasets = { git = "https://github.com/huggingface/datasets.git", branch = "main" }
-# Temporary: huggingface_hub main carries the 408-retry fix (not yet released). NOTE: main still closes the
-# shared httpx.Client on every ConnectError, which races with concurrent streaming requests
-# ("Cannot send a request, as the client has been closed"); we patch that out locally in
-# huggingface_hub/utils/_http.py. A fresh `uv sync` re-installs main *without* that local patch.
-huggingface-hub = { git = "https://github.com/huggingface/huggingface_hub.git", branch = "main" }
 
 [tool.setuptools.package-data]
 lerobot = ["envs/*.json"]

scripts/build_byte_index.py

@@ -1,51 +0,0 @@
-#!/usr/bin/env python
-"""Build mmap-able byte-index sidecars for LeRobot streaming datasets."""
-
-from __future__ import annotations
-
-import argparse
-import logging
-from pathlib import Path
-
-from lerobot.datasets.byte_index_builder import (
-    build_byte_index_tables,
-    load_existing_file_ids,
-    write_byte_index,
-)
-from lerobot.datasets.dataset_metadata import LeRobotDatasetMetadata
-
-logging.basicConfig(level=logging.INFO)
-logger = logging.getLogger(__name__)
-
-
-def main() -> None:
-    parser = argparse.ArgumentParser(description="Build LeRobot video byte-index sidecar.")
-    parser.add_argument("--repo-id", required=True)
-    parser.add_argument("--revision", default=None)
-    parser.add_argument("--data-root", required=True, help="fsspec root for videos/ + data/")
-    parser.add_argument("--output", type=Path, required=True, help="Output meta/byte_index directory")
-    parser.add_argument("--workers", type=int, default=8)
-    parser.add_argument("--max-episodes", type=int, default=None, help="Limit episodes (debug/smoke)")
-    parser.add_argument("--no-keyframes", action="store_true")
-    args = parser.parse_args()
-
-    meta = LeRobotDatasetMetadata(args.repo_id, revision=args.revision)
-    output = args.output
-    existing = load_existing_file_ids(output)
-    if existing:
-        logger.info("resuming: %s files already indexed", len(existing))
-
-    files_tbl, episodes_tbl, keyframes_tbl = build_byte_index_tables(
-        meta,
-        args.data_root,
-        include_keyframes=not args.no_keyframes,
-        workers=args.workers,
-        existing_files=existing,
-        max_episodes=args.max_episodes,
-    )
-    write_byte_index(output, files_tbl, episodes_tbl, keyframes_tbl, merge_existing=True)
-    logger.info("wrote byte index to %s", output)
-
-
-if __name__ == "__main__":
-    main()

src/lerobot/common/control_utils.py

@@ -18,7 +18,6 @@ from __future__ import annotations
 # Utilities
 ########################################################################################
 import logging
-import time
 import traceback
 from contextlib import nullcontext
 from copy import copy
@@ -244,72 +243,3 @@ def sanity_check_dataset_robot_compatibility(
         raise ValueError(
             "Dataset metadata compatibility check failed with mismatches:\n" + "\n".join(mismatches)
         )
-
-
-########################################################################################
-# Teleoperator smooth handover helpers
-# NOTE(Maxime): These functions use minimal type hints to maintain compatibility with utils
-# being a root module.
-########################################################################################
-
-
-def teleop_supports_feedback(teleop) -> bool:
-    """Return True when the teleop can receive position feedback (is actuated).
-
-    Actuated teleops (e.g. SO-101, OpenArmMini) have non-empty ``feedback_features``
-    and expose ``enable_torque`` / ``disable_torque`` motor-control methods.
-
-    TODO(Maxime): See if it is possible to unify this interface across teleops instead of duck-typing.
-    """
-    return (
-        bool(teleop.feedback_features)
-        and hasattr(teleop, "disable_torque")
-        and hasattr(teleop, "enable_torque")
-    )
-
-
-def teleop_smooth_move_to(teleop, target_pos: dict, duration_s: float = 2.0, fps: int = 30) -> None:
-    """Smoothly move an actuated teleop to ``target_pos`` via linear interpolation.
-
-    Requires the teleoperator to support feedback (i.e. have non-empty
-    ``feedback_features`` and implement ``disable_torque`` / ``enable_torque``).
-
-    ``target_pos`` is expected to be in the teleop's action/feedback key space.
-    For homogeneous setups (e.g. SO-101 leader + SO-101 follower) this matches
-    the robot action key space directly.
-
-    TODO(Maxime): This blocks up to ``duration_s`` seconds; during this time the
-    follower robot does not receive new actions, which could be an issue on LeKiwi.
-    """
-    teleop.enable_torque()
-    current = teleop.get_action()
-    steps = max(int(duration_s * fps), 1)
-
-    for step in range(steps + 1):
-        t = step / steps
-        interp = {
-            k: current[k] * (1 - t) + target_pos[k] * t if k in target_pos else current[k] for k in current
-        }
-        teleop.send_feedback(interp)
-        time.sleep(1 / fps)
-
-
-def follower_smooth_move_to(
-    robot, current: dict, target: dict, duration_s: float = 1.0, fps: int = 30
-) -> None:
-    """Smoothly move the follower robot from ``current`` to ``target`` action.
-
-    Used when the teleop is non-actuated: instead of driving the leader arm to
-    the follower, the follower is brought to the teleop's current pose so the
-    robot meets the operator's hand rather than jumping to it on the first frame.
-
-    Both ``current`` and ``target`` must be in the robot action key space
-    (i.e. the output of ``robot_action_processor``).
-    """
-    steps = max(int(duration_s * fps), 1)
-
-    for step in range(steps + 1):
-        t = step / steps
-        interp = {k: current[k] * (1 - t) + target[k] * t if k in target else current[k] for k in current}
-        robot.send_action(interp)
-        time.sleep(1 / fps)

src/lerobot/configs/default.py

@@ -39,10 +39,6 @@ class DatasetConfig:
     # This reduces memory and speeds up DataLoader IPC. The training pipeline handles the conversion.
     return_uint8: bool = False
     streaming: bool = False
-    # Whole episodes each streaming consumer keeps open to shuffle across (the randomness knob).
-    # Larger mixes more episodes per batch at the cost of cold-start latency; RAM stays small because
-    # the pool holds tabular rows only. Ignored when streaming is False.
-    streaming_episode_pool_size: int = 1024
 
     def __post_init__(self) -> None:
         if self.episodes is not None:

src/lerobot/datasets/byte_index.py

@@ -1,228 +0,0 @@
-"""Runtime in-memory byte index loaded from precomputed sidecar parquet."""
-
-from __future__ import annotations
-
-import logging
-import time
-from dataclasses import dataclass
-from pathlib import Path
-from typing import Any
-
-import numpy as np
-import pyarrow as pa
-import pyarrow.parquet as pq
-
-from .byte_index_builder import BYTE_INDEX_DIR, EPISODES_NAME, FILES_NAME, KEYFRAMES_NAME
-from .mp4_episode_slice import episode_custom_frame_mappings_json
-
-logger = logging.getLogger(__name__)
-
-
-@dataclass(frozen=True)
-class EpisodeSliceLookup:
-    global_episode_id: int
-    file_id: int
-    mdat_offset: int
-    mdat_length: int
-    frame_count: int
-    first_pts: float
-    last_pts: float
-    avg_fps: float
-
-    @property
-    def fetch_bytes(self) -> int:
-        return self.mdat_length
-
-
-@dataclass(frozen=True)
-class FileLookup:
-    file_id: int
-    file_path: str
-    file_size: int
-    moov_offset: int
-    moov_length: int
-    header_length: int
-    faststart: bool
-    avg_fps: float
-    codec: str
-
-
-class EpisodeByteIndex:
-    """Columnar byte-index resident in numpy arrays for O(1) episode lookup."""
-
-    def __init__(
-        self,
-        index_dir: str | Path | None,
-        *,
-        video_keys: list[str],
-        num_episodes: int,
-        mmap: bool = True,
-        files_table: pa.Table | None = None,
-        episodes_table: pa.Table | None = None,
-        mp4_by_rel: dict[str, Any] | None = None,
-    ):
-        self.index_dir = Path(index_dir) if index_dir is not None else None
-        self.video_keys = list(video_keys)
-        self.num_episodes = num_episodes
-        self.num_cameras = len(video_keys)
-        self._cam_to_idx = {cam: i for i, cam in enumerate(self.video_keys)}
-        self._mp4_by_rel = mp4_by_rel
-        self._frame_mappings_by_gid: dict[int, bytes] = {}
-
-        t0 = time.perf_counter()
-        if files_table is not None and episodes_table is not None:
-            files_tbl, episodes_tbl = files_table, episodes_table
-        else:
-            if self.index_dir is None:
-                raise ValueError("index_dir or in-memory tables required")
-            files_path = self.index_dir / FILES_NAME
-            episodes_path = self.index_dir / EPISODES_NAME
-            if not files_path.exists() or not episodes_path.exists():
-                raise FileNotFoundError(f"byte index missing under {self.index_dir}")
-            files_tbl = pq.read_table(files_path, memory_map=mmap)
-            episodes_tbl = pq.read_table(episodes_path, memory_map=mmap)
-
-        self._load_tables(files_tbl, episodes_tbl, mmap=mmap)
-        self.build_time_s = time.perf_counter() - t0
-        self.load_time_s = self.build_time_s
-
-    def _load_tables(self, files_tbl: pa.Table, episodes_tbl: pa.Table, *, mmap: bool) -> None:
-        def col(tbl, name: str):
-            array = tbl.column(name).combine_chunks()
-            if pa.types.is_boolean(array.type):
-                return array.to_numpy(zero_copy_only=False)
-            return array.to_numpy()
-
-        self.file_id = col(files_tbl, "file_id")
-        self.file_path = files_tbl.column("file_path").to_pylist()
-        self.file_size = col(files_tbl, "file_size")
-        self.moov_offset = col(files_tbl, "moov_offset")
-        self.moov_length = col(files_tbl, "moov_length")
-        self.header_length = col(files_tbl, "header_length")
-        self.faststart = col(files_tbl, "faststart")
-        self.file_avg_fps = col(files_tbl, "avg_fps")
-        self.codec = files_tbl.column("codec").to_pylist()
-
-        ep = episodes_tbl
-        n = len(ep)
-        gid = col(ep, "global_episode_id")
-        order = np.argsort(gid)
-        self._global_episode_id = gid[order]
-        self._episode_index = col(ep, "episode_index")[order]
-        self._camera_index = col(ep, "camera_index")[order]
-        self._file_id = col(ep, "file_id")[order]
-        self._mdat_offset = col(ep, "mdat_offset")[order]
-        self._mdat_length = col(ep, "mdat_length")[order]
-        self._frame_count = col(ep, "frame_count")[order]
-        self._first_pts = col(ep, "first_pts")[order]
-        self._last_pts = col(ep, "last_pts")[order]
-
-        expected = self.num_episodes * self.num_cameras
-        if n != expected:
-            raise ValueError(f"byte index episodes rows {n} != expected {expected}")
-
-        if self.index_dir is not None:
-            keyframes_path = self.index_dir / KEYFRAMES_NAME
-            if keyframes_path.exists():
-                kf_tbl = pq.read_table(keyframes_path, memory_map=mmap)
-                self._keyframes_rows = len(kf_tbl)
-            else:
-                self._keyframes_rows = 0
-        else:
-            self._keyframes_rows = 0
-
-        self.resident_bytes = int(
-            self._global_episode_id.nbytes
-            + self._file_id.nbytes
-            + self._mdat_offset.nbytes
-            + self._mdat_length.nbytes
-            + self.file_size.nbytes
-        )
-
-    @classmethod
-    def from_metadata_root(cls, meta_root: Path, *, video_keys: list[str], num_episodes: int) -> EpisodeByteIndex:
-        return cls(meta_root / BYTE_INDEX_DIR, video_keys=video_keys, num_episodes=num_episodes)
-
-    @classmethod
-    def from_memory_build(
-        cls,
-        meta,
-        data_root: str,
-        *,
-        workers: int = 8,
-        max_episodes: int | None = None,
-        include_frame_mappings_cache: bool = True,
-    ) -> EpisodeByteIndex:
-        """Build a complete byte index in RAM (no parquet write, no dataset push)."""
-        from .byte_index_builder import build_byte_index_in_memory
-
-        return build_byte_index_in_memory(
-            meta,
-            data_root,
-            workers=workers,
-            max_episodes=max_episodes,
-            include_frame_mappings_cache=include_frame_mappings_cache,
-        )
-
-    def lookup(self, episode_index: int, camera_key: str) -> EpisodeSliceLookup:
-        cam_idx = self._cam_to_idx[camera_key]
-        gid = episode_index * self.num_cameras + cam_idx
-        row = int(gid)
-        if row < 0 or row >= len(self._global_episode_id):
-            raise IndexError(f"episode_index={episode_index} camera={camera_key} out of range")
-        file_id = int(self._file_id[row])
-        return EpisodeSliceLookup(
-            global_episode_id=gid,
-            file_id=file_id,
-            mdat_offset=int(self._mdat_offset[row]),
-            mdat_length=int(self._mdat_length[row]),
-            frame_count=int(self._frame_count[row]),
-            first_pts=float(self._first_pts[row]),
-            last_pts=float(self._last_pts[row]),
-            avg_fps=float(self.file_avg_fps[file_id]),
-        )
-
-    def file_lookup(self, file_id: int) -> FileLookup:
-        return FileLookup(
-            file_id=file_id,
-            file_path=self.file_path[file_id],
-            file_size=int(self.file_size[file_id]),
-            moov_offset=int(self.moov_offset[file_id]),
-            moov_length=int(self.moov_length[file_id]),
-            header_length=int(self.header_length[file_id]),
-            faststart=bool(self.faststart[file_id]),
-            avg_fps=float(self.file_avg_fps[file_id]),
-            codec=self.codec[file_id],
-        )
-
-    def header_byte_range(self, file_id: int) -> tuple[int, int]:
-        length = int(self.header_length[file_id])
-        return 0, max(0, length - 1)
-
-    def custom_frame_mappings(self, episode_index: int, camera_key: str) -> bytes | None:
-        cam_idx = self._cam_to_idx[camera_key]
-        gid = episode_index * self.num_cameras + cam_idx
-        cached = self._frame_mappings_by_gid.get(gid)
-        if cached is not None:
-            return cached
-        if self._mp4_by_rel is None:
-            return None
-        lookup = self.lookup(episode_index, camera_key)
-        rel = self.file_path[lookup.file_id]
-        mp4_index = self._mp4_by_rel.get(rel)
-        if mp4_index is None:
-            return None
-        payload = episode_custom_frame_mappings_json(mp4_index, lookup.first_pts, lookup.last_pts)
-        self._frame_mappings_by_gid[gid] = payload
-        return payload
-
-    def stats_dict(self) -> dict[str, float | int]:
-        return {
-            "load_time_s": self.load_time_s,
-            "build_time_s": self.build_time_s,
-            "resident_bytes": self.resident_bytes,
-            "frame_mappings_cached": len(self._frame_mappings_by_gid),
-            "mp4_indices_cached": len(self._mp4_by_rel or {}),
-            "num_files": len(self.file_path),
-            "num_episode_rows": len(self._global_episode_id),
-        }

src/lerobot/datasets/byte_index_builder.py

@@ -1,281 +0,0 @@
-"""Build mmap-able byte-index sidecars for LeRobot streaming video fetch."""
-
-from __future__ import annotations
-
-import json
-import logging
-from concurrent.futures import ThreadPoolExecutor, as_completed
-from dataclasses import dataclass
-from pathlib import Path
-from typing import Any
-
-import fsspec
-import pyarrow as pa
-import pyarrow.parquet as pq
-
-from .mp4_episode_slice import (
-    HEADER_PROBE_BYTES,
-    MAX_HEADER_PROBE_BYTES,
-    average_fps_from_index,
-    episode_keyframes,
-    parse_mp4_file_layout,
-    parse_mp4_index,
-)
-
-logger = logging.getLogger(__name__)
-
-BYTE_INDEX_DIR = "meta/byte_index"
-FILES_NAME = "files.parquet"
-EPISODES_NAME = "episodes.parquet"
-KEYFRAMES_NAME = "keyframes.parquet"
-
-
-@dataclass
-class IndexedFile:
-    file_id: int
-    file_path: str
-    file_size: int
-    moov_offset: int
-    moov_length: int
-    header_length: int
-    faststart: bool
-    avg_fps: float
-    codec: str
-
-
-def fetch_header_bytes(path: str, file_size: int) -> bytes:
-    fs = fsspec.filesystem("hf") if path.startswith("hf://") else fsspec.filesystem("file")
-    probe = HEADER_PROBE_BYTES
-    while True:
-        with fs.open(path, "rb", block_size=max(probe, 2**20), cache_type="none") as f:
-            header = f.read(min(probe, file_size))
-        try:
-            parse_mp4_file_layout(header, file_size)
-            return header
-        except ValueError as exc:
-            if probe >= min(MAX_HEADER_PROBE_BYTES, file_size) or "mdat box not found" not in str(exc):
-                raise
-            probe = min(probe * 2, MAX_HEADER_PROBE_BYTES, file_size)
-
-
-def index_video_file(path: str, *, rel_path: str | None = None) -> tuple[IndexedFile, Any]:
-    fs = fsspec.filesystem("hf") if path.startswith("hf://") else fsspec.filesystem("file")
-    file_size = fs.info(path)["size"]
-    header = fetch_header_bytes(path, file_size)
-    layout = parse_mp4_file_layout(header, file_size)
-    if not layout.faststart:
-        logger.warning("non-faststart MP4 (moov after mdat): %s", path)
-    mp4_index = parse_mp4_index(header, file_size)
-    indexed = IndexedFile(
-        file_id=-1,
-        file_path=rel_path or path,
-        file_size=file_size,
-        moov_offset=layout.moov_offset,
-        moov_length=layout.moov_length,
-        header_length=layout.header_end,
-        faststart=layout.faststart,
-        avg_fps=average_fps_from_index(mp4_index),
-        codec=layout.codec,
-    )
-    return indexed, mp4_index
-
-
-def build_byte_index_tables(
-    meta,
-    data_root: str,
-    *,
-    file_paths: list[str] | None = None,
-    include_keyframes: bool = True,
-    workers: int = 8,
-    existing_files: dict[str, int] | None = None,
-    max_episodes: int | None = None,
-    return_mp4_indices: bool = False,
-    complete_files_table: bool = False,
-) -> tuple[pa.Table, pa.Table, pa.Table | None] | tuple[pa.Table, pa.Table, pa.Table | None, dict[str, Any]]:
-    """Build files/episodes/(optional keyframes) Arrow tables."""
-    video_keys = list(meta.video_keys)
-    n_cams = len(video_keys)
-    cam_to_idx = {cam: i for i, cam in enumerate(video_keys)}
-    num_episodes = meta.total_episodes if max_episodes is None else min(max_episodes, meta.total_episodes)
-
-    rel_paths: set[str] = set()
-    for ep_idx in range(num_episodes):
-        for cam in video_keys:
-            rel_paths.add(str(meta.get_video_file_path(ep_idx, cam)))
-    path_by_rel = {rel: f"{data_root.rstrip('/')}/{rel}" for rel in sorted(rel_paths)}
-    if file_paths is None:
-        file_paths = list(path_by_rel.values())
-    rel_by_path = {path_by_rel[rel]: rel for rel in path_by_rel}
-
-    existing_files = existing_files or {}
-    file_meta_by_rel: dict[str, dict[str, Any]] = {}
-    mp4_by_rel: dict[str, Any] = {}
-    next_file_id = max(existing_files.values(), default=-1) + 1
-
-    to_index = [rel for rel in sorted(rel_paths) if rel not in existing_files]
-    if to_index:
-        with ThreadPoolExecutor(max_workers=workers) as pool:
-            futures = {
-                pool.submit(index_video_file, path_by_rel[rel], rel_path=rel): rel for rel in to_index
-            }
-            for fut in as_completed(futures):
-                rel = futures[fut]
-                indexed, mp4_index = fut.result()
-                indexed.file_id = next_file_id
-                mp4_by_rel[rel] = mp4_index
-                file_meta_by_rel[rel] = {
-                    "file_id": indexed.file_id,
-                    "file_path": rel,
-                    "file_size": indexed.file_size,
-                    "moov_offset": indexed.moov_offset,
-                    "moov_length": indexed.moov_length,
-                    "header_length": indexed.header_length,
-                    "faststart": indexed.faststart,
-                    "avg_fps": indexed.avg_fps,
-                    "codec": indexed.codec,
-                }
-                existing_files[rel] = indexed.file_id
-                next_file_id += 1
-
-    missing_rels = {
-        str(meta.get_video_file_path(ep, cam))
-        for ep in range(num_episodes)
-        for cam in video_keys
-    } - set(mp4_by_rel.keys())
-    if missing_rels:
-        with ThreadPoolExecutor(max_workers=workers) as pool:
-            futures = {
-                pool.submit(index_video_file, path_by_rel[rel], rel_path=rel): rel
-                for rel in missing_rels
-                if rel not in mp4_by_rel
-            }
-            for fut in as_completed(futures):
-                rel = futures[fut]
-                _, mp4_index = fut.result()
-                mp4_by_rel[rel] = mp4_index
-
-    episode_rows: list[dict[str, Any]] = []
-    keyframe_rows: list[dict[str, Any]] = []
-    for ep_idx in range(num_episodes):
-        for cam in video_keys:
-            rel = str(meta.get_video_file_path(ep_idx, cam))
-            path = f"{data_root.rstrip('/')}/{rel}"
-            if rel not in existing_files:
-                raise KeyError(f"file not indexed: {rel}")
-            mp4_index = mp4_by_rel[rel]
-            ep = meta.episodes[ep_idx]
-            from_ts = float(ep[f"videos/{cam}/from_timestamp"])
-            to_ts = float(ep[f"videos/{cam}/to_timestamp"])
-            span = mp4_index.episode_byte_span(from_ts, to_ts)
-            global_episode_id = ep_idx * n_cams + cam_to_idx[cam]
-            mdat_length = span.slice_hi - span.slice_lo + 1
-            episode_rows.append(
-                {
-                    "global_episode_id": global_episode_id,
-                    "episode_index": ep_idx,
-                    "camera_key": cam,
-                    "camera_index": cam_to_idx[cam],
-                    "file_id": existing_files[rel],
-                    "mdat_offset": span.slice_lo,
-                    "mdat_length": mdat_length,
-                    "frame_count": max(1, round((to_ts - from_ts) * meta.fps)),
-                    "first_pts": from_ts,
-                    "last_pts": to_ts,
-                }
-            )
-            if include_keyframes:
-                timescale = mp4_index.timescale
-                for pts_s, byte_off in episode_keyframes(mp4_index, from_ts, to_ts):
-                    keyframe_rows.append(
-                        {
-                            "global_episode_id": global_episode_id,
-                            "pts": int(round(pts_s * timescale)),
-                            "byte_offset": byte_off,
-                        }
-                    )
-
-    referenced_rels = {
-        str(meta.get_video_file_path(ep, cam)) for ep in range(num_episodes) for cam in video_keys
-    }
-    if complete_files_table:
-        files_table = pa.Table.from_pylist([file_meta_by_rel[rel] for rel in sorted(referenced_rels)])
-    elif to_index:
-        files_table = pa.Table.from_pylist([file_meta_by_rel[rel] for rel in sorted(to_index)])
-    else:
-        files_table = None
-    episodes_table = pa.Table.from_pylist(episode_rows)
-    keyframes_table = pa.Table.from_pylist(keyframe_rows) if include_keyframes and keyframe_rows else None
-    if return_mp4_indices:
-        return files_table, episodes_table, keyframes_table, mp4_by_rel
-    return files_table, episodes_table, keyframes_table
-
-
-def build_byte_index_in_memory(
-    meta,
-    data_root: str,
-    *,
-    workers: int = 8,
-    max_episodes: int | None = None,
-    include_frame_mappings_cache: bool = False,
-):
-    """Build a complete byte index resident in RAM (no parquet write, no dataset push)."""
-    from .byte_index import EpisodeByteIndex
-
-    num_episodes = meta.total_episodes if max_episodes is None else min(max_episodes, meta.total_episodes)
-    files_tbl, episodes_tbl, _, mp4_by_rel = build_byte_index_tables(
-        meta,
-        data_root,
-        include_keyframes=False,
-        workers=workers,
-        max_episodes=max_episodes,
-        return_mp4_indices=True,
-        complete_files_table=True,
-    )
-    index = EpisodeByteIndex(
-        None,
-        video_keys=list(meta.video_keys),
-        num_episodes=num_episodes,
-        files_table=files_tbl,
-        episodes_table=episodes_tbl,
-        mp4_by_rel=mp4_by_rel,
-    )
-    if include_frame_mappings_cache:
-        for ep_idx in range(num_episodes):
-            for cam in meta.video_keys:
-                index.custom_frame_mappings(ep_idx, cam)
-    return index
-
-
-def write_byte_index(
-    output_dir: Path,
-    files_table: pa.Table | None,
-    episodes_table: pa.Table,
-    keyframes_table: pa.Table | None = None,
-    *,
-    merge_existing: bool = True,
-) -> None:
-    output_dir.mkdir(parents=True, exist_ok=True)
-    files_path = output_dir / FILES_NAME
-    episodes_path = output_dir / EPISODES_NAME
-    keyframes_path = output_dir / KEYFRAMES_NAME
-
-    if merge_existing and files_path.exists() and files_table is not None:
-        prev = pq.read_table(files_path)
-        files_table = pa.concat_tables([prev, files_table])
-
-    if files_table is not None:
-        pq.write_table(files_table, files_path)
-
-    pq.write_table(episodes_table, episodes_path)
-    if keyframes_table is not None:
-        if merge_existing and keyframes_path.exists():
-            keyframes_table = pa.concat_tables([pq.read_table(keyframes_path), keyframes_table])
-        pq.write_table(keyframes_table, keyframes_path)
-
-
-def load_existing_file_ids(index_dir: Path) -> dict[str, int]:
-    files_path = index_dir / FILES_NAME
-    if not files_path.exists():
-        return {}
-    table = pq.read_table(files_path, columns=["file_id", "file_path"])
-    return {row["file_path"]: int(row["file_id"]) for row in table.to_pylist()}

src/lerobot/datasets/dataset_tools.py

@@ -945,17 +945,8 @@ def _write_parquet(df: pd.DataFrame, path: Path, meta: LeRobotDatasetMetadata) -
         ep_dataset = embed_images(ep_dataset)
 
     table = ep_dataset.with_format("arrow")[:]
-    # Emit several row groups with a page index instead of one giant row group. A single row group forces
-    # streaming readers to materialize the whole file's columns per open shard; with random-access streaming
-    # (shuffle + delta windows) across many workers x shards that dominates RAM. Targeting ~32MB-uncompressed
-    # groups bounds per-shard memory while keeping groups large enough to scan
-    # efficiently; the page index lets readers skip to the pages they need.
-    target_row_group_bytes = 32 * 1024 * 1024
-    row_group_size = max(1, min(table.num_rows, table.num_rows * target_row_group_bytes // max(table.nbytes, 1)))
-    writer = pq.ParquetWriter(
-        path, schema=table.schema, compression="snappy", use_dictionary=True, write_page_index=True
-    )
-    writer.write_table(table, row_group_size=row_group_size)
+    writer = pq.ParquetWriter(path, schema=table.schema, compression="snappy", use_dictionary=True)
+    writer.write_table(table)
     writer.close()
 
 

src/lerobot/datasets/episode_byte_cache.py

@@ -1,263 +0,0 @@
-"""Node-local LRU byte cache using precomputed byte-index manifest sidecars."""
-
-from __future__ import annotations
-
-import logging
-import threading
-import time
-from collections import OrderedDict
-from concurrent.futures import Future, ThreadPoolExecutor
-from dataclasses import dataclass, field
-from typing import Any
-
-import fsspec
-
-from .byte_index import EpisodeByteIndex, EpisodeSliceLookup
-from .mp4_episode_slice import SparseMp4Reader
-from .torchcodec_utils import open_video_decoder
-
-logger = logging.getLogger(__name__)
-
-
-@dataclass
-class CacheStats:
-    hits: int = 0
-    misses: int = 0
-    bytes_fetched: int = 0
-    full_file_fallbacks: int = 0
-    prefetch_submitted: int = 0
-    prefetch_waits: int = 0
-    mdat_slices: int = 0
-    prefix_fetches: int = 0
-    fetch_to_buffer_s: float = 0.0
-    buffer_to_decoder_s: float = 0.0
-    buffer_hit_decoder_s: float = 0.0
-    decode_frame_s: float = 0.0
-    decode_frames: int = 0
-
-    def merge(self, other: CacheStats) -> None:
-        for name in self.__dataclass_fields__:
-            setattr(self, name, getattr(self, name) + getattr(other, name))
-
-    def stats_dict(self) -> dict[str, int | float]:
-        avg_miss = self.bytes_fetched / max(1, self.misses)
-        return {
-            "byte_cache_hits": self.hits,
-            "byte_cache_misses": self.misses,
-            "byte_cache_bytes_fetched": self.bytes_fetched,
-            "byte_cache_bytes_per_miss": avg_miss,
-            "byte_cache_full_file_fallbacks": self.full_file_fallbacks,
-            "byte_cache_prefetch_submitted": self.prefetch_submitted,
-            "byte_cache_prefetch_waits": self.prefetch_waits,
-            "byte_cache_mdat_slices": self.mdat_slices,
-            "byte_cache_prefix_fetches": self.prefix_fetches,
-            "fetch_to_buffer_ms_per_miss": 1000 * self.fetch_to_buffer_s / max(1, self.misses),
-            "buffer_to_decoder_ms_per_miss": 1000 * self.buffer_to_decoder_s / max(1, self.misses),
-            "buffer_hit_decoder_ms_per_hit": 1000 * self.buffer_hit_decoder_s / max(1, self.hits),
-            "decode_ms_per_frame": 1000 * self.decode_frame_s / max(1, self.decode_frames),
-        }
-
-
-@dataclass
-class _EpisodeEntry:
-    decoders: dict[str, Any] = field(default_factory=dict)
-    ready: threading.Event = field(default_factory=threading.Event)
-    error: Exception | None = None
-
-
-class RangeFetcher:
-    """Sequential byte-range GETs via fsspec."""
-
-    def __init__(self, path: str):
-        self.path = path
-        self._fs = fsspec.filesystem("hf") if path.startswith("hf://") else fsspec.filesystem("file")
-
-    def fetch(self, lo: int, hi: int) -> bytes:
-        if hi < lo:
-            return b""
-        with self._fs.open(self.path, "rb", block_size=max(2**20, hi - lo + 1), cache_type="none") as f:
-            f.seek(lo)
-            return f.read(hi - lo + 1)
-
-
-class EpisodeByteCache:
-    """Manifest-driven episode MP4 fetch + in-memory sparse decode."""
-
-    MAX_BYTES_PER_MISS = 25 * 1024 * 1024
-
-    def __init__(
-        self,
-        byte_index: EpisodeByteIndex,
-        max_bytes: int,
-        *,
-        data_root: str,
-        max_prefetch_workers: int = 4,
-    ):
-        if max_bytes <= 0:
-            raise ValueError(f"max_bytes must be positive; got {max_bytes}")
-        self.byte_index = byte_index
-        self.max_bytes = max_bytes
-        self.data_root = data_root.rstrip("/")
-        self._bytes_used = 0
-        self._lock = threading.Lock()
-        self._cache: OrderedDict[tuple[Any, ...], tuple[Any, int]] = OrderedDict()
-        self._header_cache: dict[int, bytes] = {}
-        self._fetcher_cache: dict[int, RangeFetcher] = {}
-        self._episodes: dict[int, _EpisodeEntry] = {}
-        self._stats = CacheStats()
-        self._executor = ThreadPoolExecutor(max_workers=max_prefetch_workers)
-        self._futures: dict[int, Future] = {}
-
-    @property
-    def stats(self) -> CacheStats:
-        with self._lock:
-            return CacheStats(**{k: getattr(self._stats, k) for k in CacheStats.__dataclass_fields__})
-
-    def submit_prefetch(self, ep_idx: int) -> None:
-        with self._lock:
-            if ep_idx in self._episodes or ep_idx in self._futures:
-                return
-            self._stats.prefetch_submitted += 1
-            fut = self._executor.submit(self._prefetch_episode, ep_idx)
-            self._futures[ep_idx] = fut
-
-    def ensure_ready(self, ep_idx: int) -> None:
-        with self._lock:
-            fut = self._futures.pop(ep_idx, None)
-        if fut is not None:
-            with self._lock:
-                self._stats.prefetch_waits += 1
-            fut.result()
-        entry = self._episodes.get(ep_idx)
-        if entry is None:
-            raise KeyError(f"episode {ep_idx} not prefetched")
-        if entry.error is not None:
-            raise entry.error
-        entry.ready.wait()
-
-    def get_decoder(self, ep_idx: int, video_key: str) -> Any:
-        entry = self._episodes[ep_idx]
-        if entry.error is not None:
-            raise entry.error
-        entry.ready.wait()
-        return entry.decoders[video_key]
-
-    def close(self) -> None:
-        self._executor.shutdown(wait=False, cancel_futures=True)
-
-    def _prefetch_episode(self, ep_idx: int) -> None:
-        entry = _EpisodeEntry()
-        self._episodes[ep_idx] = entry
-        try:
-            for cam in self.byte_index.video_keys:
-                entry.decoders[cam] = self._get_or_build_decoder(ep_idx, cam)
-        except Exception as exc:
-            entry.error = exc
-        finally:
-            entry.ready.set()
-
-    def _get_or_build_decoder(self, ep_idx: int, cam: str) -> Any:
-        key = (ep_idx, cam)
-        with self._lock:
-            cached = self._cache.get(key)
-            if cached is not None:
-                self._cache.move_to_end(key)
-                self._stats.hits += 1
-                payload, _ = cached
-                t0 = time.perf_counter()
-                dec = self._decoder_from_payload(payload, ep_idx, cam)
-                with self._lock:
-                    self._stats.buffer_hit_decoder_s += time.perf_counter() - t0
-                return dec
-
-        payload, payload_bytes, dec = self._fetch_manifest_slice(ep_idx, cam)
-
-        with self._lock:
-            self._stats.misses += 1
-            if payload_bytes > self.MAX_BYTES_PER_MISS:
-                logger.warning(
-                    "byte cache miss fetched %.1f MB (>25 MB) for ep=%s cam=%s",
-                    payload_bytes / 1e6,
-                    ep_idx,
-                    cam,
-                )
-            self._evict_until(payload_bytes)
-            self._cache[key] = (payload, payload_bytes)
-            self._bytes_used += payload_bytes
-        return dec
-
-    def _fetch_manifest_slice(self, ep_idx: int, cam: str) -> tuple[SparseMp4Reader, int, Any]:
-        lookup = self.byte_index.lookup(ep_idx, cam)
-        file_info = self.byte_index.file_lookup(lookup.file_id)
-        fetcher = self._get_fetcher(lookup.file_id, file_info.file_path)
-        t_fetch = time.perf_counter()
-        header = self._get_header_bytes(lookup.file_id, fetcher, file_info.header_length)
-        lo = lookup.mdat_offset
-        hi = lo + lookup.mdat_length - 1
-        mdat = fetcher.fetch(lo, hi)
-        fetch_s = time.perf_counter() - t_fetch
-        nbytes = len(header) + len(mdat)
-        with self._lock:
-            self._stats.bytes_fetched += nbytes
-            self._stats.mdat_slices += 1
-            self._stats.fetch_to_buffer_s += fetch_s
-
-        def lazy_fetch(pos: int, end: int) -> bytes:
-            data = fetcher.fetch(pos, end)
-            with self._lock:
-                self._stats.bytes_fetched += len(data)
-            return data
-
-        reader = SparseMp4Reader(
-            file_size=file_info.file_size,
-            header=header,
-            mdat_lo=lo,
-            mdat_bytes=mdat,
-            lazy_fetch=lazy_fetch,
-        )
-        t_init = time.perf_counter()
-        dec = self._decoder_from_payload(reader, ep_idx, cam)
-        self._validate_decoder(dec, lookup)
-        init_s = time.perf_counter() - t_init
-        with self._lock:
-            self._stats.buffer_to_decoder_s += init_s
-        self._rewind_payload(reader)
-        return reader, nbytes, dec
-
-    def _get_fetcher(self, file_id: int, rel_path: str) -> RangeFetcher:
-        if file_id not in self._fetcher_cache:
-            path = rel_path if rel_path.startswith("hf://") else f"{self.data_root}/{rel_path}"
-            self._fetcher_cache[file_id] = RangeFetcher(path)
-        return self._fetcher_cache[file_id]
-
-    def _get_header_bytes(self, file_id: int, fetcher: RangeFetcher, header_length: int) -> bytes:
-        if file_id in self._header_cache:
-            return self._header_cache[file_id]
-        hi = max(0, header_length - 1)
-        header = fetcher.fetch(0, hi)
-        with self._lock:
-            self._header_cache[file_id] = header
-            self._stats.bytes_fetched += len(header)
-        return header
-
-    def _decoder_from_payload(
-        self, payload: SparseMp4Reader, ep_idx: int, cam: str
-    ) -> Any:
-        payload.seek(0)
-        mappings = self.byte_index.custom_frame_mappings(ep_idx, cam)
-        return open_video_decoder(payload, frame_mappings=mappings)
-
-    def _validate_decoder(self, dec: Any, lookup: EpisodeSliceLookup) -> None:
-        begin = float(dec.metadata.begin_stream_seconds)
-        end = float(dec.metadata.end_stream_seconds)
-        duration = max(0.01, end - begin)
-        for ts in (begin + 1e-3, begin + 0.5 * duration, end - 1e-3):
-            dec.get_frames_played_at([ts]).data
-
-    def _rewind_payload(self, payload: SparseMp4Reader) -> None:
-        payload.seek(0)
-
-    def _evict_until(self, need: int) -> None:
-        while self._bytes_used + need > self.max_bytes and self._cache:
-            _, (_, size) = self._cache.popitem(last=False)
-            self._bytes_used -= size

src/lerobot/datasets/factory.py

@@ -106,7 +106,7 @@ def make_dataset(cfg: TrainPipelineConfig) -> LeRobotDataset | MultiLeRobotDatas
                 delta_timestamps=delta_timestamps,
                 image_transforms=image_transforms,
                 revision=cfg.dataset.revision,
-                episode_pool_size=cfg.dataset.streaming_episode_pool_size,
+                max_num_shards=cfg.num_workers,
                 tolerance_s=cfg.tolerance_s,
                 return_uint8=True,
             )

src/lerobot/datasets/mp4_episode_slice.py

@@ -1,555 +0,0 @@
-"""MP4 moov parsing and tight per-episode mdat byte-range fetching.
-
-LeRobot v3 concatenates episodes into shared MP4 files (faststart: moov at head).
-For streaming we fetch only the file header plus the episode's contiguous mdat span
-instead of the ``0..episode_end`` prefix.
-"""
-
-from __future__ import annotations
-
-import io
-import struct
-import threading
-from dataclasses import dataclass, field
-from typing import Callable
-
-KEYFRAME_PAD_S = 0.1
-HEADER_PROBE_BYTES = 4 * 1024 * 1024
-MAX_HEADER_PROBE_BYTES = 16 * 1024 * 1024
-
-
-@dataclass
-class Mp4FileLayout:
-    file_size: int
-    moov_offset: int
-    moov_length: int
-    header_end: int
-    mdat_offset: int
-    mdat_size: int
-    faststart: bool
-    codec: str
-
-
-def parse_mp4_file_layout(header_bytes: bytes, file_size: int) -> Mp4FileLayout:
-    """Return top-level MP4 layout (moov/mdat positions, faststart flag)."""
-    boxes = list(_iter_boxes(header_bytes))
-    moov_offset = mdat_offset = -1
-    moov_length = mdat_size = 0
-    for off, size, typ, _ in boxes:
-        if typ == b"moov" and moov_offset < 0:
-            moov_offset, moov_length = off, size
-        if typ == b"mdat" and mdat_offset < 0:
-            mdat_offset, mdat_size = off, size
-    if moov_offset < 0:
-        raise ValueError("moov box not found in header probe")
-    if mdat_offset < 0:
-        raise ValueError("mdat box not found in header probe; increase HEADER_PROBE_BYTES")
-    faststart = moov_offset < mdat_offset
-    header_end = mdat_offset
-    codec = _parse_video_codec(header_bytes)
-    return Mp4FileLayout(
-        file_size=file_size,
-        moov_offset=moov_offset,
-        moov_length=moov_length,
-        header_end=header_end,
-        mdat_offset=mdat_offset,
-        mdat_size=mdat_size,
-        faststart=faststart,
-        codec=codec,
-    )
-
-
-def _parse_video_codec(header_bytes: bytes) -> str:
-    moov = _find_box_payload(header_bytes, b"moov")
-    if moov is None:
-        return "unknown"
-    trak = _find_video_trak(moov)
-    if trak is None:
-        return "unknown"
-    stsd = _find_box_payload(_find_box_payload(trak, b"stbl") or b"", b"stsd")
-    if stsd is None or len(stsd) < 12:
-        return "unknown"
-    # stsd: version(1)+flags(3)+entry_count(4)+entry_size(4)+codec(4)
-    if len(stsd) >= 12:
-        return stsd[8:12].decode("latin1", errors="replace").strip("\x00")
-    return "unknown"
-
-
-def average_fps_from_index(index: Mp4VideoIndex) -> float:
-    index.ensure_tables()
-    if index.num_samples < 2:
-        return 30.0
-    duration = index.sample_pts(index.num_samples - 1)
-    if duration <= 0:
-        return 30.0
-    return index.num_samples / duration
-
-
-def episode_custom_frame_mappings_json(
-    index: Mp4VideoIndex, from_ts: float, to_ts: float, keyframe_pad_s: float = KEYFRAME_PAD_S
-) -> bytes:
-    """Build TorchCodec ``custom_frame_mappings`` JSON for one episode span."""
-    import json
-
-    index.ensure_tables()
-    lo_idx = _first_sample_at_or_after(index._pts, max(0.0, from_ts - keyframe_pad_s))
-    hi_idx = _last_sample_at_or_before(index._pts, to_ts + keyframe_pad_s)
-    hi_idx = min(hi_idx, index.num_samples - 1)
-    lo_idx = _keyframe_back(index.sync_samples, lo_idx)
-
-    sync = set(index.sync_samples)
-    timescale = index.timescale
-    # stts deltas for duration per sample (expand stts entries to per-sample delta)
-    sample_deltas: list[int] = []
-    for count, delta in index.stts:
-        sample_deltas.extend([delta] * count)
-    while len(sample_deltas) < index.num_samples:
-        sample_deltas.append(sample_deltas[-1] if sample_deltas else timescale // 30)
-
-    frames = []
-    for idx in range(lo_idx, hi_idx + 1):
-        frames.append(
-            {
-                "pts": int(round(index._pts[idx] * timescale)),
-                "duration": int(sample_deltas[idx]),
-                "key_frame": int((idx + 1) in sync) if sync else int(idx == lo_idx),
-            }
-        )
-    return json.dumps({"frames": frames}).encode()
-
-
-def episode_keyframes(
-    index: Mp4VideoIndex, from_ts: float, to_ts: float, keyframe_pad_s: float = KEYFRAME_PAD_S
-) -> list[tuple[float, int]]:
-    """Return (pts_seconds, byte_offset) for sync samples in the episode span."""
-    index.ensure_tables()
-    span = index.episode_byte_span(from_ts, to_ts, keyframe_pad_s)
-    lo_idx = _first_sample_at_or_after(index._pts, max(0.0, from_ts - keyframe_pad_s))
-    hi_idx = _last_sample_at_or_before(index._pts, to_ts + keyframe_pad_s)
-    if not index.sync_samples:
-        return [(index.sample_pts(lo_idx), index.sample_offset(lo_idx))]
-    out: list[tuple[float, int]] = []
-    for sync_one_based in index.sync_samples:
-        idx = sync_one_based - 1
-        if lo_idx <= idx <= hi_idx:
-            out.append((index.sample_pts(idx), index.sample_offset(idx)))
-    return out or [(index.sample_pts(lo_idx), index.sample_offset(lo_idx))]
-
-
-@dataclass
-class EpisodeByteSpan:
-    """Absolute file byte ranges to fetch for one episode."""
-
-    file_size: int
-    header_end: int
-    slice_lo: int
-    slice_hi: int
-
-    @property
-    def header_bytes(self) -> tuple[int, int]:
-        return 0, self.header_end - 1
-
-    @property
-    def mdat_bytes(self) -> tuple[int, int]:
-        return self.slice_lo, self.slice_hi
-
-    @property
-    def total_fetch_bytes(self) -> int:
-        header = self.header_end
-        mdat = self.slice_hi - self.slice_lo + 1
-        return header + mdat
-
-
-@dataclass
-class Mp4VideoIndex:
-    file_size: int
-    header_end: int
-    mdat_offset: int
-    mdat_size: int
-    timescale: int
-    stts: list[tuple[int, int]]
-    stsz: list[int]
-    stsc: list[tuple[int, int, int]]
-    stco: list[int]
-    sync_samples: list[int]
-    _pts: list[float] = field(default_factory=list, repr=False)
-    _offsets: list[int] = field(default_factory=list, repr=False)
-
-    def ensure_tables(self) -> None:
-        if self._pts:
-            return
-        self._pts = _pts_from_stts(self.stts, self.timescale)
-        self._offsets = _sample_byte_offsets(self.stsc, self.stco, self.stsz)
-
-    @property
-    def num_samples(self) -> int:
-        return len(self.stsz)
-
-    def sample_pts(self, index: int) -> float:
-        self.ensure_tables()
-        return self._pts[index]
-
-    def sample_offset(self, index: int) -> int:
-        self.ensure_tables()
-        index = max(0, min(index, len(self._offsets) - 1))
-        return self._offsets[index]
-
-    def sample_end(self, index: int) -> int:
-        return self.sample_offset(index) + self.stsz[index]
-
-    def episode_byte_span(self, from_ts: float, to_ts: float, keyframe_pad_s: float = KEYFRAME_PAD_S) -> EpisodeByteSpan:
-        self.ensure_tables()
-        n = self.num_samples
-        if n == 0:
-            raise ValueError("MP4 has no video samples")
-
-        pad = max(keyframe_pad_s, 0.05 * max(0.01, to_ts - from_ts))
-        lo_ts = max(0.0, from_ts - pad)
-        hi_ts = to_ts + pad
-
-        lo_idx = _first_sample_at_or_after(self._pts, lo_ts)
-        hi_idx = _last_sample_at_or_before(self._pts, hi_ts)
-        hi_idx = min(hi_idx, n - 1)
-        lo_idx = min(lo_idx, n - 1)
-
-        lo_idx = _keyframe_back(self.sync_samples, lo_idx)
-
-        slice_lo = self.sample_offset(lo_idx)
-        slice_hi = self.sample_end(min(hi_idx, len(self._offsets) - 1))
-        return EpisodeByteSpan(
-            file_size=self.file_size,
-            header_end=self.header_end,
-            slice_lo=slice_lo,
-            slice_hi=min(slice_hi, self.file_size - 1),
-        )
-
-
-class SparseMp4Reader(io.BufferedIOBase):
-    """Range-backed MP4 reader: header + one mdat span at absolute offsets."""
-
-    def __init__(
-        self,
-        file_size: int,
-        header: bytes,
-        mdat_lo: int,
-        mdat_bytes: bytes,
-        lazy_fetch: Callable[[int, int], bytes] | None = None,
-    ):
-        self._size = file_size
-        self._header = header
-        self._mdat_lo = mdat_lo
-        self._mdat_hi = mdat_lo + len(mdat_bytes)
-        self._mdat = mdat_bytes
-        self._lazy_fetch = lazy_fetch
-        self._pos = 0
-        self._lock = threading.Lock()
-
-    def readable(self) -> bool:
-        return True
-
-    def seekable(self) -> bool:
-        return True
-
-    def tell(self) -> int:
-        return self._pos
-
-    def seek(self, offset: int, whence: int = io.SEEK_SET) -> int:
-        if whence == io.SEEK_SET:
-            self._pos = offset
-        elif whence == io.SEEK_CUR:
-            self._pos += offset
-        elif whence == io.SEEK_END:
-            self._pos = self._size + offset
-        else:
-            raise ValueError(f"invalid whence: {whence}")
-        self._pos = max(0, min(self._pos, self._size))
-        return self._pos
-
-    def read(self, size: int = -1) -> bytes:
-        if size < 0:
-            size = self._size - self._pos
-        if size <= 0:
-            return b""
-
-        out = bytearray()
-        remaining = size
-        pos = self._pos
-        while remaining > 0 and pos < self._size:
-            chunk = self._read_at(pos, remaining)
-            if not chunk:
-                break
-            out.extend(chunk)
-            pos += len(chunk)
-            remaining -= len(chunk)
-        self._pos = pos
-        return bytes(out)
-
-    def _read_at(self, pos: int, n: int) -> bytes:
-        header_len = len(self._header)
-        if pos < header_len:
-            end = min(pos + n, header_len)
-            return self._header[pos:end]
-
-        if self._mdat_lo <= pos < self._mdat_hi:
-            end = min(pos + n, self._mdat_hi)
-            off = pos - self._mdat_lo
-            return self._mdat[off : off + (end - pos)]
-
-        if self._lazy_fetch is not None:
-            with self._lock:
-                end = min(pos + n, self._size)
-                return self._lazy_fetch(pos, end - 1)
-
-        return b"\x00" * min(n, self._size - pos)
-
-
-def parse_mp4_index(header_bytes: bytes, file_size: int) -> Mp4VideoIndex:
-    """Parse moov sample tables from the file header (faststart layout)."""
-    layout = parse_mp4_file_layout(header_bytes, file_size)
-    mdat_offset, mdat_size = layout.mdat_offset, layout.mdat_size
-    moov = _find_box_payload(header_bytes, b"moov")
-    if moov is None:
-        raise ValueError("moov box not found in MP4 header probe")
-
-    trak = _find_video_trak(moov)
-    if trak is None:
-        raise ValueError("video trak not found in moov")
-
-    mdhd = _find_box_payload(trak, b"mdhd")
-    if mdhd is None:
-        raise ValueError("mdhd not found")
-    timescale = _parse_mdhd_timescale(mdhd)
-
-    stbl = _find_box_payload(trak, b"stbl")
-    if stbl is None:
-        raise ValueError("stbl not found")
-
-    stts = _parse_stts(_find_box_payload(stbl, b"stts"))
-    stsz = _parse_stsz(_find_box_payload(stbl, b"stsz"))
-    stsc = _parse_stsc(_find_box_payload(stbl, b"stsc"))
-    stco_payload = _find_box_payload(stbl, b"stco")
-    co64_payload = _find_box_payload(stbl, b"co64")
-    if stco_payload is not None:
-        stco = _parse_stco(stco_payload)
-    elif co64_payload is not None:
-        stco = _parse_co64(co64_payload)
-    else:
-        raise ValueError("stco/co64 not found")
-
-    stss_payload = _find_box_payload(stbl, b"stss")
-    sync_samples = _parse_stss(stss_payload) if stss_payload else []
-
-    return Mp4VideoIndex(
-        file_size=file_size,
-        header_end=layout.header_end,
-        mdat_offset=mdat_offset,
-        mdat_size=mdat_size,
-        timescale=timescale,
-        stts=stts,
-        stsz=stsz,
-        stsc=stsc,
-        stco=stco,
-        sync_samples=sync_samples,
-    )
-
-
-def _box_header(data: bytes, offset: int) -> tuple[int, bytes, int] | None:
-    if offset + 8 > len(data):
-        return None
-    size, typ = struct.unpack_from(">I4s", data, offset)
-    header = 8
-    if size == 1:
-        if offset + 16 > len(data):
-            return None
-        size = struct.unpack_from(">Q", data, offset + 8)[0]
-        header = 16
-    elif size == 0:
-        size = len(data) - offset
-    return size, typ, header
-
-
-def _iter_boxes(data: bytes, start: int = 0, end: int | None = None):
-    end = end if end is not None else len(data)
-    off = start
-    while off + 8 <= end:
-        hdr = _box_header(data, off)
-        if hdr is None or hdr[0] < hdr[2]:
-            break
-        size, typ, header = hdr
-        yield off, size, typ, data[off + header : off + size]
-        off += size
-
-
-def _find_box_payload(data: bytes, target: bytes) -> bytes | None:
-    for _, _, typ, payload in _iter_boxes(data):
-        if typ == target:
-            return payload
-        if typ in (b"moov", b"trak", b"mdia", b"minf", b"stbl"):
-            found = _find_box_payload(payload, target)
-            if found is not None:
-                return found
-    return None
-
-
-def _find_video_trak(moov: bytes) -> bytes | None:
-    for _, _, typ, payload in _iter_boxes(moov):
-        if typ != b"trak":
-            continue
-        hdlr = _find_box_payload(payload, b"hdlr")
-        if hdlr is not None and len(hdlr) >= 12 and hdlr[8:12] == b"vide":
-            return payload
-    return None
-
-
-def _find_mdat(header_bytes: bytes, file_size: int) -> tuple[int, int]:
-    for off, size, typ, _ in _iter_boxes(header_bytes):
-        if typ == b"mdat":
-            return off, size
-    # mdat may start beyond probe; scan from file_size hint unavailable — require probe hit
-    raise ValueError("mdat box not found in header probe; increase HEADER_PROBE_BYTES")
-
-
-def _parse_mdhd_timescale(mdhd: bytes) -> int:
-    version = mdhd[0]
-    if version == 0:
-        return struct.unpack_from(">I", mdhd, 12)[0]
-    return struct.unpack_from(">I", mdhd, 20)[0]
-
-
-def _parse_stts(stts: bytes | None) -> list[tuple[int, int]]:
-    if stts is None:
-        raise ValueError("stts missing")
-    count = struct.unpack_from(">I", stts, 4)[0]
-    out = []
-    off = 8
-    for _ in range(count):
-        sample_count, delta = struct.unpack_from(">II", stts, off)
-        out.append((sample_count, delta))
-        off += 8
-    return out
-
-
-def _parse_stsz(stsz: bytes | None) -> list[int]:
-    if stsz is None:
-        raise ValueError("stsz missing")
-    sample_size, sample_count = struct.unpack_from(">II", stsz, 4)
-    if sample_size != 0:
-        return [sample_size] * sample_count
-    off = 12
-    return list(struct.unpack_from(f">{sample_count}I", stsz, off))
-
-
-def _parse_stsc(stsc: bytes | None) -> list[tuple[int, int, int]]:
-    if stsc is None:
-        raise ValueError("stsc missing")
-    count = struct.unpack_from(">I", stsc, 4)[0]
-    out = []
-    off = 8
-    for _ in range(count):
-        first_chunk, samples_per_chunk, sample_desc = struct.unpack_from(">III", stsc, off)
-        out.append((first_chunk, samples_per_chunk, sample_desc))
-        off += 12
-    return out
-
-
-def _parse_stco(stco: bytes) -> list[int]:
-    count = struct.unpack_from(">I", stco, 4)[0]
-    return list(struct.unpack_from(f">{count}I", stco, 8))
-
-
-def _parse_co64(co64: bytes) -> list[int]:
-    count = struct.unpack_from(">I", co64, 4)[0]
-    return [struct.unpack_from(">Q", co64, 8 + i * 8)[0] for i in range(count)]
-
-
-def _parse_stss(stss: bytes) -> list[int]:
-    count = struct.unpack_from(">I", stss, 4)[0]
-    return list(struct.unpack_from(f">{count}I", stss, 8))
-
-
-def _pts_from_stts(stts: list[tuple[int, int]], timescale: int) -> list[float]:
-    pts: list[float] = []
-    t = 0
-    for count, delta in stts:
-        for _ in range(count):
-            pts.append(t / timescale)
-            t += delta
-    return pts
-
-
-def _sample_byte_offsets(
-    stsc: list[tuple[int, int, int]], stco: list[int], stsz: list[int]
-) -> list[int]:
-    if not stsc:
-        stsc = [(1, len(stsz), 1)]
-
-    offsets: list[int] = []
-    chunk_idx = 0
-    sample_idx = 0
-    sc_idx = 0
-    num_chunks = len(stco)
-
-    while chunk_idx < num_chunks and sample_idx < len(stsz):
-        first_chunk, samples_per_chunk, _ = stsc[min(sc_idx, len(stsc) - 1)]
-        if sc_idx + 1 < len(stsc):
-            next_first = stsc[sc_idx + 1][0]
-            chunks_in_entry = next_first - first_chunk
-        else:
-            chunks_in_entry = num_chunks - chunk_idx
-
-        for _ in range(chunks_in_entry):
-            if chunk_idx >= num_chunks:
-                break
-            offset = stco[chunk_idx]
-            _, samples_per_chunk, _ = stsc[min(sc_idx, len(stsc) - 1)]
-            for _ in range(samples_per_chunk):
-                if sample_idx >= len(stsz):
-                    break
-                offsets.append(offset)
-                offset += stsz[sample_idx]
-                sample_idx += 1
-            chunk_idx += 1
-        sc_idx += 1
-
-    if len(offsets) < len(stsz):
-        # Pad with last known offset progression for malformed stsc edge cases.
-        last = offsets[-1] if offsets else 0
-        while len(offsets) < len(stsz):
-            idx = len(offsets)
-            offsets.append(last)
-            last += stsz[idx]
-
-    return offsets
-
-
-def _first_sample_at_or_after(pts: list[float], ts: float) -> int:
-    lo, hi = 0, len(pts)
-    while lo < hi:
-        mid = (lo + hi) // 2
-        if pts[mid] < ts:
-            lo = mid + 1
-        else:
-            hi = mid
-    return min(lo, len(pts) - 1)
-
-
-def _last_sample_at_or_before(pts: list[float], ts: float) -> int:
-    lo, hi = 0, len(pts)
-    while lo < hi:
-        mid = (lo + hi) // 2
-        if pts[mid] <= ts:
-            lo = mid + 1
-        else:
-            hi = mid
-    return max(0, lo - 1)
-
-
-def _keyframe_back(sync_samples: list[int], sample_idx: int) -> int:
-    if not sync_samples:
-        return max(0, sample_idx - 2)
-    # stss stores 1-based sample numbers
-    one_based = sample_idx + 1
-    prev = [s for s in sync_samples if s <= one_based]
-    if prev:
-        return prev[-1] - 1
-    return 0

src/lerobot/datasets/sampler.py

@@ -30,7 +30,6 @@ class EpisodeAwareSampler:
         drop_n_first_frames: int = 0,
         drop_n_last_frames: int = 0,
         shuffle: bool = False,
-        generator: torch.Generator | None = None,
     ):
         """Sampler that optionally incorporates episode boundary information.
 
@@ -42,10 +41,6 @@ class EpisodeAwareSampler:
             drop_n_first_frames: Number of frames to drop from the start of each episode.
             drop_n_last_frames: Number of frames to drop from the end of each episode.
             shuffle: Whether to shuffle the indices.
-            generator: Generator used for shuffling. Exposing this attribute (even when None) lets
-                       `accelerate` register it as the synchronized RNG in distributed training, so
-                       every rank draws the same permutation and batch shards stay disjoint. When
-                       None, shuffling falls back to the global torch RNG.
         """
         if drop_n_first_frames < 0:
             raise ValueError(f"drop_n_first_frames must be >= 0, got {drop_n_first_frames}")
@@ -78,11 +73,10 @@ class EpisodeAwareSampler:
 
         self.indices = indices
         self.shuffle = shuffle
-        self.generator = generator
 
     def __iter__(self) -> Iterator[int]:
         if self.shuffle:
-            for i in torch.randperm(len(self.indices), generator=self.generator):
+            for i in torch.randperm(len(self.indices)):
                 yield self.indices[i]
         else:
             for i in self.indices:

src/lerobot/datasets/torchcodec_utils.py

@@ -1,49 +0,0 @@
-"""TorchCodec helpers for sparse MP4 IO with optional custom frame mappings."""
-
-from __future__ import annotations
-
-import json
-from typing import Any
-
-import torch
-from torchcodec import FrameBatch, _core as core
-from torchcodec.decoders._video_decoder import _get_and_validate_stream_metadata
-
-
-def frame_mappings_tensors(payload: bytes) -> tuple[torch.Tensor, torch.Tensor, torch.Tensor]:
-    data = json.loads(payload)
-    frames = data["frames"]
-    pts = torch.tensor([int(f["pts"]) for f in frames], dtype=torch.int64)
-    key = torch.tensor([bool(f["key_frame"]) for f in frames], dtype=torch.bool)
-    dur = torch.tensor([int(f["duration"]) for f in frames], dtype=torch.int64)
-    return pts, key, dur
-
-
-class VideoDecoderLike:
-    """Minimal VideoDecoder surface used by episode byte cache."""
-
-    def __init__(self, decoder: torch.Tensor, *, stream_index: int | None = None):
-        self._decoder = decoder
-        (
-            self.metadata,
-            self.stream_index,
-            self._begin_stream_seconds,
-            self._end_stream_seconds,
-            self._num_frames,
-        ) = _get_and_validate_stream_metadata(decoder=decoder, stream_index=stream_index)
-
-    def get_frames_played_at(self, seconds: list[float]) -> FrameBatch:
-        return FrameBatch(*core.get_frames_by_pts(self._decoder, timestamps=seconds))
-
-
-def open_video_decoder(source: Any, *, frame_mappings: bytes | None = None) -> VideoDecoderLike:
-    """Open a decoder on sparse or full MP4 IO, skipping metadata scan when mappings exist."""
-    if frame_mappings is None:
-        decoder = core.create_from_file_like(source, "approximate")
-        core.add_video_stream(decoder)
-        return VideoDecoderLike(decoder)
-
-    mappings = frame_mappings_tensors(frame_mappings)
-    decoder = core.create_from_file_like(source, "custom_frame_mappings")
-    core.add_video_stream(decoder, custom_frame_mappings=mappings)
-    return VideoDecoderLike(decoder)

src/lerobot/datasets/video_utils.py

@@ -273,11 +273,7 @@ class VideoDecoderCache:
                 self._cache.move_to_end(video_path)
                 return entry[0]
 
-            # Bound per-handle buffering: with many decoders kept open at once (one per camera per active
-            # shard, across all workers), the default fsspec read cache balloons RAM on remote backends
-            # like hf:// buckets. A small readahead cache caps each handle's footprint without hurting the
-            # mostly-sequential reads torchcodec issues.
-            file_handle = fsspec.open(video_path, cache_type="readahead", block_size=2**20).__enter__()
+            file_handle = fsspec.open(video_path).__enter__()
             try:
                 decoder = VideoDecoder(file_handle, seek_mode="approximate")
             except Exception:
@@ -326,7 +322,6 @@ def decode_video_frames_torchcodec(
     log_loaded_timestamps: bool = False,
     decoder_cache: VideoDecoderCache | None = None,
     return_uint8: bool = False,
-    episode_decoder: Any | None = None,
 ) -> torch.Tensor:
     """Loads frames associated with the requested timestamps of a video using torchcodec.
 
@@ -348,10 +343,8 @@ def decode_video_frames_torchcodec(
     if decoder_cache is None:
         decoder_cache = _default_decoder_cache
 
-    if episode_decoder is not None:
-        decoder = episode_decoder
-    else:
-        decoder = decoder_cache.get_decoder(str(video_path))
+    # Use cached decoder instead of creating new one each time
+    decoder = decoder_cache.get_decoder(str(video_path))
 
     loaded_ts = []
     loaded_frames = []

src/lerobot/policies/factory.py

@@ -280,26 +280,22 @@ def make_pre_post_processors(
             policy configuration type.
     """
     if pretrained_path:
-        # TODO(Steven): Temporary patch, implement correctly the processors for Gr00t
         if isinstance(policy_cfg, GrootConfig):
-            # GROOT handles normalization in groot_pack_inputs_v3 step
-            # Need to override both stats AND normalize_min_max since saved config might be empty
-            preprocessor_overrides = {}
-            postprocessor_overrides = {}
-            preprocessor_overrides["groot_pack_inputs_v3"] = {
-                "stats": kwargs.get("dataset_stats"),
-                "normalize_min_max": True,
-            }
+            from .groot.processor_groot import make_groot_pre_post_processors_from_pretrained
 
-            # Also ensure postprocessing slices to env action dim and unnormalizes with dataset stats
-            env_action_dim = policy_cfg.output_features[ACTION].shape[0]
-            postprocessor_overrides["groot_action_unpack_unnormalize_v1"] = {
-                "stats": kwargs.get("dataset_stats"),
-                "normalize_min_max": True,
-                "env_action_dim": env_action_dim,
-            }
-            kwargs["preprocessor_overrides"] = preprocessor_overrides
-            kwargs["postprocessor_overrides"] = postprocessor_overrides
+            return make_groot_pre_post_processors_from_pretrained(
+                config=policy_cfg,
+                pretrained_path=pretrained_path,
+                dataset_stats=kwargs.get("dataset_stats"),
+                preprocessor_overrides=kwargs.get("preprocessor_overrides"),
+                postprocessor_overrides=kwargs.get("postprocessor_overrides"),
+                preprocessor_config_filename=kwargs.get(
+                    "preprocessor_config_filename", f"{POLICY_PREPROCESSOR_DEFAULT_NAME}.json"
+                ),
+                postprocessor_config_filename=kwargs.get(
+                    "postprocessor_config_filename", f"{POLICY_POSTPROCESSOR_DEFAULT_NAME}.json"
+                ),
+            )
 
         preprocessor = PolicyProcessorPipeline.from_pretrained(
             pretrained_model_name_or_path=pretrained_path,

src/lerobot/policies/groot/__init__.py

@@ -18,4 +18,12 @@ from .configuration_groot import GrootConfig
 from .modeling_groot import GrootPolicy
 from .processor_groot import make_groot_pre_post_processors
 
-__all__ = ["GrootConfig", "GrootPolicy", "make_groot_pre_post_processors"]
+__all__ = ["GR00TN17", "GR00TN17Config", "GrootConfig", "GrootPolicy", "make_groot_pre_post_processors"]
+
+
+def __getattr__(name: str):
+    if name in {"GR00TN17", "GR00TN17Config"}:
+        from .groot_n1_7 import GR00TN17, GR00TN17Config
+
+        return {"GR00TN17": GR00TN17, "GR00TN17Config": GR00TN17Config}[name]
+    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")

src/lerobot/policies/groot/action_head/action_encoder.py

@@ -1,54 +0,0 @@
-# SPDX-FileCopyrightText: Copyright (c) 2025 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
-# SPDX-License-Identifier: Apache-2.0
-#
-# 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 torch
-import torch.nn as nn
-
-
-def swish(x):
-    return x * torch.sigmoid(x)
-
-
-class SinusoidalPositionalEncoding(nn.Module):
-    """
-    Produces a sinusoidal encoding of shape (B, T, w)
-    given timesteps of shape (B, T).
-    """
-
-    def __init__(self, embedding_dim):
-        super().__init__()
-        self.embedding_dim = embedding_dim
-
-    def forward(self, timesteps):
-        # timesteps: shape (B, T)
-        # We'll compute sin/cos frequencies across dim T
-        timesteps = timesteps.float()  # ensure float
-
-        b, t = timesteps.shape
-        device = timesteps.device
-
-        half_dim = self.embedding_dim // 2
-        # typical log space frequencies for sinusoidal encoding
-        exponent = -torch.arange(half_dim, dtype=torch.float, device=device) * (
-            torch.log(torch.tensor(10000.0)) / half_dim
-        )
-        # Expand timesteps to (B, T, 1) then multiply
-        freqs = timesteps.unsqueeze(-1) * exponent.exp()  # (B, T, half_dim)
-
-        sin = torch.sin(freqs)
-        cos = torch.cos(freqs)
-        enc = torch.cat([sin, cos], dim=-1)  # (B, T, w)
-
-        return enc

src/lerobot/policies/groot/action_head/cross_attention_dit.py

@@ -14,6 +14,7 @@
 # limitations under the License.
 
 
+import logging
 from typing import TYPE_CHECKING
 
 import torch
@@ -42,6 +43,9 @@ else:
     Timesteps = None
 
 
+logger = logging.getLogger(__name__)
+
+
 class TimestepEncoder(nn.Module):
     def __init__(self, embedding_dim, compute_dtype=torch.float32):
         require_package("diffusers", extra="groot")
@@ -181,8 +185,7 @@ class BasicTransformerBlock(nn.Module):
         attn_output = self.attn1(
             norm_hidden_states,
             encoder_hidden_states=encoder_hidden_states,
-            attention_mask=attention_mask,
-            # encoder_attention_mask=encoder_attention_mask,
+            attention_mask=encoder_attention_mask if encoder_hidden_states is not None else attention_mask,
         )
         if self.final_dropout:
             attn_output = self.final_dropout(attn_output)
@@ -266,8 +269,8 @@ class DiT(ModelMixin, ConfigMixin):
         self.norm_out = nn.LayerNorm(self.inner_dim, elementwise_affine=False, eps=1e-6)
         self.proj_out_1 = nn.Linear(self.inner_dim, 2 * self.inner_dim)
         self.proj_out_2 = nn.Linear(self.inner_dim, self.config.output_dim)
-        print(
-            "Total number of DiT parameters: ",
+        logger.debug(
+            "Total number of DiT parameters: %d",
             sum(p.numel() for p in self.parameters() if p.requires_grad),
         )
 
@@ -318,6 +321,71 @@ class DiT(ModelMixin, ConfigMixin):
             return self.proj_out_2(hidden_states)
 
 
+class AlternateVLDiT(DiT):
+    """N1.7 DiT variant that alternates cross-attention over image and text tokens."""
+
+    def __init__(self, *args, attend_text_every_n_blocks: int = 2, **kwargs):
+        super().__init__(*args, **kwargs)
+        self.attend_text_every_n_blocks = attend_text_every_n_blocks
+
+    def forward(
+        self,
+        hidden_states: torch.Tensor,
+        encoder_hidden_states: torch.Tensor,
+        timestep: torch.LongTensor | None = None,
+        encoder_attention_mask: torch.Tensor | None = None,
+        return_all_hidden_states: bool = False,
+        image_mask: torch.Tensor | None = None,
+        backbone_attention_mask: torch.Tensor | None = None,
+    ):
+        if image_mask is None:
+            raise ValueError("image_mask is required for AlternateVLDiT.")
+        if backbone_attention_mask is None:
+            raise ValueError("backbone_attention_mask is required for AlternateVLDiT.")
+
+        temb = self.timestep_encoder(timestep)
+        hidden_states = hidden_states.contiguous()
+        encoder_hidden_states = encoder_hidden_states.contiguous()
+
+        image_attention_mask = image_mask & backbone_attention_mask
+        non_image_attention_mask = (~image_mask) & backbone_attention_mask
+
+        all_hidden_states = [hidden_states]
+        if not self.config.interleave_self_attention:
+            raise ValueError("AlternateVLDiT requires interleave_self_attention=True.")
+
+        for idx, block in enumerate(self.transformer_blocks):
+            if idx % 2 == 1:
+                hidden_states = block(
+                    hidden_states,
+                    attention_mask=None,
+                    encoder_hidden_states=None,
+                    encoder_attention_mask=None,
+                    temb=temb,
+                )
+            else:
+                curr_encoder_attention_mask = (
+                    non_image_attention_mask
+                    if idx % (2 * self.attend_text_every_n_blocks) == 0
+                    else image_attention_mask
+                )
+                hidden_states = block(
+                    hidden_states,
+                    attention_mask=None,
+                    encoder_hidden_states=encoder_hidden_states,
+                    encoder_attention_mask=curr_encoder_attention_mask,
+                    temb=temb,
+                )
+            all_hidden_states.append(hidden_states)
+
+        conditioning = temb
+        shift, scale = self.proj_out_1(F.silu(conditioning)).chunk(2, dim=1)
+        hidden_states = self.norm_out(hidden_states) * (1 + scale[:, None]) + shift[:, None]
+        if return_all_hidden_states:
+            return self.proj_out_2(hidden_states), all_hidden_states
+        return self.proj_out_2(hidden_states)
+
+
 class SelfAttentionTransformer(ModelMixin, ConfigMixin):
     _supports_gradient_checkpointing = True
 
@@ -362,8 +430,8 @@ class SelfAttentionTransformer(ModelMixin, ConfigMixin):
                 for _ in range(self.config.num_layers)
             ]
         )
-        print(
-            "Total number of SelfAttentionTransformer parameters: ",
+        logger.debug(
+            "Total number of SelfAttentionTransformer parameters: %d",
             sum(p.numel() for p in self.parameters() if p.requires_grad),
         )
 

src/lerobot/policies/groot/action_head/flow_matching_action_head.py

@@ -1,408 +0,0 @@
-# SPDX-FileCopyrightText: Copyright (c) 2025 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
-# SPDX-License-Identifier: Apache-2.0
-#
-# 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 dataclasses import field
-from typing import TYPE_CHECKING
-
-import torch
-import torch.nn.functional as F  # noqa: N812
-from torch import nn
-from torch.distributions import Beta
-
-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 PretrainedConfig
-    from transformers.feature_extraction_utils import BatchFeature
-else:
-    PretrainedConfig = object
-    BatchFeature = None
-
-from .action_encoder import (
-    SinusoidalPositionalEncoding,
-    swish,
-)
-from .cross_attention_dit import DiT, SelfAttentionTransformer
-
-
-class CategorySpecificLinear(nn.Module):
-    def __init__(self, num_categories, input_dim, hidden_dim):
-        super().__init__()
-        self.num_categories = num_categories
-        # For each category, we have separate weights and biases.
-        self.W = nn.Parameter(0.02 * torch.randn(num_categories, input_dim, hidden_dim))
-        self.b = nn.Parameter(torch.zeros(num_categories, hidden_dim))
-
-    def forward(self, x, cat_ids):
-        selected_w = self.W[cat_ids]
-        selected_b = self.b[cat_ids]
-        return torch.bmm(x, selected_w) + selected_b.unsqueeze(1)
-
-
-class CategorySpecificMLP(nn.Module):
-    def __init__(self, num_categories, input_dim, hidden_dim, output_dim):
-        super().__init__()
-        self.num_categories = num_categories
-        self.layer1 = CategorySpecificLinear(num_categories, input_dim, hidden_dim)
-        self.layer2 = CategorySpecificLinear(num_categories, hidden_dim, output_dim)
-
-    def forward(self, x, cat_ids):
-        hidden = F.relu(self.layer1(x, cat_ids))
-        return self.layer2(hidden, cat_ids)
-
-
-class MultiEmbodimentActionEncoder(nn.Module):
-    def __init__(self, action_dim, hidden_size, num_embodiments):
-        super().__init__()
-        self.hidden_size = hidden_size
-        self.num_embodiments = num_embodiments
-
-        # W1: R^{w x d}, W2: R^{w x 2w}, W3: R^{w x w}
-        self.W1 = CategorySpecificLinear(num_embodiments, action_dim, hidden_size)  # (d -> w)
-        self.W2 = CategorySpecificLinear(num_embodiments, 2 * hidden_size, hidden_size)  # (2w -> w)
-        self.W3 = CategorySpecificLinear(num_embodiments, hidden_size, hidden_size)  # (w -> w)
-        self.pos_encoding = SinusoidalPositionalEncoding(hidden_size)
-
-    def forward(self, actions, timesteps, cat_ids):
-        """
-        actions:   shape (B, T, action_dim)
-        timesteps: shape (B,)  -- a single scalar per batch item
-        cat_ids:   shape (B,)
-        returns:   shape (B, T, hidden_size)
-        """
-        b, t, _ = actions.shape
-
-        # 1) Expand each batch's single scalar time 'tau' across all T steps
-        #    so that shape => (B, T)
-        #    e.g. if timesteps is (B,), replicate across T
-        if timesteps.dim() == 1 and timesteps.shape[0] == b:
-            # shape (B,) => (B,T)
-            timesteps = timesteps.unsqueeze(1).expand(-1, t)
-        else:
-            raise ValueError("Expected `timesteps` to have shape (B,) so we can replicate across T.")
-
-        # 2) Standard action MLP step for shape => (B, T, w)
-        a_emb = self.W1(actions, cat_ids)
-
-        # 3) Get the sinusoidal encoding (B, T, w)
-        tau_emb = self.pos_encoding(timesteps).to(dtype=a_emb.dtype)
-
-        # 4) Concat along last dim => (B, T, 2w), then W2 => (B, T, w), swish
-        x = torch.cat([a_emb, tau_emb], dim=-1)
-        x = swish(self.W2(x, cat_ids))
-
-        # 5) Finally W3 => (B, T, w)
-        x = self.W3(x, cat_ids)
-        return x
-
-
-class FlowmatchingActionHeadConfig(PretrainedConfig):
-    """NOTE: N1.5 uses XEmbFlowmatchingPolicyHeadConfig as action head"""
-
-    add_pos_embed: bool = field(default=True, metadata={"help": "Whether to add positional embedding"})
-    model_dtype: str = field(default="float32", metadata={"help": "Model data type."})
-    diffusion_model_cfg: dict = field(default=None, metadata={"help": "Diffusion model configuration."})
-    input_embedding_dim: int = field(default=1536, metadata={"help": "Input embedding channel dimension."})
-    backbone_embedding_dim: int = field(
-        default=1536, metadata={"help": "Backbone embedding channel dimension."}
-    )
-
-    hidden_size: int = field(default=1024, metadata={"help": "Input embedding dimension."})
-    max_seq_len: int = field(default=1024, metadata={"help": "Maximum Sequence Length"})
-    action_dim: int = field(default=None, metadata={"help": "Action dimension."})
-    action_horizon: int = field(default=None, metadata={"help": "Action horizon."})
-    noise_beta_alpha: float = field(default=1.5, metadata={"help": ""})
-    noise_beta_beta: float = field(default=1.0, metadata={"help": ""})
-    noise_s: float = field(default=0.999, metadata={"help": "Flow matching noise Beta distribution s."})
-    num_timestep_buckets: int = field(
-        default=1000, metadata={"help": "Number of timestep discretization buckets."}
-    )
-    num_inference_timesteps: int = field(
-        default=None,
-        metadata={"help": "Number of inference steps for noise diffusion."},
-    )
-    max_num_embodiments: int = field(default=32, metadata={"help": "Number of embodiments."})
-    tune_projector: bool = field(default=True, metadata={"help": "Whether to tune the projector."})
-    tune_diffusion_model: bool = field(
-        default=True, metadata={"help": "Whether to tune the diffusion model."}
-    )
-    load_pretrained_det_decode_layer_path: str = field(
-        default=None, metadata={"help": "Path to pretrained detection model."}
-    )
-    detection_coeff: float = field(default=1.0, metadata={"help": "Detection coefficient."})
-
-    freeze_decode_layer: bool = field(default=False)
-    expand_batch: int = field(default=None)
-    use_vlln: bool = field(default=True)
-
-    vl_self_attention_cfg: dict = field(default=None)
-    num_target_vision_tokens: int = field(default=32, metadata={"help": "Number of target vision tokens."})
-
-    def __init__(self, **kwargs):
-        super().__init__(**kwargs)
-        for key, value in kwargs.items():
-            setattr(self, key, value)
-
-
-class FlowmatchingActionHead(nn.Module):
-    config_class = FlowmatchingActionHeadConfig
-    supports_gradient_checkpointing = True
-
-    def __init__(
-        self,
-        config: FlowmatchingActionHeadConfig,
-    ):
-        super().__init__()
-        self.hidden_size = config.hidden_size
-        self.input_embedding_dim = config.input_embedding_dim
-
-        self.model = DiT(**config.diffusion_model_cfg)
-        self.action_dim = config.action_dim
-        self.action_horizon = config.action_horizon
-        self.num_inference_timesteps = config.num_inference_timesteps
-
-        self.state_encoder = CategorySpecificMLP(
-            num_categories=config.max_num_embodiments,
-            input_dim=config.max_state_dim,
-            hidden_dim=self.hidden_size,
-            output_dim=self.input_embedding_dim,
-        )
-        self.action_encoder = MultiEmbodimentActionEncoder(
-            action_dim=config.action_dim,
-            hidden_size=self.input_embedding_dim,
-            num_embodiments=config.max_num_embodiments,
-        )
-        self.action_decoder = CategorySpecificMLP(
-            num_categories=config.max_num_embodiments,
-            input_dim=self.hidden_size,
-            hidden_dim=self.hidden_size,
-            output_dim=self.action_dim,
-        )
-        self.future_tokens = nn.Embedding(config.num_target_vision_tokens, self.input_embedding_dim)
-        nn.init.normal_(self.future_tokens.weight, mean=0.0, std=0.02)
-
-        self.vlln = nn.LayerNorm(config.backbone_embedding_dim) if config.use_vlln else nn.Identity()
-        self.vl_self_attention = (
-            SelfAttentionTransformer(**config.vl_self_attention_cfg) if config.use_vlln else nn.Identity()
-        )
-
-        if config.add_pos_embed:
-            self.position_embedding = nn.Embedding(config.max_seq_len, self.input_embedding_dim)
-            nn.init.normal_(self.position_embedding.weight, mean=0.0, std=0.02)
-
-        self._noise_beta_alpha = config.noise_beta_alpha
-        self._noise_beta_beta = config.noise_beta_beta
-        self._beta_dist = None
-        self.num_timestep_buckets = config.num_timestep_buckets
-        self.config = config
-        self.set_trainable_parameters(config.tune_projector, config.tune_diffusion_model)
-
-    def set_trainable_parameters(self, tune_projector: bool, tune_diffusion_model: bool):
-        self.tune_projector = tune_projector
-        self.tune_diffusion_model = tune_diffusion_model
-        for p in self.parameters():
-            p.requires_grad = True
-        if not tune_projector:
-            self.state_encoder.requires_grad_(False)
-            self.action_encoder.requires_grad_(False)
-            self.action_decoder.requires_grad_(False)
-            if self.config.add_pos_embed:
-                self.position_embedding.requires_grad_(False)
-        if not tune_diffusion_model:
-            self.model.requires_grad_(False)
-        print(f"Tune action head projector: {self.tune_projector}")
-        print(f"Tune action head diffusion model: {self.tune_diffusion_model}")
-        # Check if any parameters are still trainable. If not, print a warning.
-        if not tune_projector and not tune_diffusion_model:
-            for name, p in self.named_parameters():
-                if p.requires_grad:
-                    print(f"Action head trainable parameter: {name}")
-        if not any(p.requires_grad for p in self.parameters()):
-            print("Warning: No action head trainable parameters found.")
-
-    def set_frozen_modules_to_eval_mode(self):
-        """
-        Huggingface will call model.train() at each training_step. To ensure
-        the expected behaviors for modules like dropout, batchnorm, etc., we
-        need to call model.eval() for the frozen modules.
-        """
-        if self.training:
-            if not self.tune_projector:
-                self.state_encoder.eval()
-                self.action_encoder.eval()
-                self.action_decoder.eval()
-                if self.config.add_pos_embed:
-                    self.position_embedding.eval()
-            if not self.tune_diffusion_model:
-                self.model.eval()
-
-    def sample_time(self, batch_size, device, dtype):
-        if self._beta_dist is None:
-            self._beta_dist = Beta(self._noise_beta_alpha, self._noise_beta_beta, validate_args=False)
-        sample = self._beta_dist.sample([batch_size]).to(device, dtype=dtype)
-        return (self.config.noise_s - sample) / self.config.noise_s
-
-    def prepare_input(self, batch: dict) -> BatchFeature:
-        return BatchFeature(data=batch)
-
-    def process_backbone_output(self, backbone_output: BatchFeature) -> BatchFeature:
-        backbone_features = backbone_output["backbone_features"]
-        backbone_features = self.vlln(backbone_features)
-        backbone_features = self.vl_self_attention(backbone_features)
-        backbone_output["backbone_features"] = backbone_features
-        return backbone_output
-
-    def forward(self, backbone_output: BatchFeature, action_input: BatchFeature) -> BatchFeature:
-        # Set frozen modules to eval
-        self.set_frozen_modules_to_eval_mode()
-
-        backbone_output = self.process_backbone_output(backbone_output)
-
-        if self.config.expand_batch is not None:
-            for k, v in backbone_output.items():
-                ndim = len(v.shape)
-                factors = [self.config.expand_batch]
-                while len(factors) < ndim:
-                    factors.append(1)
-                factors = tuple(factors)
-                expanded = v.repeat(*factors)
-                backbone_output[k] = expanded
-
-            for k, v in action_input.items():
-                ndim = len(v.shape)
-                factors = [self.config.expand_batch]
-                while len(factors) < ndim:
-                    factors.append(1)
-                factors = tuple(factors)
-                expanded = v.repeat(*factors)
-                action_input[k] = expanded
-
-        # Get vision and language embeddings.
-        vl_embs = backbone_output.backbone_features
-        device = vl_embs.device
-
-        # Get embodiment ID.
-        embodiment_id = action_input.embodiment_id
-
-        # Embed state.
-        state_features = self.state_encoder(action_input.state, embodiment_id)
-
-        # Embed noised action trajectory.
-        actions = action_input.action
-        noise = torch.randn(actions.shape, device=actions.device, dtype=actions.dtype)
-        t = self.sample_time(actions.shape[0], device=actions.device, dtype=actions.dtype)
-        t = t[:, None, None]  # shape (B,1,1) for broadcast
-
-        noisy_trajectory = (1 - t) * noise + t * actions
-        velocity = actions - noise
-
-        # Convert (continuous) t -> discrete if needed
-        t_discretized = (t[:, 0, 0] * self.num_timestep_buckets).long()
-        action_features = self.action_encoder(noisy_trajectory, t_discretized, embodiment_id)
-
-        # Maybe add position embedding.
-        if self.config.add_pos_embed:
-            pos_ids = torch.arange(action_features.shape[1], dtype=torch.long, device=device)
-            pos_embs = self.position_embedding(pos_ids).unsqueeze(0)
-            action_features = action_features + pos_embs
-
-        # Join vision, language, state and action embedding along sequence dimension.
-        future_tokens = self.future_tokens.weight.unsqueeze(0).expand(vl_embs.shape[0], -1, -1)
-        sa_embs = torch.cat((state_features, future_tokens, action_features), dim=1)
-
-        vl_attn_mask = backbone_output.backbone_attention_mask
-
-        model_output = self.model(
-            hidden_states=sa_embs,
-            encoder_hidden_states=vl_embs,
-            encoder_attention_mask=vl_attn_mask,
-            timestep=t_discretized,
-            return_all_hidden_states=False,  # NOTE (YL): not using flare now
-        )
-        pred = self.action_decoder(model_output, embodiment_id)
-        pred_actions = pred[:, -actions.shape[1] :]
-
-        # Slice out only the action portion of pred and target.
-        action_mask = action_input.action_mask
-        loss = F.mse_loss(pred_actions, velocity, reduction="none") * action_mask
-        loss = loss.sum() / action_mask.sum()
-        output_dict = {
-            "loss": loss,
-        }
-        return BatchFeature(data=output_dict)
-
-    @torch.no_grad()
-    def get_action(self, backbone_output: BatchFeature, action_input: BatchFeature) -> BatchFeature:
-        backbone_output = self.process_backbone_output(backbone_output)
-
-        # Get vision and language embeddings.
-        vl_embs = backbone_output.backbone_features
-        embodiment_id = action_input.embodiment_id
-
-        # Embed state.
-        state_features = self.state_encoder(action_input.state, embodiment_id)
-
-        # Set initial actions as the sampled noise.
-        batch_size = vl_embs.shape[0]
-        device = vl_embs.device
-        actions = torch.randn(
-            size=(batch_size, self.config.action_horizon, self.config.action_dim),
-            dtype=vl_embs.dtype,
-            device=device,
-        )
-
-        num_steps = self.num_inference_timesteps
-        dt = 1.0 / num_steps
-
-        # Run denoising steps.
-        for t in range(num_steps):
-            t_cont = t / float(num_steps)  # e.g. goes 0, 1/N, 2/N, ...
-            t_discretized = int(t_cont * self.num_timestep_buckets)
-
-            # Embed noised action trajectory.
-            timesteps_tensor = torch.full(size=(batch_size,), fill_value=t_discretized, device=device)
-            action_features = self.action_encoder(actions, timesteps_tensor, embodiment_id)
-            # Maybe add position embedding.
-            if self.config.add_pos_embed:
-                pos_ids = torch.arange(action_features.shape[1], dtype=torch.long, device=device)
-                pos_embs = self.position_embedding(pos_ids).unsqueeze(0)
-                action_features = action_features + pos_embs
-
-            # Join vision, language, state and action embedding along sequence dimension.
-            future_tokens = self.future_tokens.weight.unsqueeze(0).expand(vl_embs.shape[0], -1, -1)
-            sa_embs = torch.cat((state_features, future_tokens, action_features), dim=1)
-
-            # Run model forward.
-            model_output = self.model(
-                hidden_states=sa_embs,
-                encoder_hidden_states=vl_embs,
-                timestep=timesteps_tensor,
-            )
-            pred = self.action_decoder(model_output, embodiment_id)
-
-            pred_velocity = pred[:, -self.action_horizon :]
-
-            # Update actions using euler integration.
-            actions = actions + dt * pred_velocity
-        return BatchFeature(data={"action_pred": actions})
-
-    @property
-    def device(self):
-        return next(iter(self.parameters())).device
-
-    @property
-    def dtype(self):
-        return next(iter(self.parameters())).dtype

src/lerobot/policies/groot/configuration_groot.py

@@ -14,12 +14,228 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
+import logging
 from dataclasses import dataclass, field
+from pathlib import Path
 
 from lerobot.configs import FeatureType, NormalizationMode, PolicyFeature, PreTrainedConfig
 from lerobot.optim import AdamWConfig, CosineDecayWithWarmupSchedulerConfig
 from lerobot.utils.constants import ACTION, OBS_STATE
 
+from .utils import read_json
+
+logger = logging.getLogger(__name__)
+
+GROOT_N1_7 = "n1.7"
+# Legacy GR00T N1.5 identifier. N1.5 is NOT a supported model_version (it is
+# intentionally absent from _GROOT_MODEL_VERSION_ALIASES so normalize_groot_model_version
+# still rejects it). It is retained only so that infer_groot_model_version can recognise
+# an N1.5 base path/checkpoint and the N1.7 config/loader can reject the mismatch.
+GROOT_N1_5 = "n1.5"
+# Canonical guidance appended to every error raised when an N1.5 checkpoint, config,
+# or processor pipeline is detected. Keep this message in sync with docs/source/groot.mdx.
+GROOT_N1_5_REMOVAL_GUIDANCE = (
+    "GR00T N1.5 support was removed from LeRobot. "
+    "To keep using an N1.5 checkpoint, pin the last release that supports it: "
+    "`pip install 'lerobot==0.5.1'`. To use the current release, migrate to GR00T N1.7 "
+    "(model_version='n1.7', base model nvidia/GR00T-N1.7-3B)."
+)
+GROOT_N1_7_BASE_MODEL = "nvidia/GR00T-N1.7-3B"
+GROOT_N1_7_BACKBONE_MODEL = "nvidia/Cosmos-Reason2-2B"
+# Default GR00T N1.7 training resolution. Fallback if processor_config lacks sizing. Prevents mismatched
+# full-res patchification by forcing a resize. Mirrored by GR00T_N1_7_DEFAULTS in groot_n1_7.py.
+N1_7_DEFAULT_IMAGE_TARGET_SIZE = (256, 256)
+N1_7_DEFAULT_IMAGE_CROP_SIZE = (230, 230)
+GROOT_ACTION_DECODE_TRANSFORM_LIBERO = "libero"
+# Sentinel meaning "the user did not pick an action decode transform": __post_init__ resolves it
+# to the embodiment default ('libero' for 'libero_sim', otherwise None). It is distinct from an
+# explicit 'none' (resolved to None) so an opt-out survives a draccus save/load round-trip.
+GROOT_ACTION_DECODE_TRANSFORM_AUTO = "auto"
+
+_GROOT_MODEL_VERSION_ALIASES = {
+    "n1.7": GROOT_N1_7,
+    "n1_7": GROOT_N1_7,
+    "n1d7": GROOT_N1_7,
+    "n17": GROOT_N1_7,
+    "1.7": GROOT_N1_7,
+}
+
+# Legacy N1.5 spellings, kept ONLY so they can be detected and rejected with
+# GROOT_N1_5_REMOVAL_GUIDANCE (see GROOT_N1_5 above). Never map these to a supported version.
+_GROOT_N1_5_VERSION_ALIASES = {"n1.5", "n1_5", "n1d5", "n15", "1.5"}
+
+_GROOT_ACTION_DECODE_TRANSFORM_ALIASES = {
+    GROOT_ACTION_DECODE_TRANSFORM_AUTO: GROOT_ACTION_DECODE_TRANSFORM_AUTO,
+    "none": None,
+    "": None,
+    GROOT_ACTION_DECODE_TRANSFORM_LIBERO: GROOT_ACTION_DECODE_TRANSFORM_LIBERO,
+}
+
+
+def normalize_groot_model_version(model_version: str) -> str:
+    normalized = _GROOT_MODEL_VERSION_ALIASES.get(model_version.lower())
+    if normalized is None:
+        supported = GROOT_N1_7
+        message = f"Unsupported GR00T model_version '{model_version}'. Supported versions: {supported}."
+        if model_version.lower() in _GROOT_N1_5_VERSION_ALIASES:
+            message = f"{message} {GROOT_N1_5_REMOVAL_GUIDANCE}"
+        raise ValueError(message)
+    return normalized
+
+
+def normalize_groot_action_decode_transform(transform: str | None) -> str | None:
+    if transform is None:
+        return None
+    normalized = _GROOT_ACTION_DECODE_TRANSFORM_ALIASES.get(transform.lower())
+    if normalized is None and transform.lower() not in _GROOT_ACTION_DECODE_TRANSFORM_ALIASES:
+        supported = ", ".join(
+            sorted(key for key, value in _GROOT_ACTION_DECODE_TRANSFORM_ALIASES.items() if value is not None)
+        )
+        raise ValueError(
+            f"Unsupported GR00T N1.7 action decode transform '{transform}'. "
+            f"Supported transforms: none, {supported}."
+        )
+    return normalized
+
+
+def infer_groot_model_version(model_path: str | None) -> str | None:
+    if not model_path:
+        return None
+    model_path_lower = model_path.lower()
+    if "gr00t-n1.7" in model_path_lower or "gr00t_n1.7" in model_path_lower:
+        return GROOT_N1_7
+    # Detect legacy N1.5 paths so the N1.7 config/loader can reject the mismatch.
+    # N1.5 is unsupported, but it must still be recognised here to fail loudly
+    # rather than silently treating an N1.5 checkpoint as N1.7.
+    if "gr00t-n1.5" in model_path_lower or "gr00t_n1.5" in model_path_lower:
+        return GROOT_N1_5
+    config_version = _infer_groot_model_version_from_local_config(model_path)
+    if config_version is not None:
+        return config_version
+    return None
+
+
+def is_raw_groot_n1_7_checkpoint(model_path: str | Path | None) -> bool:
+    if model_path is None:
+        return False
+
+    path = Path(model_path).expanduser()
+    if path.is_dir():
+        config_path = path / "config.json"
+    elif path.name == "config.json":
+        config_path = path
+    else:
+        return False
+
+    config = read_json(config_path)
+    return "type" not in config and _infer_groot_model_version_from_config(config) == GROOT_N1_7
+
+
+def infer_groot_n1_7_embodiment_tag(model_path: str | Path | None) -> str | None:
+    if model_path is None:
+        return None
+
+    processor_config_path = Path(model_path).expanduser() / "processor_config.json"
+    processor_config = read_json(processor_config_path)
+
+    modality_configs = processor_config.get("processor_kwargs", {}).get("modality_configs", {})
+    if not isinstance(modality_configs, dict):
+        return None
+    if "libero_sim" in modality_configs:
+        return "libero_sim"
+    if len(modality_configs) == 1:
+        return next(iter(modality_configs))
+    return None
+
+
+def infer_groot_n1_7_action_horizon(
+    model_path: str | Path | None, embodiment_tag: str | None = None
+) -> int | None:
+    if model_path is None:
+        return None
+
+    processor_config_path = Path(model_path).expanduser() / "processor_config.json"
+    processor_config = read_json(processor_config_path)
+
+    processor_kwargs = processor_config.get("processor_kwargs", {})
+    if not isinstance(processor_kwargs, dict):
+        return None
+    modality_configs = processor_kwargs.get("modality_configs", {})
+    if not isinstance(modality_configs, dict):
+        return None
+
+    if embodiment_tag is None:
+        embodiment_tag = infer_groot_n1_7_embodiment_tag(model_path)
+    if embodiment_tag is None:
+        return None
+
+    embodiment_config = modality_configs.get(embodiment_tag, {})
+    if not isinstance(embodiment_config, dict):
+        return None
+    action_config = embodiment_config.get("action", {})
+    if not isinstance(action_config, dict):
+        return None
+    delta_indices = action_config.get("delta_indices", [])
+    if not isinstance(delta_indices, list):
+        return None
+    return len(delta_indices) or None
+
+
+def infer_groot_n1_7_action_execution_horizon(
+    model_path: str | Path | None, embodiment_tag: str | None = None
+) -> int | None:
+    action_horizon = infer_groot_n1_7_action_horizon(model_path, embodiment_tag)
+    if action_horizon is None:
+        return None
+
+    if embodiment_tag is None:
+        embodiment_tag = infer_groot_n1_7_embodiment_tag(model_path)
+    if embodiment_tag == "libero_sim":
+        # NVIDIA's N1.7 LIBERO rollout wrapper replans after 8 of the 16 decoded
+        # actions. Keeping that execution cadence avoids stale open-loop chunks.
+        return min(action_horizon, 8)
+    return action_horizon
+
+
+def _infer_groot_model_version_from_local_config(model_path: str) -> str | None:
+    path = Path(model_path).expanduser()
+    if path.is_dir():
+        config_path = path / "config.json"
+    elif path.name == "config.json":
+        config_path = path
+    else:
+        return None
+
+    return _infer_groot_model_version_from_config(read_json(config_path))
+
+
+def _infer_groot_model_version_from_config(config: dict) -> str | None:
+    model_version = config.get("model_version")
+    if isinstance(model_version, str):
+        if model_version.lower() in _GROOT_N1_5_VERSION_ALIASES:
+            return GROOT_N1_5
+        try:
+            return normalize_groot_model_version(model_version)
+        except ValueError:
+            return None
+
+    candidates = [config.get("model_type"), *(config.get("architectures") or [])]
+    for candidate in candidates:
+        if not isinstance(candidate, str):
+            continue
+        normalized = candidate.lower().replace("-", "_")
+        if normalized in {"gr00tn1d7", "gr00t_n1d7", "gr00t_n1_7"}:
+            return GROOT_N1_7
+        if normalized in {"gr00t_n1_5", "gr00tn1_5", "gr00t_n15", "gr00t_n1d5", "gr00tn1d5"}:
+            return GROOT_N1_5
+    if config.get("model_name") == GROOT_N1_7_BACKBONE_MODEL:
+        return GROOT_N1_7
+    # The Eagle VLM backbone is specific to pre-N1.7 GR00T checkpoints (N1.7 uses Cosmos/Qwen3-VL).
+    backbone_cfg = config.get("backbone_cfg")
+    if isinstance(backbone_cfg, dict) and "eagle_path" in backbone_cfg:
+        return GROOT_N1_5
+    return None
+
 
 @PreTrainedConfig.register_subclass("groot")
 @dataclass
@@ -28,35 +244,44 @@ class GrootConfig(PreTrainedConfig):
 
     # Basic policy settings
     n_obs_steps: int = 1
-    chunk_size: int = 50
-    n_action_steps: int = 50
+    chunk_size: int = 40
+    n_action_steps: int = 40
 
     # Dimension settings (must match pretrained GR00T model expectations)
     # Maximum state dimension. Shorter states will be zero-padded.
-    max_state_dim: int = 64
+    max_state_dim: int = 132
 
     # Maximum action dimension. Shorter actions will be zero-padded.
-    max_action_dim: int = 32
+    max_action_dim: int = 132
 
-    # Normalization (start with identity, adjust as needed)
+    # GR00T normalizes state/action internally in its processor steps (min/max with
+    # q01/q99 percentiles, per embodiment), and the Qwen3-VL backbone's image processor
+    # handles image normalization. The policy therefore does NOT use LeRobot's
+    # NormalizerProcessorStep/UnnormalizerProcessorStep, so this mapping is intentionally
+    # IDENTITY for every feature and is not consulted by make_groot_pre_post_processors.
     normalization_mapping: dict[str, NormalizationMode] = field(
         default_factory=lambda: {
             "VISUAL": NormalizationMode.IDENTITY,
-            "STATE": NormalizationMode.MEAN_STD,
-            "ACTION": NormalizationMode.MEAN_STD,
+            "STATE": NormalizationMode.IDENTITY,
+            "ACTION": NormalizationMode.IDENTITY,
         }
     )
 
-    # Image preprocessing (adjust to match Groot's expected input)
-    image_size: tuple[int, int] = (224, 224)
+    # Groot-specific model parameters
 
-    # Groot-specific model parameters (from groot_finetune_script.py)
+    # Path or HuggingFace model ID for the base GR00T N1.7 model whose backbone weights and
+    # checkpoint sidecars (statistics.json, processor_config.json, ...) are loaded. This is the
+    # model *source*, and is intentionally distinct from the inherited `pretrained_path`:
+    # `pretrained_path` (`--policy.path`) points at a saved LeRobot checkpoint directory whose
+    # `config.json` carries a `type` field, whereas a raw NVIDIA GR00T checkpoint has no such
+    # field and so can only be loaded through `base_model_path` (`--policy.base_model_path`).
+    # Defaults to GROOT_N1_7_BASE_MODEL when unset (resolved in __post_init__).
+    base_model_path: str | None = None
 
-    # Path or HuggingFace model ID for the base Groot model
-    base_model_path: str = "nvidia/GR00T-N1.5-3B"
-
-    # HF repo ID (or local path) that hosts vocab.json and merges.txt for Eagle tokenizer.
-    tokenizer_assets_repo: str = "lerobot/eagle2hg-processor-groot-n1p5"
+    # Optional named action transform applied after raw N1.7 checkpoint decoding and before env.step().
+    # 'auto' (default) resolves to the embodiment default ('libero' for 'libero_sim', otherwise no
+    # transform). Pass 'none' to explicitly disable the transform, including for 'libero_sim'.
+    action_decode_transform: str | None = GROOT_ACTION_DECODE_TRANSFORM_AUTO
 
     # Embodiment tag to use for training (e.g. 'new_embodiment', 'gr1')
     embodiment_tag: str = "new_embodiment"
@@ -75,20 +300,31 @@ class GrootConfig(PreTrainedConfig):
     # Whether to fine-tune the diffusion model
     tune_diffusion_model: bool = True
 
-    # LoRA parameters (from groot_finetune_script.py)
-    # Rank for the LORA model. If 0, no LORA will be used.
-    lora_rank: int = 0
+    # Whether to fine-tune the VL LayerNorm + VL self-attention projector in the action head.
+    tune_vlln: bool = True
 
-    # Alpha value for the LORA model
-    lora_alpha: int = 16
+    # Number of top LLM backbone layers to fine-tune (0 = none). Lets you adapt just the final
+    # language layers without unfreezing the whole backbone; independent of `tune_llm`, which tunes
+    # the entire LLM.
+    tune_top_llm_layers: int = 0
 
-    # Dropout rate for the LORA model
-    lora_dropout: float = 0.1
+    # Inference-time knob: Number of flow-matching denoising steps used to decode an action chunk.
+    # Trades inference latency for action quality.
+    # None keeps the checkpoint value (GR00T N1.7 default: 4).
+    num_inference_timesteps: int | None = None
 
-    # Whether to use the full model for LORA
-    lora_full_model: bool = False
+    # Inference-time knob: Real-Time Chunking (RTC) overlap-blend ramp rate, used when the RTC engine
+    # supplies a previous-chunk prefix. Higher values blend the overlapping prefix more aggressively.
+    # None keeps the checkpoint value (GR00T N1.7 default: 6.0).
+    rtc_ramp_rate: float | None = None
 
-    # Training parameters (matching groot_finetune_script.py)
+    # Inference-time knob: Whether to request the flash-attention-2 kernel for the Qwen3-VL backbone.
+    # flash-attn is an optional, user-managed optimization; when it is absent (the default),
+    # the backbone transparently falls back to SDPA, which is numerically equivalent.
+    # Set to True only after installing a flash-attn build matching your torch/CUDA env.
+    use_flash_attention: bool = False
+
+    # Training parameters
     optimizer_lr: float = 1e-4
     optimizer_betas: tuple[float, float] = (0.95, 0.999)
     optimizer_eps: float = 1e-8
@@ -96,17 +332,22 @@ class GrootConfig(PreTrainedConfig):
     warmup_ratio: float = 0.05
     use_bf16: bool = True
 
-    # Dataset parameters
-    # Video backend to use for training ('decord' or 'torchvision_av')
+    # TODO(Steven): Remove these deprecated fields in a future release.
+    # Deprecated Isaac-GR00T runner / GR00T N1.5 fields, plus the (never-wired) LoRA fields — all
+    # unused by the LeRobot N1.7 implementation except the `tokenizer_assets_repo` N1.5 tripwire and
+    # the `image_size` legacy remap in __post_init__. They are kept ONLY so a config.json saved by an
+    # earlier lerobot release (notably a GR00T N1.5 checkpoint) still parses under draccus — which
+    # rejects unknown fields — and is then rejected with a clear N1.5 removal message rather than an
+    # opaque draccus decoding error.
+    image_size: tuple[int, int] = (256, 256)  # image sizing is handled by the backbone's image processor.
+    tokenizer_assets_repo: str | None = None
+    lora_rank: int = 0
+    lora_alpha: int = 16
+    lora_dropout: float = 0.1
+    lora_full_model: bool = False
     video_backend: str = "decord"
-
-    # Whether to balance dataset weights in mixture datasets
     balance_dataset_weights: bool = True
-
-    # Whether to sample trajectories weighted by their length
     balance_trajectory_weights: bool = True
-
-    # Optional dataset paths for delegating training to Isaac-GR00T runner
     dataset_paths: list[str] | None = None
     output_dir: str = "./tmp/gr00t"
     save_steps: int = 1000
@@ -117,6 +358,65 @@ class GrootConfig(PreTrainedConfig):
     resume: bool = False
 
     def __post_init__(self):
+        if self.tokenizer_assets_repo is not None:
+            raise ValueError(
+                "Config sets 'tokenizer_assets_repo', which only existed for GR00T N1.5; this looks "
+                f"like a legacy GR00T N1.5 checkpoint or config. {GROOT_N1_5_REMOVAL_GUIDANCE}"
+            )
+
+        self.action_decode_transform = normalize_groot_action_decode_transform(self.action_decode_transform)
+        if self.base_model_path is None:
+            self.base_model_path = GROOT_N1_7_BASE_MODEL
+
+        # The N1.7 LIBERO checkpoints emit a [0, 1] gripper action, but the LIBERO
+        # simulator expects the OpenVLA/[-1, 1] sign convention. NVIDIA's rollout
+        # wrapper applies this conversion; mirror it here so eval on the
+        # 'libero_sim' embodiment grasps correctly instead of scoring 0% success.
+        # This matches the embodiment-specific handling already done for the
+        # action execution horizon (see infer_groot_n1_7_action_execution_horizon).
+        # Only the 'auto' sentinel resolves to the embodiment default; an explicit
+        # 'none' (normalized to None above) keeps the transform disabled.
+        if self.action_decode_transform == GROOT_ACTION_DECODE_TRANSFORM_AUTO:
+            self.action_decode_transform = (
+                GROOT_ACTION_DECODE_TRANSFORM_LIBERO if self.embodiment_tag == "libero_sim" else None
+            )
+
+        # GR00T N1.5-era default values (e.g. --policy.chunk_size=50 from old commands or
+        # stale configs) are migrated to the values the N1.7 checkpoints expect, with a
+        # warning. The dataclass defaults are already the N1.7 values, so a plain
+        # GrootConfig() never triggers this.
+        legacy_default_remaps = (
+            ("max_state_dim", 64, 132),
+            ("max_action_dim", 32, 132),
+            ("chunk_size", 50, 40),
+            ("n_action_steps", 50, 40),
+            ("image_size", (224, 224), (256, 256)),
+        )
+        for field_name, legacy_value, n1_7_value in legacy_default_remaps:
+            current_value = getattr(self, field_name)
+            if isinstance(legacy_value, tuple):
+                current_value = tuple(current_value)
+            if current_value == legacy_value:
+                logger.warning(
+                    "GrootConfig.%s=%s matches a legacy GR00T N1.5-era default; remapping it to %s, "
+                    "the value expected by GR00T N1.7 checkpoints. Set a different value explicitly "
+                    "if this is not what you want.",
+                    field_name,
+                    legacy_value,
+                    n1_7_value,
+                )
+                setattr(self, field_name, n1_7_value)
+
+        inferred_version = infer_groot_model_version(self.base_model_path)
+        if inferred_version is not None and inferred_version != GROOT_N1_7:
+            message = (
+                f"GR00T model_version '{GROOT_N1_7}' does not match base_model_path "
+                f"'{self.base_model_path}', which looks like '{inferred_version}'."
+            )
+            if inferred_version == GROOT_N1_5:
+                message = f"{message} {GROOT_N1_5_REMOVAL_GUIDANCE}"
+            raise ValueError(message)
+
         super().__post_init__()
 
         if self.n_action_steps > self.chunk_size:
@@ -124,9 +424,6 @@ class GrootConfig(PreTrainedConfig):
                 f"n_action_steps ({self.n_action_steps}) cannot exceed chunk_size ({self.chunk_size})"
             )
 
-        # groot_repo_path is now optional since we ported the components
-        # No validation needed
-
     def validate_features(self) -> None:
         """Validate and set up input/output features for Groot."""
         image_features = [key for key, feat in self.input_features.items() if feat.type == FeatureType.VISUAL]
@@ -192,7 +489,10 @@ class GrootConfig(PreTrainedConfig):
     @property
     def action_delta_indices(self) -> list[int]:
         """Return indices for delta actions."""
-        return list(range(min(self.chunk_size, 16)))
+        model_action_horizon = (
+            infer_groot_n1_7_action_horizon(self.base_model_path, self.embodiment_tag) or 40
+        )
+        return list(range(min(self.chunk_size, model_action_horizon)))
 
     @property
     def reward_delta_indices(self) -> None:

src/lerobot/policies/groot/eagle2_hg_model/configuration_eagle2_5_vl.py

@@ -1,135 +0,0 @@
-# SPDX-FileCopyrightText: Copyright (c) 2025 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
-# SPDX-License-Identifier: Apache-2.0
-#
-# 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 copy
-
-from transformers.configuration_utils import PretrainedConfig
-from transformers.models.llama.configuration_llama import LlamaConfig
-from transformers.models.qwen2.configuration_qwen2 import Qwen2Config
-from transformers.models.qwen3.configuration_qwen3 import Qwen3Config
-from transformers.models.siglip.configuration_siglip import SiglipVisionConfig
-from transformers.utils import logging
-
-logger = logging.get_logger(__name__)
-
-
-class Eagle25VLConfig(PretrainedConfig):
-    model_type = "eagle_2_5_vl"
-    is_composition = True
-    sub_configs = {"vision_config": SiglipVisionConfig, "text_config": Qwen2Config}
-
-    def __init__(
-        self,
-        vision_config=None,
-        text_config=None,
-        use_backbone_lora=0,
-        use_llm_lora=0,
-        pad2square=False,
-        select_layer=-4,
-        force_image_size=None,
-        downsample_ratio=0.5,
-        template=None,
-        dynamic_image_size=False,
-        use_thumbnail=False,
-        loss_version="v1",
-        min_dynamic_tiles=1,
-        max_dynamic_tiles=6,
-        mlp_checkpoint=False,
-        initializer_range=0.02,
-        _attn_implementation="flash_attention_2",
-        _attn_implementation_autoset=False,
-        llm_config=None,
-        image_token_index=None,
-        use_pixel_shuffle=True,
-        mlp_connector_layers=2,
-        **kwargs,
-    ):
-        super().__init__(**kwargs)
-
-        if vision_config is None:
-            vision_config = {"model_type": "siglip_vision_model"}
-            logger.info("vision_config is None. Initializing the InternVisionConfig with default values.")
-
-        if text_config is None:
-            text_config = {"architectures": ["Qwen2ForCausalLM"]}
-            logger.info(
-                "text_config is None. Initializing the LlamaConfig config with default values (`LlamaConfig`)."
-            )
-
-        if vision_config["model_type"] == "siglip_vision_model":
-            self.vision_config = SiglipVisionConfig(**vision_config)
-        else:
-            raise ValueError("Unsupported model_type: {}".format(vision_config["model_type"]))
-
-        if text_config["architectures"][0] == "LlamaForCausalLM":
-            self.text_config = LlamaConfig(**text_config)
-        elif text_config["architectures"][0] == "Qwen2ForCausalLM":
-            self.text_config = Qwen2Config(**text_config)
-        elif text_config["architectures"][0] == "Qwen3ForCausalLM":
-            self.text_config = Qwen3Config(**text_config)
-        else:
-            raise ValueError("Unsupported architecture: {}".format(text_config["architectures"][0]))
-        self.use_backbone_lora = use_backbone_lora
-        self.use_llm_lora = use_llm_lora
-        self.mlp_checkpoint = mlp_checkpoint
-        self.pad2square = pad2square
-        self.select_layer = select_layer
-        self.force_image_size = force_image_size
-        self.downsample_ratio = downsample_ratio
-        self.template = template
-        self.dynamic_image_size = dynamic_image_size
-        self.use_thumbnail = use_thumbnail
-        self.loss_version = loss_version
-        self.initializer_range = initializer_range
-        self.min_dynamic_tiles = min_dynamic_tiles
-        self.max_dynamic_tiles = max_dynamic_tiles
-        self.tie_word_embeddings = self.text_config.tie_word_embeddings
-        self._attn_implementation = _attn_implementation
-        self._attn_implementation_autoset = _attn_implementation_autoset
-        self.image_token_index = image_token_index
-        self.use_pixel_shuffle = use_pixel_shuffle
-        self.mlp_connector_layers = mlp_connector_layers
-        logger.info(f"min_dynamic_tiles: {self.min_dynamic_tiles}")
-        logger.info(f"max_dynamic_tiles: {self.max_dynamic_tiles}")
-
-    def to_dict(self):
-        """
-        Serializes this instance to a Python dictionary. Override the default [`~PretrainedConfig.to_dict`].
-
-        Returns:
-            `Dict[str, any]`: Dictionary of all the attributes that make up this configuration instance,
-        """
-        output = copy.deepcopy(self.__dict__)
-        output["vision_config"] = self.vision_config.to_dict()
-        output["text_config"] = self.text_config.to_dict()
-        output["model_type"] = self.__class__.model_type
-        output["use_backbone_lora"] = self.use_backbone_lora
-        output["use_llm_lora"] = self.use_llm_lora
-        output["pad2square"] = self.pad2square
-        output["select_layer"] = self.select_layer
-        output["force_image_size"] = self.force_image_size
-        output["downsample_ratio"] = self.downsample_ratio
-        output["template"] = self.template
-        output["dynamic_image_size"] = self.dynamic_image_size
-        output["use_thumbnail"] = self.use_thumbnail
-        output["min_dynamic_tiles"] = self.min_dynamic_tiles
-        output["max_dynamic_tiles"] = self.max_dynamic_tiles
-        output["tie_word_embeddings"] = self.tie_word_embeddings
-        output["_attn_implementation"] = self._attn_implementation
-        output["_attn_implementation_autoset"] = self._attn_implementation_autoset
-        output["use_pixel_shuffle"] = self.use_pixel_shuffle
-        output["mlp_connector_layers"] = self.mlp_connector_layers
-        return output

src/lerobot/policies/groot/eagle2_hg_model/image_processing_eagle2_5_vl_fast.py

@@ -1,503 +0,0 @@
-# --------------------------------------------------------
-# NVIDIA
-# Copyright (c) 2025 NVIDIA
-# Licensed under The MIT License [see LICENSE for details]
-# --------------------------------------------------------
-
-from __future__ import annotations
-
-# copy from https://github.com/huggingface/transformers/blob/main/src/transformers/models/llava_onevision/image_processing_llava_onevision_fast.py
-from transformers.image_processing_utils import (
-    BatchFeature,
-    get_patch_output_size,
-)
-from transformers.image_processing_utils_fast import (
-    BaseImageProcessorFast,
-    ImagesKwargs,
-    group_images_by_shape,
-    reorder_images,
-)
-from transformers.image_utils import (
-    IMAGENET_STANDARD_MEAN,  # 0.5, 0.5, 0.5
-    IMAGENET_STANDARD_STD,  # 0.5, 0.5, 0.5
-    ChannelDimension,
-    ImageInput,
-    PILImageResampling,
-    SizeDict,
-    get_image_size,
-    make_flat_list_of_images,
-    validate_kwargs,
-)
-from transformers.processing_utils import Unpack
-from transformers.utils import (
-    TensorType,
-    add_start_docstrings,
-    is_torch_available,
-    is_torchvision_v2_available,
-)
-from transformers.video_utils import VideoInput
-
-if is_torch_available():
-    import torch
-if is_torchvision_v2_available():
-    from torchvision.transforms.v2 import functional as F  # noqa: N812
-    from transformers.image_utils import pil_torch_interpolation_mapping
-else:
-    from torchvision.transforms import functional as F  # noqa: N812
-
-
-def crop(img: torch.Tensor, left: int, top: int, right: int, bottom: int) -> torch.Tensor:
-    """Crop the given numpy array.
-
-    Args:
-        img (torch.Tensor): Image to be cropped. Format should be (C, H, W).
-        left (int): The left coordinate of the crop box.
-        top (int): The top coordinate of the crop box.
-        right (int): The right coordinate of the crop box.
-        bottom (int): The bottom coordinate of the crop box.
-
-    Returns:
-        torch.Tensor: Cropped image.
-    """
-    if not isinstance(img, torch.Tensor):
-        raise TypeError(f"img should be torch.Tensor. Got {type(img)}")
-
-    if img.ndim not in [2, 3]:
-        raise ValueError(f"Image should have 2 or 3 dimensions. Got {img.ndim}")
-
-    img_height = img.shape[1]
-    img_width = img.shape[2]
-    if top < 0 or left < 0 or bottom > img_height or right > img_width:
-        raise ValueError("Crop coordinates out of bounds")
-
-    if top >= bottom or left >= right:
-        raise ValueError("Invalid crop coordinates")
-
-    return img[:, top:bottom, left:right]
-
-
-class Eagle25VLFastImageProcessorKwargs(ImagesKwargs):
-    max_dynamic_tiles: int | None
-    min_dynamic_tiles: int | None
-    use_thumbnail: bool | None
-    pad_during_tiling: bool | None
-    do_pad: bool | None
-
-
-@add_start_docstrings(
-    "Constructs a fast ConvNeXT image processor. Based on [`SiglipImageProcessor`] with incorporation of processing each video frame.",
-    # BASE_IMAGE_PROCESSOR_FAST_DOCSTRING, TODO: this was depreciated from transformers remove!
-    """
-        image_grid_pinpoints (`List[List[int]]`, *optional*):
-            A list of possible resolutions to use for processing high resolution images. The best resolution is selected
-            based on the original size of the image. Can be overridden by `image_grid_pinpoints` in the `preprocess`
-            method. Not used for processing videos.
-        do_pad (`bool`, *optional*):
-            Whether to pad the image. If `True`, will pad the patch dimension of the images in the batch to the largest
-            number of patches in the batch. Padding will be applied to the bottom and right with zeros.
-    """,
-)
-class Eagle25VLImageProcessorFast(BaseImageProcessorFast):
-    resample = PILImageResampling.BICUBIC
-    image_mean = IMAGENET_STANDARD_MEAN
-    image_std = IMAGENET_STANDARD_STD
-    size = {"height": 448, "width": 448}
-    default_to_square = False
-    crop_size = None
-    do_resize = True
-    do_center_crop = None
-    do_rescale = True
-    do_normalize = True
-    do_convert_rgb = True
-    do_pad = True
-    max_dynamic_tiles = 12
-    min_dynamic_tiles = 1
-    use_thumbnail = True
-    pad_during_tiling = False
-    valid_kwargs = Eagle25VLFastImageProcessorKwargs
-    model_input_names = ["pixel_values_videos"]
-
-    def __init__(self, **kwargs: Unpack[Eagle25VLFastImageProcessorKwargs]):
-        super().__init__(**kwargs)
-
-    @add_start_docstrings(
-        # BASE_IMAGE_PROCESSOR_FAST_DOCSTRING_PREPROCESS, TODO: this was depreciated from transformers remove!
-        """
-            max_dynamic_tiles (`int`, *optional*):
-                The maximum number of dynamic tiles to use for processing high resolution images.
-            min_dynamic_tiles (`int`, *optional*):
-                The minimum number of dynamic tiles to use for processing high resolution images.
-            use_thumbnail (`bool`, *optional*):
-                Whether to use a thumbnail for processing high resolution images.
-            pad_during_tiling (`bool`, *optional*):
-                Whether to pad the image during tiling.
-            do_pad (`bool`, *optional*):
-                    Whether to pad the image. If `True`, will pad the patch dimension of the images in the batch to the largest
-                    number of patches in the batch. Padding will be applied to the bottom and right with zeros.
-        """,
-    )
-
-    # NOTE(YL): we will overload the preprocess method to add the image_flags
-    # def preprocess(
-    #     self, images: ImageInput, **kwargs: Unpack[Eagle25VLFastImageProcessorKwargs]
-    # ) -> BatchFeature:
-    #     return super().preprocess(images, **kwargs)
-
-    def _prepare_images_structure(
-        self,
-        images: ImageInput,
-        expected_ndims: int = 3,
-    ) -> ImageInput:
-        """
-        Prepare the images structure for processing.
-
-        Args:
-            images (`ImageInput`):
-                The input images to process.
-            expected_ndims (`int`, *optional*, defaults to 3):
-                Expected number of dimensions for the images (added for transformers >=4.53.0 compatibility).
-
-        Returns:
-            `ImageInput`: The images with a valid nesting.
-        """
-        return make_flat_list_of_images(images)
-
-    def _resize_for_patching(
-        self,
-        image: torch.Tensor,
-        target_resolution: tuple,
-        interpolation: F.InterpolationMode,
-        input_data_format: ChannelDimension,
-    ) -> torch.Tensor:
-        """
-        Resizes an image to a target resolution while maintaining aspect ratio.
-
-        Args:
-            image ("torch.Tensor"):
-                The input image.
-            target_resolution (tuple):
-                The target resolution (height, width) of the image.
-            interpolation (`InterpolationMode`):
-                Resampling filter to use if resizing the image.
-            input_data_format (`ChannelDimension` or `str`):
-                The channel dimension format of the input image.
-
-        Returns:
-            "torch.Tensor": The resized and padded image.
-        """
-        new_height, new_width = get_patch_output_size(image, target_resolution, input_data_format)
-
-        # Resize the image
-        resized_image = F.resize(image, (new_height, new_width), interpolation=interpolation)
-
-        return resized_image
-
-    def find_closest_aspect_ratio(self, aspect_ratio, target_ratios, width, height, image_size):
-        """
-        previous version mainly focus on ratio.
-        We also consider area ratio here.
-        """
-        best_factor = float("-inf")
-        best_ratio = (1, 1)
-        area = width * height
-        for ratio in target_ratios:
-            target_aspect_ratio = ratio[0] / ratio[1]
-            # ratio_diff = abs(aspect_ratio - target_aspect_ratio)
-            # area_ratio = (ratio[0] * ratio[1] * image_size * image_size) / area
-            """
-            new area > 60% of original image area is enough.
-            """
-            factor_based_on_area_n_ratio = min(
-                (ratio[0] * ratio[1] * image_size * image_size) / area, 0.6
-            ) * min(target_aspect_ratio / aspect_ratio, aspect_ratio / target_aspect_ratio)
-
-            if factor_based_on_area_n_ratio > best_factor:
-                best_factor = factor_based_on_area_n_ratio
-                best_ratio = ratio
-
-        return best_ratio
-
-    def _pad_for_patching(
-        self, image: torch.Tensor, target_resolution: tuple, input_data_format: ChannelDimension
-    ) -> torch.Tensor:
-        """
-        Pad an image to a target resolution while maintaining aspect ratio.
-        """
-        target_height, target_width = target_resolution
-        new_height, new_width = get_patch_output_size(image, target_resolution, input_data_format)
-
-        paste_x = (target_width - new_width) // 2
-        paste_y = (target_height - new_height) // 2
-
-        padded_image = F.pad(image, padding=[paste_x, paste_y, paste_x, paste_y])
-
-        return padded_image
-
-    def _get_image_patches(
-        self,
-        image: torch.Tensor,
-        min_num: int,
-        max_num: int,
-        size: tuple,
-        tile_size: int,
-        use_thumbnail: bool,
-        interpolation: F.InterpolationMode,
-        pad_during_tiling: bool,
-    ) -> list[torch.Tensor]:
-        image_size = get_image_size(image, channel_dim=ChannelDimension.FIRST)
-        orig_height, orig_width = image_size
-        aspect_ratio = orig_width / orig_height
-
-        # calculate the existing image aspect ratio
-        target_ratios = {
-            (i, j)
-            for n in range(min_num, max_num + 1)
-            for i in range(1, n + 1)
-            for j in range(1, n + 1)
-            if i * j <= max_num and i * j >= min_num
-        }
-        target_ratios = sorted(target_ratios, key=lambda x: x[0] * x[1])
-
-        # find the closest aspect ratio to the target
-        target_aspect_ratio = self.find_closest_aspect_ratio(
-            aspect_ratio, target_ratios, orig_width, orig_height, tile_size
-        )
-
-        # calculate the target width and height
-        target_width = tile_size * target_aspect_ratio[0]
-        target_height = tile_size * target_aspect_ratio[1]
-        blocks = target_aspect_ratio[0] * target_aspect_ratio[1]
-        if pad_during_tiling:
-            resized_image = self._resize_for_patching(
-                image,
-                (target_height, target_width),
-                interpolation=interpolation,
-                input_data_format=ChannelDimension.FIRST,
-            )
-            padded_image = self._pad_for_patching(
-                resized_image,
-                (target_height, target_width),
-                input_data_format=ChannelDimension.FIRST,
-            )
-            image_used_to_split = padded_image
-        else:
-            image_used_to_split = F.resize(image, (target_height, target_width), interpolation=interpolation)
-
-        processed_tiles = []
-        for i in range(blocks):
-            box = (
-                (i % (target_width // tile_size)) * tile_size,
-                (i // (target_width // tile_size)) * tile_size,
-                ((i % (target_width // tile_size)) + 1) * tile_size,
-                ((i // (target_width // tile_size)) + 1) * tile_size,
-            )
-            # split the image
-            split_img = crop(image_used_to_split, box[0], box[1], box[2], box[3])
-            processed_tiles.append(split_img)
-        assert len(processed_tiles) == blocks
-
-        if use_thumbnail and len(processed_tiles) != 1:
-            thumbnail_img = F.resize(image, (tile_size, tile_size), interpolation=interpolation)
-            processed_tiles.append(thumbnail_img)
-
-        return processed_tiles
-
-    def _pad_for_batching(
-        self,
-        pixel_values: list[torch.Tensor],
-    ) -> list[torch.Tensor]:
-        """
-        Pads images on the `num_of_patches` dimension with zeros to form a batch of same number of patches.
-
-        Args:
-            pixel_values (`List[torch.Tensor]`):
-                An array of pixel values of each images of shape (`batch_size`, `num_patches`, `image_in_3D`)
-
-        Returns:
-            List[`torch.Tensor`]: The padded images.
-        """
-        max_patch = max(len(x) for x in pixel_values)
-        pixel_values = [
-            torch.nn.functional.pad(image, pad=[0, 0, 0, 0, 0, 0, 0, max_patch - image.shape[0]])
-            for image in pixel_values
-        ]
-
-        return pixel_values
-
-    def _preprocess(
-        self,
-        images: list[torch.Tensor],
-        do_resize: bool,
-        size: SizeDict,
-        max_dynamic_tiles: int,
-        min_dynamic_tiles: int,
-        use_thumbnail: bool,
-        pad_during_tiling: bool,
-        interpolation: F.InterpolationMode | None,
-        do_center_crop: bool,
-        crop_size: SizeDict,
-        do_rescale: bool,
-        rescale_factor: float,
-        do_normalize: bool,
-        image_mean: float | list[float] | None,
-        image_std: float | list[float] | None,
-        do_pad: bool,
-        return_tensors: str | TensorType | None,
-        pad_size: SizeDict | None = None,  # Added for transformers >=4.53.0 compatibility
-        disable_grouping: bool | None = None,  # Added for transformers >=4.53.0 compatibility
-    ) -> BatchFeature:
-        processed_images = []
-        image_sizes = []
-        # Determine the size tuple
-        if size and size.height and size.width:
-            size_tuple = (size.height, size.width)
-        else:
-            size_tuple = (size.shortest_edge, size.shortest_edge)
-
-        # Determine the patch size
-        if crop_size and crop_size.height:
-            tile_size = crop_size.height
-        elif size and size.height:
-            tile_size = size.height
-        else:
-            tile_size = size.shortest_edge
-
-        for image in images:
-            image_patches = self._get_image_patches(
-                image,
-                min_num=min_dynamic_tiles,
-                max_num=max_dynamic_tiles,
-                size=size_tuple,
-                tile_size=tile_size,
-                use_thumbnail=use_thumbnail,
-                interpolation=interpolation,
-                pad_during_tiling=pad_during_tiling,
-            )
-
-            # Group images by size for batched processing
-            processed_image_patches_grouped = {}
-            # Added for transformers >=4.53.0 compatibility
-            grouped_image_patches, grouped_image_patches_index = group_images_by_shape(
-                image_patches,
-                disable_grouping=disable_grouping,
-            )
-
-            for shape, stacked_image_patches in grouped_image_patches.items():
-                if do_resize:
-                    stacked_image_patches = self.resize(
-                        image=stacked_image_patches,
-                        size=size,
-                        interpolation=interpolation,
-                    )
-                if do_center_crop:
-                    stacked_image_patches = self.center_crop(stacked_image_patches, crop_size)
-                # Fused rescale and normalize
-                stacked_image_patches = self.rescale_and_normalize(
-                    stacked_image_patches,
-                    do_rescale,
-                    rescale_factor,
-                    do_normalize,
-                    image_mean,
-                    image_std,
-                )
-                processed_image_patches_grouped[shape] = stacked_image_patches
-            processed_image_patches = reorder_images(
-                processed_image_patches_grouped, grouped_image_patches_index
-            )
-            processed_image_patches = (
-                torch.stack(processed_image_patches, dim=0) if return_tensors else processed_image_patches
-            )
-            processed_images.append(processed_image_patches)
-            image_sizes.append(get_image_size(image, ChannelDimension.FIRST))
-
-        if do_pad:
-            processed_images = self._pad_for_batching(processed_images)
-
-        # processed_images = torch.stack(processed_images, dim=0) if return_tensors else processed_images
-        processed_images = torch.cat(processed_images, dim=0) if return_tensors else processed_images
-        return BatchFeature(
-            data={"pixel_values": processed_images, "image_sizes": image_sizes},
-            tensor_type=return_tensors,
-        )
-
-    def preprocess(
-        self,
-        images: ImageInput,
-        videos: VideoInput = None,
-        **kwargs: Unpack[Eagle25VLFastImageProcessorKwargs],
-    ) -> BatchFeature:
-        validate_kwargs(
-            captured_kwargs=kwargs.keys(),
-            valid_processor_keys=self.valid_kwargs.__annotations__.keys(),
-        )
-        # Set default kwargs from self. This ensures that if a kwarg is not provided
-        # by the user, it gets its default value from the instance, or is set to None.
-        for kwarg_name in self.valid_kwargs.__annotations__:
-            kwargs.setdefault(kwarg_name, getattr(self, kwarg_name, None))
-
-        # Extract parameters that are only used for preparing the input images
-        do_convert_rgb = kwargs.pop("do_convert_rgb")
-        input_data_format = kwargs.pop("input_data_format")
-        device = kwargs.pop("device")
-        # Prepare input images
-        # transformers >= 4.53.0: uses _prepare_image_like_inputs instead of _prepare_input_images
-        if images is not None:
-            images = self._prepare_image_like_inputs(
-                images=images,
-                do_convert_rgb=do_convert_rgb,
-                input_data_format=input_data_format,
-                device=device,
-            )
-
-        if videos is not None:
-            videos = self._prepare_image_like_inputs(
-                images=videos,
-                do_convert_rgb=do_convert_rgb,
-                input_data_format=input_data_format,
-                device=device,
-            )
-
-        # Update kwargs that need further processing before being validated
-        kwargs = self._further_process_kwargs(**kwargs)
-
-        # Validate kwargs
-        self._validate_preprocess_kwargs(**kwargs)
-
-        # torch resize uses interpolation instead of resample
-        # Added for transformers >=4.53.0 compatibility
-        resample = kwargs.pop("resample", self.resample)
-        kwargs["interpolation"] = (
-            pil_torch_interpolation_mapping[resample]
-            if isinstance(resample, PILImageResampling | int)
-            else resample
-        )
-
-        # Filter kwargs to only include those accepted by _preprocess
-        valid_preprocess_kwargs = {
-            "do_resize",
-            "size",
-            "max_dynamic_tiles",
-            "min_dynamic_tiles",
-            "use_thumbnail",
-            "pad_during_tiling",
-            "interpolation",
-            "do_center_crop",
-            "crop_size",
-            "do_rescale",
-            "rescale_factor",
-            "do_normalize",
-            "image_mean",
-            "image_std",
-            "do_pad",
-            "return_tensors",
-            "pad_size",
-            "disable_grouping",
-        }
-        filtered_kwargs = {k: v for k, v in kwargs.items() if k in valid_preprocess_kwargs}
-        if images is not None:
-            return self._preprocess(images, **filtered_kwargs)
-        elif videos is not None:
-            return self._preprocess(videos, **filtered_kwargs)
-
-
-__all__ = ["Eagle25VLImageProcessorFast"]

src/lerobot/policies/groot/eagle2_hg_model/modeling_eagle2_5_vl.py

@@ -1,396 +0,0 @@
-# --------------------------------------------------------
-# NVIDIA
-# Copyright (c) 2025 NVIDIA
-# Licensed under The MIT License [see LICENSE for details]
-# --------------------------------------------------------
-
-import inspect
-
-import torch
-import torch.utils.checkpoint as cp
-from peft import LoraConfig, get_peft_model
-from torch import nn
-from torch.nn import CrossEntropyLoss
-from transformers import GenerationConfig
-from transformers.generation import GenerationMixin
-from transformers.modeling_outputs import CausalLMOutputWithPast
-from transformers.modeling_utils import PreTrainedModel
-from transformers.models.llama.modeling_llama import LlamaForCausalLM
-from transformers.models.qwen2.modeling_qwen2 import Qwen2ForCausalLM
-from transformers.models.qwen3.modeling_qwen3 import Qwen3ForCausalLM
-from transformers.models.siglip.modeling_siglip import SiglipVisionModel
-from transformers.utils import add_start_docstrings, logging
-
-from .configuration_eagle2_5_vl import Eagle25VLConfig
-
-logger = logging.get_logger(__name__)
-
-
-# copy from https://github.com/huggingface/transformers/blob/main/src/transformers/models/llava_onevision/modeling_llava_onevision.py#L241C1-L280C1
-EAGLE2_5_VL_START_DOCSTRING = r"""
-    This model inherits from [`PreTrainedModel`]. Check the superclass documentation for the generic methods the
-    library implements for all its model (such as downloading or saving, resizing the input embeddings, pruning heads
-    etc.)
-
-    This model is also a PyTorch [torch.nn.Module](https://pytorch.org/docs/stable/nn.html#torch.nn.Module) subclass.
-    Use it as a regular PyTorch Module and refer to the PyTorch documentation for all matter related to general usage
-    and behavior.
-
-    Parameters:
-        config ([`Eagle25VLConfig`]):
-            Model configuration class with all the parameters of the model. Initializing with a config file does not
-            load the weights associated with the model, only the configuration. Check out the
-            [`~PreTrainedModel.from_pretrained`] method to load the model weights.
-"""
-
-
-@add_start_docstrings(
-    "The bare Eagle2_5_VL Model outputting raw hidden-states without any specific head on top.",
-    EAGLE2_5_VL_START_DOCSTRING,
-)
-class Eagle25VLPreTrainedModel(PreTrainedModel):
-    config_class = Eagle25VLConfig
-    base_model_prefix = "model"
-    main_input_name = "input_ids"
-    supports_gradient_checkpointing = True
-    _no_split_modules = [
-        "Qwen2DecoderLayer",
-        "LlamaDecoderLayer",
-        "Siglip2EncoderLayer",
-        "SiglipEncoderLayer",
-    ]
-    _skip_keys_device_placement = "past_key_values"
-    _supports_flash_attn = True
-    _supports_flash_attn_2 = True
-    _supports_cache_class = True
-    _supports_static_cache = True
-    _supports_quantized_cache = True
-    _supports_sdpa = True
-
-    def _init_weights(self, module):
-        std = self.config.initializer_range
-        if isinstance(module, nn.Linear | nn.Conv2d):
-            module.weight.data.normal_(mean=0.0, std=std)
-            if module.bias is not None:
-                module.bias.data.zero_()
-        elif isinstance(module, nn.Embedding):
-            module.weight.data.normal_(mean=0.0, std=std)
-            if module.padding_idx is not None:
-                module.weight.data[module.padding_idx].zero_()
-
-
-class Eagle25VLForConditionalGeneration(Eagle25VLPreTrainedModel, GenerationMixin):
-    config_class = Eagle25VLConfig
-
-    def __init__(self, config: Eagle25VLConfig, vision_model=None, language_model=None):
-        super().__init__(config)
-
-        image_size = config.force_image_size or config.vision_config.image_size
-        patch_size = config.vision_config.patch_size
-        self.patch_size = patch_size
-        if config.use_pixel_shuffle:
-            self.num_image_token = int((image_size // patch_size) ** 2 * (config.downsample_ratio**2))
-        else:
-            self.num_image_token = int((image_size // patch_size) ** 2)
-
-        self.select_layer = config.select_layer
-        self.downsample_ratio = config.downsample_ratio
-        self.loss_version = config.loss_version
-        self.mlp_checkpoint = config.mlp_checkpoint
-        self.use_pixel_shuffle = config.use_pixel_shuffle
-        self.mlp_connector_layers = config.mlp_connector_layers
-        logger.info(f"num_image_token: {self.num_image_token}")
-        logger.info(f"mlp_checkpoint: {self.mlp_checkpoint}")
-        if vision_model is not None:
-            self.vision_model = vision_model
-        else:
-            if config.vision_config.model_type == "siglip_vision_model":
-                config.vision_config._attn_implementation = "flash_attention_2"
-                self.vision_model = SiglipVisionModel(config.vision_config)
-            else:
-                raise NotImplementedError(f"{config.vision_config.model_type} is not implemented.")
-
-        if language_model is not None:
-            self.language_model = language_model
-        else:
-            if config.text_config.architectures[0] == "LlamaForCausalLM":
-                self.language_model = LlamaForCausalLM(config.text_config)
-            elif config.text_config.architectures[0] == "Phi3ForCausalLM":
-                raise NotImplementedError("Phi3 is not implemented.")
-                # self.language_model = Phi3ForCausalLM(config.text_config)
-            elif config.text_config.architectures[0] == "Qwen2ForCausalLM":
-                assert config.text_config._attn_implementation == "flash_attention_2", (
-                    f"Qwen2 must use flash_attention_2 but got {config.text_config._attn_implementation}"
-                )
-                self.language_model = Qwen2ForCausalLM(config.text_config)
-            elif config.text_config.architectures[0] == "Qwen3ForCausalLM":
-                self.language_model = Qwen3ForCausalLM(config.text_config)
-            else:
-                raise NotImplementedError(f"{config.text_config.architectures[0]} is not implemented.")
-
-        vit_hidden_size = config.vision_config.hidden_size
-        llm_hidden_size = config.text_config.hidden_size
-
-        if config.mlp_connector_layers == 2:
-            self.mlp1 = nn.Sequential(
-                nn.LayerNorm(vit_hidden_size * int(1 / self.downsample_ratio) ** 2),
-                nn.Linear(vit_hidden_size * int(1 / self.downsample_ratio) ** 2, llm_hidden_size),
-                nn.GELU(),
-                nn.Linear(llm_hidden_size, llm_hidden_size),
-            )
-        elif config.mlp_connector_layers == 1 and config.use_pixel_shuffle:
-            self.mlp1 = nn.Sequential(
-                nn.Linear(vit_hidden_size * int(1 / self.downsample_ratio) ** 2, llm_hidden_size),
-            )
-        elif config.mlp_connector_layers == 1 and not config.use_pixel_shuffle:
-            self.mlp1 = nn.Sequential(
-                nn.Linear(vit_hidden_size, llm_hidden_size),
-            )
-        else:
-            raise NotImplementedError(f"{config.mlp_connector_layers} is not implemented.")
-
-        self.image_token_index = config.image_token_index
-        self.neftune_alpha = None
-
-        if config.use_backbone_lora:
-            self.wrap_backbone_lora(r=config.use_backbone_lora, lora_alpha=2 * config.use_backbone_lora)
-
-        self.use_llm_lora = config.use_llm_lora
-        if config.use_llm_lora:
-            self.wrap_llm_lora(r=config.use_llm_lora, lora_alpha=2 * config.use_llm_lora)
-
-        self.check_forward_kwargs()
-
-    def check_forward_kwargs(self):
-        # We intentionally avoid using **kwargs in forward because Hugging Face Transformers
-        # has special handling for functions with **kwargs parameters that would affect
-        # how our model is processed during training and inference.
-        forward_params = inspect.signature(self.forward).parameters
-        assert not any(k.kind == inspect.Parameter.VAR_KEYWORD for k in forward_params.values())
-
-    def wrap_backbone_lora(self, r=128, lora_alpha=256, lora_dropout=0.05):
-        lora_config = LoraConfig(
-            r=r,
-            target_modules=[
-                "self_attn.q_proj",
-                "self_attn.k_proj",
-                "self_attn.v_proj",
-                "self_attn.out_proj",
-                "mlp.fc1",
-                "mlp.fc2",
-            ],
-            lora_alpha=lora_alpha,
-            lora_dropout=lora_dropout,
-        )
-        self.vision_model = get_peft_model(self.vision_model, lora_config)
-        self.vision_model.print_trainable_parameters()
-
-    def wrap_llm_lora(self, r=128, lora_alpha=256, lora_dropout=0.05):
-        lora_config = LoraConfig(
-            r=r,
-            target_modules=[
-                "self_attn.q_proj",
-                "self_attn.k_proj",
-                "self_attn.v_proj",
-                "self_attn.o_proj",
-                "mlp.gate_proj",
-                "mlp.down_proj",
-                "mlp.up_proj",
-            ],
-            lora_alpha=lora_alpha,
-            lora_dropout=lora_dropout,
-            task_type="CAUSAL_LM",
-        )
-        self.language_model = get_peft_model(self.language_model, lora_config)
-        self.language_model.enable_input_require_grads()
-        self.language_model.print_trainable_parameters()
-        self.use_llm_lora = True
-
-    def forward(
-        self,
-        pixel_values: torch.FloatTensor,
-        input_ids: torch.LongTensor = None,
-        attention_mask: torch.Tensor | None = None,
-        position_ids: torch.LongTensor | None = None,
-        image_flags: torch.LongTensor | None = None,
-        past_key_values: list[torch.FloatTensor] | None = None,
-        labels: torch.LongTensor | None = None,
-        use_cache: bool | None = None,
-        output_attentions: bool | None = None,
-        output_hidden_states: bool | None = None,
-        return_dict: bool | None = None,
-        num_tiles_list: list[torch.Tensor] | None = None,
-    ) -> tuple | CausalLMOutputWithPast:
-        return_dict = return_dict if return_dict is not None else self.config.use_return_dict
-
-        input_embeds = self.language_model.get_input_embeddings()(input_ids)
-
-        vit_embeds = self.extract_feature(pixel_values)
-
-        if image_flags is not None:
-            image_flags = image_flags.view(-1)
-            vit_embeds = vit_embeds[image_flags == 1]
-
-        b, n, c = input_embeds.shape
-        input_embeds = input_embeds.reshape(b * n, c)
-
-        input_ids = input_ids.reshape(b * n)
-        selected = input_ids == self.image_token_index
-        try:
-            input_embeds[selected] = input_embeds[selected] * 0.0 + vit_embeds.reshape(-1, c)
-        except Exception as e:
-            vit_embeds = vit_embeds.reshape(-1, c)
-            print(
-                f"warning: {e}, input_embeds[selected].shape={input_embeds[selected].shape}, "
-                f"vit_embeds.shape={vit_embeds.shape}"
-            )
-            n_token = selected.sum()
-            input_embeds[selected] = input_embeds[selected] * 0.0 + vit_embeds[:n_token]
-
-        input_embeds = input_embeds.reshape(b, n, c)
-
-        outputs = self.language_model(
-            inputs_embeds=input_embeds,
-            attention_mask=attention_mask,
-            position_ids=position_ids,
-            past_key_values=past_key_values,
-            use_cache=use_cache,
-            output_attentions=output_attentions,
-            output_hidden_states=output_hidden_states,
-        )
-        logits = outputs.logits
-
-        loss = None
-        if labels is not None:
-            # Shift so that tokens < n predict n
-            shift_logits = logits[..., :-1, :].contiguous()
-            shift_labels = labels[..., 1:].contiguous()
-            # Flatten the tokens
-            loss_fct = CrossEntropyLoss()
-            shift_logits = shift_logits.view(-1, self.language_model.config.vocab_size)
-            shift_labels = shift_labels.view(-1)
-            # Enable model parallelism
-            shift_labels = shift_labels.to(shift_logits.device)
-            loss = loss_fct(shift_logits, shift_labels)
-
-        if not return_dict:
-            output = (logits,) + outputs[1:]
-            return (loss,) + output if loss is not None else output
-
-        return CausalLMOutputWithPast(
-            loss=loss,
-            logits=logits,
-            past_key_values=outputs.past_key_values,
-            hidden_states=outputs.hidden_states,
-            attentions=outputs.attentions,
-        )
-
-    def pixel_shuffle(self, x, scale_factor=0.5):
-        n, w, h, c = x.size()
-        # N, W, H, C --> N, W, H * scale, C // scale
-        x = x.view(n, w, int(h * scale_factor), int(c / scale_factor))
-        # N, W, H * scale, C // scale --> N, H * scale, W, C // scale
-        x = x.permute(0, 2, 1, 3).contiguous()
-        # N, H * scale, W, C // scale --> N, H * scale, W * scale, C // (scale ** 2)
-        x = x.view(n, int(h * scale_factor), int(w * scale_factor), int(c / (scale_factor * scale_factor)))
-
-        x = x.permute(0, 2, 1, 3).contiguous()
-        return x
-
-    def extract_feature(self, pixel_values):
-        if self.select_layer == -1:
-            vit_embeds = self.vision_model(
-                pixel_values=pixel_values, output_hidden_states=False, return_dict=True
-            )
-            if hasattr(vit_embeds, "last_hidden_state"):
-                vit_embeds = vit_embeds.last_hidden_state
-
-        else:
-            vit_embeds = self.vision_model(
-                pixel_values=pixel_values, output_hidden_states=True, return_dict=True
-            ).hidden_states[self.select_layer]
-
-        if self.use_pixel_shuffle:
-            h = w = int(vit_embeds.shape[1] ** 0.5)
-            vit_embeds = vit_embeds.reshape(vit_embeds.shape[0], h, w, -1)
-            vit_embeds = self.pixel_shuffle(
-                vit_embeds, scale_factor=self.downsample_ratio
-            )  # torch.Size([B, 1024, 1024]) -> torch.Size([B, 16, 16, 4096])
-            vit_embeds = vit_embeds.reshape(
-                vit_embeds.shape[0], -1, vit_embeds.shape[-1]
-            )  # torch.Size([B, 16, 16, 4096]) -> torch.Size([B, 256, 4096])
-
-        if self.mlp_checkpoint and vit_embeds.requires_grad:
-            vit_embeds = cp.checkpoint(self.mlp1, vit_embeds)
-        else:
-            vit_embeds = self.mlp1(vit_embeds)
-
-        return vit_embeds
-
-    @torch.no_grad()
-    def generate(
-        self,
-        pixel_values: torch.FloatTensor | None = None,
-        input_ids: torch.FloatTensor | None = None,
-        attention_mask: torch.LongTensor | None = None,
-        visual_features: torch.FloatTensor | None = None,
-        generation_config: GenerationConfig | None = None,
-        output_hidden_states: bool | None = None,
-        image_sizes: list[tuple[int, int]] | None = None,
-        **generate_kwargs,
-    ) -> torch.LongTensor:
-        if pixel_values is not None:
-            if visual_features is not None:
-                vit_embeds = visual_features
-            else:
-                vit_embeds = self.extract_feature(pixel_values)
-
-            input_embeds = self.language_model.get_input_embeddings()(input_ids)
-            b, n, c = input_embeds.shape
-            input_embeds = input_embeds.reshape(b * n, c)
-
-            input_ids = input_ids.reshape(b * n)
-            selected = input_ids == self.config.image_token_index
-            assert selected.sum() != 0
-            input_embeds[selected] = vit_embeds.reshape(-1, c).to(input_embeds.device)
-
-            input_embeds = input_embeds.reshape(b, n, c)
-        else:
-            input_embeds = self.language_model.get_input_embeddings()(input_ids)
-
-        if "use_cache" not in generate_kwargs:
-            generate_kwargs["use_cache"] = True
-
-        outputs = self.language_model.generate(
-            inputs_embeds=input_embeds,
-            attention_mask=attention_mask,
-            generation_config=generation_config,
-            output_hidden_states=output_hidden_states,
-            **generate_kwargs,
-        )
-
-        return outputs
-
-    # Copied from transformers.models.llava_next.modeling_llava_next.LlavaNextForConditionalGeneration.get_input_embeddings
-    def get_input_embeddings(self):
-        return self.language_model.get_input_embeddings()
-
-    # Copied from transformers.models.llava_next.modeling_llava_next.LlavaNextForConditionalGeneration.set_input_embeddings
-    def set_input_embeddings(self, value):
-        self.language_model.set_input_embeddings(value)
-
-    # Copied from transformers.models.llava_next.modeling_llava_next.LlavaNextForConditionalGeneration.get_output_embeddings
-    def get_output_embeddings(self):
-        return self.language_model.get_output_embeddings()
-
-    # Copied from transformers.models.llava_next.modeling_llava_next.LlavaNextForConditionalGeneration.set_output_embeddings
-    def set_output_embeddings(self, new_embeddings):
-        self.language_model.set_output_embeddings(new_embeddings)
-
-    # Copied from transformers.models.llava_next.modeling_llava_next.LlavaNextForConditionalGeneration.set_decoder
-    def set_decoder(self, decoder):
-        self.language_model.set_decoder(decoder)
-
-    # Copied from transformers.models.llava_next.modeling_llava_next.LlavaNextForConditionalGeneration.get_decoder
-    def get_decoder(self):
-        return self.language_model.get_decoder()

src/lerobot/policies/groot/eagle2_hg_model/processing_eagle2_5_vl.py

@@ -1,541 +0,0 @@
-# Copyright 2024 The HuggingFace Inc. team.
-#
-# Licensed under the Apache License, Version 2.0 (the "License");
-# you may not use this file except in compliance with the License.
-# You may obtain a copy of the License at
-#
-#     http://www.apache.org/licenses/LICENSE-2.0
-#
-# Unless required by applicable law or agreed to in writing, software
-# distributed under the License is distributed on an "AS IS" BASIS,
-# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
-# See the License for the specific language governing permissions and
-# limitations under the License.
-"""
-Processor class for Eagle25VL.
-copy from https://github.com/huggingface/transformers/blob/main/src/transformers/models/llava_onevision/processing_llava_onevision.py
-"""
-
-import base64
-import os
-import re
-from io import BytesIO
-
-import requests
-import torch
-from PIL import Image
-from transformers.feature_extraction_utils import BatchFeature
-from transformers.image_utils import ImageInput
-from transformers.processing_utils import ProcessingKwargs, ProcessorMixin, Unpack
-from transformers.tokenization_utils_base import PreTokenizedInput, TextInput
-from transformers.utils import logging
-from transformers.video_utils import VideoInput
-
-logger = logging.get_logger(__name__)
-
-
-FRAME_FACTOR = 2
-FPS = 2.0
-FPS_MIN_FRAMES = 4
-FPS_MAX_FRAMES = 256
-
-
-def to_rgb(pil_image: Image.Image) -> Image.Image:
-    if pil_image.mode == "RGBA":
-        white_background = Image.new("RGB", pil_image.size, (255, 255, 255))
-        white_background.paste(pil_image, mask=pil_image.split()[3])  # Use alpha channel as mask
-        return white_background
-    else:
-        return pil_image.convert("RGB")
-
-
-def fetch_image(ele: dict[str, str | Image.Image]) -> Image.Image:
-    image = ele["image"] if "image" in ele else ele["image_url"]
-    image_obj = None
-    if isinstance(image, Image.Image):
-        image_obj = image
-    elif image.startswith("http://") or image.startswith("https://"):
-        response = requests.get(image, stream=True, timeout=10)
-        image_obj = Image.open(BytesIO(response.content))
-    elif image.startswith("file://"):
-        image_obj = Image.open(image[7:])
-    elif image.startswith("data:image"):
-        if "base64," in image:
-            _, base64_data = image.split("base64,", 1)
-            data = base64.b64decode(base64_data)
-            image_obj = Image.open(BytesIO(data))
-    else:
-        image_obj = Image.open(image)
-    if image_obj is None:
-        raise ValueError(
-            f"Unrecognized image input, support local path, http url, base64 and PIL.Image, got {image}"
-        )
-    image = to_rgb(image_obj)
-    if "scale_factor" in ele:
-        scale_factor = ele["scale_factor"]
-        image = image.resize((image.width * scale_factor, image.height * scale_factor), Image.BILINEAR)
-    return image
-
-
-class Eagle25VLProcessorKwargs(ProcessingKwargs, total=False):
-    # see processing_utils.ProcessingKwargs documentation for usage.
-    _defaults = {
-        "text_kwargs": {
-            "padding": False,
-        },
-        "images_kwargs": {},
-        "videos_kwargs": {"max_dynamic_tiles": 1},
-    }
-
-
-class Eagle25VLProcessor(ProcessorMixin):
-    r"""
-    Constructs a Eagle25VL processor which wraps a Eagle25VL video processor, Eagle25VL image processor and a Eagle25VL tokenizer into a single processor.
-
-    [`Eagle25VLProcessor`] offers all the functionalities of [`Eagle25VLVideoProcessor`], [`Eagle25VLImageProcessor`] and [`Eagle25VLTokenizer`]. See the
-    [`~Eagle25VLVideoProcessor.__call__`], [`~Eagle25VLProcessor.__call__`] and [`~Eagle25VLProcessor.decode`] for more information.
-
-    Args:
-        image_processor ([`LlavaOnevisionImageProcessor`], *optional*):
-            The image processor is a required input.
-        tokenizer ([`LlamaTokenizerFast`], *optional*):
-            The tokenizer is a required input.
-        num_image_tokens (`int`, *optional*):
-            Number of image tokens for one imagethat will be returned by vision tower.
-        vision_feature_select_strategy (`str`, *optional*):
-            The feature selection strategy used to select the vision feature from the vision backbone.
-            Should be same as in model's config
-        chat_template (`str`, *optional*): A Jinja template which will be used to convert lists of messages
-            in a chat into a tokenizable string.
-        image_token (`str`, *optional*, defaults to `"<image>"`):
-            Special token used to denote image location.
-        video_token (`str`, *optional*, defaults to `"<video>"`):
-            Special token used to denote video location.
-    """
-
-    attributes = ["image_processor", "tokenizer"]
-    valid_kwargs = [
-        "chat_template",
-        "num_image_tokens",
-        "vision_feature_select_strategy",
-        "image_token",
-        "video_token",
-        "images_kwargs",
-        "videos_kwargs",
-        "text_kwargs",
-    ]
-    tokenizer_class = "AutoTokenizer"
-
-    def __init__(
-        self,
-        image_processor=None,
-        tokenizer=None,
-        vision_feature_select_strategy=None,
-        chat_template=None,
-        image_token="<IMG_CONTEXT>",  # nosec: B107
-        video_token="<IMG_CONTEXT>",  # nosec: B107
-        tokens_per_tile=256,
-        image_placeholder="image",
-        video_placeholder="video",
-        image_start_token="<img>",
-        image_end_token="</img>",
-        **kwargs,
-    ):
-        self.vision_feature_select_strategy = vision_feature_select_strategy
-        self.image_token = tokenizer.image_token if hasattr(tokenizer, "image_token") else image_token
-        self.video_token = tokenizer.video_token if hasattr(tokenizer, "video_token") else video_token
-        self.image_token_id = (
-            tokenizer.image_token_id
-            if getattr(tokenizer, "image_token_id", None)
-            else tokenizer.convert_tokens_to_ids(self.image_token)
-        )
-        self.video_token_id = (
-            tokenizer.video_token_id
-            if getattr(tokenizer, "video_token_id", None)
-            else tokenizer.convert_tokens_to_ids(self.video_token)
-        )
-        self.image_placeholder = image_placeholder
-        self.video_placeholder = video_placeholder
-        self.tokens_per_tile = tokens_per_tile
-        self.image_start_token = image_start_token
-        self.image_end_token = image_end_token
-        if "auto_map" in kwargs:
-            self.auto_map = kwargs["auto_map"]
-        super().__init__(image_processor, tokenizer, chat_template=chat_template)
-
-    def replace_media_placeholder(
-        self, text, image_list, video_list, timestamps_list, fps_list, **output_kwargs
-    ):
-        num_of_images_in_this_sample = 0
-        num_of_videos_in_this_sample = 0
-        # Regular expression pattern to match formats like <image-1> or <video-2>
-        pattern = re.compile(rf"<({self.image_placeholder}|{self.video_placeholder})-(\d+)>")
-        unified_frame_list = []
-
-        # image_min_dynamic_tiles = output_kwargs["images_kwargs"].get(
-        #     "min_dynamic_tiles", self.image_processor.min_dynamic_tiles
-        # )
-        # image_max_dynamic_tiles = output_kwargs["images_kwargs"].get(
-        #     "max_dynamic_tiles", self.image_processor.max_dynamic_tiles
-        # )
-        # image_use_thumbnail = output_kwargs["images_kwargs"].get(
-        #     "use_thumbnail", self.image_processor.use_thumbnail
-        # )
-        video_min_dynamic_tiles = output_kwargs["videos_kwargs"].get(
-            "min_dynamic_tiles", self.image_processor.min_dynamic_tiles
-        )
-        video_max_dynamic_tiles = output_kwargs["videos_kwargs"].get(
-            "max_dynamic_tiles", self.image_processor.max_dynamic_tiles
-        )
-        video_use_thumbnail = output_kwargs["videos_kwargs"].get(
-            "use_thumbnail", self.image_processor.use_thumbnail
-        )
-
-        tile_size = self.image_processor.size.get("height", 448)
-
-        # Function to replace tags in a single text
-        def replace_in_text(text):
-            # repl callback function for each match replacement operation
-            def repl(match):
-                nonlocal unified_frame_list
-                nonlocal num_of_images_in_this_sample
-                nonlocal num_of_videos_in_this_sample
-                media_type = match.group(1)  # 'image' or 'video'
-                idx_in_list = int(match.group(2)) - 1  # Convert to list index (0-based)
-                # Select the corresponding path based on media type
-                idx_mapper = {
-                    0: "first",
-                    1: "second",
-                    2: "third",
-                    3: "fourth",
-                    4: "fifth",
-                    5: "sixth",
-                    6: "seventh",
-                    7: "eighth",
-                    8: "ninth",
-                    9: "tenth",
-                }
-                if media_type == "image":
-                    image_inputs = self.image_processor(
-                        images=[image_list[idx_in_list]],
-                        videos=None,
-                        **output_kwargs["images_kwargs"],
-                    )
-                    if isinstance(image_inputs["pixel_values"], list):
-                        _pv = image_inputs["pixel_values"]
-                        if _pv and isinstance(_pv[0], list):
-                            _pv = [t for sub in _pv for t in sub]
-                        image_inputs["pixel_values"] = torch.stack(
-                            [t if isinstance(t, torch.Tensor) else torch.as_tensor(t) for t in _pv]
-                        )
-                    num_all_tiles = image_inputs["pixel_values"].shape[0]
-                    special_placeholder = f"<image {idx_in_list + 1}>{self.image_start_token}{self.image_token * num_all_tiles * self.tokens_per_tile}{self.image_end_token}"
-                    unified_frame_list.append(image_inputs)
-                    num_of_images_in_this_sample += 1
-
-                elif media_type == "video":
-                    video_inputs = self.image_processor(
-                        images=None,
-                        videos=[video_list[idx_in_list]],
-                        **output_kwargs["videos_kwargs"],
-                    )
-                    if isinstance(video_inputs["pixel_values"], list):
-                        _pv = video_inputs["pixel_values"]
-                        if _pv and isinstance(_pv[0], list):
-                            _pv = [t for sub in _pv for t in sub]
-                        video_inputs["pixel_values"] = torch.stack(
-                            [t if isinstance(t, torch.Tensor) else torch.as_tensor(t) for t in _pv]
-                        )
-                    num_all_tiles = video_inputs["pixel_values"].shape[0]
-                    image_sizes = video_inputs["image_sizes"]
-                    if timestamps_list is not None and -1 not in timestamps_list:
-                        frame_timestamps = timestamps_list[idx_in_list]
-                    else:
-                        frame_timestamps = None
-                    sampled_fps = fps_list[idx_in_list] if fps_list is not None else None
-
-                    num_of_tiles_each_frame = [
-                        self.get_number_tiles_based_on_image_size(
-                            image_size,
-                            video_min_dynamic_tiles,
-                            video_max_dynamic_tiles,
-                            video_use_thumbnail,
-                            tile_size,
-                        )
-                        for image_size in image_sizes
-                    ]
-                    assert sum(num_of_tiles_each_frame) == num_all_tiles, (
-                        f"The number of tiles in each frame is not equal to the total number of tiles: {sum(num_of_tiles_each_frame)} != {num_all_tiles}"
-                    )
-
-                    if frame_timestamps is not None:
-                        assert len(frame_timestamps) == len(num_of_tiles_each_frame), (
-                            f"The number of timestamps is not equal to the number of frames: {len(frame_timestamps)} != {len(num_of_tiles_each_frame)}"
-                        )
-                        special_placeholder = [
-                            f"Frame {i + 1} sample at {frame_timestamps[i]:.2f}s: {self.image_start_token}{self.image_token * num_of_tiles * self.tokens_per_tile}{self.image_end_token}"
-                            for i, num_of_tiles in enumerate(num_of_tiles_each_frame)
-                        ]
-                    else:
-                        special_placeholder = [
-                            f"Frame {i + 1}: {self.image_start_token}{self.image_token * num_of_tiles * self.tokens_per_tile}{self.image_end_token}"
-                            for i, num_of_tiles in enumerate(num_of_tiles_each_frame)
-                        ]
-
-                    if sampled_fps is not None:
-                        special_placeholder = (
-                            f"The {idx_mapper[idx_in_list]} video sampled with {sampled_fps:.2f} fps: "
-                            + "".join(special_placeholder)
-                        )
-                    else:
-                        special_placeholder = f"The {idx_mapper[idx_in_list]} video: " + "".join(
-                            special_placeholder
-                        )
-                    unified_frame_list.append(video_inputs)
-                    num_of_videos_in_this_sample += 1
-                else:
-                    raise ValueError(f"Unknown media type: {media_type}")
-                return special_placeholder
-
-            return pattern.sub(repl, text)
-
-        text = replace_in_text(text)
-        if len(unified_frame_list) > 0:
-
-            def _to_tensor(v):
-                if isinstance(v, torch.Tensor):
-                    return v
-                if isinstance(v, list):
-                    if v and isinstance(v[0], list):
-                        v = [t for sub in v for t in sub]
-                    return torch.stack([t if isinstance(t, torch.Tensor) else torch.as_tensor(t) for t in v])
-                return torch.as_tensor(v)
-
-            pixel_values = torch.cat([_to_tensor(frame["pixel_values"]) for frame in unified_frame_list])
-            image_sizes = torch.cat([_to_tensor(frame["image_sizes"]) for frame in unified_frame_list])
-        else:
-            pixel_values = None
-            image_sizes = None
-        return (
-            text,
-            pixel_values,
-            image_sizes,
-            num_of_images_in_this_sample,
-            num_of_videos_in_this_sample,
-        )
-
-    def __call__(
-        self,
-        images: ImageInput = None,
-        text: TextInput | PreTokenizedInput | list[TextInput] | list[PreTokenizedInput] = None,
-        audio=None,
-        videos: VideoInput = None,
-        **kwargs: Unpack[Eagle25VLProcessorKwargs],
-    ) -> BatchFeature:
-        """
-        Main method to prepare for the model one or several sequences(s) and image(s). This method forwards the `text`
-        and `kwargs` arguments to LlamaTokenizerFast's [`~LlamaTokenizerFast.__call__`] if `text` is not `None` to encode
-        the text. To prepare the image(s), this method forwards the `images` and `kwrags` arguments to
-        LlavaNextImageProcessor's [`~LlavaNextImageProcessor.__call__`] if `images` is not `None`. Please refer to the docstring
-        of the above two methods for more information.
-
-        Args:
-            images (`PIL.Image.Image`, `np.ndarray`, `torch.Tensor`, `List[PIL.Image.Image]`, `List[np.ndarray]`, `List[torch.Tensor]`):
-                The image or batch of images to be prepared. Each image can be a PIL image, NumPy array or PyTorch
-                tensor. Both channels-first and channels-last formats are supported.
-            text (`str`, `List[str]`, `List[List[str]]`):
-                The sequence or batch of sequences to be encoded. Each sequence can be a string or a list of strings
-                (pretokenized string). If the sequences are provided as list of strings (pretokenized), you must set
-                `is_split_into_words=True` (to lift the ambiguity with a batch of sequences).
-            videos (`np.ndarray`, `torch.Tensor`, `List[np.ndarray]`, `List[torch.Tensor]`):
-                The image or batch of videos to be prepared. Each video can be a 4D NumPy array or PyTorch
-
-        Returns:
-            [`BatchFeature`]: A [`BatchFeature`] with the following fields:
-
-            - **input_ids** -- List of token ids to be fed to a model. Returned when `text` is not `None`.
-            - **attention_mask** -- List of indices specifying which tokens should be attended to by the model (when
-              `return_attention_mask=True` or if *"attention_mask"* is in `self.model_input_names` and if `text` is not
-              `None`).
-            - **pixel_values** -- Pixel values to be fed to a model. Returned when `images` is not `None`.
-            - **pixel_values_videos** -- Pixel values of a video input to be fed to a model. Returned when `videos` is not `None`.
-            - **image_sizes** -- Size of each image that will be used to unpad an image. Returned when `images` is not `None`.
-        """
-
-        output_kwargs = self._merge_kwargs(
-            Eagle25VLProcessorKwargs,
-            tokenizer_init_kwargs=self.tokenizer.init_kwargs,
-            **kwargs,
-        )
-
-        if isinstance(text, str):
-            text_list = [text]
-        elif not isinstance(text, list) and not isinstance(text[0], str):
-            raise ValueError("Invalid input text. Please provide a string, or a list of strings")
-        elif isinstance(text, list) and isinstance(text[0], str):
-            text_list = text
-
-        if images is None:
-            images = []
-        if videos is None:
-            videos = []
-
-        pixel_values_list = []
-        image_sizes_list = []
-        new_sample_list = []
-        image_start_idx = 0
-        video_start_idx = 0
-        timestamps_batch = output_kwargs["videos_kwargs"].pop("timestamps", None)
-        fps_batch = output_kwargs["videos_kwargs"].pop("fps", None)
-        for sample in text_list:
-            timestamps_list = timestamps_batch[video_start_idx:] if timestamps_batch is not None else None
-            fps_list = fps_batch[video_start_idx:] if fps_batch is not None else None
-            (
-                sample,
-                pixel_values,
-                image_sizes,
-                num_of_images_in_this_sample,
-                num_of_videos_in_this_sample,
-            ) = self.replace_media_placeholder(
-                sample,
-                images[image_start_idx:],
-                videos[video_start_idx:],
-                timestamps_list,
-                fps_list,
-                **output_kwargs,
-            )
-            new_sample_list.append(sample)
-            if pixel_values is not None:
-                pixel_values_list.append(pixel_values)
-                image_sizes_list.append(image_sizes)
-            image_start_idx += num_of_images_in_this_sample
-            video_start_idx += num_of_videos_in_this_sample
-
-        if len(pixel_values_list) > 0:
-            image_inputs = {
-                "pixel_values": torch.cat(pixel_values_list),
-                "image_sizes": torch.cat(image_sizes_list),
-            }
-        else:
-            image_inputs = {}
-        video_inputs = {}
-        text_inputs = self.tokenizer(new_sample_list, **output_kwargs["text_kwargs"])
-        return BatchFeature(data={**text_inputs, **image_inputs, **video_inputs})
-
-    def get_number_tiles_based_on_image_size(
-        self, image_size: tuple, min_num: int, max_num: int, use_thumbnail: bool, tile_size: int
-    ) -> int:
-        """
-        Get the number of tiles based on the image size.
-        """
-        orig_height, orig_width = image_size
-        aspect_ratio = orig_width / orig_height
-        # calculate the existing image aspect ratio
-        target_ratios = {
-            (i, j)
-            for n in range(min_num, max_num + 1)
-            for i in range(1, n + 1)
-            for j in range(1, n + 1)
-            if i * j <= max_num and i * j >= min_num
-        }
-        target_ratios = sorted(target_ratios, key=lambda x: x[0] * x[1])
-
-        # find the closest aspect ratio to the target
-        target_aspect_ratio = self.image_processor.find_closest_aspect_ratio(
-            aspect_ratio, target_ratios, orig_width, orig_height, tile_size
-        )
-        tiles_num = target_aspect_ratio[0] * target_aspect_ratio[1]
-        if use_thumbnail and tiles_num > 1:
-            tiles_num += 1
-        return tiles_num
-
-    # Copied from transformers.models.clip.processing_clip.CLIPProcessor.batch_decode with CLIP->Llama
-    def batch_decode(self, *args, **kwargs):
-        """
-        This method forwards all its arguments to LlamaTokenizerFast's [`~PreTrainedTokenizer.batch_decode`]. Please
-        refer to the docstring of this method for more information.
-        """
-        return self.tokenizer.batch_decode(*args, **kwargs)
-
-    # Copied from transformers.models.clip.processing_clip.CLIPProcessor.decode with CLIP->Llama
-    def decode(self, *args, **kwargs):
-        """
-        This method forwards all its arguments to LlamaTokenizerFast's [`~PreTrainedTokenizer.decode`]. Please refer to
-        the docstring of this method for more information.
-        """
-        return self.tokenizer.decode(*args, **kwargs)
-
-    @property
-    # Copied from transformers.models.clip.processing_clip.CLIPProcessor.model_input_names
-    def model_input_names(self):
-        tokenizer_input_names = self.tokenizer.model_input_names
-        image_processor_input_names = self.image_processor.model_input_names
-        return list(dict.fromkeys(tokenizer_input_names + image_processor_input_names))
-
-    # override to save video-config in a separate config file
-    def save_pretrained(self, save_directory, **kwargs):
-        if os.path.isfile(save_directory):
-            raise ValueError(f"Provided path ({save_directory}) should be a directory, not a file")
-        os.makedirs(save_directory, exist_ok=True)
-
-        outputs = super().save_pretrained(save_directory, **kwargs)
-        return outputs
-
-    # override to load video-config from a separate config file
-    @classmethod
-    def from_pretrained(cls, pretrained_model_name_or_path, **kwargs):
-        processor = super().from_pretrained(pretrained_model_name_or_path, **kwargs)
-
-        # if return_unused_kwargs a tuple is returned where the second element is 'unused_kwargs'
-        if isinstance(processor, tuple):
-            processor = processor[0]
-        return processor
-
-    # Copy from https://github.com/QwenLM/Qwen2.5-VL/blob/main/qwen-vl-utils/src/qwen_vl_utils/vision_process.py
-    def process_vision_info(
-        self,
-        conversations: list[dict] | list[list[dict]],
-        return_video_kwargs: bool = False,
-    ) -> tuple[list[Image.Image] | None, list[torch.Tensor | list[Image.Image]] | None, dict | None]:
-        vision_infos = self.extract_vision_info(conversations)
-        ## Read images or videos
-        image_inputs = []
-        video_inputs = []
-        video_sample_fps_list = []
-        video_timestamps_list = []
-        for vision_info in vision_infos:
-            if "image" in vision_info or "image_url" in vision_info:
-                image_inputs.append(fetch_image(vision_info))
-            else:
-                raise ValueError("image, image_url or video should in content.")
-        if len(image_inputs) == 0:
-            image_inputs = None
-        if len(video_inputs) == 0:
-            video_inputs = None
-        if return_video_kwargs:
-            return (
-                image_inputs,
-                video_inputs,
-                {"fps": video_sample_fps_list, "timestamps": video_timestamps_list},
-            )
-        return image_inputs, video_inputs
-
-    def extract_vision_info(self, conversations: list[dict] | list[list[dict]]) -> list[dict]:
-        vision_infos = []
-        if isinstance(conversations[0], dict):
-            conversations = [conversations]
-        for conversation in conversations:
-            for message in conversation:
-                if isinstance(message["content"], list):
-                    for ele in message["content"]:
-                        if (
-                            "image" in ele
-                            or "image_url" in ele
-                            or "video" in ele
-                            or ele["type"] in ("image", "image_url", "video")
-                        ):
-                            vision_infos.append(ele)
-        return vision_infos
-
-
-__all__ = ["Eagle25VLProcessor"]

src/lerobot/policies/groot/groot_n1.py

@@ -1,380 +0,0 @@
-# SPDX-FileCopyrightText: Copyright (c) 2025 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
-# SPDX-License-Identifier: Apache-2.0
-#
-# 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 pathlib import Path
-from typing import TYPE_CHECKING, Any
-
-import numpy as np
-import torch
-import torch.nn as nn
-from huggingface_hub import snapshot_download
-from huggingface_hub.errors import HFValidationError, RepositoryNotFoundError
-
-from lerobot.utils.import_utils import _transformers_available
-
-# Conditional import for type checking and lazy loading
-if TYPE_CHECKING or _transformers_available:
-    from huggingface_hub.dataclasses import strict
-    from transformers import AutoConfig, AutoModel, PretrainedConfig, PreTrainedModel
-    from transformers.feature_extraction_utils import BatchFeature
-else:
-
-    def strict(cls):
-        return cls
-
-    AutoConfig = None
-    AutoModel = None
-    PretrainedConfig = object
-    PreTrainedModel = object
-    BatchFeature = None
-
-try:
-    import tree
-except ImportError:
-    tree = None
-
-from lerobot.utils.constants import ACTION, HF_LEROBOT_HOME
-
-from .action_head.flow_matching_action_head import (
-    FlowmatchingActionHead,
-    FlowmatchingActionHeadConfig,
-)
-from .utils import ensure_eagle_cache_ready
-
-DEFAULT_VENDOR_EAGLE_PATH = str((Path(__file__).resolve().parent / "eagle2_hg_model").resolve())
-DEFAULT_TOKENIZER_ASSETS_REPO = "lerobot/eagle2hg-processor-groot-n1p5"
-
-
-class EagleBackbone(nn.Module):
-    def __init__(
-        self,
-        tune_llm: bool = False,
-        tune_visual: bool = False,
-        select_layer: int = -1,
-        reproject_vision: bool = False,
-        use_flash_attention: bool = False,
-        load_bf16: bool = False,
-        eagle_path: str = DEFAULT_VENDOR_EAGLE_PATH,
-        tokenizer_assets_repo: str = DEFAULT_TOKENIZER_ASSETS_REPO,
-        project_to_dim: int = 1536,
-    ):
-        """
-        Args:
-            tune_llm: whether to tune the LLM model (default: True)
-            tune_visual: whether to tune the visual model (default: False)
-        """
-        super().__init__()
-        assert not reproject_vision, "Reproject vision is not implemented here, set to False"
-
-        # Prefer loading Eagle model config from the cache directory where vendor files were copied.
-        vendor_dir = DEFAULT_VENDOR_EAGLE_PATH
-        cache_dir = HF_LEROBOT_HOME / tokenizer_assets_repo
-        try:
-            ensure_eagle_cache_ready(vendor_dir, cache_dir, tokenizer_assets_repo)
-        except Exception as exc:  # nosec: B110
-            print(f"[GROOT] Warning: failed to prepare Eagle cache for backbone: {exc}")
-
-        config = AutoConfig.from_pretrained(str(cache_dir), trust_remote_code=True)
-        self.eagle_model = AutoModel.from_config(config, trust_remote_code=True)
-
-        if project_to_dim is not None:
-            self.eagle_linear = torch.nn.Linear(2048, project_to_dim)
-        else:
-            self.eagle_linear = torch.nn.Identity()
-
-        # needed since we don't use these layers. Also saves compute
-        while len(self.eagle_model.language_model.model.layers) > select_layer:
-            self.eagle_model.language_model.model.layers.pop(-1)
-
-        self.select_layer = select_layer
-        self.set_trainable_parameters(tune_llm, tune_visual)
-
-    def set_trainable_parameters(self, tune_llm: bool, tune_visual: bool):
-        self.tune_llm = tune_llm
-        self.tune_visual = tune_visual
-        for p in self.parameters():
-            p.requires_grad = True
-        if not tune_llm:
-            self.eagle_model.language_model.requires_grad_(False)
-        if not tune_visual:
-            self.eagle_model.vision_model.requires_grad_(False)
-            self.eagle_model.mlp1.requires_grad_(False)
-        print(f"Tune backbone llm: {self.tune_llm}")
-        print(f"Tune backbone visual: {self.tune_visual}")
-        # Check if any parameters are still trainable. If not, print a warning.
-        if not tune_llm and not tune_visual:
-            for name, p in self.named_parameters():
-                if p.requires_grad:
-                    print(f"Backbone trainable parameter: {name}")
-        if not any(p.requires_grad for p in self.parameters()):
-            print("Warning: No backbone trainable parameters found.")
-
-    def set_frozen_modules_to_eval_mode(self):
-        """
-        Huggingface will call model.train() at each training_step. To ensure
-        the expected behaviors for modules like dropout, batchnorm, etc., we
-        need to call model.eval() for the frozen modules.
-        """
-        if self.training:
-            if self.eagle_model.language_model and not self.tune_llm:
-                self.eagle_model.language_model.eval()
-            if self.eagle_model.vision_model and not self.tune_visual:
-                self.eagle_model.vision_model.eval()
-
-    def prepare_input(self, batch: dict) -> BatchFeature:
-        return BatchFeature(data=batch)
-
-    def forward_eagle(self, vl_input: BatchFeature) -> BatchFeature:
-        eagle_prefix = "eagle_"
-        eagle_input = {
-            k.removeprefix(eagle_prefix): v for k, v in vl_input.items() if k.startswith(eagle_prefix)
-        }
-        del eagle_input["image_sizes"]
-
-        eagle_output = self.eagle_model(**eagle_input, output_hidden_states=True, return_dict=True)
-        eagle_features = eagle_output.hidden_states[self.select_layer]
-
-        eagle_features = self.eagle_linear(eagle_features)
-        return eagle_features, eagle_input["attention_mask"]
-
-    def forward(self, vl_input: BatchFeature) -> BatchFeature:
-        self.set_frozen_modules_to_eval_mode()
-
-        eagle_embeds, eagle_mask = self.forward_eagle(vl_input)
-
-        # YL (TODO HACK): to resolve DDP issue when tune_visual=True
-        # Ensure all trainable parameters in vision_model are used in the forward pass for DDP compatibility
-        if self.training and self.tune_visual:
-            dummy_term = torch.tensor(
-                0.0, device=eagle_embeds.device, dtype=eagle_embeds.dtype, requires_grad=True
-            )
-            for param in self.eagle_model.vision_model.parameters():
-                if param.requires_grad:
-                    dummy_term = dummy_term + 0.0 * param.sum()
-            eagle_embeds = eagle_embeds + dummy_term
-
-        return BatchFeature(
-            data={"backbone_features": eagle_embeds, "backbone_attention_mask": eagle_mask}
-        )  # [B, T2, hidden_size]
-
-
-BACKBONE_FEATURE_KEY = "backbone_features"
-ACTION_KEY = "action_pred"
-LOSS_KEY = "loss"
-ERROR_MSG = "Error: unexpected input/output"
-N_COLOR_CHANNELS = 3
-
-
-# config
-@strict
-class GR00TN15Config(PretrainedConfig):
-    model_type = "gr00t_n1_5"
-
-    backbone_cfg: dict[str, Any] | None = None
-    action_head_cfg: dict[str, Any] | None = None
-    action_horizon: int = 0
-    action_dim: int = 0
-    compute_dtype: str = "float32"
-
-    def __post_init__(self, **kwargs):
-        self.backbone_cfg = {} if self.backbone_cfg is None else self.backbone_cfg
-        self.action_head_cfg = {} if self.action_head_cfg is None else self.action_head_cfg
-        super().__post_init__(**kwargs)
-
-
-# real model
-class GR00TN15(PreTrainedModel):
-    supports_gradient_checkpointing = True
-    config_class = GR00TN15Config
-    """
-    we expect the backbone output to have a key 'backbone_features' with shape (batch_size, n, hidden_size)
-    here n is variable and can be e.g. time, 1 or user specified
-    we expect the action head output to have a key 'action_pred' with shape (batch_size, time, action_dim) during inference time
-    we expect these to have type BatchFeature, and they can of course have many other user specified keys too
-    """
-
-    def __init__(
-        self,
-        config: GR00TN15Config,
-        local_model_path: str,
-    ):
-        assert isinstance(config.backbone_cfg, dict)
-        assert isinstance(config.action_head_cfg, dict)
-
-        super().__init__(config)
-        self.local_model_path = local_model_path
-
-        self.backbone = EagleBackbone(**config.backbone_cfg)
-        action_head_cfg = FlowmatchingActionHeadConfig(**config.action_head_cfg)
-        self.action_head = FlowmatchingActionHead(action_head_cfg)
-
-        self.action_horizon = config.action_horizon
-        self.action_dim = config.action_dim
-        self.compute_dtype = config.compute_dtype
-        self.post_init()
-
-    def validate_inputs(self, inputs):
-        # NOTE -- this should be handled internally by the model
-        # however, doing that will likely be breaking changes -- so we'll need to do it after the deadline
-
-        detected_error = False
-        error_msg = ERROR_MSG
-        if ACTION in inputs:
-            action = inputs[ACTION]
-            # In inference, action may be omitted or None; validate only when it's a tensor.
-            if action is None:
-                pass  # allow None during inference
-            elif isinstance(action, torch.Tensor):
-                shape_ok = (
-                    len(action.shape) == 3
-                    and action.shape[1] == self.action_horizon
-                    and action.shape[2] == self.action_dim
-                )
-                if not shape_ok:
-                    error_msg += f"\n{action.shape=}"
-                    detected_error = True
-            else:
-                # Unexpected non-tensor type provided for action
-                error_msg += f"\nInvalid type for action: {type(action)}"
-                detected_error = True
-
-        if "video" in inputs:
-            video = inputs["video"]
-            type_ok = isinstance(video, np.ndarray)
-            dtype_ok = video.dtype == np.uint8
-            shape_ok = len(video.shape) == 6 and video.shape[3] == N_COLOR_CHANNELS
-            if not type_ok:
-                error_msg += f"\n{type(video)=}"
-                detected_error = True
-            if not dtype_ok:
-                error_msg += f"\n{video.dtype=}"
-                detected_error = True
-            if not shape_ok:
-                error_msg += f"\n{video.shape=}"
-                detected_error = True
-
-        if detected_error:
-            raise ValueError(error_msg)
-
-    def validate_data(self, action_head_outputs, backbone_outputs, is_training):
-        fail_backbone = (
-            not isinstance(backbone_outputs, BatchFeature) or BACKBONE_FEATURE_KEY not in backbone_outputs
-        )
-
-        if fail_backbone:
-            error_msg = ERROR_MSG
-            error_msg += f"\n{isinstance(backbone_outputs, BatchFeature)=}"
-            error_msg += f"\n{BACKBONE_FEATURE_KEY in backbone_outputs=}"
-            error_msg += f"\n{backbone_outputs[BACKBONE_FEATURE_KEY].shape=}"
-            raise ValueError(error_msg)
-
-        fail_action_head = (not isinstance(action_head_outputs, BatchFeature)) or not (
-            (
-                LOSS_KEY in action_head_outputs and is_training
-            )  # there might not be an action prediction during training
-            or (
-                ACTION_KEY in action_head_outputs
-                and action_head_outputs[ACTION_KEY].shape[1] == self.action_horizon
-                and action_head_outputs[ACTION_KEY].shape[2] == self.action_dim
-            )
-        )
-
-        if fail_action_head:
-            error_msg = ERROR_MSG
-            error_msg += f"\n{isinstance(action_head_outputs, BatchFeature)=}"
-            error_msg += f"\n{LOSS_KEY in action_head_outputs=}"
-            error_msg += f"\n{action_head_outputs[ACTION_KEY].shape=}"
-            error_msg += f"\n{self.action_horizon=}"
-            error_msg += f"\n{self.action_dim=}"
-            raise ValueError(error_msg)
-
-    def forward(
-        self,
-        inputs: dict,
-    ) -> BatchFeature:
-        backbone_inputs, action_inputs = self.prepare_input(inputs)
-        backbone_outputs = self.backbone(backbone_inputs)
-        action_head_outputs = self.action_head(backbone_outputs, action_inputs)
-        self.validate_data(action_head_outputs, backbone_outputs, is_training=True)
-        return action_head_outputs
-
-    def get_action(
-        self,
-        inputs: dict,
-    ) -> BatchFeature:
-        backbone_inputs, action_inputs = self.prepare_input(inputs)
-        # Because the behavior of backbones remains the same for training and inference, we can use `forward` for backbones.
-        backbone_outputs = self.backbone(backbone_inputs)
-        action_head_outputs = self.action_head.get_action(backbone_outputs, action_inputs)
-        self.validate_data(action_head_outputs, backbone_outputs, is_training=False)
-        return action_head_outputs
-
-    def prepare_input(self, inputs) -> tuple[BatchFeature, BatchFeature]:
-        self.validate_inputs(inputs)
-        backbone_inputs = self.backbone.prepare_input(inputs)
-        action_inputs = self.action_head.prepare_input(inputs)
-
-        def to_device_with_maybe_dtype(x):
-            # Cast floating tensors to a memory-efficient compute dtype when requested.
-            # Rationale: Upcasting backbone activations to fp32 significantly increases VRAM.
-            # When compute_dtype is bfloat16, prefer bf16 for activations to match AMP behavior.
-            if not isinstance(x, torch.Tensor):
-                return x
-            if torch.is_floating_point(x):
-                if getattr(self, "compute_dtype", None) == "bfloat16":
-                    return x.to(self.device, dtype=torch.bfloat16)
-                # Fallback: preserve previous behavior if not using bf16 compute
-                return x.to(self.device, dtype=self.action_head.dtype)
-            # Non-floating tensors: move device only
-            return x.to(self.device)
-
-        backbone_inputs = tree.map_structure(to_device_with_maybe_dtype, backbone_inputs)
-        action_inputs = tree.map_structure(to_device_with_maybe_dtype, action_inputs)
-        return backbone_inputs, action_inputs
-
-    @classmethod
-    def from_pretrained(cls, pretrained_model_name_or_path: str, **kwargs):
-        tune_visual = kwargs.pop("tune_visual", True)
-        tune_llm = kwargs.pop("tune_llm", False)
-        tune_projector = kwargs.pop("tune_projector", True)
-        tune_diffusion_model = kwargs.pop("tune_diffusion_model", True)
-
-        print(f"Loading pretrained dual brain from {pretrained_model_name_or_path}")
-        print(f"Tune backbone vision tower: {tune_visual}")
-        print(f"Tune backbone LLM: {tune_llm}")
-        print(f"Tune action head projector: {tune_projector}")
-        print(f"Tune action head DiT: {tune_diffusion_model}")
-
-        # get the current model path being downloaded
-        try:
-            # NOTE(YL) This downloads the model to the local cache and returns the local path to the model
-            # saved in ~/.cache/huggingface/hub/
-            local_model_path = snapshot_download(pretrained_model_name_or_path, repo_type="model")
-            # HFValidationError, RepositoryNotFoundError
-        except (HFValidationError, RepositoryNotFoundError):
-            print(
-                f"Model not found or avail in the huggingface hub. Loading from local path: {pretrained_model_name_or_path}"
-            )
-            local_model_path = pretrained_model_name_or_path
-
-        pretrained_model = super().from_pretrained(
-            local_model_path, local_model_path=local_model_path, **kwargs
-        )
-
-        pretrained_model.backbone.set_trainable_parameters(tune_visual=tune_visual, tune_llm=tune_llm)
-        pretrained_model.action_head.set_trainable_parameters(
-            tune_projector=tune_projector, tune_diffusion_model=tune_diffusion_model
-        )
-        return pretrained_model

src/lerobot/policies/groot/groot_n1_7.py

@@ -0,0 +1,933 @@
+# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+# SPDX-License-Identifier: Apache-2.0
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+from __future__ import annotations
+
+import importlib
+import logging
+from contextlib import suppress
+from copy import deepcopy
+from typing import TYPE_CHECKING, Any
+
+import torch
+import torch.nn.functional as F  # noqa: N812
+from huggingface_hub import snapshot_download
+from huggingface_hub.errors import HFValidationError, RepositoryNotFoundError
+from torch import nn
+from torch.distributions import Beta
+
+from lerobot.utils.import_utils import _transformers_available, require_package
+
+from .action_head.cross_attention_dit import AlternateVLDiT, DiT, SelfAttentionTransformer
+from .configuration_groot import N1_7_DEFAULT_IMAGE_CROP_SIZE, N1_7_DEFAULT_IMAGE_TARGET_SIZE
+
+if TYPE_CHECKING or _transformers_available:
+    from transformers import (
+        AutoConfig,
+        AutoModel,
+        PretrainedConfig,
+        PreTrainedModel,
+        Qwen3VLConfig,
+        Qwen3VLForConditionalGeneration,
+    )
+    from transformers.feature_extraction_utils import BatchFeature
+else:
+    AutoConfig = None
+    AutoModel = None
+    PretrainedConfig = object
+    PreTrainedModel = object
+    BatchFeature = None
+    Qwen3VLConfig = None
+    Qwen3VLForConditionalGeneration = None
+
+try:
+    import tree
+except ImportError:
+    tree = None
+
+logger = logging.getLogger(__name__)
+
+
+GR00T_N1_7_DEFAULTS: dict[str, Any] = {
+    "model_dtype": "bfloat16",
+    "dtype": "bfloat16",
+    "model_name": "nvidia/Cosmos-Reason2-2B",
+    "backbone_model_type": "qwen",
+    "model_revision": None,
+    "tune_top_llm_layers": 0,
+    "backbone_embedding_dim": 2048,
+    "tune_llm": False,
+    "tune_visual": False,
+    "select_layer": 16,
+    "reproject_vision": False,
+    "use_flash_attention": False,
+    "load_bf16": False,
+    "backbone_trainable_params_fp32": True,
+    "image_crop_size": N1_7_DEFAULT_IMAGE_CROP_SIZE,
+    "image_target_size": N1_7_DEFAULT_IMAGE_TARGET_SIZE,
+    "shortest_image_edge": None,
+    "crop_fraction": None,
+    "random_rotation_angle": None,
+    "color_jitter_params": None,
+    "use_albumentations_transforms": True,
+    "extra_augmentation_config": None,
+    "formalize_language": True,
+    "apply_sincos_state_encoding": False,
+    "use_percentiles": True,
+    "use_relative_action": False,
+    "max_state_dim": 132,
+    "max_action_dim": 132,
+    "action_horizon": 40,
+    "hidden_size": 1024,
+    "input_embedding_dim": 1536,
+    "state_history_length": 1,
+    "add_pos_embed": True,
+    "attn_dropout": 0.2,
+    "use_vlln": True,
+    "max_seq_len": 1024,
+    "use_alternate_vl_dit": True,
+    "attend_text_every_n_blocks": 2,
+    "diffusion_model_cfg": {
+        "positional_embeddings": None,
+        "num_layers": 32,
+        "num_attention_heads": 32,
+        "attention_head_dim": 48,
+        "norm_type": "ada_norm",
+        "dropout": 0.2,
+        "final_dropout": True,
+        "output_dim": 1024,
+        "interleave_self_attention": True,
+    },
+    "vl_self_attention_cfg": {
+        "positional_embeddings": None,
+        "num_layers": 4,
+        "num_attention_heads": 32,
+        "attention_head_dim": 64,
+        "dropout": 0.2,
+        "final_dropout": True,
+    },
+    "num_inference_timesteps": 4,
+    "noise_beta_alpha": 1.5,
+    "noise_beta_beta": 1.0,
+    "noise_s": 0.999,
+    "num_timestep_buckets": 1000,
+    "tune_projector": True,
+    "tune_diffusion_model": True,
+    "tune_vlln": True,
+    "state_dropout_prob": 0.2,
+    "exclude_state": False,
+    "use_mean_std": False,
+    "max_num_embodiments": 32,
+    "rtc_ramp_rate": 6.0,
+}
+
+
+class GR00TN17Config(PretrainedConfig):
+    """Configuration for NVIDIA GR00T N1.7.
+
+    N1.7 uses the Cosmos-Reason2-2B / Qwen3-VL backbone and a multi-embodiment
+    flow-matching action head. This mirrors the public N1.7 checkpoint config
+    while keeping it local to LeRobot and independent from the external
+    Isaac-GR00T ``gr00t`` Python package.
+    """
+
+    model_type = "Gr00tN1d7"
+
+    _defaults = GR00T_N1_7_DEFAULTS
+
+    def __init__(self, **kwargs):
+        super().__init__(**kwargs)
+        for key, value in GR00T_N1_7_DEFAULTS.items():
+            setattr(self, key, deepcopy(kwargs.pop(key, value)))
+        for key, value in kwargs.items():
+            setattr(self, key, value)
+
+
+class CategorySpecificLinear(nn.Module):
+    """Linear layer with category-specific weights for multi-embodiment support."""
+
+    def __init__(self, num_categories: int, input_dim: int, hidden_dim: int):
+        super().__init__()
+        self.num_categories = num_categories
+        self.W = nn.Parameter(0.02 * torch.randn(num_categories, input_dim, hidden_dim))
+        self.b = nn.Parameter(torch.zeros(num_categories, hidden_dim))
+
+    def forward(self, x: torch.Tensor, cat_ids: torch.Tensor) -> torch.Tensor:
+        selected_w = self.W[cat_ids]
+        selected_b = self.b[cat_ids]
+        return torch.bmm(x, selected_w) + selected_b.unsqueeze(1)
+
+
+class CategorySpecificMLP(nn.Module):
+    """Two-layer MLP with category-specific weights."""
+
+    def __init__(self, num_categories: int, input_dim: int, hidden_dim: int, output_dim: int):
+        super().__init__()
+        self.layer1 = CategorySpecificLinear(num_categories, input_dim, hidden_dim)
+        self.layer2 = CategorySpecificLinear(num_categories, hidden_dim, output_dim)
+
+    def forward(self, x: torch.Tensor, cat_ids: torch.Tensor) -> torch.Tensor:
+        hidden = F.relu(self.layer1(x, cat_ids))
+        return self.layer2(hidden, cat_ids)
+
+
+class SinusoidalPositionalEncoding(nn.Module):
+    """Sinusoidal encoding of shape ``(B, T, D)`` for timestep tensors ``(B, T)``.
+
+    The frequency scalar is intentionally created on CPU and then broadcast with
+    the device-local arange result. That mirrors Isaac-GR00T's N1.7 timestep
+    embedding and avoids tiny dtype/device construction differences in parity
+    tests.
+    """
+
+    def __init__(self, embedding_dim: int):
+        super().__init__()
+        self.embedding_dim = embedding_dim
+
+    def forward(self, timesteps: torch.Tensor) -> torch.Tensor:
+        timesteps = timesteps.float()
+        half_dim = self.embedding_dim // 2
+        exponent = -torch.arange(half_dim, dtype=torch.float, device=timesteps.device) * (
+            torch.log(torch.tensor(10000.0)) / half_dim
+        )
+        freqs = timesteps.unsqueeze(-1) * exponent.exp()
+        return torch.cat([torch.sin(freqs), torch.cos(freqs)], dim=-1)
+
+
+def swish(x: torch.Tensor) -> torch.Tensor:
+    return x * torch.sigmoid(x)
+
+
+class MultiEmbodimentActionEncoder(nn.Module):
+    """Action encoder with category-specific projections and sinusoidal time encoding."""
+
+    def __init__(self, action_dim: int, hidden_size: int, num_embodiments: int):
+        super().__init__()
+        self.W1 = CategorySpecificLinear(num_embodiments, action_dim, hidden_size)
+        self.W2 = CategorySpecificLinear(num_embodiments, 2 * hidden_size, hidden_size)
+        self.W3 = CategorySpecificLinear(num_embodiments, hidden_size, hidden_size)
+        self.pos_encoding = SinusoidalPositionalEncoding(hidden_size)
+
+    def forward(self, actions: torch.Tensor, timesteps: torch.Tensor, cat_ids: torch.Tensor) -> torch.Tensor:
+        batch_size, horizon, _ = actions.shape
+        if timesteps.dim() != 1 or timesteps.shape[0] != batch_size:
+            raise ValueError("Expected `timesteps` to have shape (B,).")
+        timesteps = timesteps.unsqueeze(1).expand(-1, horizon)
+        action_emb = self.W1(actions, cat_ids)
+        time_emb = self.pos_encoding(timesteps).to(dtype=action_emb.dtype)
+        x = swish(self.W2(torch.cat([action_emb, time_emb], dim=-1), cat_ids))
+        return self.W3(x, cat_ids)
+
+
+class Qwen3Backbone(nn.Module):
+    """Cosmos-Reason2/Qwen3-VL backbone used by GR00T N1.7.
+
+    The public checkpoint stores the action head in the GR00T checkpoint but
+    uses a Hugging Face Qwen3-VL-compatible backbone interface. This wrapper
+    keeps the nested HF module layout compatible across transformer versions
+    and exposes the hidden states consumed by the action head.
+    """
+
+    def __init__(
+        self,
+        model_name: str = "nvidia/Cosmos-Reason2-2B",
+        tune_llm: bool = False,
+        tune_visual: bool = False,
+        select_layer: int = -1,
+        reproject_vision: bool = False,
+        use_flash_attention: bool = False,
+        load_bf16: bool = False,
+        tune_top_llm_layers: int = 0,
+        trainable_params_fp32: bool = False,
+        transformers_loading_kwargs: dict[str, Any] | None = None,
+        load_pretrained_weights: bool = True,
+    ):
+        require_package("transformers", extra="groot")
+        super().__init__()
+        transformers_loading_kwargs = transformers_loading_kwargs or {"trust_remote_code": True}
+
+        extra_kwargs: dict[str, Any] = {}
+        if use_flash_attention:
+            try:
+                import flash_attn  # noqa: F401
+
+                extra_kwargs["attn_implementation"] = "flash_attention_2"
+            except ImportError:
+                logger.warning("flash_attn is not installed. Falling back to SDPA attention.")
+                extra_kwargs["attn_implementation"] = "sdpa"
+        if load_bf16:
+            extra_kwargs["torch_dtype"] = torch.bfloat16
+
+        if load_pretrained_weights:
+            self.model = Qwen3VLForConditionalGeneration.from_pretrained(
+                model_name,
+                **extra_kwargs,
+                **transformers_loading_kwargs,
+            ).eval()
+        else:
+            self.model = self._from_backbone_config(
+                model_name=model_name,
+                model_kwargs=extra_kwargs,
+                config_kwargs=transformers_loading_kwargs,
+            ).eval()
+
+        while len(self.language_model.layers) > select_layer:
+            self.language_model.layers.pop(-1)
+
+        self.select_layer = select_layer
+        self.set_trainable_parameters(tune_llm, tune_visual, tune_top_llm_layers)
+        if load_bf16 and trainable_params_fp32:
+            for parameter in self.parameters():
+                if parameter.requires_grad:
+                    parameter.data = parameter.data.to(torch.float32)
+
+    def set_trainable_parameters(
+        self, tune_llm: bool, tune_visual: bool, tune_top_llm_layers: int = 0
+    ) -> None:
+        self.tune_llm = tune_llm
+        self.tune_visual = tune_visual
+        for parameter in self.parameters():
+            parameter.requires_grad = True
+        if not tune_llm:
+            self.language_model.requires_grad_(False)
+        if not tune_visual:
+            self.visual.requires_grad_(False)
+        if tune_top_llm_layers > 0:
+            for layer in self.language_model.layers[-tune_top_llm_layers:]:
+                for parameter in layer.parameters():
+                    parameter.requires_grad = True
+
+    def set_frozen_modules_to_eval_mode(self) -> None:
+        if self.training:
+            if self.language_model and not self.tune_llm:
+                self.language_model.eval()
+            if self.visual and not self.tune_visual:
+                self.visual.eval()
+
+    @property
+    def language_model(self) -> nn.Module:
+        return getattr(self.model, "model", self.model).language_model
+
+    @property
+    def visual(self) -> nn.Module:
+        return getattr(self.model, "model", self.model).visual
+
+    def _from_backbone_config(
+        self,
+        *,
+        model_name: str,
+        model_kwargs: dict[str, Any],
+        config_kwargs: dict[str, Any],
+    ) -> nn.Module:
+        if _is_cosmos_reason2_backbone(model_name):
+            backbone_config = _cosmos_reason2_qwen3_vl_config()
+        else:
+            backbone_config = AutoConfig.from_pretrained(model_name, **config_kwargs)
+        return Qwen3VLForConditionalGeneration._from_config(backbone_config, **model_kwargs)
+
+    def prepare_input(self, batch: dict[str, Any]) -> BatchFeature:
+        return BatchFeature(data=batch)
+
+    def _ensure_mm_token_type_ids(self, model_input: dict[str, torch.Tensor]) -> None:
+        if "mm_token_type_ids" in model_input:
+            return
+        if "image_grid_thw" not in model_input and "video_grid_thw" not in model_input:
+            return
+
+        input_ids = model_input.get("input_ids")
+        if input_ids is None:
+            return
+
+        mm_token_type_ids = torch.zeros(input_ids.shape, dtype=torch.int32, device=input_ids.device)
+        image_token_id = getattr(self.model.config, "image_token_id", None)
+        video_token_id = getattr(self.model.config, "video_token_id", None)
+        if image_token_id is not None:
+            mm_token_type_ids[input_ids == image_token_id] = 1
+        if video_token_id is not None:
+            mm_token_type_ids[input_ids == video_token_id] = 2
+
+        model_input["mm_token_type_ids"] = mm_token_type_ids
+
+    def _ensure_legacy_qwen3_position_ids(self, model_input: dict[str, torch.Tensor]) -> None:
+        """Restore the Qwen3-VL text position ids used by older Transformers releases.
+
+        Transformers 5.x computes 3-row multimodal RoPE ids for Qwen3-VL and then
+        drops text position ids before calling text-layer flash attention. GR00T
+        N1.7 was aligned against the older Transformers path, where a fourth text
+        position row is forwarded alongside the temporal/height/width rows. Adding
+        the row here preserves the newer multimodal position computation while
+        keeping flash attention on the legacy code path.
+        """
+
+        if "position_ids" in model_input:
+            return
+
+        qwen3_model = getattr(self.model, "model", self.model)
+        compute_3d_position_ids = getattr(qwen3_model, "compute_3d_position_ids", None)
+        if compute_3d_position_ids is None:
+            return
+
+        position_ids = compute_3d_position_ids(
+            input_ids=model_input.get("input_ids"),
+            image_grid_thw=model_input.get("image_grid_thw"),
+            video_grid_thw=model_input.get("video_grid_thw"),
+            inputs_embeds=None,
+            attention_mask=model_input.get("attention_mask"),
+            past_key_values=None,
+            mm_token_type_ids=model_input.get("mm_token_type_ids"),
+        )
+        if position_ids.ndim == 3 and position_ids.shape[0] == 3:
+            position_ids = torch.cat([position_ids[:1], position_ids], dim=0)
+
+        model_input["position_ids"] = position_ids
+
+    def _last_decoder_layer_output(self, model_input: dict[str, torch.Tensor]) -> torch.Tensor:
+        """Return the pre-final-norm decoder output consumed by the N1.7 action head.
+
+        Older Transformers releases exposed this tensor as ``hidden_states[-1]``.
+        Newer releases expose the post-final-norm tensor there instead. Capturing
+        the last decoder layer output directly keeps the N1.7 action head input
+        stable across Transformers versions.
+        """
+
+        captured: dict[str, torch.Tensor] = {}
+
+        def capture_output(_module: nn.Module, _inputs: tuple[Any, ...], output: Any) -> None:
+            if isinstance(output, torch.Tensor):
+                captured["features"] = output
+            elif isinstance(output, (tuple, list)) and output:
+                captured["features"] = output[0]
+            elif hasattr(output, "last_hidden_state"):
+                captured["features"] = output.last_hidden_state
+
+        hook = self.language_model.layers[-1].register_forward_hook(capture_output)
+        try:
+            outputs = self.model(**model_input, output_hidden_states=True)
+        finally:
+            hook.remove()
+
+        return captured.get("features", outputs.hidden_states[-1])
+
+    def forward(self, vl_input: BatchFeature) -> BatchFeature:
+        self.set_frozen_modules_to_eval_mode()
+        keys_to_use = ["input_ids", "attention_mask", "pixel_values", "image_grid_thw"]
+        optional_keys = ["mm_token_type_ids", "pixel_values_videos", "video_grid_thw"]
+        model_input = {key: vl_input[key] for key in keys_to_use}
+        model_input.update({key: vl_input[key] for key in optional_keys if key in vl_input})
+        self._ensure_mm_token_type_ids(model_input)
+        self._ensure_legacy_qwen3_position_ids(model_input)
+        features = self._last_decoder_layer_output(model_input)
+        image_mask = model_input["input_ids"] == self.model.config.image_token_id
+        attention_mask = model_input["attention_mask"] == 1
+        return BatchFeature(
+            data={
+                "backbone_features": features,
+                "backbone_attention_mask": attention_mask,
+                "image_mask": image_mask,
+            }
+        )
+
+
+class GR00TN17ActionHead(nn.Module):
+    supports_gradient_checkpointing = True
+
+    def __init__(self, config: GR00TN17Config):
+        require_package("diffusers", extra="groot")
+        super().__init__()
+        self.config = config
+        self.hidden_size = config.hidden_size
+        self.input_embedding_dim = config.input_embedding_dim
+
+        if config.use_alternate_vl_dit:
+            self.model = AlternateVLDiT(
+                **config.diffusion_model_cfg,
+                cross_attention_dim=config.backbone_embedding_dim,
+                attend_text_every_n_blocks=config.attend_text_every_n_blocks,
+            )
+        else:
+            self.model = DiT(
+                **config.diffusion_model_cfg,
+                cross_attention_dim=config.backbone_embedding_dim,
+            )
+
+        self.action_dim = config.max_action_dim
+        self.action_horizon = config.action_horizon
+        self.num_inference_timesteps = config.num_inference_timesteps
+        self.state_encoder = CategorySpecificMLP(
+            num_categories=config.max_num_embodiments,
+            input_dim=config.max_state_dim * config.state_history_length,
+            hidden_dim=self.hidden_size,
+            output_dim=self.input_embedding_dim,
+        )
+        self.action_encoder = MultiEmbodimentActionEncoder(
+            action_dim=self.action_dim,
+            hidden_size=self.input_embedding_dim,
+            num_embodiments=config.max_num_embodiments,
+        )
+        self.action_decoder = CategorySpecificMLP(
+            num_categories=config.max_num_embodiments,
+            input_dim=self.hidden_size,
+            hidden_dim=self.hidden_size,
+            output_dim=self.action_dim,
+        )
+        self.vlln = nn.LayerNorm(config.backbone_embedding_dim) if config.use_vlln else nn.Identity()
+        vl_self_attention_cfg = getattr(config, "vl_self_attention_cfg", None)
+        if vl_self_attention_cfg and vl_self_attention_cfg.get("num_layers", 0) > 0:
+            self.vl_self_attention = SelfAttentionTransformer(**vl_self_attention_cfg)
+        else:
+            self.vl_self_attention = nn.Identity()
+        if config.add_pos_embed:
+            self.position_embedding = nn.Embedding(config.max_seq_len, self.input_embedding_dim)
+            nn.init.normal_(self.position_embedding.weight, mean=0.0, std=0.02)
+        self.state_dropout_prob = config.state_dropout_prob
+        self._noise_beta_alpha = config.noise_beta_alpha
+        self._noise_beta_beta = config.noise_beta_beta
+        self._beta_dist = None
+        self.num_timestep_buckets = config.num_timestep_buckets
+        self.set_trainable_parameters(config.tune_projector, config.tune_diffusion_model, config.tune_vlln)
+
+    def set_trainable_parameters(
+        self, tune_projector: bool, tune_diffusion_model: bool, tune_vlln: bool
+    ) -> None:
+        self.tune_projector = tune_projector
+        self.tune_diffusion_model = tune_diffusion_model
+        self.tune_vlln = tune_vlln
+        for parameter in self.parameters():
+            parameter.requires_grad = True
+        if not tune_projector:
+            self.state_encoder.requires_grad_(False)
+            self.action_encoder.requires_grad_(False)
+            self.action_decoder.requires_grad_(False)
+            if self.config.add_pos_embed:
+                self.position_embedding.requires_grad_(False)
+        if not tune_diffusion_model:
+            self.model.requires_grad_(False)
+        if not tune_vlln:
+            self.vlln.requires_grad_(False)
+            self.vl_self_attention.requires_grad_(False)
+
+    def set_frozen_modules_to_eval_mode(self) -> None:
+        if self.training:
+            if not self.tune_projector:
+                self.state_encoder.eval()
+                self.action_encoder.eval()
+                self.action_decoder.eval()
+                if self.config.add_pos_embed:
+                    self.position_embedding.eval()
+            if not self.tune_diffusion_model:
+                self.model.eval()
+            if not self.tune_vlln:
+                self.vlln.eval()
+                self.vl_self_attention.eval()
+
+    def sample_time(self, batch_size: int, device: torch.device, dtype: torch.dtype) -> torch.Tensor:
+        if self._beta_dist is None:
+            beta_alpha = torch.tensor(self._noise_beta_alpha, device="cpu", dtype=torch.float32)
+            beta_beta = torch.tensor(self._noise_beta_beta, device="cpu", dtype=torch.float32)
+            self._beta_dist = Beta(beta_alpha, beta_beta, validate_args=False)
+        sample = self._beta_dist.sample([batch_size]).to(device, dtype=dtype)
+        return (1 - sample) * self.config.noise_s
+
+    def process_backbone_output(self, backbone_output: BatchFeature) -> BatchFeature:
+        backbone_features = self.vlln(backbone_output["backbone_features"])
+        backbone_output["backbone_features"] = self.vl_self_attention(backbone_features)
+        return backbone_output
+
+    def forward(self, backbone_output: BatchFeature, action_input: BatchFeature) -> BatchFeature:
+        self.set_frozen_modules_to_eval_mode()
+        backbone_output = self.process_backbone_output(backbone_output)
+        vl_embeds = backbone_output.backbone_features
+        device = vl_embeds.device
+        embodiment_id = action_input.embodiment_id
+
+        if action_input.state.shape[1] != self.config.state_history_length:
+            raise ValueError("state history length does not match GR00T N1.7 config.")
+        state = action_input.state.view(action_input.state.shape[0], 1, -1)
+        state_features = self.state_encoder(state, embodiment_id)
+
+        if self.training and self.state_dropout_prob > 0:
+            do_dropout = (
+                torch.rand(state_features.shape[0], device=state_features.device) < self.state_dropout_prob
+            )
+            state_features = state_features * (1 - do_dropout[:, None, None].to(dtype=state_features.dtype))
+
+        actions = action_input.action
+        noise = torch.randn(actions.shape, device=actions.device, dtype=actions.dtype)
+        t = self.sample_time(actions.shape[0], device=actions.device, dtype=actions.dtype)
+        t = t[:, None, None]
+        noisy_trajectory = (1 - t) * noise + t * actions
+        velocity = actions - noise
+        t_discretized = (t[:, 0, 0] * self.num_timestep_buckets).long()
+        action_features = self.action_encoder(noisy_trajectory, t_discretized, embodiment_id)
+
+        if self.config.add_pos_embed:
+            pos_ids = torch.arange(action_features.shape[1], dtype=torch.long, device=device)
+            action_features = action_features + self.position_embedding(pos_ids).unsqueeze(0)
+
+        sa_embs = torch.cat((state_features, action_features), dim=1)
+        if self.config.use_alternate_vl_dit:
+            model_output, _ = self.model(
+                hidden_states=sa_embs,
+                encoder_hidden_states=vl_embeds,
+                encoder_attention_mask=backbone_output.backbone_attention_mask,
+                timestep=t_discretized,
+                return_all_hidden_states=True,
+                image_mask=backbone_output.image_mask,
+                backbone_attention_mask=backbone_output.backbone_attention_mask,
+            )
+        else:
+            model_output, _ = self.model(
+                hidden_states=sa_embs,
+                encoder_hidden_states=vl_embeds,
+                encoder_attention_mask=backbone_output.backbone_attention_mask,
+                timestep=t_discretized,
+                return_all_hidden_states=True,
+            )
+
+        pred = self.action_decoder(model_output, embodiment_id)
+        pred_actions = pred[:, -actions.shape[1] :]
+        action_mask = action_input.action_mask.to(dtype=pred_actions.dtype)
+        action_loss = F.mse_loss(pred_actions, velocity, reduction="none") * action_mask
+        loss = action_loss.sum() / (action_mask.sum() + 1e-6)
+        return BatchFeature(
+            data={
+                "loss": loss,
+                "action_loss": action_loss,
+                "action_mask": action_mask,
+                "backbone_features": vl_embeds,
+                "state_features": state_features,
+            }
+        )
+
+    def _encode_features(self, backbone_output: BatchFeature, action_input: BatchFeature) -> BatchFeature:
+        backbone_output = self.process_backbone_output(backbone_output)
+        state = action_input.state
+        if state.shape[1] != self.config.state_history_length:
+            raise ValueError("state history length does not match GR00T N1.7 config.")
+        state = state.view(state.shape[0], 1, -1)
+        state_features = self.state_encoder(state, action_input.embodiment_id)
+        return BatchFeature(
+            data={"backbone_features": backbone_output.backbone_features, "state_features": state_features}
+        )
+
+    @torch.no_grad()
+    def get_action_with_features(
+        self,
+        backbone_features: torch.Tensor,
+        state_features: torch.Tensor,
+        embodiment_id: torch.Tensor,
+        backbone_output: BatchFeature,
+        action_input: BatchFeature,
+        options: dict[str, Any] | None = None,
+    ) -> BatchFeature:
+        vl_embeds = backbone_features
+        batch_size = vl_embeds.shape[0]
+        device = vl_embeds.device
+        actions = torch.randn(
+            size=(batch_size, self.config.action_horizon, self.action_dim),
+            dtype=vl_embeds.dtype,
+            device=device,
+        )
+        dt = 1.0 / self.num_inference_timesteps
+        vel_strength = torch.ones_like(actions)
+
+        if "action" in action_input:
+            if options is None:
+                raise ValueError("RTC options are required when action is provided to get_action.")
+            action_horizon_before_padding = options["action_horizon"]
+            actions[:, : options["rtc_overlap_steps"], :] = action_input["action"][
+                :,
+                action_horizon_before_padding - options["rtc_overlap_steps"] : action_horizon_before_padding,
+                :,
+            ]
+            vel_strength[:, : options["rtc_frozen_steps"], :] = 0.0
+            intermediate_steps = options["rtc_overlap_steps"] - options["rtc_frozen_steps"]
+            t = torch.linspace(0.0, 1.0, intermediate_steps + 2, device=device)
+            ramp = 1 - torch.exp(-options["rtc_ramp_rate"] * t)
+            ramp = ramp / ramp[-1].clamp_min(1e-8)
+            vel_strength[:, options["rtc_frozen_steps"] : options["rtc_overlap_steps"], :] = ramp[1:-1][
+                None, :, None
+            ].to(device)
+
+        for t_step in range(self.num_inference_timesteps):
+            t_cont = t_step / float(self.num_inference_timesteps)
+            t_discretized = int(t_cont * self.num_timestep_buckets)
+            timesteps_tensor = torch.full(size=(batch_size,), fill_value=t_discretized, device=device)
+            action_features = self.action_encoder(actions, timesteps_tensor, embodiment_id)
+            if self.config.add_pos_embed:
+                pos_ids = torch.arange(action_features.shape[1], dtype=torch.long, device=device)
+                action_features = action_features + self.position_embedding(pos_ids).unsqueeze(0)
+            sa_embs = torch.cat((state_features, action_features), dim=1)
+
+            if self.config.use_alternate_vl_dit:
+                model_output = self.model(
+                    hidden_states=sa_embs,
+                    encoder_hidden_states=vl_embeds,
+                    timestep=timesteps_tensor,
+                    image_mask=backbone_output.image_mask,
+                    backbone_attention_mask=backbone_output.backbone_attention_mask,
+                )
+            else:
+                model_output = self.model(
+                    hidden_states=sa_embs,
+                    encoder_hidden_states=vl_embeds,
+                    timestep=timesteps_tensor,
+                )
+            pred = self.action_decoder(model_output, embodiment_id)
+            actions = actions + dt * pred[:, -self.action_horizon :] * vel_strength
+
+        return BatchFeature(
+            data={
+                "action_pred": actions,
+                "backbone_features": vl_embeds,
+                "state_features": state_features,
+            }
+        )
+
+    @torch.no_grad()
+    def get_action(
+        self,
+        backbone_output: BatchFeature,
+        action_input: BatchFeature,
+        options: dict[str, Any] | None = None,
+    ) -> BatchFeature:
+        features = self._encode_features(backbone_output, action_input)
+        return self.get_action_with_features(
+            backbone_features=features.backbone_features,
+            state_features=features.state_features,
+            embodiment_id=action_input.embodiment_id,
+            backbone_output=backbone_output,
+            action_input=action_input,
+            options=options,
+        )
+
+    @property
+    def device(self) -> torch.device:
+        return next(iter(self.parameters())).device
+
+    @property
+    def dtype(self) -> torch.dtype:
+        return next(iter(self.parameters())).dtype
+
+    def prepare_input(self, batch: dict[str, Any]) -> BatchFeature:
+        return BatchFeature(data=batch)
+
+
+def _is_cosmos_reason2_backbone(model_name: str) -> bool:
+    return str(model_name).rstrip("/") == "nvidia/Cosmos-Reason2-2B"
+
+
+def _cosmos_reason2_qwen3_vl_config() -> PretrainedConfig:
+    return Qwen3VLConfig(
+        image_token_id=151655,
+        video_token_id=151656,
+        vision_start_token_id=151652,
+        vision_end_token_id=151653,
+        tie_word_embeddings=True,
+        text_config={
+            "attention_bias": False,
+            "attention_dropout": 0.0,
+            "bos_token_id": 151643,
+            "dtype": "bfloat16",
+            "eos_token_id": 151645,
+            "head_dim": 128,
+            "hidden_act": "silu",
+            "hidden_size": 2048,
+            "initializer_range": 0.02,
+            "intermediate_size": 6144,
+            "max_position_embeddings": 262144,
+            "model_type": "qwen3_vl_text",
+            "num_attention_heads": 16,
+            "num_hidden_layers": 28,
+            "num_key_value_heads": 8,
+            "rms_norm_eps": 1e-6,
+            "rope_scaling": {
+                "mrope_interleaved": True,
+                "mrope_section": [24, 20, 20],
+                "rope_type": "default",
+            },
+            "rope_theta": 5000000,
+            "tie_word_embeddings": True,
+            "use_cache": True,
+            "vocab_size": 151936,
+        },
+        vision_config={
+            "deepstack_visual_indexes": [5, 11, 17],
+            "depth": 24,
+            "hidden_act": "gelu_pytorch_tanh",
+            "hidden_size": 1024,
+            "in_channels": 3,
+            "initializer_range": 0.02,
+            "intermediate_size": 4096,
+            "model_type": "qwen3_vl",
+            "num_heads": 16,
+            "num_position_embeddings": 2304,
+            "out_hidden_size": 2048,
+            "patch_size": 16,
+            "spatial_merge_size": 2,
+            "temporal_patch_size": 2,
+        },
+    )
+
+
+def get_backbone_cls(config: GR00TN17Config):
+    if "nvidia/Cosmos-Reason2" in config.model_name or "Qwen/Qwen3-VL" in config.model_name:
+        return Qwen3Backbone
+    if config.backbone_model_type == "qwen":
+        logger.warning(
+            "Unrecognized GR00T N1.7 backbone model name '%s'; assuming a Qwen3-VL-compatible "
+            "backbone because backbone_model_type='qwen'.",
+            config.model_name,
+        )
+        return Qwen3Backbone
+    raise ValueError(f"Unsupported GR00T N1.7 backbone model: {config.model_name}")
+
+
+class GR00TN17(PreTrainedModel):
+    """GR00T N1.7 model with a Cosmos-Reason2/Qwen3-VL backbone."""
+
+    config_class = GR00TN17Config
+    supports_gradient_checkpointing = True
+
+    def __init__(
+        self,
+        config: GR00TN17Config,
+        transformers_loading_kwargs: dict[str, Any] | None = None,
+        load_backbone_weights: bool = True,
+    ):
+        _register_with_transformers()
+        super().__init__(config)
+        transformers_loading_kwargs = transformers_loading_kwargs or {"trust_remote_code": True}
+        self.config = config
+        backbone_cls = get_backbone_cls(config)
+        self.backbone = backbone_cls(
+            model_name=config.model_name,
+            tune_llm=config.tune_llm,
+            tune_visual=config.tune_visual,
+            select_layer=config.select_layer,
+            reproject_vision=config.reproject_vision,
+            use_flash_attention=config.use_flash_attention,
+            load_bf16=config.load_bf16,
+            tune_top_llm_layers=config.tune_top_llm_layers,
+            trainable_params_fp32=config.backbone_trainable_params_fp32,
+            transformers_loading_kwargs=transformers_loading_kwargs,
+            load_pretrained_weights=load_backbone_weights,
+        )
+        self.action_head = GR00TN17ActionHead(config)
+        self.post_init()
+
+    def prepare_input(self, inputs: dict[str, Any]) -> tuple[BatchFeature, BatchFeature]:
+        global tree
+        if tree is None:
+            require_package("dm-tree", extra="groot", import_name="tree")
+            tree = importlib.import_module("tree")
+        backbone_inputs = self.backbone.prepare_input(inputs)
+        action_inputs = self.action_head.prepare_input(inputs)
+
+        def to_device_with_dtype(x):
+            if not isinstance(x, torch.Tensor):
+                return x
+            if torch.is_floating_point(x):
+                return x.to(self.device, dtype=self.dtype)
+            return x.to(self.device)
+
+        return (
+            tree.map_structure(to_device_with_dtype, backbone_inputs),
+            tree.map_structure(to_device_with_dtype, action_inputs),
+        )
+
+    def forward(self, inputs: dict[str, Any]) -> BatchFeature:
+        backbone_inputs, action_inputs = self.prepare_input(inputs)
+        backbone_outputs = self.backbone(backbone_inputs)
+        return self.action_head(backbone_outputs, action_inputs)
+
+    def get_action(self, inputs: dict[str, Any], options: dict[str, Any] | None = None) -> BatchFeature:
+        backbone_inputs, action_inputs = self.prepare_input(inputs)
+        backbone_outputs = self.backbone(backbone_inputs)
+        return self.action_head.get_action(backbone_outputs, action_inputs, options)
+
+    @property
+    def device(self) -> torch.device:
+        return next(iter(self.parameters())).device
+
+    @property
+    def dtype(self) -> torch.dtype:
+        return next(iter(self.parameters())).dtype
+
+    @classmethod
+    def from_pretrained(cls, pretrained_model_name_or_path: str, **kwargs):
+        tune_visual = kwargs.pop("tune_visual", True)
+        tune_llm = kwargs.pop("tune_llm", False)
+        tune_projector = kwargs.pop("tune_projector", True)
+        tune_diffusion_model = kwargs.pop("tune_diffusion_model", True)
+        tune_vlln = kwargs.pop("tune_vlln", True)
+        transformers_loading_kwargs = kwargs.pop("transformers_loading_kwargs", None) or {
+            "trust_remote_code": True
+        }
+        load_backbone_weights = kwargs.pop("load_backbone_weights", False)
+        for key in ("cache_dir", "local_files_only", "token"):
+            if key in kwargs:
+                transformers_loading_kwargs.setdefault(key, kwargs[key])
+
+        try:
+            local_model_path = snapshot_download(
+                pretrained_model_name_or_path,
+                repo_type="model",
+                revision=kwargs.get("revision"),
+                cache_dir=kwargs.get("cache_dir"),
+                local_files_only=kwargs.get("local_files_only", False),
+                token=kwargs.get("token"),
+            )
+        except (HFValidationError, RepositoryNotFoundError):
+            local_model_path = pretrained_model_name_or_path
+
+        pretrained_model = super().from_pretrained(
+            local_model_path,
+            transformers_loading_kwargs=transformers_loading_kwargs,
+            load_backbone_weights=load_backbone_weights,
+            **kwargs,
+        )
+        pretrained_model.backbone.set_trainable_parameters(
+            tune_visual=tune_visual,
+            tune_llm=tune_llm,
+            tune_top_llm_layers=pretrained_model.config.tune_top_llm_layers,
+        )
+        pretrained_model.action_head.set_trainable_parameters(
+            tune_projector=tune_projector,
+            tune_diffusion_model=tune_diffusion_model,
+            tune_vlln=tune_vlln,
+        )
+        return pretrained_model
+
+
+def _register_with_transformers() -> None:
+    """Register GR00T N1.7 with transformers' Auto* factories.
+
+    Idempotent: ``register(..., exist_ok=True)`` makes repeat calls no-ops (with a fallback that
+    suppresses the already-registered error on transformers builds whose ``register()`` predates
+    ``exist_ok``), so no run-once guard is needed.
+    """
+    if AutoConfig is None or AutoModel is None:
+        return
+    try:
+        AutoConfig.register(GR00TN17Config.model_type, GR00TN17Config, exist_ok=True)
+    except TypeError:
+        with suppress(ValueError):
+            AutoConfig.register(GR00TN17Config.model_type, GR00TN17Config)
+    try:
+        AutoModel.register(GR00TN17Config, GR00TN17, exist_ok=True)
+    except TypeError:
+        with suppress(ValueError):
+            AutoModel.register(GR00TN17Config, GR00TN17)

src/lerobot/policies/groot/modeling_groot.py

@@ -17,28 +17,22 @@
 """
 Groot Policy Wrapper for LeRobot Integration
 
-Minimal integration that delegates to Isaac-GR00T components where possible
-without porting their code. The intent is to:
-
-- Download and load the pretrained GR00T model via GR00TN15.from_pretrained
-- Optionally align action horizon similar to gr00t_finetune.py
-- Expose predict_action via GR00T model.get_action
-- Provide a training forward that can call the GR00T model forward if batch
-  structure matches.
-
-Notes:
-- Dataset loading and full training orchestration is handled by Isaac-GR00T
-  TrainRunner in their codebase. If you want to invoke that flow end-to-end
-  from LeRobot, see `GrootPolicy.finetune_with_groot_runner` below.
+Minimal integration that delegates to Isaac-GR00T N1.7 components where
+possible without porting their code. Dataset loading and training
+orchestration are handled by LeRobot's standard training stack.
 """
 
 import builtins
+import logging
 import os
 from collections import deque
 from pathlib import Path
 from typing import TypeVar
 
 import torch
+from huggingface_hub import hf_hub_download
+from huggingface_hub.constants import SAFETENSORS_SINGLE_FILE
+from huggingface_hub.errors import HfHubHTTPError
 from torch import Tensor
 
 from lerobot.configs import FeatureType, PolicyFeature
@@ -46,8 +40,19 @@ from lerobot.utils.constants import ACTION, OBS_IMAGES
 from lerobot.utils.import_utils import require_package
 
 from ..pretrained import PreTrainedPolicy
-from .configuration_groot import GrootConfig
-from .groot_n1 import GR00TN15
+from ..utils import get_device_from_parameters
+from .configuration_groot import (
+    GROOT_N1_5,
+    GROOT_N1_5_REMOVAL_GUIDANCE,
+    GROOT_N1_7,
+    GrootConfig,
+    infer_groot_model_version,
+    infer_groot_n1_7_action_execution_horizon,
+    infer_groot_n1_7_action_horizon,
+)
+from .groot_n1_7 import GR00TN17
+
+logger = logging.getLogger(__name__)
 
 T = TypeVar("T", bound="GrootPolicy")
 
@@ -67,37 +72,38 @@ class GrootPolicy(PreTrainedPolicy):
 
         # Initialize GR00T model using ported components
         self._groot_model = self._create_groot_model()
+        self._action_queue_steps = self._resolve_action_queue_steps()
 
         self.reset()
 
     def _create_groot_model(self):
-        """Create and initialize the GR00T model using Isaac-GR00T API.
+        """Create and initialize the GR00T N1.7 model using the ported components."""
+        model_kwargs = {
+            "pretrained_model_name_or_path": self.config.base_model_path,
+            "tune_llm": self.config.tune_llm,
+            "tune_visual": self.config.tune_visual,
+            "tune_projector": self.config.tune_projector,
+            "tune_diffusion_model": self.config.tune_diffusion_model,
+            # Forwarded as a GR00TN17Config override; read back by set_trainable_parameters.
+            "tune_top_llm_layers": self.config.tune_top_llm_layers,
+            "use_flash_attention": self.config.use_flash_attention,
+        }
+        # Surface the inference-time knobs onto the model config only when the user set them; None
+        # leaves the value baked into the checkpoint untouched.
+        if self.config.num_inference_timesteps is not None:
+            model_kwargs["num_inference_timesteps"] = self.config.num_inference_timesteps
+        if self.config.rtc_ramp_rate is not None:
+            model_kwargs["rtc_ramp_rate"] = self.config.rtc_ramp_rate
 
-        This is only called when creating a NEW policy (not when loading from checkpoint).
-
-        Steps (delegating to Isaac-GR00T):
-        1) Download and load pretrained model via GR00TN15.from_pretrained
-        2) Align action horizon with data_config if provided
-        """
-        # Handle Flash Attention compatibility issues
-        self._handle_flash_attention_compatibility()
-
-        model = GR00TN15.from_pretrained(
-            pretrained_model_name_or_path=self.config.base_model_path,
-            tune_llm=self.config.tune_llm,
-            tune_visual=self.config.tune_visual,
-            tune_projector=self.config.tune_projector,
-            tune_diffusion_model=self.config.tune_diffusion_model,
+        return GR00TN17.from_pretrained(
+            **model_kwargs,
+            tune_vlln=self.config.tune_vlln,
+            transformers_loading_kwargs={"trust_remote_code": True},
         )
 
-        model.compute_dtype = "bfloat16" if self.config.use_bf16 else model.compute_dtype
-        model.config.compute_dtype = model.compute_dtype
-
-        return model
-
     def reset(self):
         """Reset policy state when environment resets."""
-        self._action_queue = deque([], maxlen=self.config.n_action_steps)
+        self._action_queue = deque([], maxlen=self._action_queue_steps)
 
     @classmethod
     def from_pretrained(
@@ -118,7 +124,7 @@ class GrootPolicy(PreTrainedPolicy):
         """Load Groot policy from pretrained model.
 
         Handles two cases:
-        1. Base GR00T models (e.g., 'nvidia/GR00T-N1.5-3B') - loads the raw model
+        1. Base GR00T N1.7 models - loads the raw model
         2. Fine-tuned LeRobot checkpoints - loads config and weights from safetensors
 
         Args:
@@ -137,13 +143,11 @@ class GrootPolicy(PreTrainedPolicy):
         Returns:
             Initialized GrootPolicy instance with loaded model
         """
-        from huggingface_hub import hf_hub_download
-        from huggingface_hub.constants import SAFETENSORS_SINGLE_FILE
-        from huggingface_hub.errors import HfHubHTTPError
-
-        print(
-            "The Groot policy is a wrapper around Nvidia's GR00T N1.5 model.\n"
-            f"Loading pretrained model from: {pretrained_name_or_path}"
+        requested_version = infer_groot_model_version(str(pretrained_name_or_path)) or GROOT_N1_7
+        logger.info(
+            "The Groot policy wraps NVIDIA's GR00T %s model. Loading pretrained model from: %s",
+            requested_version,
+            pretrained_name_or_path,
         )
 
         model_id = str(pretrained_name_or_path)
@@ -174,7 +178,7 @@ class GrootPolicy(PreTrainedPolicy):
 
         if is_finetuned_checkpoint:
             # This is a fine-tuned LeRobot checkpoint - use parent class loading
-            print("Detected fine-tuned LeRobot checkpoint, loading with state dict...")
+            logger.info("Detected fine-tuned LeRobot checkpoint, loading with state dict...")
             return super().from_pretrained(
                 pretrained_name_or_path=pretrained_name_or_path,
                 config=config,
@@ -190,11 +194,13 @@ class GrootPolicy(PreTrainedPolicy):
             )
 
         # This is a base GR00T model - load it fresh
-        print("Detected base GR00T model, loading from HuggingFace...")
+        logger.info("Detected base GR00T model, loading from HuggingFace...")
 
         if config is None:
             # Create default config with the pretrained path
-            config = GrootConfig(base_model_path=str(pretrained_name_or_path))
+            config = GrootConfig(
+                base_model_path=str(pretrained_name_or_path),
+            )
 
             # Add minimal visual feature required for validation
             # validate_features() will automatically add state and action features
@@ -215,6 +221,15 @@ class GrootPolicy(PreTrainedPolicy):
             if hasattr(config, key):
                 setattr(config, key, value)
 
+        inferred_version = infer_groot_model_version(config.base_model_path)
+        if inferred_version is not None and inferred_version != GROOT_N1_7:
+            message = (
+                f"GR00T model_version '{GROOT_N1_7}' does not match base_model_path "
+                f"'{config.base_model_path}', which looks like '{inferred_version}'."
+            )
+            if inferred_version == GROOT_N1_5:
+                message = f"{message} {GROOT_N1_5_REMOVAL_GUIDANCE}"
+            raise ValueError(message)
         # Create a fresh policy instance - this will automatically load the GR00T model
         # in __init__ via _create_groot_model()
         policy = cls(config)
@@ -225,21 +240,160 @@ class GrootPolicy(PreTrainedPolicy):
     def get_optim_params(self) -> dict:
         return self.parameters()
 
+    def _resolve_action_queue_steps(self) -> int:
+        n_action_steps = int(self.config.n_action_steps)
+        checkpoint_action_horizon = infer_groot_n1_7_action_horizon(
+            self.config.base_model_path,
+            self.config.embodiment_tag,
+        )
+        execution_horizon = infer_groot_n1_7_action_execution_horizon(
+            self.config.base_model_path,
+            self.config.embodiment_tag,
+        )
+        horizons = [n_action_steps]
+        if checkpoint_action_horizon is not None:
+            horizons.append(checkpoint_action_horizon)
+        if execution_horizon is not None:
+            horizons.append(execution_horizon)
+        return min(horizons)
+
+    def _resolve_prediction_horizon(self, actions: Tensor) -> int:
+        """Return the policy-facing action horizon for a native GR00T prediction."""
+
+        horizons = [actions.shape[1]]
+        checkpoint_action_horizon = infer_groot_n1_7_action_horizon(
+            self.config.base_model_path,
+            self.config.embodiment_tag,
+        )
+        if checkpoint_action_horizon is not None:
+            horizons.append(checkpoint_action_horizon)
+
+        for horizon in (self.config.chunk_size, self.config.n_action_steps):
+            horizon = int(horizon)
+            if horizon > 0:
+                horizons.append(horizon)
+
+        return max(1, min(horizons))
+
+    def _filter_groot_inputs(self, batch: dict[str, Tensor], *, include_action: bool) -> dict[str, Tensor]:
+        allowed_base = {"state", "state_mask", "embodiment_id"}
+        if include_action:
+            allowed_base.update({"action", "action_mask"})
+
+        allowed_base.update(
+            {
+                "input_ids",
+                "attention_mask",
+                "pixel_values",
+                "image_grid_thw",
+                "mm_token_type_ids",
+                "pixel_values_videos",
+                "video_grid_thw",
+            }
+        )
+        allowed_base.add("action_mask")
+
+        return {
+            k: v for k, v in batch.items() if k in allowed_base and not (k.startswith("next.") or k == "info")
+        }
+
+    def _prepare_n1_7_rtc_inputs(
+        self,
+        inputs: dict[str, Tensor],
+        *,
+        inference_delay: object,
+        prev_chunk_left_over: object,
+    ) -> tuple[dict[str, Tensor], dict[str, object] | None]:
+        if prev_chunk_left_over is None:
+            return inputs, None
+        if not isinstance(prev_chunk_left_over, torch.Tensor):
+            raise TypeError("prev_chunk_left_over must be a torch.Tensor for GR00T N1.7 RTC.")
+        if prev_chunk_left_over.numel() == 0:
+            return inputs, None
+
+        prev_actions = prev_chunk_left_over
+        if prev_actions.ndim == 2:
+            prev_actions = prev_actions.unsqueeze(0)
+        elif prev_actions.ndim != 3:
+            raise ValueError("prev_chunk_left_over must have shape (T, A) or (B, T, A) for GR00T N1.7 RTC.")
+
+        state = inputs.get("state")
+        if state is None:
+            raise ValueError("GR00T N1.7 RTC requires `state` in the preprocessed batch.")
+        batch_size = state.shape[0]
+        if prev_actions.shape[0] == 1 and batch_size > 1:
+            prev_actions = prev_actions.expand(batch_size, -1, -1).clone()
+        elif prev_actions.shape[0] != batch_size:
+            raise ValueError("prev_chunk_left_over batch size must match the current GR00T N1.7 batch size.")
+
+        # The generic LeRobot RTC engine pads short leftovers with exact zero
+        # rows for fixed-shape policy calls. Native GR00T N1.7 RTC treats every
+        # provided prefix row as a real action constraint, so strip that padding
+        # before constructing the native overlap options.
+        valid_prefix_rows = prev_actions.detach().abs().sum(dim=(0, 2)) > 0
+        if valid_prefix_rows.any():
+            valid_prefix_steps = int(valid_prefix_rows.nonzero()[-1].item()) + 1
+            prev_actions = prev_actions[:, :valid_prefix_steps, :]
+        else:
+            return inputs, None
+
+        model_action_horizon = int(
+            getattr(self._groot_model.config, "action_horizon", self.config.chunk_size)
+        )
+        max_action_dim = int(getattr(self._groot_model.config, "max_action_dim", self.config.max_action_dim))
+        if prev_actions.shape[1] > model_action_horizon:
+            prev_actions = prev_actions[:, -model_action_horizon:, :]
+
+        action_horizon = int(prev_actions.shape[1])
+        if action_horizon <= 0:
+            return inputs, None
+
+        if prev_actions.shape[2] > max_action_dim:
+            prev_actions = prev_actions[:, :, :max_action_dim]
+        elif prev_actions.shape[2] < max_action_dim:
+            pad = torch.zeros(
+                prev_actions.shape[0],
+                prev_actions.shape[1],
+                max_action_dim - prev_actions.shape[2],
+                dtype=prev_actions.dtype,
+                device=prev_actions.device,
+            )
+            prev_actions = torch.cat([prev_actions, pad], dim=2)
+
+        prev_actions = prev_actions.to(device=state.device, dtype=state.dtype)
+
+        rtc_config = getattr(self.config, "rtc_config", None)
+        execution_horizon = int(getattr(rtc_config, "execution_horizon", action_horizon))
+        overlap_steps = max(0, min(action_horizon, execution_horizon))
+        if overlap_steps == 0:
+            return inputs, None
+
+        try:
+            frozen_steps = int(inference_delay or 0)
+        except (TypeError, ValueError):
+            frozen_steps = 0
+        frozen_steps = max(0, min(frozen_steps, overlap_steps))
+
+        options = {
+            "action_horizon": action_horizon,
+            "rtc_overlap_steps": overlap_steps,
+            "rtc_frozen_steps": frozen_steps,
+            "rtc_ramp_rate": float(getattr(self._groot_model.config, "rtc_ramp_rate", 6.0)),
+        }
+
+        inputs = dict(inputs)
+        inputs["action"] = prev_actions
+        return inputs, options
+
     def forward(self, batch: dict[str, Tensor]) -> tuple[Tensor, dict]:
         """Training forward pass.
 
         Delegates to Isaac-GR00T model.forward when inputs are compatible.
         """
-        # Build a clean input dict for GR00T: keep only tensors GR00T consumes
-        allowed_base = {"state", "state_mask", "action", "action_mask", "embodiment_id"}
-        groot_inputs = {
-            k: v
-            for k, v in batch.items()
-            if (k in allowed_base or k.startswith("eagle_")) and not (k.startswith("next.") or k == "info")
-        }
+        groot_inputs = self._filter_groot_inputs(batch, include_action=True)
 
         # Get device from model parameters
-        device = next(self.parameters()).device
+        device = get_device_from_parameters(self)
 
         # Run GR00T forward under bf16 autocast when enabled to reduce activation memory
         # Rationale: Matches original GR00T finetuning (bf16 compute, fp32 params) and avoids fp32 upcasts.
@@ -248,38 +402,52 @@ class GrootPolicy(PreTrainedPolicy):
 
         # Isaac-GR00T returns a BatchFeature; loss key is typically 'loss'
         loss = outputs.get("loss")
+        if loss is None:
+            raise RuntimeError(
+                "GR00T model.forward did not return a 'loss'. Training batches must include "
+                "'action' and 'action_mask'; check the preprocessor output."
+            )
 
         loss_dict = {"loss": loss.item()}
 
         return loss, loss_dict
 
     @torch.no_grad()
-    def predict_action_chunk(self, batch: dict[str, Tensor]) -> Tensor:
+    def predict_action_chunk(self, batch: dict[str, Tensor], **kwargs: object) -> Tensor:
         """Predict a chunk of actions for inference by delegating to Isaac-GR00T.
 
         Returns a tensor of shape (B, n_action_steps, action_dim).
+
+        For N1.7, LeRobot's RTC leftovers are converted into the native GR00T
+        action-overlap options before calling the underlying model.
         """
         self.eval()
 
-        # Build a clean input dict for GR00T: keep only tensors GR00T consumes
-        # Preprocessing is handled by the processor pipeline, so we just filter the batch
-        # NOTE: During inference, we should NOT pass action/action_mask (that's what we're predicting)
-        allowed_base = {"state", "state_mask", "embodiment_id"}
-        groot_inputs = {
-            k: v
-            for k, v in batch.items()
-            if (k in allowed_base or k.startswith("eagle_")) and not (k.startswith("next.") or k == "info")
-        }
+        # Preprocessing is handled by the processor pipeline, so we just filter the batch.
+        # During inference, we do not pass action because it is predicted.
+        # N1.7 still carries a 2-D action horizon mask from its checkpoint processor.
+        groot_inputs = self._filter_groot_inputs(batch, include_action=False)
+        groot_inputs, groot_options = self._prepare_n1_7_rtc_inputs(
+            groot_inputs,
+            inference_delay=kwargs.get("inference_delay"),
+            prev_chunk_left_over=kwargs.get("prev_chunk_left_over"),
+        )
 
         # Get device from model parameters
-        device = next(self.parameters()).device
+        device = get_device_from_parameters(self)
 
         # Use bf16 autocast for inference to keep memory low and match backbone dtype
         with torch.autocast(device_type=device.type, dtype=torch.bfloat16, enabled=self.config.use_bf16):
-            outputs = self._groot_model.get_action(groot_inputs)
+            if groot_options is not None:
+                outputs = self._groot_model.get_action(groot_inputs, options=groot_options)
+            else:
+                outputs = self._groot_model.get_action(groot_inputs)
 
         actions = outputs.get("action_pred")
 
+        prediction_horizon = self._resolve_prediction_horizon(actions)
+        actions = actions[:, :prediction_horizon]
+
         original_action_dim = self.config.output_features[ACTION].shape[0]
         actions = actions[:, :, :original_action_dim]
 
@@ -292,40 +460,5 @@ class GrootPolicy(PreTrainedPolicy):
 
         if len(self._action_queue) == 0:
             actions = self.predict_action_chunk(batch)
-            self._action_queue.extend(actions.transpose(0, 1))
+            self._action_queue.extend(actions[:, : self._action_queue_steps].transpose(0, 1))
         return self._action_queue.popleft()
-
-    # -------------------------
-    # Internal helpers
-    # -------------------------
-    def _handle_flash_attention_compatibility(self) -> None:
-        """Handle Flash Attention compatibility issues by setting environment variables.
-
-        This addresses the common 'undefined symbol' error that occurs when Flash Attention
-        is compiled against a different PyTorch version than what's currently installed.
-        """
-
-        # Set environment variables to handle Flash Attention compatibility
-        # These help with symbol resolution issues
-        os.environ.setdefault("FLASH_ATTENTION_FORCE_BUILD", "0")
-        os.environ.setdefault("FLASH_ATTENTION_SKIP_CUDA_BUILD", "0")
-
-        # Try to import flash_attn and handle failures gracefully
-        try:
-            import flash_attn
-
-            print(f"[GROOT] Flash Attention version: {flash_attn.__version__}")
-        except ImportError as e:
-            print(f"[GROOT] Flash Attention not available: {e}")
-            print("[GROOT] Will use fallback attention mechanism")
-        except Exception as e:
-            if "undefined symbol" in str(e):
-                print(f"[GROOT] Flash Attention compatibility issue detected: {e}")
-                print("[GROOT] This is likely due to PyTorch/Flash Attention version mismatch")
-                print("[GROOT] Consider reinstalling Flash Attention with compatible version:")
-                print("  pip uninstall flash-attn")
-                print("  pip install --no-build-isolation flash-attn==2.6.3")
-                print("[GROOT] Continuing with fallback attention mechanism")
-            else:
-                print(f"[GROOT] Flash Attention error: {e}")
-                print("[GROOT] Continuing with fallback attention mechanism")

src/lerobot/policies/groot/utils.py

@@ -1,47 +1,256 @@
+# SPDX-FileCopyrightText: Copyright (c) 2025 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+# SPDX-License-Identifier: Apache-2.0
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""Shared, side-effect-free utilities for the GR00T N1.7 policy.
+
+These helpers are consumed by both the config layer (checkpoint sidecar
+inspection) and the processor layer (stat flattening, action decoding, language
+and image packing). They are pure functions with no GR00T-specific state so they
+can be unit-tested in isolation and reused without importing the heavier
+config/processor modules.
+"""
+
+from __future__ import annotations
+
+import json
 from pathlib import Path
-from shutil import copytree
+from typing import Any
 
-from huggingface_hub import hf_hub_download
+import numpy as np
+import torch
 
 
-def ensure_eagle_cache_ready(vendor_dir: Path, cache_dir: Path, assets_repo: str) -> None:
-    """Populate the Eagle processor directory in cache and ensure tokenizer assets exist.
-
-    - Copies the vendored Eagle files into cache_dir (overwriting when needed).
-    - Downloads vocab.json and merges.txt into the same cache_dir if missing.
-    """
-    cache_dir = Path(cache_dir)
-    vendor_dir = Path(vendor_dir)
-
+def read_json(path: Path) -> dict[str, Any]:
+    """Read a JSON object from ``path``, returning ``{}`` on any read/parse error."""
     try:
-        # Populate/refresh cache with vendor files to ensure a complete processor directory
-        print(f"[GROOT] Copying vendor Eagle files to cache: {vendor_dir} -> {cache_dir}")
-        copytree(vendor_dir, cache_dir, dirs_exist_ok=True)
-    except Exception as exc:  # nosec: B110
-        print(f"[GROOT] Warning: Failed to copy vendor Eagle files to cache: {exc}")
+        with path.open() as f:
+            data = json.load(f)
+    except (OSError, json.JSONDecodeError):
+        return {}
+    return data if isinstance(data, dict) else {}
 
-    required_assets = [
-        "vocab.json",
-        "merges.txt",
-        "added_tokens.json",
-        "chat_template.json",
-        "special_tokens_map.json",
-        "config.json",
-        "generation_config.json",
-        "preprocessor_config.json",
-        "processor_config.json",
-        "tokenizer_config.json",
-    ]
 
-    print(f"[GROOT] Assets repo: {assets_repo} \n Cache dir: {cache_dir}")
+def as_int_pair(value: Any) -> list[int] | None:
+    if not isinstance(value, (list, tuple)) or len(value) != 2:
+        return None
+    try:
+        return [int(value[0]), int(value[1])]
+    except (TypeError, ValueError):
+        return None
 
-    for fname in required_assets:
-        dst = cache_dir / fname
-        if not dst.exists():
-            print(f"[GROOT] Fetching {fname}")
-            hf_hub_download(
-                repo_id=assets_repo,
-                filename=fname,
-                repo_type="model",
-                local_dir=str(cache_dir),
+
+def as_optional_int(value: Any) -> int | None:
+    if value is None:
+        return None
+    try:
+        return int(value)
+    except (TypeError, ValueError):
+        return None
+
+
+def as_optional_float(value: Any) -> float | None:
+    if value is None:
+        return None
+    try:
+        return float(value)
+    except (TypeError, ValueError):
+        return None
+
+
+def as_float_list(values: Any) -> list[float]:
+    if values is None:
+        return []
+    if isinstance(values, torch.Tensor):
+        return values.detach().cpu().reshape(-1).float().tolist()
+    if isinstance(values, np.ndarray):
+        return values.reshape(-1).astype(np.float32).tolist()
+    if isinstance(values, (list, tuple)):
+        flattened: list[float] = []
+        for value in values:
+            flattened.extend(as_float_list(value))
+        return flattened
+    return [float(values)]
+
+
+def config_value(value: Any) -> str:
+    if hasattr(value, "value"):
+        value = value.value
+    text = str(value).lower()
+    return {
+        "relative": "relative",
+        "absolute": "absolute",
+        "delta": "delta",
+        "eef": "eef",
+        "non_eef": "non_eef",
+        "default": "default",
+        "xyz_rot6d": "xyz+rot6d",
+        "xyz+rot6d": "xyz+rot6d",
+        "xyz_rotvec": "xyz+rotvec",
+        "xyz+rotvec": "xyz+rotvec",
+    }.get(text, text)
+
+
+def has_modality_stats(stats: dict[str, dict[str, Any]] | None) -> bool:
+    if not stats:
+        return False
+    return any(bool(modality_stats) for modality_stats in stats.values())
+
+
+def stat_dim_from_entry(entry: dict[str, Any]) -> int:
+    for stat_name in ("mean", "q01", "min", "max", "std"):
+        value = entry.get(stat_name)
+        if isinstance(value, list) and len(value) > 0:
+            return len(value)
+    return 0
+
+
+def flatten_n1_7_modality_stats(
+    *,
+    embodiment_stats: dict[str, Any],
+    embodiment_config: dict[str, Any],
+    modality: str,
+    use_percentiles: bool,
+    use_relative_action: bool,
+) -> dict[str, list[float]]:
+    """Flatten one N1.7 modality's grouped statistics in checkpoint order.
+
+    When checkpoints request percentile normalization, q01/q99 replace min/max
+    for regular groups. Relative action groups read from ``relative_action``
+    stats and keep min/max, matching Isaac-GR00T's processor override.
+    """
+
+    source_stats = embodiment_stats.get(modality, {})
+    modality_config = embodiment_config.get(modality, {})
+    if not isinstance(source_stats, dict) or not isinstance(modality_config, dict):
+        return {}
+    modality_keys = modality_config.get("modality_keys", [])
+    if not isinstance(modality_keys, list):
+        return {}
+
+    flattened: dict[str, list[float]] = {}
+    action_configs = modality_config.get("action_configs", []) if modality == "action" else []
+    if not isinstance(action_configs, list):
+        action_configs = []
+    relative_stats = embodiment_stats.get("relative_action", {})
+    if not isinstance(relative_stats, dict):
+        relative_stats = {}
+
+    for stat_name in ("min", "max", "mean", "std"):
+        values: list[float] = []
+        source_stat_name = stat_name
+        if use_percentiles and stat_name == "min":
+            source_stat_name = "q01"
+        elif use_percentiles and stat_name == "max":
+            source_stat_name = "q99"
+
+        for idx, modality_key in enumerate(modality_keys):
+            if not isinstance(modality_key, str):
+                continue
+            key_source_stats = source_stats
+            key_stat_name = source_stat_name
+            if modality == "action" and use_relative_action and idx < len(action_configs):
+                action_config = action_configs[idx]
+                if isinstance(action_config, dict) and config_value(action_config.get("rep")) == "relative":
+                    key_source_stats = relative_stats
+                    key_stat_name = stat_name
+            key_stats = key_source_stats.get(modality_key, {})
+            if not isinstance(key_stats, dict):
+                raise KeyError(f"Missing statistics for {modality}.{modality_key}")
+            raw_values = key_stats.get(key_stat_name)
+            if raw_values is None:
+                raise KeyError(f"Missing '{key_stat_name}' statistics for {modality}.{modality_key}")
+            values.extend(as_float_list(raw_values))
+        if values:
+            flattened[stat_name] = values
+
+    return flattened
+
+
+def rot6d_to_matrix(rot6d: np.ndarray) -> np.ndarray:
+    rows = rot6d.reshape(2, 3).astype(np.float64)
+    row1 = rows[0] / np.linalg.norm(rows[0])
+    row2 = rows[1] - np.dot(row1, rows[1]) * row1
+    row2 = row2 / np.linalg.norm(row2)
+    row3 = np.cross(row1, row2)
+    return np.vstack([row1, row2, row3])
+
+
+def xyz_rot6d_to_homogeneous(xyz_rot6d: np.ndarray) -> np.ndarray:
+    transform = np.eye(4, dtype=np.float64)
+    transform[:3, :3] = rot6d_to_matrix(xyz_rot6d[3:])
+    transform[:3, 3] = xyz_rot6d[:3]
+    return transform
+
+
+def homogeneous_to_xyz_rot6d(transform: np.ndarray) -> np.ndarray:
+    return np.concatenate([transform[:3, 3], transform[:2, :3].reshape(-1)], axis=0)
+
+
+def relative_eef_to_absolute(action: np.ndarray, reference_state: np.ndarray) -> np.ndarray:
+    """Convert relative EEF deltas in xyz+rot6d format to absolute EEF poses."""
+
+    out = np.empty_like(action, dtype=np.float64)
+    for batch_idx in range(action.shape[0]):
+        reference = xyz_rot6d_to_homogeneous(reference_state[batch_idx])
+        for timestep in range(action.shape[1]):
+            relative = xyz_rot6d_to_homogeneous(action[batch_idx, timestep])
+            out[batch_idx, timestep] = homogeneous_to_xyz_rot6d(reference @ relative)
+    return out.astype(np.float32)
+
+
+def infer_n1_7_batch_size_and_device(
+    obs: dict[str, Any], action: torch.Tensor | None
+) -> tuple[int, torch.device]:
+    for value in list(obs.values()) + [action]:
+        if isinstance(value, torch.Tensor):
+            return value.shape[0], value.device
+    video = obs.get("video")
+    if isinstance(video, np.ndarray):
+        return video.shape[0], torch.device("cpu")
+    return 1, torch.device("cpu")
+
+
+def prepare_n1_7_language_batch(
+    language: Any,
+    batch_size: int,
+    *,
+    formalize_language: bool,
+) -> list[str]:
+    default_language = "Perform the task."
+    if language is None or (isinstance(language, str) and language == ""):
+        languages = [default_language] * batch_size
+    elif isinstance(language, str):
+        languages = [language] * batch_size
+    elif isinstance(language, (list, tuple)):
+        languages = list(language)
+        if len(languages) == 0:
+            languages = [default_language] * batch_size
+        elif len(languages) == 1 and batch_size > 1:
+            languages = languages * batch_size
+        elif len(languages) != batch_size:
+            raise ValueError(
+                f"language batch has {len(languages)} entries, but GR00T N1.7 input batch has {batch_size}."
             )
+    else:
+        languages = [str(language)] * batch_size
+
+    formatted = []
+    for item in languages:
+        text = str(item) if item else default_language
+        if formalize_language:
+            text = text.lower()
+            text = "".join(ch for ch in text if ch.isalnum() or ch.isspace() or ch == "_")
+        formatted.append(text)
+    return formatted

src/lerobot/processor/pipeline.py

@@ -32,6 +32,7 @@ from __future__ import annotations
 
 import importlib
 import json
+import os
 import re
 from abc import ABC, abstractmethod
 from collections.abc import Callable, Iterable, Sequence
@@ -280,11 +281,6 @@ class DataProcessorPipeline[TInput, TOutput](HubMixin):
 
     before_step_hooks: list[Callable[[int, EnvTransition], None]] = field(default_factory=list, repr=False)
     after_step_hooks: list[Callable[[int, EnvTransition], None]] = field(default_factory=list, repr=False)
-    _serialized_state_filenames: tuple[str | None, ...] | None = field(
-        default=None,
-        init=False,
-        repr=False,
-    )
 
     def __call__(self, data: TInput) -> TOutput:
         """Processes input data through the full pipeline.
@@ -342,108 +338,30 @@ class DataProcessorPipeline[TInput, TOutput](HubMixin):
             transition = processor_step(transition)
             yield transition
 
-    def _get_sanitized_name(self) -> str:
-        """Return a filename-safe version of the pipeline name.
+    def _save_pretrained(self, save_directory: Path, **kwargs):
+        """Internal method to comply with `HubMixin`'s saving mechanism.
 
-        Returns:
-            The lower-cased pipeline name with non-alphanumeric characters replaced by underscores.
+        This method does the actual saving work and is called by HubMixin.save_pretrained.
         """
-        return re.sub(r"[^a-zA-Z0-9_]", "_", self.name.lower())
+        config_filename = kwargs.pop("config_filename", None)
 
-    @staticmethod
-    def _get_state_filename(
-        *,
-        step_index: int,
-        registry_name: str | None,
-        sanitized_name: str,
-    ) -> str:
-        """Return the safetensors filename for one stateful processor step.
+        # Sanitize the pipeline name to create a valid filename prefix.
+        sanitized_name = re.sub(r"[^a-zA-Z0-9_]", "_", self.name.lower())
 
-        Args:
-            step_index: The index of the processor step in this pipeline.
-            registry_name: The registered processor step name, if available.
-            sanitized_name: The filename-safe pipeline name.
+        if config_filename is None:
+            config_filename = f"{sanitized_name}.json"
 
-        Returns:
-            The state filename used by the existing disk serialization format.
-        """
-        if registry_name:
-            return f"{sanitized_name}_step_{step_index}_{registry_name}.safetensors"
-
-        return f"{sanitized_name}_step_{step_index}.safetensors"
-
-    @staticmethod
-    def _get_state_key(state_filename: str) -> str:
-        """Return the in-memory state key for a serialized state filename.
-
-        Args:
-            state_filename: The `.safetensors` filename from the serialized config.
-
-        Returns:
-            The state key used by the in-memory pipeline state dictionary.
-        """
-        return state_filename.removesuffix(".safetensors")
-
-    @staticmethod
-    def _get_state_filenames_from_config(loaded_config: dict[str, Any]) -> tuple[str | None, ...]:
-        """Return serialized state filenames in step order.
-
-        Args:
-            loaded_config: A validated processor pipeline config.
-
-        Returns:
-            A tuple containing each step's serialized state filename, or None for stateless steps.
-        """
-        return tuple(step_entry.get("state_file") for step_entry in loaded_config["steps"])
-
-    def _get_state_filenames_for_loading(self) -> tuple[str | None, ...]:
-        """Return expected state filenames in step order for `load_state_dict()`.
-
-        Returns:
-            The preserved serialized state filenames when available, otherwise filenames derived from
-            current non-empty step state.
-        """
-        if self._serialized_state_filenames is not None and len(self._serialized_state_filenames) == len(
-            self.steps
-        ):
-            return self._serialized_state_filenames
-
-        sanitized_name = self._get_sanitized_name()
-        state_filenames: list[str | None] = []
-
-        for step_index, processor_step in enumerate(self.steps):
-            step_state_dict = processor_step.state_dict()
-            if not step_state_dict:
-                state_filenames.append(None)
-                continue
-
-            registry_name = getattr(processor_step.__class__, "_registry_name", None)
-            state_filenames.append(
-                self._get_state_filename(
-                    step_index=step_index,
-                    registry_name=registry_name,
-                    sanitized_name=sanitized_name,
-                )
-            )
-
-        return tuple(state_filenames)
-
-    def get_config(self) -> dict[str, Any]:
-        """Return the JSON-serializable pipeline configuration.
-
-        Returns:
-            A dictionary with the same content that `save_pretrained()` writes as JSON.
-        """
-        sanitized_name = self._get_sanitized_name()
-        pipeline_config: dict[str, Any] = {
+        config: dict[str, Any] = {
             "name": self.name,
             "steps": [],
         }
 
+        # Iterate through each step to build its configuration entry.
         for step_index, processor_step in enumerate(self.steps):
             registry_name = getattr(processor_step.__class__, "_registry_name", None)
-            step_entry: dict[str, Any] = {}
 
+            step_entry: dict[str, Any] = {}
+            # Prefer registry name for portability, otherwise fall back to full class path.
             if registry_name:
                 step_entry["registry_name"] = registry_name
             else:
@@ -451,110 +369,31 @@ class DataProcessorPipeline[TInput, TOutput](HubMixin):
                     f"{processor_step.__class__.__module__}.{processor_step.__class__.__name__}"
                 )
 
-            step_entry["config"] = processor_step.get_config()
+            # Save step configuration if `get_config` is implemented.
+            if hasattr(processor_step, "get_config"):
+                step_entry["config"] = processor_step.get_config()
 
-            step_state_dict = processor_step.state_dict()
-            if step_state_dict:
-                step_entry["state_file"] = self._get_state_filename(
-                    step_index=step_index,
-                    registry_name=registry_name,
-                    sanitized_name=sanitized_name,
-                )
+            # Save step state if `state_dict` is implemented and returns a non-empty dict.
+            if hasattr(processor_step, "state_dict"):
+                state = processor_step.state_dict()
+                if state:
+                    # Clone tensors to avoid modifying the original state.
+                    cloned_state = {key: tensor.clone() for key, tensor in state.items()}
 
-            pipeline_config["steps"].append(step_entry)
+                    # Create a unique filename for the state file.
+                    if registry_name:
+                        state_filename = f"{sanitized_name}_step_{step_index}_{registry_name}.safetensors"
+                    else:
+                        state_filename = f"{sanitized_name}_step_{step_index}.safetensors"
 
-        return pipeline_config
+                    save_file(cloned_state, os.path.join(str(save_directory), state_filename))
+                    step_entry["state_file"] = state_filename
 
-    def state_dict(self) -> dict[str, dict[str, torch.Tensor]]:
-        """Return pipeline state tensors grouped by state key.
+            config["steps"].append(step_entry)
 
-        Returns:
-            A dictionary mapping suffixless state keys to cloned step state dictionaries.
-        """
-        sanitized_name = self._get_sanitized_name()
-        pipeline_state_dict: dict[str, dict[str, torch.Tensor]] = {}
-
-        for step_index, processor_step in enumerate(self.steps):
-            step_state_dict = processor_step.state_dict()
-            if not step_state_dict:
-                continue
-
-            registry_name = getattr(processor_step.__class__, "_registry_name", None)
-            state_filename = self._get_state_filename(
-                step_index=step_index,
-                registry_name=registry_name,
-                sanitized_name=sanitized_name,
-            )
-            state_key = self._get_state_key(state_filename)
-            pipeline_state_dict[state_key] = {
-                tensor_name: tensor.clone() for tensor_name, tensor in step_state_dict.items()
-            }
-
-        return pipeline_state_dict
-
-    def load_state_dict(
-        self,
-        state_dict: dict[str, dict[str, torch.Tensor]],
-    ) -> None:
-        """Load pipeline state tensors into the existing steps.
-
-        Args:
-            state_dict: A dictionary mapping suffixless state keys to step state dictionaries.
-
-        Raises:
-            KeyError: If loading finds missing expected state or unexpected extra state.
-        """
-        expected_state_filenames = self._get_state_filenames_for_loading()
-        used_state_keys: set[str] = set()
-
-        for step_index, (processor_step, state_filename) in enumerate(
-            zip(self.steps, expected_state_filenames, strict=True)
-        ):
-            if state_filename is None:
-                continue
-
-            state_key = self._get_state_key(state_filename)
-            if state_key not in state_dict:
-                raise KeyError(
-                    f"Missing state key '{state_key}' for processor step {step_index}. "
-                    f"Available state keys: {sorted(state_dict.keys())}"
-                )
-
-            processor_step.load_state_dict(state_dict[state_key])
-            used_state_keys.add(state_key)
-
-        unexpected_state_keys = set(state_dict) - used_state_keys
-        if unexpected_state_keys:
-            expected_state_key_set = {
-                self._get_state_key(state_filename)
-                for state_filename in expected_state_filenames
-                if state_filename is not None
-            }
-            raise KeyError(
-                f"Unexpected processor state keys: {sorted(unexpected_state_keys)}. "
-                f"Expected state keys: {sorted(expected_state_key_set)}"
-            )
-
-    def _save_pretrained(self, save_directory: Path, **kwargs) -> None:
-        """Internal method to comply with `HubMixin`'s saving mechanism.
-
-        This method does the actual saving work and is called by HubMixin.save_pretrained.
-        """
-        config_filename = kwargs.pop("config_filename", None)
-        sanitized_name = self._get_sanitized_name()
-
-        if config_filename is None:
-            config_filename = f"{sanitized_name}.json"
-
-        pipeline_config = self.get_config()
-        pipeline_state_dict = self.state_dict()
-
-        for state_key, step_state_dict in pipeline_state_dict.items():
-            state_filename = f"{state_key}.safetensors"
-            save_file(step_state_dict, save_directory / state_filename)
-
-        with open(save_directory / config_filename, "w") as file_pointer:
-            json.dump(pipeline_config, file_pointer, indent=2)
+        # Write the main configuration JSON file.
+        with open(os.path.join(str(save_directory), config_filename), "w") as file_pointer:
+            json.dump(config, file_pointer, indent=2)
 
     def save_pretrained(
         self,
@@ -738,54 +577,12 @@ class DataProcessorPipeline[TInput, TOutput](HubMixin):
         cls._validate_overrides_used(validated_overrides, loaded_config)
 
         # 5. Construct and return the final pipeline instance
-        pipeline = cls(
+        return cls(
             steps=steps,
             name=loaded_config.get("name", "DataProcessorPipeline"),
             to_transition=to_transition or cast(Callable[[TInput], EnvTransition], batch_to_transition),
             to_output=to_output or cast(Callable[[EnvTransition], TOutput], transition_to_batch),
         )
-        pipeline._serialized_state_filenames = cls._get_state_filenames_from_config(loaded_config)
-        return pipeline
-
-    @classmethod
-    def from_config(
-        cls,
-        config: dict[str, Any],
-        *,
-        state_dict: dict[str, dict[str, torch.Tensor]] | None = None,
-        overrides: dict[str, Any] | None = None,
-        to_transition: Callable[[TInput], EnvTransition] | None = None,
-        to_output: Callable[[EnvTransition], TOutput] | None = None,
-    ) -> DataProcessorPipeline[TInput, TOutput]:
-        """Build a pipeline from an in-memory config and optional state tensors.
-
-        Args:
-            config: A config dictionary with the same structure as the saved processor JSON.
-            state_dict: Optional in-memory pipeline state grouped by suffixless state key.
-            overrides: Optional constructor overrides keyed by registry name or class name.
-            to_transition: Optional converter from input data to `EnvTransition`.
-            to_output: Optional converter from `EnvTransition` to output data.
-
-        Returns:
-            A processor pipeline built from the config and optional state.
-        """
-        cls._validate_loaded_config("<in-memory config>", config, "<in-memory config>")
-
-        steps, remaining_override_keys = cls._build_steps_from_config(config, overrides or {})
-        cls._validate_overrides_used(remaining_override_keys, config)
-
-        pipeline = cls(
-            steps=steps,
-            name=config.get("name", "DataProcessorPipeline"),
-            to_transition=to_transition or cast(Callable[[TInput], EnvTransition], batch_to_transition),
-            to_output=to_output or cast(Callable[[EnvTransition], TOutput], transition_to_batch),
-        )
-        pipeline._serialized_state_filenames = cls._get_state_filenames_from_config(config)
-
-        if state_dict is not None:
-            pipeline.load_state_dict(state_dict)
-
-        return pipeline
 
     @classmethod
     def _load_config(
@@ -869,7 +666,9 @@ class DataProcessorPipeline[TInput, TOutput](HubMixin):
                 ) from e
 
     @classmethod
-    def _validate_loaded_config(cls, model_id: str, loaded_config: Any, config_filename: str) -> None:
+    def _validate_loaded_config(
+        cls, model_id: str, loaded_config: dict[str, Any], config_filename: str
+    ) -> None:
         """Validate that a config was loaded and is a valid processor config.
 
         This method validates processor config format with intelligent migration detection:
@@ -889,7 +688,7 @@ class DataProcessorPipeline[TInput, TOutput](HubMixin):
 
         Args:
             model_id: The model identifier (used for migration detection)
-            loaded_config: The loaded config value to validate (may be non-dict)
+            loaded_config: The loaded config dictionary (guaranteed non-None)
             config_filename: The config filename that was loaded (for error messages)
 
         Raises:
@@ -903,14 +702,9 @@ class DataProcessorPipeline[TInput, TOutput](HubMixin):
                     model_id,
                     f"Config file '{config_filename}' is not a valid processor configuration",
                 )
-            loaded_config_description = (
-                list(loaded_config.keys())
-                if isinstance(loaded_config, dict)
-                else type(loaded_config).__name__
-            )
             raise ValueError(
                 f"Config file '{config_filename}' is not a valid processor configuration. "
-                f"Expected a config with 'steps' field, but got: {loaded_config_description}"
+                f"Expected a config with 'steps' field, but got: {list(loaded_config.keys())}"
             )
 
     @classmethod
@@ -972,41 +766,26 @@ class DataProcessorPipeline[TInput, TOutput](HubMixin):
             ImportError: If a step class cannot be imported or found in registry
             ValueError: If a step cannot be instantiated with its configuration
         """
-        steps, remaining_override_keys = cls._build_steps_from_config(loaded_config, overrides)
-
-        for step_instance, step_entry in zip(steps, loaded_config["steps"], strict=True):
-            cls._load_step_state(step_instance, step_entry, model_id, base_path, hub_download_kwargs)
-
-        return steps, remaining_override_keys
-
-    @classmethod
-    def _build_steps_from_config(
-        cls,
-        loaded_config: dict[str, Any],
-        overrides: dict[str, Any],
-    ) -> tuple[list[ProcessorStep], set[str]]:
-        """Build processor steps from config without loading tensor state.
-
-        Args:
-            loaded_config: The loaded processor configuration.
-            overrides: User-provided constructor overrides keyed by step key.
-
-        Returns:
-            A tuple containing instantiated steps and override keys that did not match a step.
-        """
-        processor_steps: list[ProcessorStep] = []
-        remaining_override_keys = set(overrides.keys())
+        steps: list[ProcessorStep] = []
+        override_keys = set(overrides.keys())
 
         for step_entry in loaded_config["steps"]:
+            # 1. Get step class and key
             step_class, step_key = cls._resolve_step_class(step_entry)
-            processor_step = cls._instantiate_step(step_entry, step_class, step_key, overrides)
 
-            if step_key in remaining_override_keys:
-                remaining_override_keys.discard(step_key)
+            # 2. Instantiate step with overrides
+            step_instance = cls._instantiate_step(step_entry, step_class, step_key, overrides)
 
-            processor_steps.append(processor_step)
+            # 3. Load step state if available
+            cls._load_step_state(step_instance, step_entry, model_id, base_path, hub_download_kwargs)
 
-        return processor_steps, remaining_override_keys
+            # 4. Track used overrides
+            if step_key in override_keys:
+                override_keys.discard(step_key)
+
+            steps.append(step_instance)
+
+        return steps, override_keys
 
     @classmethod
     def _resolve_step_class(cls, step_entry: dict[str, Any]) -> tuple[type[ProcessorStep], str]:
@@ -1317,7 +1096,7 @@ class DataProcessorPipeline[TInput, TOutput](HubMixin):
         return True
 
     @classmethod
-    def _is_processor_config(cls, config: Any) -> bool:
+    def _is_processor_config(cls, config: dict) -> bool:
         """Check if config follows DataProcessorPipeline format.
 
         This method validates the processor configuration structure:
@@ -1368,9 +1147,6 @@ class DataProcessorPipeline[TInput, TOutput](HubMixin):
         Returns:
             True if config follows valid DataProcessorPipeline format, False otherwise
         """
-        if not isinstance(config, dict):
-            return False
-
         # Must have a "steps" field with a list of step configurations
         if not isinstance(config.get("steps"), list):
             return False

src/lerobot/rollout/__init__.py

@@ -23,7 +23,6 @@ from .configs import (
     DAggerKeyboardConfig,
     DAggerPedalConfig,
     DAggerStrategyConfig,
-    EpisodicStrategyConfig,
     HighlightStrategyConfig,
     RolloutConfig,
     RolloutStrategyConfig,
@@ -50,7 +49,6 @@ from .inference import (
 from .strategies import (
     BaseStrategy,
     DAggerStrategy,
-    EpisodicStrategy,
     HighlightStrategy,
     RolloutStrategy,
     SentryStrategy,
@@ -68,8 +66,6 @@ __all__ = [
     "HardwareContext",
     "HighlightStrategy",
     "HighlightStrategyConfig",
-    "EpisodicStrategy",
-    "EpisodicStrategyConfig",
     "InferenceEngine",
     "InferenceEngineConfig",
     "PolicyContext",

src/lerobot/rollout/configs.py

@@ -121,35 +121,6 @@ class DAggerPedalConfig:
     upload: str = "KEY_C"
 
 
-@RolloutStrategyConfig.register_subclass("episodic")
-@dataclass
-class EpisodicStrategyConfig(RolloutStrategyConfig):
-    """Episode-oriented recording that mirrors the behavior of ``lerobot-record``.
-
-    Records ``dataset.num_episodes`` episodes of maximum ``dataset.episode_time_s`` each.
-    After each episode, runs ``dataset.reset_time_s`` seconds of reset time.
-
-    Keyboard controls:
-        Right arrow  — end current episode or reset phase early
-        Left arrow   — discard current episode and re-record
-        Escape       — stop recording session
-
-    In between episodes:
-    - if there is no teleop leader, the robot is held at its initial joint positions captured at startup.
-    - else, the robot is moved smoothly to the position of the teleop leader.
-    """
-
-    # This only applies if there are no teleop leaders specified.
-    # When True (default), moves the robot back to the joint positions captured at startup.
-    # Otherwise, leave the robot in its current position.
-    reset_to_initial_position: bool = True
-
-    # Whether to turn on or off the leader -> follower smooth handover behavior.
-    # When False, fallback to follower -> leader handover.
-    # Note that leader -> follower handover is only supported when the leader has `send_feedback` capability.
-    smooth_leader_to_follower_handover: bool = True
-
-
 @RolloutStrategyConfig.register_subclass("dagger")
 @dataclass
 class DAggerStrategyConfig(RolloutStrategyConfig):
@@ -258,13 +229,7 @@ class RolloutConfig:
 
         # TODO(Steven): DAgger shouldn't require a dataset (user may want to just rollout+intervene without recording), but for now we require it to simplify the implementation.
         needs_dataset = isinstance(
-            self.strategy,
-            (
-                SentryStrategyConfig,
-                HighlightStrategyConfig,
-                DAggerStrategyConfig,
-                EpisodicStrategyConfig,
-            ),
+            self.strategy, (SentryStrategyConfig, HighlightStrategyConfig, DAggerStrategyConfig)
         )
         if needs_dataset and (self.dataset is None or not self.dataset.repo_id):
             raise ValueError(f"{self.strategy.type} strategy requires --dataset.repo_id to be set")

src/lerobot/rollout/strategies/__init__.py

@@ -17,7 +17,6 @@
 from .base import BaseStrategy
 from .core import RolloutStrategy, estimate_max_episode_seconds, safe_push_to_hub, send_next_action
 from .dagger import DAggerEvents, DAggerPhase, DAggerStrategy
-from .episodic import EpisodicStrategy
 from .factory import create_strategy
 from .highlight import HighlightStrategy
 from .sentry import SentryStrategy
@@ -28,7 +27,6 @@ __all__ = [
     "DAggerPhase",
     "DAggerStrategy",
     "HighlightStrategy",
-    "EpisodicStrategy",
     "RolloutStrategy",
     "SentryStrategy",
     "create_strategy",

src/lerobot/rollout/strategies/dagger.py

@@ -56,14 +56,10 @@ from typing import Any
 
 import numpy as np
 
-from lerobot.common.control_utils import (
-    follower_smooth_move_to,
-    is_headless,
-    teleop_smooth_move_to,
-    teleop_supports_feedback,
-)
+from lerobot.common.control_utils import is_headless
 from lerobot.datasets import VideoEncodingManager
 from lerobot.datasets.utils import DEFAULT_VIDEO_FILE_SIZE_IN_MB
+from lerobot.teleoperators import Teleoperator
 from lerobot.utils.constants import ACTION, OBS_STR
 from lerobot.utils.feature_utils import build_dataset_frame
 from lerobot.utils.import_utils import _pynput_available
@@ -73,6 +69,7 @@ from lerobot.utils.utils import log_say
 
 from ..configs import DAggerKeyboardConfig, DAggerPedalConfig, DAggerStrategyConfig
 from ..context import RolloutContext
+from ..robot_wrapper import ThreadSafeRobot
 from .core import RolloutStrategy, estimate_max_episode_seconds, safe_push_to_hub, send_next_action
 
 PYNPUT_AVAILABLE = _pynput_available
@@ -174,6 +171,64 @@ class DAggerEvents:
         self.upload_requested.clear()
 
 
+# ---------------------------------------------------------------------------
+# Teleoperator helpers
+# ---------------------------------------------------------------------------
+
+
+def _teleop_supports_feedback(teleop: Teleoperator) -> bool:
+    """Return True when the teleop can receive position feedback (is actuated).
+    TODO(Maxime): See if it is possible to unify this interface across teleops instead of duck-typing.
+    """
+    return (
+        bool(teleop.feedback_features)
+        and hasattr(teleop, "disable_torque")
+        and hasattr(teleop, "enable_torque")
+    )
+
+
+def _teleop_smooth_move_to(
+    teleop: Teleoperator, target_pos: dict, duration_s: float = 2.0, fps: int = 30
+) -> None:
+    """Smoothly move an actuated teleop to ``target_pos`` via linear interpolation.
+
+    Requires the teleoperator to support feedback
+    (i.e. have non-empty ``feedback_features`` and implement ``disable_torque`` / ``enable_torque``).
+
+    TODO(Maxime): This blocks up to ``duration_s`` seconds, during this time
+    the follower robot doesn't receive new actions, this could be an issue on LeKiwi.
+    """
+    teleop.enable_torque()
+    current = teleop.get_action()
+    steps = max(int(duration_s * fps), 1)
+
+    for step in range(steps + 1):
+        t = step / steps
+        interp = {
+            k: current[k] * (1 - t) + target_pos[k] * t if k in target_pos else current[k] for k in current
+        }
+        teleop.send_feedback(interp)
+        time.sleep(1 / fps)
+
+
+def _follower_smooth_move_to(
+    robot: ThreadSafeRobot, current: dict, target: dict, duration_s: float = 1.0, fps: int = 30
+) -> None:
+    """Smoothly move the follower robot from ``current`` to ``target`` action.
+
+    Used when the teleop is non-actuated: instead of driving the leader arm
+    to the follower, we bring the follower to the teleop's current pose.
+    Both ``current`` and ``target`` must be in robot-action key space.
+    """
+    steps = max(int(duration_s * fps), 1)
+
+    for step in range(steps + 1):
+        t = step / steps
+        interp = {k: current[k] * (1 - t) + target[k] * t if k in target else current[k] for k in current}
+        robot.send_action(interp)
+        time.sleep(1 / fps)
+
+
 # ---------------------------------------------------------------------------
 # Input device handlers
 # ---------------------------------------------------------------------------
@@ -701,31 +756,31 @@ class DAggerStrategy(RolloutStrategy):
             logger.info("Pausing engine - robot holds position")
             engine.pause()
 
-            if teleop_supports_feedback(teleop) and prev_action is not None:
+            if _teleop_supports_feedback(teleop) and prev_action is not None:
                 # TODO(Maxime): prev_action is in robot action key space (output of robot_action_processor).
                 # send_feedback expects teleop feedback key space. For homogeneous setups (e.g. SO-101
                 # leader + SO-101 follower) the keys are identical so this works. If the processor pipeline
                 # does non-trivial key renaming (e.g. a rename_map on action keys), the interpolation in
-                # teleop_smooth_move_to silently no-ops and the arm doesn't move.
+                # _teleop_smooth_move_to silently no-ops and the arm doesn't move.
                 logger.info("Smooth handover: moving leader arm to follower position")
-                teleop_smooth_move_to(teleop, prev_action)
+                _teleop_smooth_move_to(teleop, prev_action)
 
         elif old_phase == DAggerPhase.PAUSED and new_phase == DAggerPhase.CORRECTING:
             logger.info("Entering correction mode - human teleop control")
-            if not teleop_supports_feedback(teleop) and prev_action is not None:
+            if not _teleop_supports_feedback(teleop) and prev_action is not None:
                 logger.info("Smooth handover: sliding follower to teleop position")
                 obs = robot.get_observation()
                 teleop_action = teleop.get_action()
                 processed = ctx.processors.teleop_action_processor((teleop_action, obs))
                 target = ctx.processors.robot_action_processor((processed, obs))
-                follower_smooth_move_to(robot, prev_action, target)
+                _follower_smooth_move_to(robot, prev_action, target)
 
             # unlock the teleop for human control
-            if teleop_supports_feedback(teleop):
+            if _teleop_supports_feedback(teleop):
                 teleop.disable_torque()
 
         elif old_phase == DAggerPhase.CORRECTING and new_phase == DAggerPhase.PAUSED:
-            if teleop_supports_feedback(teleop):
+            if _teleop_supports_feedback(teleop):
                 teleop.enable_torque()
 
         elif new_phase == DAggerPhase.AUTONOMOUS:
@@ -735,7 +790,7 @@ class DAggerStrategy(RolloutStrategy):
             engine.resume()
 
             # release teleop before resuming the policy
-            if teleop_supports_feedback(teleop):
+            if _teleop_supports_feedback(teleop):
                 teleop.disable_torque()
 
     # ------------------------------------------------------------------

src/lerobot/rollout/strategies/episodic.py

@@ -1,335 +0,0 @@
-# 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.
-
-"""Episodic rollout strategy: mirrors the behavior of ``lerobot-record``.
-
-- Policy drives the robot during each recording episode.
-- An optional teleoperator can drive the robot during reset phases so the
-  operator can bring the environment back to its starting configuration.
-  If no teleop is connected the robot stays in its current position.
-- Keyboard controls:
-
-      Right arrow  — end the current episode or reset phase early
-      Left arrow   — discard the current episode and re-record it
-      Escape       — stop the recording session
-
-Dataset naming follows the rollout convention: repo names must start with ``rollout_``.
-"""
-
-from __future__ import annotations
-
-import contextlib
-import logging
-import time
-
-from lerobot.common.control_utils import (
-    follower_smooth_move_to,
-    init_keyboard_listener,
-    is_headless,
-    teleop_smooth_move_to,
-    teleop_supports_feedback,
-)
-from lerobot.datasets import VideoEncodingManager
-from lerobot.utils.constants import ACTION, OBS_STR
-from lerobot.utils.feature_utils import build_dataset_frame
-from lerobot.utils.robot_utils import precise_sleep
-from lerobot.utils.utils import log_say
-from lerobot.utils.visualization_utils import log_rerun_data
-
-from ..configs import EpisodicStrategyConfig
-from ..context import RolloutContext
-from .core import RolloutStrategy, safe_push_to_hub, send_next_action
-
-logger = logging.getLogger(__name__)
-
-
-class EpisodicStrategy(RolloutStrategy):
-    """Policy-driven multi-episode recording, mirrors the behavior of ``lerobot-record``.
-
-    Each recording episode runs the policy for maximum ``dataset.episode_time_s``
-    seconds, recording every frame.  A reset phase of ``dataset.reset_time_s``
-    follows every episode (except the last) so the operator can manually
-    reset the environment.  During the reset phase, an optional teleoperator
-    drives the robot; if none is present the robot returns to its initial joint positions captured at startup.
-
-    The policy state (hidden state, RTC queue, interpolator) is reset at
-    the start of each recording episode.
-
-    Keyboard events:
-        right arrow  → end current episode or reset phase early
-        left arrow   → discard & re-record current episode
-        ESC          → stop the session
-    """
-
-    config: EpisodicStrategyConfig
-
-    def __init__(self, config: EpisodicStrategyConfig) -> None:
-        super().__init__(config)
-        self._listener = None
-        self._events: dict | None = None
-
-    def setup(self, ctx: RolloutContext) -> None:
-        """Start the inference engine and attach the keyboard listener."""
-        self._init_engine(ctx)
-        self._listener, self._events = init_keyboard_listener()
-        logger.info("Episodic strategy ready")
-
-    def run(self, ctx: RolloutContext) -> None:
-        """Main multi-episode recording loop."""
-        cfg = ctx.runtime.cfg
-        dataset_cfg = cfg.dataset
-        robot = ctx.hardware.robot_wrapper
-        teleop = ctx.hardware.teleop
-        dataset = ctx.data.dataset
-        events = self._events
-        features = ctx.data.dataset_features
-
-        fps = cfg.fps
-        episode_time_s = dataset_cfg.episode_time_s
-        reset_time_s = dataset_cfg.reset_time_s
-        num_episodes = dataset_cfg.num_episodes
-        single_task = dataset_cfg.single_task or cfg.task
-        play_sounds = cfg.play_sounds
-
-        display_compressed = (
-            True
-            if (cfg.display_data and cfg.display_ip is not None and cfg.display_port is not None)
-            else cfg.display_compressed_images
-        )
-
-        with VideoEncodingManager(dataset):
-            try:
-                recorded_episodes = 0
-                while recorded_episodes < num_episodes and not events["stop_recording"]:
-                    if ctx.runtime.shutdown_event.is_set():
-                        break
-
-                    # Reset policy state at episode start (discard leftover hidden state / queue)
-                    self._engine.reset()
-                    self._interpolator.reset()
-                    self._engine.resume()
-
-                    log_say(f"Recording episode {dataset.num_episodes}", play_sounds)
-                    self._policy_loop(
-                        ctx=ctx,
-                        robot=robot,
-                        events=events,
-                        features=features,
-                        fps=fps,
-                        control_time_s=episode_time_s,
-                        dataset=dataset,
-                        single_task=single_task,
-                    )
-
-                    # Reset phase, skip after the last episode (but run when re-recording)
-                    if not events["stop_recording"] and (
-                        recorded_episodes < num_episodes - 1 or events["rerecord_episode"]
-                    ):
-                        log_say("Reset the environment", play_sounds)
-
-                        if teleop:
-                            # Smooth handover so the transition to teleop control is jerk-free.
-                            # For actuated teleops: drive the leader arm to the follower's current
-                            # position so the operator takes over without fighting the arm.
-                            # For non-actuated teleops: slide the follower to the teleop's current
-                            # pose instead, since the leader cannot be driven.
-                            obs = robot.get_observation()
-                            current_pos = {k: v for k, v in obs.items() if k.endswith(".pos")}
-                            if (
-                                teleop_supports_feedback(teleop)
-                                and self.config.smooth_leader_to_follower_handover
-                            ):
-                                logger.info("Smooth handover: moving leader arm to follower position")
-                                teleop_smooth_move_to(teleop, current_pos, duration_s=2)
-                                teleop.disable_torque()
-                            else:
-                                logger.info("Smooth handover: sliding follower to teleop position")
-                                teleop_action = teleop.get_action()
-                                processed = ctx.processors.teleop_action_processor((teleop_action, obs))
-                                target = ctx.processors.robot_action_processor((processed, obs))
-                                follower_smooth_move_to(robot, current_pos, target, duration_s=1)
-
-                        elif self.config.reset_to_initial_position:
-                            # No teleop: return the robot to its startup position.
-                            self._return_to_initial_position(hw=ctx.hardware, duration_s=1)
-
-                        self._reset_loop(
-                            ctx=ctx,
-                            robot=robot,
-                            teleop=teleop,
-                            events=events,
-                            fps=fps,
-                            control_time_s=reset_time_s,
-                            display_data=cfg.display_data,
-                            display_compressed=display_compressed,
-                        )
-
-                    if events["rerecord_episode"]:
-                        log_say("Re-record episode", play_sounds)
-                        events["rerecord_episode"] = False
-                        events["exit_early"] = False
-                        dataset.clear_episode_buffer()
-
-                        # returns to its initial joint positions captured at startup
-                        if not teleop and self.config.reset_to_initial_position:
-                            self._return_to_initial_position(hw=ctx.hardware, duration_s=1)
-
-                        continue
-
-                    dataset.save_episode()
-                    recorded_episodes += 1
-            finally:
-                # Save any frames buffered in the current episode so an unexpected
-                # exception or KeyboardInterrupt does not silently drop recorded data.
-                # suppress: save_episode raises if the buffer is empty (nothing to lose).
-                logger.info("Episodic control loop ended — saving any in-progress episode")
-                with contextlib.suppress(Exception):
-                    dataset.save_episode()
-
-    def _policy_loop(
-        self,
-        ctx: RolloutContext,
-        robot,
-        events: dict,
-        features: dict,
-        fps: float,
-        control_time_s: float,
-        dataset,
-        single_task: str,
-    ) -> None:
-        """Policy-driven recording loop for a single episode."""
-        interpolator = self._interpolator
-        control_interval = interpolator.get_control_interval(fps)
-
-        timestamp = 0.0
-        start_t = time.perf_counter()
-
-        while timestamp < control_time_s:
-            loop_start = time.perf_counter()
-
-            if events["exit_early"]:
-                events["exit_early"] = False
-                break
-
-            if ctx.runtime.shutdown_event.is_set():
-                break
-
-            obs = robot.get_observation()
-            obs_processed = self._process_observation_and_notify(ctx.processors, obs)
-
-            if self._handle_warmup(ctx.runtime.cfg.use_torch_compile, loop_start, control_interval):
-                continue
-
-            action_dict = send_next_action(obs_processed, obs, ctx, interpolator)
-
-            if action_dict is not None:
-                obs_frame = build_dataset_frame(features, obs_processed, prefix=OBS_STR)
-                action_frame = build_dataset_frame(features, action_dict, prefix=ACTION)
-                dataset.add_frame({**obs_frame, **action_frame, "task": single_task})
-                self._log_telemetry(obs_processed, action_dict, ctx.runtime)
-
-            dt = time.perf_counter() - loop_start
-            sleep_t = control_interval - dt
-            if sleep_t < 0:
-                logger.warning(
-                    f"Record loop is running slower ({1 / dt:.1f} Hz) than the target FPS ({fps} Hz). "
-                    "Dataset frames might be dropped and robot control might be unstable. "
-                    "Common causes are: 1) Camera FPS not keeping up 2) Policy inference taking too long "
-                    "3) CPU starvation"
-                )
-            precise_sleep(max(sleep_t, 0.0))
-            timestamp = time.perf_counter() - start_t
-
-    def _reset_loop(
-        self,
-        ctx: RolloutContext,
-        robot,
-        teleop,
-        events: dict,
-        fps: float,
-        control_time_s: float,
-        display_data: bool,
-        display_compressed: bool,
-    ) -> None:
-        """Reset-phase loop: teleop drives the robot if available, no recording."""
-        processors = ctx.processors
-        control_interval = 1.0 / fps
-
-        timestamp = 0.0
-        start_t = time.perf_counter()
-
-        while timestamp < control_time_s:
-            loop_start = time.perf_counter()
-
-            if events["exit_early"]:
-                events["exit_early"] = False
-                break
-
-            if ctx.runtime.shutdown_event.is_set():
-                break
-
-            obs = robot.get_observation()
-
-            if teleop is not None:
-                act = teleop.get_action()
-                act_teleop = processors.teleop_action_processor((act, obs))
-                robot_action = processors.robot_action_processor((act_teleop, obs))
-                robot.send_action(robot_action)
-
-                if display_data:
-                    obs_processed = processors.robot_observation_processor(obs)
-                    log_rerun_data(
-                        observation=obs_processed,
-                        action=act_teleop,
-                        compress_images=display_compressed,
-                    )
-
-            dt = time.perf_counter() - loop_start
-            sleep_t = control_interval - dt
-            precise_sleep(max(sleep_t, 0.0))
-            timestamp = time.perf_counter() - start_t
-
-    def teardown(self, ctx: RolloutContext) -> None:
-        """Finalise dataset, stop listener, push to hub, and disconnect hardware."""
-        cfg = ctx.runtime.cfg
-        play_sounds = cfg.play_sounds
-
-        log_say("Stop recording", play_sounds, blocking=True)
-
-        if not is_headless() and self._listener is not None:
-            self._listener.stop()
-
-        if ctx.data.dataset is not None:
-            logger.info("Finalizing dataset...")
-            ctx.data.dataset.finalize()
-
-        if (
-            cfg.dataset is not None
-            and cfg.dataset.push_to_hub
-            and ctx.data.dataset is not None
-            and safe_push_to_hub(
-                ctx.data.dataset,
-                tags=cfg.dataset.tags,
-                private=cfg.dataset.private,
-            )
-        ):
-            logger.info("Dataset uploaded to hub")
-            log_say("Dataset uploaded to hub", play_sounds)
-
-        self._teardown_hardware(
-            ctx.hardware,
-            return_to_initial_position=cfg.return_to_initial_position,
-        )
-        log_say("Exiting", play_sounds)
-        logger.info("Episodic strategy teardown complete")

src/lerobot/rollout/strategies/factory.py

@@ -21,7 +21,6 @@ from typing import TYPE_CHECKING
 from .base import BaseStrategy
 from .core import RolloutStrategy
 from .dagger import DAggerStrategy
-from .episodic import EpisodicStrategy
 from .highlight import HighlightStrategy
 from .sentry import SentryStrategy
 
@@ -43,8 +42,4 @@ def create_strategy(config: RolloutStrategyConfig) -> RolloutStrategy:
         return HighlightStrategy(config)
     if config.type == "dagger":
         return DAggerStrategy(config)
-    if config.type == "episodic":
-        return EpisodicStrategy(config)
-    raise ValueError(
-        f"Unknown strategy type '{config.type}'. Available: base, sentry, highlight, dagger, episodic"
-    )
+    raise ValueError(f"Unknown strategy type '{config.type}'. Available: base, sentry, highlight, dagger")

src/lerobot/scripts/lerobot_rollout.py

@@ -25,7 +25,6 @@ Strategies
     --strategy.type=sentry     Continuous recording with auto-upload
     --strategy.type=highlight  Ring buffer + keystroke save
     --strategy.type=dagger     Human-in-the-loop (DAgger / RaC)
-    --strategy.type=episodic   Episode-oriented recording with reset phases
 
 Inference backends
 ------------------
@@ -112,18 +111,6 @@ Usage examples
         --display_data=true \\
         --use_torch_compile=true
 
-    # Episodic mode — episode-oriented recording with reset phases
-    lerobot-rollout \\
-        --strategy.type=episodic \\
-        --policy.path=user/my_policy \\
-        --robot.type=so100_follower \\
-        --robot.port=/dev/ttyACM0 \\
-        --teleop.type=so100_leader \\
-        --teleop.port=/dev/ttyACM1 \\
-        --dataset.repo_id=user/rollout_episodic_data \\
-        --dataset.num_episodes=20 \\
-        --dataset.single_task="Grab the cube"
-
     # Resume a previous sentry recording session
     lerobot-rollout \\
         --strategy.type=sentry \\

src/lerobot/scripts/lerobot_train.py

@@ -232,18 +232,15 @@ def train(cfg: TrainPipelineConfig, accelerator: "Accelerator | None" = None):
         torch.backends.cudnn.benchmark = True
     torch.backends.cuda.matmul.allow_tf32 = True
 
-    # Dataset loading synchronization: each node's local main process downloads first to avoid
-    # race conditions (the global main process only exists on node 0, so gating on it would let
-    # all ranks of the other nodes download and build the Arrow cache concurrently).
-    if accelerator.is_local_main_process:
-        if is_main_process:
-            logging.info("Creating dataset")
+    # Dataset loading synchronization: main process downloads first to avoid race conditions
+    if is_main_process:
+        logging.info("Creating dataset")
         dataset = make_dataset(cfg)
 
     accelerator.wait_for_everyone()
 
-    # Now all other processes can safely load the dataset from the local cache
-    if not accelerator.is_local_main_process:
+    # Now all other processes can safely load the dataset
+    if not is_main_process:
         dataset = make_dataset(cfg)
 
     # Create environment used for evaluating checkpoints during training on simulation data.
@@ -387,21 +384,14 @@ def train(cfg: TrainPipelineConfig, accelerator: "Accelerator | None" = None):
         logging.info(f"{num_total_params=} ({format_big_number(num_total_params)})")
 
     # create dataloader for offline training
-    if hasattr(active_cfg, "drop_n_last_frames") and not cfg.dataset.streaming:
+    if hasattr(active_cfg, "drop_n_last_frames"):
         shuffle = False
-        # A dedicated generator (rather than the global torch RNG) lets accelerator.prepare
-        # synchronize the shuffle permutation across ranks, keeping batch shards disjoint even
-        # when ranks consume the global RNG asymmetrically (e.g. eval on the main process only).
-        sampler_generator = torch.Generator()
-        if cfg.seed is not None:
-            sampler_generator.manual_seed(cfg.seed)
         sampler = EpisodeAwareSampler(
             dataset.meta.episodes["dataset_from_index"],
             dataset.meta.episodes["dataset_to_index"],
             episode_indices_to_use=dataset.episodes,
             drop_n_last_frames=active_cfg.drop_n_last_frames,
             shuffle=True,
-            generator=sampler_generator,
         )
     else:
         shuffle = True
@@ -426,16 +416,9 @@ def train(cfg: TrainPipelineConfig, accelerator: "Accelerator | None" = None):
 
     # Prepare everything with accelerator
     accelerator.wait_for_everyone()
-    if cfg.dataset.streaming:
-        # The streaming IterableDataset is already rank-disjoint via split_dataset_by_node, so we must
-        # NOT hand the dataloader to accelerate: its IterableDatasetShard would keep only every
-        # world_size-th batch of each rank's already-disjoint stream (silently training on 1/N of the
-        # data while decoding all of it). Batches are moved to the device manually in the loop below.
-        policy, optimizer, lr_scheduler = accelerator.prepare(policy, optimizer, lr_scheduler)
-    else:
-        policy, optimizer, dataloader, lr_scheduler = accelerator.prepare(
-            policy, optimizer, dataloader, lr_scheduler
-        )
+    policy, optimizer, dataloader, lr_scheduler = accelerator.prepare(
+        policy, optimizer, dataloader, lr_scheduler
+    )
     dl_iter = cycle(dataloader)
 
     policy.train()
@@ -475,9 +458,6 @@ def train(cfg: TrainPipelineConfig, accelerator: "Accelerator | None" = None):
     for _ in range(step, cfg.steps):
         start_time = time.perf_counter()
         batch = next(dl_iter)
-        if cfg.dataset.streaming:
-            # The streaming dataloader is not accelerate-prepared (see above), so move to device here.
-            batch = {k: (v.to(device, non_blocking=True) if torch.is_tensor(v) else v) for k, v in batch.items()}
         for cam_key in dataset.meta.camera_keys:
             if cam_key in batch and batch[cam_key].dtype == torch.uint8:
                 batch[cam_key] = batch[cam_key].to(dtype=torch.float32) / 255.0

tests/datasets/test_byte_index.py

@@ -1,150 +0,0 @@
-"""Acceptance tests for manifest byte-index sidecars.
-
-Run on a compute node (not login-node):
-
-  srun --partition=hopper-dev --nodes=1 --ntasks=1 --cpus-per-task=8 --mem=32G --time=00:30:00 \\
-    bash -lc 'cd /admin/home/pepijn/lerobot && conda run --no-capture-output -n lerobot \\
-      env -u HF_HUB_ENABLE_HF_TRANSFER python -m pytest tests/datasets/test_byte_index.py -m integration -v'
-"""
-
-from __future__ import annotations
-
-import json
-import socket
-
-import pytest
-
-pytest.importorskip("torchcodec")
-
-REPO = "allenai/MolmoAct2-BimanualYAM-Dataset"
-REV = "e9f21ae15074330839f2ac25ed4b49d76dfa1f9c"
-BUCKET = "hf://buckets/pepijn223/MolmoAct2-BimanualYAM-Dataset-bucket"
-MAX_EPISODES = 64
-
-COMPUTE_NODE = pytest.mark.skipif(
-    "login" in socket.gethostname(),
-    reason="run on compute node via srun (see module docstring), not login-node",
-)
-
-
-@pytest.fixture(scope="module")
-def byte_index_dir(tmp_path_factory):
-    from lerobot.datasets.byte_index_builder import build_byte_index_tables, write_byte_index
-    from lerobot.datasets.dataset_metadata import LeRobotDatasetMetadata
-
-    out = tmp_path_factory.mktemp("byte_index")
-    meta = LeRobotDatasetMetadata(REPO, revision=REV)
-    files, episodes, _ = build_byte_index_tables(
-        meta, BUCKET, workers=4, max_episodes=MAX_EPISODES, include_keyframes=False
-    )
-    write_byte_index(out, files, episodes, None, merge_existing=False)
-    return out, meta
-
-
-@pytest.mark.integration
-@COMPUTE_NODE
-def test_index_load_fast_and_small(byte_index_dir):
-    from lerobot.datasets.byte_index import EpisodeByteIndex
-
-    out, meta = byte_index_dir
-    index = EpisodeByteIndex(out, video_keys=meta.video_keys, num_episodes=MAX_EPISODES)
-    assert index.load_time_s < 1.0
-    assert index.resident_bytes < 1_000_000_000
-
-
-@pytest.mark.integration
-@COMPUTE_NODE
-def test_tight_fetch_under_25mb(byte_index_dir):
-    from lerobot.datasets.byte_index import EpisodeByteIndex
-    from lerobot.datasets.byte_index_builder import build_byte_index_in_memory
-    from lerobot.datasets.episode_byte_cache import EpisodeByteCache
-
-    _, meta = byte_index_dir
-    index = build_byte_index_in_memory(meta, BUCKET, workers=4, max_episodes=MAX_EPISODES)
-    cache = EpisodeByteCache(index, max_bytes=80_000_000_000, data_root=BUCKET)
-    for ep in [0, MAX_EPISODES // 2, MAX_EPISODES - 1]:
-        cache.submit_prefetch(ep)
-        cache.ensure_ready(ep)
-    stats = cache.stats.stats_dict()
-    assert stats["byte_cache_bytes_per_miss"] < 25 * 1024 * 1024
-
-
-@pytest.mark.integration
-@COMPUTE_NODE
-def test_in_memory_build_matches_parquet(byte_index_dir):
-    from lerobot.datasets.byte_index import EpisodeByteIndex
-    from lerobot.datasets.byte_index_builder import build_byte_index_in_memory
-
-    out, meta = byte_index_dir
-    disk = EpisodeByteIndex(out, video_keys=meta.video_keys, num_episodes=MAX_EPISODES)
-    mem = build_byte_index_in_memory(meta, BUCKET, workers=4, max_episodes=MAX_EPISODES)
-    for ep in [0, MAX_EPISODES // 2, MAX_EPISODES - 1]:
-        for cam in meta.video_keys:
-            a = disk.lookup(ep, cam)
-            b = mem.lookup(ep, cam)
-            assert a.mdat_offset == b.mdat_offset
-            assert a.mdat_length == b.mdat_length
-            assert abs(a.first_pts - b.first_pts) < 1e-6
-
-
-@pytest.mark.integration
-@COMPUTE_NODE
-def test_custom_frame_mappings_available(byte_index_dir):
-    from lerobot.datasets.byte_index_builder import build_byte_index_in_memory
-
-    _, meta = byte_index_dir
-    index = build_byte_index_in_memory(meta, BUCKET, workers=4, max_episodes=MAX_EPISODES)
-    cam = meta.video_keys[0]
-    ep = MAX_EPISODES // 2
-    payload = index.custom_frame_mappings(ep, cam)
-    assert payload is not None
-    data = json.loads(payload)
-    assert len(data["frames"]) > 10
-    assert any(f["key_frame"] for f in data["frames"])
-    assert all("pts" in f and "duration" in f for f in data["frames"])
-
-
-@pytest.mark.integration
-@COMPUTE_NODE
-def test_metadata_skip_decoder_init(byte_index_dir):
-    from lerobot.datasets.byte_index_builder import build_byte_index_in_memory
-    from lerobot.datasets.episode_byte_cache import EpisodeByteCache
-
-    _, meta = byte_index_dir
-    index = build_byte_index_in_memory(meta, BUCKET, workers=4, max_episodes=MAX_EPISODES)
-    cache = EpisodeByteCache(index, max_bytes=8_000_000_000, data_root=BUCKET)
-    cam = meta.video_keys[0]
-    ep = 0
-    cache.submit_prefetch(ep)
-    cache.ensure_ready(ep)
-    dec = cache.get_decoder(ep, cam)
-    assert dec.metadata.num_frames is not None
-    assert dec.metadata.num_frames > 0
-    begin = float(dec.metadata.begin_stream_seconds)
-    end = float(dec.metadata.end_stream_seconds)
-    ts = begin + 0.5 * (end - begin)
-    frame = dec.get_frames_played_at([ts]).data
-    assert frame.ndim == 4
-
-
-@pytest.mark.integration
-@COMPUTE_NODE
-def test_sparse_decode_produces_frames(byte_index_dir):
-    from lerobot.datasets.byte_index_builder import build_byte_index_in_memory
-    from lerobot.datasets.episode_byte_cache import EpisodeByteCache
-
-    _, meta = byte_index_dir
-    index = build_byte_index_in_memory(meta, BUCKET, workers=4, max_episodes=MAX_EPISODES)
-    cache = EpisodeByteCache(index, max_bytes=80_000_000_000, data_root=BUCKET)
-    cam = meta.video_keys[0]
-    ep = 0
-    cache.submit_prefetch(ep)
-    cache.ensure_ready(ep)
-    dec = cache.get_decoder(ep, cam)
-    begin = float(dec.metadata.begin_stream_seconds)
-    end = float(dec.metadata.end_stream_seconds)
-    ts = begin + 0.5 * (end - begin)
-    frame = dec.get_frames_played_at([ts]).data
-    assert frame.ndim == 4
-    assert frame.numel() > 0
-    assert float(frame.float().std()) > 1.0

tests/datasets/test_sampler.py

@@ -114,30 +114,6 @@ def test_shuffle():
     assert set(sampler) == {0, 1, 2, 3, 4, 5}
 
 
-def test_shuffle_with_generator_is_deterministic():
-    # Two samplers shuffling with same-seed generators must yield identical permutations.
-    # This is what keeps batch shards disjoint across ranks in distributed training, where
-    # accelerate synchronizes the sampler's generator state instead of the global torch RNG.
-    sampler_a = EpisodeAwareSampler([0], [6], shuffle=True, generator=torch.Generator().manual_seed(42))
-    sampler_b = EpisodeAwareSampler([0], [6], shuffle=True, generator=torch.Generator().manual_seed(42))
-    assert list(sampler_a) == list(sampler_b)
-
-    # Desyncing the global RNG must not affect the permutation.
-    sampler_c = EpisodeAwareSampler([0], [6], shuffle=True, generator=torch.Generator().manual_seed(42))
-    order_before = list(sampler_c)
-    sampler_c.generator.manual_seed(42)
-    torch.randperm(1000)  # consume global RNG, as rank-asymmetric code (e.g. eval) would
-    assert list(sampler_c) == order_before
-
-
-def test_generator_attribute_defaults_to_none():
-    # accelerate detects synchronizable samplers via `hasattr(sampler, "generator")`,
-    # so the attribute must exist even when no generator is passed.
-    sampler = EpisodeAwareSampler([0], [6], shuffle=True)
-    assert sampler.generator is None
-    assert set(sampler) == {0, 1, 2, 3, 4, 5}
-
-
 def test_negative_drop_first_frames_raises():
     with pytest.raises(ValueError, match="drop_n_first_frames must be >= 0"):
         EpisodeAwareSampler([0], [10], drop_n_first_frames=-1)

tests/datasets/test_streaming.py

@@ -13,6 +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.
+import numpy as np
 import pytest
 import torch
 
@@ -24,6 +25,52 @@ from lerobot.utils.constants import ACTION
 from tests.fixtures.constants import DUMMY_REPO_ID
 
 
+def get_frames_expected_order(streaming_ds: StreamingLeRobotDataset) -> list[int]:
+    """Replicates the shuffling logic of StreamingLeRobotDataset to get the expected order of indices."""
+    rng = np.random.default_rng(streaming_ds.seed)
+    buffer_size = streaming_ds.buffer_size
+    num_shards = streaming_ds.num_shards
+
+    shards_indices = []
+    for shard_idx in range(num_shards):
+        shard = streaming_ds.hf_dataset.shard(num_shards, index=shard_idx)
+        shard_indices = [item["index"] for item in shard]
+        shards_indices.append(shard_indices)
+
+    shard_iterators = {i: iter(s) for i, s in enumerate(shards_indices)}
+
+    buffer_indices_generator = streaming_ds._iter_random_indices(rng, buffer_size)
+
+    frames_buffer = []
+    expected_indices = []
+
+    while shard_iterators:  # While there are still available shards
+        available_shard_keys = list(shard_iterators.keys())
+        if not available_shard_keys:
+            break
+
+        # Call _infinite_generator_over_elements with current available shards (key difference!)
+        shard_key = next(streaming_ds._infinite_generator_over_elements(rng, available_shard_keys))
+
+        try:
+            frame_index = next(shard_iterators[shard_key])
+
+            if len(frames_buffer) == buffer_size:
+                i = next(buffer_indices_generator)
+                expected_indices.append(frames_buffer[i])
+                frames_buffer[i] = frame_index
+            else:
+                frames_buffer.append(frame_index)
+
+        except StopIteration:
+            del shard_iterators[shard_key]  # Remove exhausted shard
+
+    rng.shuffle(frames_buffer)
+    expected_indices.extend(frames_buffer)
+
+    return expected_indices
+
+
 def test_single_frame_consistency(tmp_path, lerobot_dataset_factory):
     """Test if are correctly accessed"""
     ds_num_frames = 400
@@ -73,9 +120,10 @@ def test_single_frame_consistency(tmp_path, lerobot_dataset_factory):
     [False, True],
 )
 def test_frames_order_over_epochs(tmp_path, lerobot_dataset_factory, shuffle):
-    """Each epoch covers every frame exactly once; shuffle reshuffles across epochs."""
+    """Test if streamed frames correspond to shuffling operations over in-memory dataset."""
     ds_num_frames = 400
     ds_num_episodes = 10
+    buffer_size = 100
     seed = 42
     n_epochs = 3
 
@@ -90,17 +138,25 @@ def test_frames_order_over_epochs(tmp_path, lerobot_dataset_factory, shuffle):
     )
 
     streaming_ds = StreamingLeRobotDataset(
-        repo_id=repo_id, root=local_path, episode_pool_size=4, seed=seed, shuffle=shuffle
+        repo_id=repo_id, root=local_path, buffer_size=buffer_size, seed=seed, shuffle=shuffle
     )
 
-    epochs = [[int(frame["index"]) for frame in streaming_ds] for _ in range(n_epochs)]
-    for epoch_indices in epochs:
-        assert sorted(epoch_indices) == list(range(ds_num_frames)), "epoch did not cover every frame once"
-    if shuffle:
-        assert epochs[0] != epochs[1], "shuffle did not reshuffle across epochs"
-        assert epochs[0] != list(range(ds_num_frames)), "shuffle left the stream in sequential order"
-    else:
-        assert epochs[0] == epochs[1] == epochs[2], "unshuffled epochs must repeat the same order"
+    first_epoch_indices = [frame["index"] for frame in streaming_ds]
+    expected_indices = get_frames_expected_order(streaming_ds)
+
+    assert first_epoch_indices == expected_indices, "First epoch indices do not match expected indices"
+
+    expected_indices = get_frames_expected_order(streaming_ds)
+    for _ in range(n_epochs):
+        streaming_indices = [frame["index"] for frame in streaming_ds]
+        frames_match = all(
+            s_index == e_index for s_index, e_index in zip(streaming_indices, expected_indices, strict=True)
+        )
+
+        if shuffle:
+            assert not frames_match
+        else:
+            assert frames_match
 
 
 @pytest.mark.parametrize(
@@ -108,11 +164,15 @@ def test_frames_order_over_epochs(tmp_path, lerobot_dataset_factory, shuffle):
     [False, True],
 )
 def test_frames_order_with_shards(tmp_path, lerobot_dataset_factory, shuffle):
-    """Multi-shard streams keep exactly-once coverage and deterministic per-seed order."""
+    """Test if streamed frames correspond to shuffling operations over in-memory dataset with multiple shards."""
     ds_num_frames = 100
     ds_num_episodes = 10
+    buffer_size = 10
+
     seed = 42
+    n_epochs = 3
     data_file_size_mb = 0.001
+
     chunks_size = 1
 
     local_path = tmp_path / "test"
@@ -127,21 +187,31 @@ def test_frames_order_with_shards(tmp_path, lerobot_dataset_factory, shuffle):
         chunks_size=chunks_size,
     )
 
-    def make_ds():
-        return StreamingLeRobotDataset(
-            repo_id=repo_id,
-            root=local_path,
-            episode_pool_size=3,
-            seed=seed,
-            shuffle=shuffle,
-            max_num_shards=4,
+    streaming_ds = StreamingLeRobotDataset(
+        repo_id=repo_id,
+        root=local_path,
+        buffer_size=buffer_size,
+        seed=seed,
+        shuffle=shuffle,
+        max_num_shards=4,
+    )
+
+    first_epoch_indices = [frame["index"] for frame in streaming_ds]
+    expected_indices = get_frames_expected_order(streaming_ds)
+
+    assert first_epoch_indices == expected_indices, "First epoch indices do not match expected indices"
+
+    for _ in range(n_epochs):
+        streaming_indices = [
+            frame["index"] for frame in streaming_ds
+        ]  # NOTE: this is the same as first_epoch_indices
+        frames_match = all(
+            s_index == e_index for s_index, e_index in zip(streaming_indices, expected_indices, strict=True)
         )
-
-    first = [int(frame["index"]) for frame in make_ds()]
-    again = [int(frame["index"]) for frame in make_ds()]
-
-    assert sorted(first) == list(range(ds_num_frames)), "epoch did not cover every frame once"
-    assert first == again, "same seed must reproduce the same order"
+        if shuffle:
+            assert not frames_match
+        else:
+            assert frames_match
 
 
 @pytest.mark.parametrize(
@@ -218,11 +288,6 @@ def test_frames_with_delta_consistency(tmp_path, lerobot_dataset_factory, state_
 
                 check = torch.allclose(left, right) and left.shape == right.shape
 
-            else:
-                # Scalar numerics: streaming yields python floats/ints where map-style yields
-                # 0-dim tensors (long-standing accepted difference). Compare by value.
-                check = float(left) == float(right)
-
             key_checks.append((key, check))
 
         assert all(t[1] for t in key_checks), (

tests/datasets/test_streaming_distributed.py

@@ -1,100 +0,0 @@
-# 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.
-
-"""End-to-end distributed streaming smoke test under a real `accelerate launch`.
-
-Mirrors tests/training/test_multi_gpu.py but runs on CPU and only checks the dataloading contract: with
-two processes, `split_dataset_by_node` (auto-resolved from the Accelerate state) must give each rank a
-disjoint set of frames that together cover the dataset. Skips if the environment can't actually spawn
->= 2 processes (e.g. local macOS multi-CPU), so it never silently passes as a single process.
-"""
-
-import json
-import shutil
-import subprocess
-import sys
-
-import pytest
-
-pytest.importorskip("datasets", reason="datasets is required (install lerobot[dataset])")
-pytest.importorskip("accelerate", reason="accelerate is required (install lerobot[training])")
-
-from tests.fixtures.constants import DUMMY_REPO_ID
-
-WORKER = """
-import json, sys
-from accelerate import PartialState
-from lerobot.datasets.streaming_dataset import StreamingLeRobotDataset
-
-root, repo_id, out_dir = sys.argv[1], sys.argv[2], sys.argv[3]
-state = PartialState()
-ds = StreamingLeRobotDataset(
-    repo_id=repo_id, root=root, shuffle=False, episode_pool_size=8, max_num_shards=8
-)
-indices = [int(frame["index"]) for frame in ds]
-payload = {"rank": state.process_index, "world": state.num_processes, "indices": indices}
-with open(f"{out_dir}/rank_{state.process_index}.json", "w") as f:
-    json.dump(payload, f)
-"""
-
-
-@pytest.mark.skipif(shutil.which("accelerate") is None, reason="accelerate CLI not available")
-def test_accelerate_launch_ranks_are_disjoint(tmp_path, lerobot_dataset_factory):
-    total_frames = 160
-    repo_id = f"{DUMMY_REPO_ID}-acc"
-    root = tmp_path / "ds"
-    lerobot_dataset_factory(
-        root=root,
-        repo_id=repo_id,
-        total_episodes=8,
-        total_frames=total_frames,
-        use_videos=False,
-        data_files_size_in_mb=0.001,
-        chunks_size=1,
-    )
-
-    worker = tmp_path / "worker.py"
-    worker.write_text(WORKER)
-    out_dir = tmp_path / "out"
-    out_dir.mkdir()
-
-    cmd = [
-        "accelerate",
-        "launch",
-        "--num_processes=2",
-        "--num_machines=1",
-        "--mixed_precision=no",
-        "--dynamo_backend=no",
-        "--cpu",
-        str(worker),
-        str(root),
-        repo_id,
-        str(out_dir),
-    ]
-    result = subprocess.run(cmd, capture_output=True, text=True, timeout=600)
-    assert result.returncode == 0, (
-        f"accelerate launch failed:\nSTDOUT:\n{result.stdout}\nSTDERR:\n{result.stderr}"
-    )
-
-    payloads = [json.loads(p.read_text()) for p in sorted(out_dir.glob("rank_*.json"))]
-    if len(payloads) < 2 or any(p["world"] < 2 for p in payloads):
-        pytest.skip("environment did not spawn >= 2 distributed processes (e.g. local macOS multi-CPU)")
-
-    rank_sets = [set(p["indices"]) for p in payloads]
-    assert rank_sets[0].isdisjoint(rank_sets[1]), "ranks streamed overlapping frames under accelerate launch"
-    assert set().union(*rank_sets) == set(range(total_frames)), "ranks did not jointly cover all frames"
-
-
-if __name__ == "__main__":
-    sys.exit(pytest.main([__file__, "-v"]))

tests/datasets/test_streaming_native.py

@@ -1,430 +0,0 @@
-# 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.
-
-"""Tests for the HF-native large-scale streaming additions: distributed (per-rank) sharding,
-DataLoader worker splitting, the episode pool (randomness, coverage, exact deltas), video
-prefetching, deterministic fast-forward resume, and schema parity."""
-
-import pytest
-import torch
-from torch.utils.data import DataLoader
-
-pytest.importorskip("datasets", reason="datasets is required (install lerobot[dataset])")
-
-from lerobot.datasets.streaming_dataset import StreamingLeRobotDataset
-from lerobot.utils.constants import ACTION
-from tests.fixtures.constants import DUMMY_REPO_ID
-
-
-def _make_local_dataset(factory, root, repo_id, *, total_episodes, total_frames, use_videos=False, **kw):
-    factory(
-        root=root,
-        repo_id=repo_id,
-        total_episodes=total_episodes,
-        total_frames=total_frames,
-        use_videos=use_videos,
-        data_files_size_in_mb=0.001,
-        chunks_size=1,
-        **kw,
-    )
-
-
-def _stream_indices(ds: StreamingLeRobotDataset) -> list[int]:
-    return [int(frame["index"]) for frame in ds]
-
-
-def test_resolve_distributed_prefers_explicit_then_env(monkeypatch):
-    assert StreamingLeRobotDataset._resolve_distributed(2, 8) == (2, 8)
-
-    monkeypatch.delenv("RANK", raising=False)
-    monkeypatch.delenv("WORLD_SIZE", raising=False)
-    # No accelerate state, no env -> single process.
-    assert StreamingLeRobotDataset._resolve_distributed(None, None) == (0, 1)
-
-    monkeypatch.setenv("RANK", "3")
-    monkeypatch.setenv("WORLD_SIZE", "4")
-    assert StreamingLeRobotDataset._resolve_distributed(None, None) == (3, 4)
-
-
-def test_split_by_node_disjoint_across_ranks(tmp_path, lerobot_dataset_factory):
-    """Each rank must stream a disjoint set of frames, and the ranks together must cover every frame."""
-    repo_id = f"{DUMMY_REPO_ID}-ranks"
-    total_frames, total_episodes = 200, 8
-    _make_local_dataset(
-        lerobot_dataset_factory,
-        tmp_path / "ds",
-        repo_id,
-        total_episodes=total_episodes,
-        total_frames=total_frames,
-    )
-
-    world_size = 2
-    per_rank = []
-    for rank in range(world_size):
-        ds = StreamingLeRobotDataset(
-            repo_id=repo_id,
-            root=tmp_path / "ds",
-            shuffle=False,
-            episode_pool_size=8,
-            max_num_shards=8,
-            rank=rank,
-            world_size=world_size,
-        )
-        per_rank.append(set(_stream_indices(ds)))
-
-    assert per_rank[0].isdisjoint(per_rank[1]), (
-        "ranks streamed overlapping frames (duplicate data across GPUs)"
-    )
-    assert per_rank[0] | per_rank[1] == set(range(total_frames)), "ranks did not jointly cover all frames"
-
-
-def test_dataloader_workers_no_duplicates_within_rank(tmp_path, lerobot_dataset_factory):
-    """DataLoader workers within a rank must split shards so no frame is yielded twice."""
-    repo_id = f"{DUMMY_REPO_ID}-workers"
-    total_frames, total_episodes = 120, 8
-    _make_local_dataset(
-        lerobot_dataset_factory,
-        tmp_path / "ds",
-        repo_id,
-        total_episodes=total_episodes,
-        total_frames=total_frames,
-    )
-
-    ds = StreamingLeRobotDataset(
-        repo_id=repo_id, root=tmp_path / "ds", shuffle=False, episode_pool_size=4, max_num_shards=4
-    )
-    loader = DataLoader(ds, batch_size=None, num_workers=2)
-    indices = [int(batch["index"]) for batch in loader]
-
-    assert len(indices) == len(set(indices)), "DataLoader workers yielded duplicate frames within a rank"
-
-
-def test_sarm_window_covers_long_horizon_without_padding(tmp_path, lerobot_dataset_factory):
-    """A delta window longer than the old 100-frame ceiling must fetch real frames, not pad them.
-
-    SARM uses a window of 8 steps spaced 1s (~160 frames @ fps20). Here fps=30, so +5s = 150 frames > 100.
-    """
-    repo_id = f"{DUMMY_REPO_ID}-sarm"
-    # A single long episode so a +150-frame lookahead is unambiguously inside the episode (the fixture
-    # gives episodes variable lengths, so multi-episode boundaries can't be assumed).
-    episode_frames = 300
-    _make_local_dataset(
-        lerobot_dataset_factory, tmp_path / "ds", repo_id, total_episodes=1, total_frames=episode_frames
-    )
-
-    horizon_s = 5.0  # 150 frames @ fps30, well beyond LOOKAHEAD_BACKTRACKTABLE=100
-    delta_timestamps = {ACTION: [0.0, horizon_s]}
-    ds = StreamingLeRobotDataset(
-        repo_id=repo_id,
-        root=tmp_path / "ds",
-        shuffle=False,
-        episode_pool_size=1,
-        max_num_shards=1,
-        delta_timestamps=delta_timestamps,
-    )
-
-    horizon_frames = int(round(horizon_s * ds.fps))
-    assert horizon_frames > 100, "test must exceed the old LOOKAHEAD_BACKTRACKTABLE ceiling"
-    checked = 0
-    for frame in ds:
-        idx = int(frame["index"])
-        # The +horizon target is inside the single episode -> it must be a real frame, not padding.
-        if idx + horizon_frames < episode_frames:
-            assert not bool(frame[f"{ACTION}_is_pad"][-1]), (
-                f"frame {idx}: +{horizon_frames} target was padded; long delta window did not reach it"
-            )
-            checked += 1
-    assert checked > 0, "test did not exercise any in-episode long-horizon frame"
-
-
-def test_pool_order_is_deterministic_per_seed(tmp_path, lerobot_dataset_factory):
-    repo_id = f"{DUMMY_REPO_ID}-seeds"
-    _make_local_dataset(lerobot_dataset_factory, tmp_path / "ds", repo_id, total_episodes=6, total_frames=120)
-
-    def order(seed):
-        return _stream_indices(
-            StreamingLeRobotDataset(
-                repo_id=repo_id,
-                root=tmp_path / "ds",
-                shuffle=True,
-                seed=seed,
-                episode_pool_size=4,
-                max_num_shards=2,
-            )
-        )
-
-    assert order(0) == order(0), "same seed must reproduce the same order"
-    assert order(0) != order(1), "different seeds should give different orders"
-
-
-def test_pool_epochs_reshuffle_and_cover(tmp_path, lerobot_dataset_factory):
-    """Consecutive passes over the same dataset object reshuffle (epoch advances) but keep coverage."""
-    repo_id = f"{DUMMY_REPO_ID}-epochs"
-    total_frames = 120
-    _make_local_dataset(
-        lerobot_dataset_factory, tmp_path / "ds", repo_id, total_episodes=6, total_frames=total_frames
-    )
-    ds = StreamingLeRobotDataset(
-        repo_id=repo_id, root=tmp_path / "ds", shuffle=True, seed=3, episode_pool_size=4, max_num_shards=2
-    )
-    epoch_0 = _stream_indices(ds)
-    epoch_1 = _stream_indices(ds)
-    assert sorted(epoch_0) == sorted(epoch_1) == list(range(total_frames))
-    assert epoch_0 != epoch_1, "epoch did not reshuffle"
-
-
-def test_pool_mixes_episodes(tmp_path, lerobot_dataset_factory):
-    """Early samples should already come from several distinct episodes (the pool's purpose)."""
-    repo_id = f"{DUMMY_REPO_ID}-mix"
-    _make_local_dataset(lerobot_dataset_factory, tmp_path / "ds", repo_id, total_episodes=8, total_frames=200)
-    ds = StreamingLeRobotDataset(
-        repo_id=repo_id, root=tmp_path / "ds", shuffle=True, seed=0, episode_pool_size=8, max_num_shards=4
-    )
-    episodes_in_head = {int(frame["episode_index"]) for _, frame in zip(range(20), ds, strict=False)}
-    assert len(episodes_in_head) >= 3, f"pool did not mix episodes: {episodes_in_head}"
-
-
-def test_schema_parity_with_map_style(tmp_path, lerobot_dataset_factory):
-    """Streamed samples must have the same keys / shapes / dtypes as map-style LeRobotDataset."""
-    repo_id = f"{DUMMY_REPO_ID}-parity"
-    map_ds = lerobot_dataset_factory(
-        root=tmp_path / "ds", repo_id=repo_id, total_episodes=4, total_frames=80, use_videos=True
-    )
-    stream_ds = StreamingLeRobotDataset(
-        repo_id=repo_id, root=tmp_path / "ds", shuffle=False, episode_pool_size=4, max_num_shards=2
-    )
-
-    map_frame = map_ds[0]
-    stream_frame = next(iter(stream_ds))
-
-    assert set(stream_frame) == set(map_frame), set(stream_frame) ^ set(map_frame)
-    for key, value in stream_frame.items():
-        ref = map_frame[key]
-        if isinstance(value, torch.Tensor):
-            assert isinstance(ref, torch.Tensor) and value.shape == ref.shape and value.dtype == ref.dtype, (
-                f"{key}: stream {tuple(value.shape)}/{value.dtype} vs map {tuple(ref.shape)}/{ref.dtype}"
-            )
-        elif isinstance(value, str):
-            assert isinstance(ref, str), f"{key}: {type(value)} vs {type(ref)}"
-        else:
-            # Scalar numerics: streaming yields python floats where map-style yields 0-dim tensors
-            # (a long-standing, accepted difference). Compare by value rather than exact type.
-            assert float(value) == float(ref), f"{key}: {value} vs {ref}"
-
-
-def test_video_path_resolution_local(tmp_path, lerobot_dataset_factory, monkeypatch):
-    """For a local (prewarmed) root, video decode must be issued against the local path, not hf://."""
-    import lerobot.datasets.streaming_dataset as sd
-
-    repo_id = f"{DUMMY_REPO_ID}-vpath"
-    lerobot_dataset_factory(
-        root=tmp_path / "ds", repo_id=repo_id, total_episodes=2, total_frames=40, use_videos=True
-    )
-    ds = StreamingLeRobotDataset(
-        repo_id=repo_id, root=tmp_path / "ds", shuffle=False, episode_pool_size=1, max_num_shards=1
-    )
-
-    seen_paths = []
-
-    def fake_decode(video_path, query_ts, *args, **kwargs):
-        seen_paths.append(str(video_path))
-        return torch.zeros(len(query_ts), 3, 64, 96)
-
-    monkeypatch.setattr(sd, "decode_video_frames_torchcodec", fake_decode)
-    next(iter(ds))
-
-    assert seen_paths, "no video decode was issued"
-    assert all(str(ds.root) in p and not p.startswith("hf://") for p in seen_paths), seen_paths
-
-
-def test_shuffle_decorrelates_output_order(tmp_path, lerobot_dataset_factory):
-    """With shuffle on, streamed frame order must differ from the underlying sequential order."""
-    repo_id = f"{DUMMY_REPO_ID}-shuf"
-    _make_local_dataset(lerobot_dataset_factory, tmp_path / "ds", repo_id, total_episodes=8, total_frames=200)
-    ordered = _stream_indices(
-        StreamingLeRobotDataset(
-            repo_id=repo_id, root=tmp_path / "ds", shuffle=False, episode_pool_size=1, max_num_shards=1
-        )
-    )
-    shuffled = _stream_indices(
-        StreamingLeRobotDataset(
-            repo_id=repo_id, root=tmp_path / "ds", shuffle=True, episode_pool_size=8, max_num_shards=4, seed=0
-        )
-    )
-    assert sorted(shuffled) == sorted(ordered), "shuffling changed the set of frames"
-    assert shuffled != ordered, "shuffle did not decorrelate output order"
-
-
-def test_native_resume_never_repeats_and_loss_is_bounded(tmp_path, lerobot_dataset_factory):
-    """Native state_dict resume: no sample is re-yielded; loss is bounded by the shuffle buffers."""
-    repo_id = f"{DUMMY_REPO_ID}-native-resume"
-    total_frames = 100
-    _make_local_dataset(
-        lerobot_dataset_factory, tmp_path / "ds", repo_id, total_episodes=5, total_frames=total_frames
-    )
-
-    def fresh_ds():
-        return StreamingLeRobotDataset(
-            repo_id=repo_id,
-            root=tmp_path / "ds",
-            shuffle=True,
-            seed=7,
-            episode_pool_size=2,
-            frame_shuffle_buffer_size=8,
-        )
-
-    ds = fresh_ds()
-    it = iter(ds)
-    consumed = [int(next(it)["index"]) for _ in range(30)]
-    state = ds.state_dict()
-
-    resumed_ds = fresh_ds()
-    resumed_ds.load_state_dict(state)
-    rest = [int(frame["index"]) for frame in resumed_ds]
-
-    assert not set(consumed) & set(rest), "resume re-yielded already-seen frames"
-    # in-flight buffer contents are skipped on resume (documented datasets behavior):
-    # bounded by the episode pool (2 episodes of <= ~30 frames here) + frame buffer (8)
-    covered = len(set(consumed) | set(rest))
-    max_in_flight = 2 * 30 + 8
-    assert covered >= total_frames - max_in_flight
-    assert covered + len(consumed) >= total_frames - max_in_flight
-
-
-def test_pipeline_uses_native_primitives(tmp_path, lerobot_dataset_factory):
-    """The tabular pipeline is pure datasets: batch(by_column) + shuffle + map + shuffle."""
-    repo_id = f"{DUMMY_REPO_ID}-native-pipe"
-    _make_local_dataset(lerobot_dataset_factory, tmp_path / "ds", repo_id, total_episodes=4, total_frames=80)
-    ds = StreamingLeRobotDataset(repo_id=repo_id, root=tmp_path / "ds", shuffle=True, episode_pool_size=2)
-    import datasets as hf_datasets
-
-    assert isinstance(ds._pipeline, hf_datasets.IterableDataset)
-    state = ds._pipeline.state_dict()  # the native resume protocol is available end-to-end
-    assert state is not None
-
-
-# --- Plan B: random-episode admission via reshard() + multi-input-shard shuffle ---
-
-
-def test_reshard_makes_one_shard_per_episode(tmp_path, lerobot_dataset_factory):
-    """With one row group per episode (the writer's invariant), reshard() turns each episode into its
-    own shard, so num_shards == total_episodes even when many episodes share a single data file."""
-    import pyarrow.parquet as pq
-
-    repo_id = f"{DUMMY_REPO_ID}-reshard"
-    total_episodes = 3
-    # Default (large) data-file size packs all (unequal-length) episodes into one file, so the only way
-    # num_shards can reach total_episodes is per-row-group resharding.
-    lerobot_dataset_factory(
-        root=tmp_path / "ds",
-        repo_id=repo_id,
-        total_episodes=total_episodes,
-        total_frames=90,
-        use_videos=False,
-    )
-    ds = StreamingLeRobotDataset(repo_id=repo_id, root=tmp_path / "ds", shuffle=False, episode_pool_size=3)
-
-    file_to_eps = ds._episode_files()
-    assert len(file_to_eps) == 1, "test expects all episodes packed into a single data file"
-    for (chunk_idx, file_idx), eps in file_to_eps.items():
-        rel = ds.meta.data_path.format(chunk_index=chunk_idx, file_index=file_idx)
-        assert pq.ParquetFile(str(ds.root / rel)).num_row_groups == len(eps)
-
-    assert ds.num_shards == total_episodes
-
-
-def test_max_buffer_input_shards_admits_random_episodes(tmp_path, lerobot_dataset_factory):
-    """max_buffer_input_shards (== concurrently-live random episodes) drives the per-batch episode mix:
-    a single batch should already span most of the live episodes."""
-    repo_id = f"{DUMMY_REPO_ID}-frac"
-    total_episodes = 8
-    lerobot_dataset_factory(
-        root=tmp_path / "ds",
-        repo_id=repo_id,
-        total_episodes=total_episodes,
-        total_frames=240,
-        use_videos=False,
-    )
-    ds = StreamingLeRobotDataset(
-        repo_id=repo_id,
-        root=tmp_path / "ds",
-        shuffle=True,
-        seed=0,
-        episode_pool_size=total_episodes,
-        max_buffer_input_shards=total_episodes,
-    )
-    assert ds.max_buffer_input_shards == total_episodes
-
-    batch = 32
-    head = {int(frame["episode_index"]) for _, frame in zip(range(batch), ds, strict=False)}
-    assert len(head) >= min(total_episodes, batch) - 2, f"batch did not mix random episodes: {head}"
-
-
-def test_collapsed_row_groups_raise(tmp_path, lerobot_dataset_factory):
-    """A data file that collapses several episodes into a single row group (bulk df.to_parquet /
-    push_to_hub) must be rejected with an actionable error: reshard() cannot address its episodes."""
-    import pyarrow.parquet as pq
-
-    repo_id = f"{DUMMY_REPO_ID}-collapsed"
-    lerobot_dataset_factory(
-        root=tmp_path / "ds", repo_id=repo_id, total_episodes=3, total_frames=90, use_videos=False
-    )
-    # Rewrite every data file as a single row group (simulating the aggregate/push_to_hub collapse).
-    for parquet_path in (tmp_path / "ds" / "data").rglob("*.parquet"):
-        pq.write_table(pq.read_table(parquet_path), parquet_path)
-
-    with pytest.raises(ValueError, match="ONE ROW GROUP PER EPISODE"):
-        StreamingLeRobotDataset(repo_id=repo_id, root=tmp_path / "ds", shuffle=False, episode_pool_size=3)
-
-
-def test_collapsed_row_groups_can_be_bypassed(tmp_path, lerobot_dataset_factory):
-    """validate_row_groups=False skips the row-group check (collapsed datasets still load, degraded)."""
-    import pyarrow.parquet as pq
-
-    repo_id = f"{DUMMY_REPO_ID}-collapsed-bypass"
-    lerobot_dataset_factory(
-        root=tmp_path / "ds", repo_id=repo_id, total_episodes=3, total_frames=90, use_videos=False
-    )
-    for parquet_path in (tmp_path / "ds" / "data").rglob("*.parquet"):
-        pq.write_table(pq.read_table(parquet_path), parquet_path)
-
-    ds = StreamingLeRobotDataset(
-        repo_id=repo_id, root=tmp_path / "ds", shuffle=False, episode_pool_size=3, validate_row_groups=False
-    )
-    assert sorted(int(frame["index"]) for frame in ds) == list(range(90))
-
-
-def test_distributed_divisibility_guard_raises(tmp_path, lerobot_dataset_factory):
-    """When num_shards (== episodes after reshard) is not divisible by world_size, every rank would
-    stream the whole dataset; the guard must raise instead of silently degrading."""
-    repo_id = f"{DUMMY_REPO_ID}-divis"
-    lerobot_dataset_factory(
-        root=tmp_path / "ds", repo_id=repo_id, total_episodes=3, total_frames=90, use_videos=False
-    )
-    with pytest.raises(ValueError, match="not divisible by world_size"):
-        StreamingLeRobotDataset(
-            repo_id=repo_id, root=tmp_path / "ds", shuffle=False, episode_pool_size=3, rank=0, world_size=2
-        )
-
-    # Bypassing the guard downgrades it to a warning (no raise).
-    ds = StreamingLeRobotDataset(
-        repo_id=repo_id,
-        root=tmp_path / "ds",
-        shuffle=False,
-        episode_pool_size=3,
-        rank=0,
-        world_size=2,
-        validate_row_groups=False,
-    )
-    assert ds.num_shards == 3

tests/fixtures/files.py

@@ -17,7 +17,6 @@ from pathlib import Path
 import datasets
 import numpy as np
 import pandas as pd
-import pyarrow.parquet as pq
 import pytest
 from datasets import Dataset
 
@@ -36,24 +35,6 @@ from lerobot.datasets.utils import (
 )
 
 
-def _to_parquet_one_row_group_per_episode(hf_dataset: Dataset, path: Path) -> None:
-    """Write ``hf_dataset`` to ``path`` with one Parquet row group per episode.
-
-    Mirrors the LeRobot recording writer (one ``write_table`` per episode) so each episode stays an
-    independently addressable shard after ``datasets.IterableDataset.reshard()``, which
-    ``StreamingLeRobotDataset`` relies on. ``Dataset.to_parquet`` would collapse the file into a
-    single row group instead.
-    """
-    table = hf_dataset.with_format("arrow")[:]
-    episode_index = np.asarray(hf_dataset["episode_index"])
-    boundaries = np.where(np.diff(episode_index) != 0)[0] + 1
-    starts = [0, *boundaries.tolist()]
-    ends = [*boundaries.tolist(), len(episode_index)]
-    with pq.ParquetWriter(str(path), table.schema) as writer:
-        for start, end in zip(starts, ends, strict=True):
-            writer.write_table(table.slice(start, end - start))
-
-
 def write_hf_dataset(
     hf_dataset: Dataset,
     local_dir: Path,
@@ -86,7 +67,7 @@ def write_hf_dataset(
         # If the dataset is small enough, write it to a single file.
         path = local_dir / DEFAULT_DATA_PATH.format(chunk_index=0, file_index=0)
         path.parent.mkdir(parents=True, exist_ok=True)
-        _to_parquet_one_row_group_per_episode(hf_dataset, path)
+        hf_dataset.to_parquet(path)
         return
 
     # If the dataset is too large, split it into smaller chunks, keeping episodes whole.
@@ -133,8 +114,8 @@ def write_hf_dataset(
         path = local_dir / DEFAULT_DATA_PATH.format(chunk_index=chunk_idx, file_index=file_idx)
         path.parent.mkdir(parents=True, exist_ok=True)
 
-        # Write the shard to a Parquet file (one row group per episode).
-        _to_parquet_one_row_group_per_episode(dataset_shard, path)
+        # Write the shard to a Parquet file.
+        dataset_shard.to_parquet(path)
 
         # Update chunk and file indices for the next iteration.
         chunk_idx, file_idx = update_chunk_file_indices(chunk_idx, file_idx, chunk_size)

tests/policies/groot/artifacts/.gitignore

@@ -0,0 +1,2 @@
+# Local-only parity artifacts (regenerated via dump_original_n1_7.py); never committed.
+*.npz

tests/policies/groot/test_groot_lerobot.py

@@ -14,7 +14,7 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
-"""Test script for LeRobot's Groot policy forward and inference passes."""
+"""Test script for LeRobot's GR00T N1.7 policy forward and inference passes."""
 
 import gc
 import os
@@ -41,13 +41,20 @@ pytestmark = pytest.mark.skipif(
 )
 
 
-# Define constants for dummy data
+# Define constants for dummy data (GR00T N1.7 native conventions).
+# N1.7 internally uses a 40-step action chunk, 132-dim state/action, and 256px images
+# (see GrootConfig.__post_init__). Use a chunk-sized action horizon so the dummy batch
+# matches the model's native action space.
 DUMMY_STATE_DIM = 44
 DUMMY_ACTION_DIM = 44
-DUMMY_ACTION_HORIZON = 16
+DUMMY_ACTION_HORIZON = 40
 IMAGE_SIZE = 256
 DEVICE = auto_select_torch_device()
-MODEL_PATH = "aractingi/bimanual-handover-groot-10k"
+# GR00T N1.7 checkpoint (N1.5 is no longer supported). The N1.7-3B base model loads
+# via GrootPolicy.from_pretrained with root-level sharded safetensors.
+MODEL_PATH = "nvidia/GR00T-N1.7-3B"
+# Valid N1.7 embodiment tag carried by the checkpoint metadata.
+EMBODIMENT_TAG = "gr1_unified"
 
 
 def cleanup_memory():
@@ -88,13 +95,13 @@ def instantiate_lerobot_groot(
     PolicyProcessorPipeline[dict[str, Any], dict[str, Any]],
     PolicyProcessorPipeline[PolicyAction, PolicyAction],
 ]:
-    """Instantiate LeRobot Groot policy with preprocessor and postprocessor."""
+    """Instantiate LeRobot GR00T N1.7 policy with preprocessor and postprocessor."""
     if from_pretrained:
         policy = GrootPolicy.from_pretrained(
             pretrained_name_or_path=model_path,
             strict=False,
         )
-        policy.config.embodiment_tag = "gr1"
+        policy.config.embodiment_tag = EMBODIMENT_TAG
     else:
         config = GrootConfig(
             base_model_path=model_path,
@@ -102,7 +109,7 @@ def instantiate_lerobot_groot(
             chunk_size=DUMMY_ACTION_HORIZON,
             image_size=[IMAGE_SIZE, IMAGE_SIZE],
             device=DEVICE,
-            embodiment_tag="gr1",
+            embodiment_tag=EMBODIMENT_TAG,
         )
         policy = GrootPolicy(config)
 
@@ -148,8 +155,8 @@ def create_dummy_data(device=DEVICE):
 
 @require_cuda
 def test_lerobot_groot_inference():
-    """Test the inference pass (select_action) of LeRobot's Groot policy."""
-    print("Test: LeRobot Groot Inference Pass")
+    """Test the inference pass (select_action) of LeRobot's GR00T N1.7 policy."""
+    print("Test: LeRobot GR00T N1.7 Inference Pass")
 
     set_seed_all(42)
 
@@ -181,9 +188,9 @@ def test_lerobot_groot_inference():
 
 @require_cuda
 def test_lerobot_groot_forward_pass():
-    """Test the forward pass of LeRobot's Groot policy."""
+    """Test the forward pass of LeRobot's GR00T N1.7 policy."""
     print("\n" + "=" * 50)
-    print("Test: LeRobot Groot Forward Pass (Training Mode)")
+    print("Test: LeRobot GR00T N1.7 Forward Pass (Training Mode)")
 
     set_seed_all(42)
 

tests/policies/groot/test_groot_vs_original.py

@@ -1,6 +1,6 @@
 #!/usr/bin/env python
 
-# Copyright 2025 The HuggingFace Inc. team. All rights reserved.
+# 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.
@@ -14,431 +14,194 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
-"""Test script to verify Groot policy integration with LeRobot vs the original implementation, only meant to be run locally!"""
+"""Parity test: original NVIDIA GR00T N1.7 vs the GR00T N1.7 integration in LeRobot.
+
+Verifies that the self-contained LeRobot reimplementation of the GR00T N1.7 action
+head + Qwen3-VL backbone produces the SAME raw model output (``action_pred``, the
+normalized flow-matching prediction before any action decoding) as NVIDIA's original
+``gr00t`` package, given byte-identical pre-processed inputs and the same
+flow-matching seed. The comparison is parametrized over every embodiment tag present
+in the checkpoint.
+
+To keep the comparison fair, the original outputs + the exact collated inputs are
+produced once per embodiment in the original ``gr00t`` env via the companion script
+``utils/dump_original_n1_7.py`` (in the ``utils`` package next to this file) and saved
+to per-tag ``.npz`` files.
+This test discovers those artifacts, replays the identical inputs through the LeRobot
+model, and compares.
+
+This test is LOCAL-only and skips on CI, when ``gr00t``-side prerequisites are not
+present, or when no artifact has been generated. By default it looks for artifacts in
+``<this dir>/artifacts/``; override with ``GROOT_N1_7_PARITY_DIR``. See the
+"Original-vs-LeRobot parity test" section of ``src/lerobot/policies/groot/README.md``
+for the full run procedure.
+"""
 
-import gc
 import os
-from copy import deepcopy
-from typing import Any
+from pathlib import Path
 
 import numpy as np
 import pytest
 import torch
 
-from lerobot.policies.groot.configuration_groot import GrootConfig
-from lerobot.policies.groot.modeling_groot import GrootPolicy
-from lerobot.policies.groot.processor_groot import make_groot_pre_post_processors
-from lerobot.processor import PolicyProcessorPipeline
-from lerobot.types import PolicyAction
-
-pytest.importorskip("gr00t")
-pytest.importorskip("transformers")
-
 pytestmark = pytest.mark.skipif(
     os.environ.get("CI") == "true" or os.environ.get("GITHUB_ACTIONS") == "true",
-    reason="This test requires local Groot installation and is not meant for CI",
+    reason="Requires a local GR00T N1.7 checkpoint + pre-generated artifacts; not for CI.",
 )
 
+from lerobot.policies.groot.configuration_groot import GROOT_N1_7  # noqa: E402,F401
 
-from gr00t.data.dataset import ModalityConfig  # noqa: E402
-from gr00t.data.embodiment_tags import EmbodimentTag  # noqa: E402
-from gr00t.data.transform.base import ComposedModalityTransform  # noqa: E402
-from gr00t.model.policy import Gr00tPolicy  # noqa: E402
+SEED = 42
+DEVICE = os.environ.get("GROOT_PARITY_DEVICE", "cuda" if torch.cuda.is_available() else "cpu")
+ATOL = float(os.environ.get("GROOT_PARITY_ATOL", "1e-3"))
+RTOL = float(os.environ.get("GROOT_PARITY_RTOL", "1e-3"))
 
-# GR1 humanoid dimensions (from pretrained model metadata)
-# The actual GR1 robot has 44 dimensions for both state and action
-# GR00TTransform will pad state to 64 and truncate action to 32
-DUMMY_STATE_DIM = 44
-DUMMY_ACTION_DIM = 44
-DUMMY_ACTION_HORIZON = 16
-IMAGE_SIZE = 256
-DEVICE = "cpu"
-MODEL_PATH = "nvidia/GR00T-N1.5-3B"
-
-GR1_BODY_PARTS = {
-    "left_arm": 7,
-    "left_hand": 6,
-    "left_leg": 6,
-    "neck": 3,
-    "right_arm": 7,
-    "right_hand": 6,
-    "right_leg": 6,
-    "waist": 3,
-}
+# Artifact filenames are original_n1_7_<embodiment_tag>.npz
+_ARTIFACT_PREFIX = "original_n1_7_"
+_ARTIFACT_SUFFIX = ".npz"
 
 
-def cleanup_memory():
-    """Clean up GPU/MPS memory to prevent OOM errors between tests."""
-    print("\nCleaning up memory...")
-    gc.collect()
-    if torch.cuda.is_available():
-        torch.cuda.empty_cache()
-        torch.cuda.synchronize()
-    if torch.backends.mps.is_available():
-        torch.mps.empty_cache()
-    print("Memory cleanup complete.")
+def _artifact_dir() -> Path:
+    """Directory holding the per-embodiment .npz artifacts.
 
-
-def set_seed_all(seed: int):
-    """Set random seed for all RNG sources to ensure reproducibility."""
-    import random
-
-    random.seed(seed)
-    np.random.seed(seed)
-    torch.manual_seed(seed)
-
-    if torch.cuda.is_available():
-        torch.cuda.manual_seed(seed)
-        torch.cuda.manual_seed_all(seed)
-
-    # Set deterministic behavior
-    torch.backends.cudnn.deterministic = True
-    torch.backends.cudnn.benchmark = False
-    torch.use_deterministic_algorithms(True, warn_only=True)
-
-
-def instantiate_lerobot_groot(
-    from_pretrained: bool = False,
-    model_path: str = MODEL_PATH,
-) -> tuple[
-    GrootPolicy,
-    PolicyProcessorPipeline[dict[str, Any], dict[str, Any]],
-    PolicyProcessorPipeline[PolicyAction, PolicyAction],
-]:
-    """Instantiate LeRobot Groot policy with preprocessor and postprocessor."""
-    if from_pretrained:
-        policy = GrootPolicy.from_pretrained(
-            pretrained_name_or_path=model_path,
-            strict=False,
-        )
-        policy.config.embodiment_tag = "gr1"
-    else:
-        config = GrootConfig(
-            base_model_path=model_path,
-            n_action_steps=DUMMY_ACTION_HORIZON,
-            chunk_size=DUMMY_ACTION_HORIZON,
-            image_size=[IMAGE_SIZE, IMAGE_SIZE],
-            device=DEVICE,
-            embodiment_tag="gr1",
-        )
-        policy = GrootPolicy(config)
-
-    policy.to(DEVICE)
-    policy.config.device = DEVICE
-
-    preprocessor, postprocessor = make_groot_pre_post_processors(
-        config=policy.config,
-        dataset_stats=None,  # Pass None for dataset_stats to disable normalization (original GR00T doesn't normalize)
-    )
-
-    return (policy, preprocessor, postprocessor)
-
-
-def instantiate_original_groot(
-    from_pretrained: bool = False,
-    model_path: str = MODEL_PATH,
-):
-    """Instantiate original Groot policy from NVIDIA's implementation."""
-    from gr00t.data.transform.concat import ConcatTransform
-    from gr00t.data.transform.state_action import StateActionToTensor
-    from gr00t.data.transform.video import VideoToNumpy, VideoToTensor
-    from gr00t.model.transforms import GR00TTransform
-
-    video_keys = ["video.ego_view"]
-    state_keys = [
-        "state"
-    ]  # Important: Use single concatenated "state" key (not split body parts) to match preprocessing
-    action_keys = [
-        "action.left_arm",
-        "action.right_arm",
-        "action.left_hand",
-        "action.right_hand",
-        "action.left_leg",
-        "action.right_leg",
-        "action.neck",
-        "action.waist",
-    ]
-    language_keys = ["annotation.human.action.task_description"]
-
-    modality_config = {
-        "video": ModalityConfig(
-            delta_indices=[0],  # Current frame only
-            modality_keys=video_keys,
-        ),
-        "state": ModalityConfig(
-            delta_indices=[0],
-            modality_keys=state_keys,
-        ),
-        "action": ModalityConfig(
-            delta_indices=list(range(DUMMY_ACTION_HORIZON)),
-            modality_keys=action_keys,
-        ),
-        "language": ModalityConfig(
-            delta_indices=[0],
-            modality_keys=language_keys,
-        ),
-    }
-
-    modality_transform = ComposedModalityTransform(
-        transforms=[
-            VideoToTensor(apply_to=video_keys),
-            VideoToNumpy(apply_to=video_keys),  # Convert to numpy (GR00TTransform expects numpy arrays)
-            # State is already a single concatenated key, so no StateActionToTensor needed
-            # Convert action from numpy to tensor
-            StateActionToTensor(apply_to=action_keys),
-            # Concatenate only video and actions (state is already single key)
-            ConcatTransform(
-                video_concat_order=video_keys,
-                state_concat_order=[],  # Empty:state is already single key
-                action_concat_order=action_keys,
-            ),
-            GR00TTransform(
-                max_state_dim=64,
-                max_action_dim=32,
-                state_horizon=1,
-                action_horizon=DUMMY_ACTION_HORIZON,
-                training=False,
-            ),
-        ]
-    )
-
-    policy = Gr00tPolicy(
-        model_path=model_path,
-        embodiment_tag=EmbodimentTag.GR1,
-        modality_config=modality_config,
-        modality_transform=modality_transform,
-        device=DEVICE,
-    )
-
-    return policy, modality_config, modality_transform
-
-
-def create_dummy_data(device=DEVICE):
-    """Create dummy data for testing both implementations."""
-    batch_size = 2
-    prompt = "Pick up the red cube and place it in the bin"
-    state = torch.randn(batch_size, DUMMY_STATE_DIM, dtype=torch.float32, device=device)
-
-    batch = {
-        "observation.state": state,
-        "action": torch.randn(
-            batch_size,
-            DUMMY_ACTION_HORIZON,
-            DUMMY_ACTION_DIM,
-            dtype=torch.float32,
-            device=device,  # Action ground truth (for training)
-        ),
-        "observation.images.ego_view": torch.rand(
-            batch_size,
-            3,
-            IMAGE_SIZE,
-            IMAGE_SIZE,
-            dtype=torch.float32,
-            device=device,  # Images in [0, 1] range as expected by LeRobot
-        ),
-        "task": [prompt for _ in range(batch_size)],
-    }
-
-    return batch
-
-
-def convert_lerobot_to_original_format(batch, modality_config):
-    """Convert LeRobot batch format to original Groot format.
-
-    The original Groot expects observations in this format:
-    {
-        "video.<camera_name>": np.ndarray (T, H, W, C) or (B, T, H, W, C)
-        "state.<state_component>": np.ndarray (T, D) or (B, T, D)
-        "action.<action_component>": np.ndarray (T, D) or (B, T, D)
-        "annotation.<annotation_type>": str or list[str]
-    }
+    Self-contained by default: a sibling ``artifacts/`` directory next to this test.
+    Override with ``GROOT_N1_7_PARITY_DIR`` (e.g. to point at a scratch location).
+    The directory is read-only here -- it is populated by ``utils/dump_original_n1_7.py``
+    run in the original gr00t environment; the test never creates it.
     """
-    # Original Groot expects (T, H, W, C) format for images
-    # LeRobot has (B, C, H, W) format, so we need to convert
-    observation = {}
-
-    for img_key in ["ego_view"]:
-        lerobot_key = f"observation.images.{img_key}"
-        if lerobot_key in batch:
-            img = batch[lerobot_key]
-            # Convert from (B, C, H, W) to (B, T=1, H, W, C)
-            img_np = img.permute(0, 2, 3, 1).unsqueeze(1).cpu().numpy()
-            # Convert [0, 1] to [0, 255] uint8 as expected by original
-            img_np = (img_np * 255).astype(np.uint8)
-            observation[f"video.{img_key}"] = img_np
-
-    # Important: The Original's GR00TTransform expects "state" as (B, T, D), not split body parts
-    if "observation.state" in batch:
-        state = batch["observation.state"]
-        state_np = state.unsqueeze(1).cpu().numpy()  # (B, 1, D)
-        observation["state"] = state_np
-
-    if "action" in batch:
-        action = batch["action"]
-        action_np = action.cpu().numpy()
-
-        start_idx = 0
-        for part_name, part_dim in GR1_BODY_PARTS.items():
-            end_idx = start_idx + part_dim
-            observation[f"action.{part_name}"] = action_np[:, :, start_idx:end_idx]
-            start_idx = end_idx
-
-    if "task" in batch:
-        task_list = batch["task"]
-        # GR00TTransform expects language with (B, T) shape for batched data
-        # Create a (B, T=1) array where each element is the string directly
-        bsz = len(task_list)
-        task_array = np.empty((bsz, 1), dtype=object)
-        for i in range(bsz):
-            task_array[i, 0] = task_list[i]  # Assign string directly to each (i, 0) position
-        observation["annotation.human.action.task_description"] = task_array
-
-    return observation
+    env = os.environ.get("GROOT_N1_7_PARITY_DIR")
+    if env:
+        return Path(env)
+    return Path(__file__).resolve().parent / "artifacts"
 
 
-def test_groot_original_vs_lerobot_pretrained():
-    """Test Groot original implementation vs LeRobot implementation with pretrained weights."""
-    print("Test: Groot Original vs LeRobot with Pretrained Weights (Inference)")
+def _discover_artifacts() -> list[tuple[str, Path]]:
+    """Return [(embodiment_tag, npz_path), ...] for every dumped artifact."""
+    d = _artifact_dir()
+    if not d.is_dir():
+        return []
+    out = []
+    for p in sorted(d.glob(f"{_ARTIFACT_PREFIX}*{_ARTIFACT_SUFFIX}")):
+        tag = p.name[len(_ARTIFACT_PREFIX) : -len(_ARTIFACT_SUFFIX)]
+        out.append((tag, p))
+    return out
 
-    set_seed_all(42)
 
-    lerobot_policy, lerobot_preprocessor, lerobot_postprocessor = instantiate_lerobot_groot(
-        from_pretrained=True
+def _resolve_checkpoint() -> str:
+    env = os.environ.get("GROOT_N1_7_LIBERO_CKPT")
+    if env:
+        if not Path(env).exists():
+            pytest.skip(f"GROOT_N1_7_LIBERO_CKPT={env} does not exist")
+        return env
+    try:
+        from huggingface_hub import snapshot_download
+
+        root = snapshot_download(
+            "nvidia/GR00T-N1.7-LIBERO",
+            local_files_only=True,
+            allow_patterns=["libero_10/*"],
+        )
+    except Exception as exc:  # noqa: BLE001
+        pytest.skip(f"GR00T N1.7 LIBERO checkpoint not available locally: {exc}")
+    ckpt = Path(root) / "libero_10"
+    if not (ckpt / "config.json").exists():
+        pytest.skip(f"GR00T N1.7 LIBERO checkpoint incomplete at {ckpt}")
+    return str(ckpt)
+
+
+def _load_artifact(path: Path):
+    data = np.load(path, allow_pickle=True)
+    original_action = torch.from_numpy(data["action_pred"]).float()
+    dtypes = dict(zip(data["meta_keys"].tolist(), data["meta_dtypes"].tolist(), strict=False))
+    inputs = {}
+    for key in data.files:
+        if not key.startswith("in::"):
+            continue
+        name = key[4:]
+        arr = data[key]
+        t = torch.from_numpy(np.asarray(arr))
+        declared = dtypes.get(key, "")
+        if "int" in declared or "long" in declared:
+            t = t.long()
+        inputs[name] = t
+    return original_action, inputs
+
+
+def _unflatten(inputs: dict[str, torch.Tensor]) -> dict:
+    """Rebuild the nested model-input dict from dot-prefixed flat keys."""
+    nested: dict = {}
+    for dotted, value in inputs.items():
+        parts = dotted.split(".")
+        cur = nested
+        for p in parts[:-1]:
+            cur = cur.setdefault(p, {})
+        cur[parts[-1]] = value
+    return nested.get("inputs", nested)
+
+
+@pytest.fixture(scope="module")
+def lerobot_model():
+    """Load the LeRobot GR00T N1.7 model once (fp32 + SDPA) and reuse across tags."""
+    ckpt = _resolve_checkpoint()
+    from lerobot.policies.groot.groot_n1_7 import GR00TN17
+
+    model = GR00TN17.from_pretrained(
+        ckpt,
+        tune_llm=False,
+        tune_visual=False,
+        tune_projector=False,
+        tune_diffusion_model=False,
+        tune_vlln=False,
+        transformers_loading_kwargs={"trust_remote_code": True},
     )
-    original_policy, modality_config, modality_transform = instantiate_original_groot(from_pretrained=True)
+    # fp32 + SDPA on both sides: bf16 + differing attention kernels otherwise introduce
+    # ~1e-2 numerical noise unrelated to the implementations.
+    model.compute_dtype = "float32"
+    model.config.compute_dtype = model.compute_dtype
+    model.to(device=DEVICE, dtype=torch.float32)
+    model.eval()
+    return model
 
-    batch = create_dummy_data()
-    batch_lerobot = deepcopy(batch)
 
-    print("\n[LeRobot] Running inference...")
-    lerobot_policy.eval()
-    batch_lerobot_processed = lerobot_preprocessor(batch_lerobot)
+_ARTIFACTS = _discover_artifacts()
 
-    # Important: Reset seed immediately before inference to ensure identical RNG state
-    torch.manual_seed(42)
 
-    with torch.no_grad():
-        lerobot_actions = lerobot_policy.select_action(batch_lerobot_processed)
+@pytest.mark.skipif(
+    not _ARTIFACTS,
+    reason=(
+        "No GR00T N1.7 parity artifacts found. Generate them first in the original gr00t "
+        "env:\n  .venv-original/bin/python tests/policies/groot/utils/dump_original_n1_7.py "
+        "--ckpt <ckpt> --out-dir tests/policies/groot/artifacts --device cuda"
+    ),
+)
+@pytest.mark.parametrize("embodiment_tag,artifact", _ARTIFACTS, ids=[t for t, _ in _ARTIFACTS])
+def test_groot_get_action_parity(embodiment_tag, artifact, lerobot_model):
+    """Raw model.get_action(action_pred) parity per embodiment: original vs LeRobot."""
+    original_action, flat_inputs = _load_artifact(artifact)
+    model_inputs = _unflatten(flat_inputs)
 
-    print("\n[Original] Running inference...")
-    original_policy.model.eval()
-    observation = convert_lerobot_to_original_format(batch, modality_config)
-    original_obs_transformed = modality_transform(deepcopy(observation))
+    # Align the flow-matching RNG exactly as the producer did (seed right before sampling).
+    torch.manual_seed(SEED)
+    if torch.cuda.is_available():
+        torch.cuda.manual_seed_all(SEED)
+    with torch.inference_mode():
+        out = lerobot_model.get_action(model_inputs)
+    lerobot_action = out["action_pred"].float().cpu()
 
-    # Important: Reset seed immediately before inference to ensure identical RNG state
-    torch.manual_seed(42)
+    t = min(original_action.shape[1], lerobot_action.shape[1])
+    d = min(original_action.shape[2], lerobot_action.shape[2])
+    original_action = original_action[:, :t, :d]
+    lerobot_action = lerobot_action[:, :t, :d]
 
-    with torch.no_grad():
-        original_model_output = original_policy.model.get_action(original_obs_transformed)
-        original_actions_raw = original_model_output["action_pred"]  # [2, 16, 32]
-    # Take first timestep
-    original_actions = original_actions_raw[:, 0, :].to(lerobot_actions.device).to(lerobot_actions.dtype)
-
-    print("Action Comparison:")
-    diff = lerobot_actions - original_actions
-    abs_diff = torch.abs(diff)
-
-    for batch_idx in range(lerobot_actions.shape[0]):
-        print(f"\n{'=' * 60}")
-        print(f"Batch {batch_idx}")
-        print(f"{'=' * 60}")
-        print(f"{'Idx':<5} {'LeRobot':<14} {'Original':<14} {'Difference':<14}")
-        print("-" * 60)
-        for action_idx in range(lerobot_actions.shape[1]):
-            lr_val = lerobot_actions[batch_idx, action_idx].item()
-            orig_val = original_actions[batch_idx, action_idx].item()
-            diff_val = abs(lr_val - orig_val)
-            sign = "+" if (lr_val - orig_val) > 0 else "-"
-            print(f"{action_idx:<5} {lr_val:>13.6f} {orig_val:>13.6f} {sign}{diff_val:>12.6f}")
-
-    max_diff = abs_diff.max().item()
-    tolerance = 0.001
-    assert torch.allclose(lerobot_actions, original_actions, atol=tolerance), (
-        f"Actions differ by more than tolerance ({tolerance}): max diff = {max_diff:.6f}"
+    diff = torch.abs(lerobot_action - original_action)
+    max_diff = diff.max().item()
+    print(
+        f"\n[{embodiment_tag}] shapes lerobot={tuple(lerobot_action.shape)} "
+        f"original={tuple(original_action.shape)}  "
+        f"max|diff|={max_diff:.6e}  mean|diff|={diff.mean().item():.6e}"
     )
-    print(f"\nSuccess: Actions match within tolerance ({tolerance})!")
 
-    del lerobot_policy, lerobot_preprocessor, lerobot_postprocessor
-    del original_policy, modality_config, modality_transform
-    del batch, batch_lerobot, observation
-    cleanup_memory()
-
-
-def test_groot_forward_pass_comparison():
-    """Test forward pass comparison between LeRobot and Original Groot implementations."""
-    print("Test: Forward Pass Comparison (Training Mode)")
-
-    set_seed_all(42)
-
-    lerobot_policy, lerobot_preprocessor, lerobot_postprocessor = instantiate_lerobot_groot(
-        from_pretrained=True
+    assert torch.allclose(lerobot_action, original_action, atol=ATOL, rtol=RTOL), (
+        f"GR00T N1.7 raw action_pred differs for embodiment '{embodiment_tag}' beyond "
+        f"atol={ATOL}, rtol={RTOL}: max|diff|={max_diff:.6e}"
     )
-    original_policy, modality_config, modality_transform = instantiate_original_groot(from_pretrained=True)
-
-    batch = create_dummy_data()
-    lerobot_policy.eval()
-    original_policy.model.eval()
-
-    print("\n[LeRobot] Running forward pass...")
-    batch_lerobot = deepcopy(batch)
-    batch_lerobot_processed = lerobot_preprocessor(batch_lerobot)
-
-    set_seed_all(42)
-    with torch.no_grad():
-        lerobot_loss, lerobot_metrics = lerobot_policy.forward(batch_lerobot_processed)
-
-    print(f"  Loss: {lerobot_loss.item():.6f}")
-
-    print("\n[Original] Running forward pass...")
-    observation = convert_lerobot_to_original_format(batch, modality_config)
-    transformed_obs = modality_transform(observation)
-
-    if "action" not in transformed_obs:
-        action_for_forward = batch_lerobot_processed["action"]
-        action_mask_for_forward = batch_lerobot_processed["action_mask"]
-
-        # Match action horizon if needed
-        if action_for_forward.shape[1] != original_policy.model.action_horizon:
-            if action_for_forward.shape[1] < original_policy.model.action_horizon:
-                pad_size = original_policy.model.action_horizon - action_for_forward.shape[1]
-                last_action = action_for_forward[:, -1:, :]
-                padding = last_action.repeat(1, pad_size, 1)
-                action_for_forward = torch.cat([action_for_forward, padding], dim=1)
-
-                mask_padding = torch.zeros(
-                    action_mask_for_forward.shape[0],
-                    pad_size,
-                    action_mask_for_forward.shape[2],
-                    dtype=action_mask_for_forward.dtype,
-                    device=action_mask_for_forward.device,
-                )
-                action_mask_for_forward = torch.cat([action_mask_for_forward, mask_padding], dim=1)
-            else:
-                action_for_forward = action_for_forward[:, : original_policy.model.action_horizon, :]
-                action_mask_for_forward = action_mask_for_forward[
-                    :, : original_policy.model.action_horizon, :
-                ]
-
-        transformed_obs["action"] = action_for_forward
-        transformed_obs["action_mask"] = action_mask_for_forward
-
-    set_seed_all(42)
-    with torch.no_grad():
-        original_outputs = original_policy.model.forward(transformed_obs)
-
-    original_loss = original_outputs["loss"]
-    print(f"  Loss: {original_loss.item():.6f}")
-
-    loss_diff = abs(lerobot_loss.item() - original_loss.item())
-    loss_rel_diff = loss_diff / (abs(original_loss.item()) + 1e-8) * 100
-
-    print("\nLoss Values:")
-    print(f"  LeRobot: {lerobot_loss.item():.6f}")
-    print(f"  Original: {original_loss.item():.6f}")
-    print(f"  Absolute difference: {loss_diff:.6f}")
-    print(f"  Relative difference: {loss_rel_diff:.2f}%")
-
-    del lerobot_policy, lerobot_preprocessor, lerobot_postprocessor
-    del original_policy, modality_config, modality_transform
-    del batch, batch_lerobot, observation, transformed_obs
-    cleanup_memory()

tests/policies/groot/utils/__init__.py

@@ -0,0 +1 @@
+"""Utilities shared by GR00T policy tests."""

tests/policies/groot/utils/dump_original_n1_7.py

@@ -0,0 +1,198 @@
+#!/usr/bin/env python
+# Copyright 2026 The HuggingFace Inc. team. All rights reserved.
+# Licensed under the Apache License, Version 2.0 (the "License").
+"""Producer (run in the ORIGINAL gr00t env): dump original GR00T N1.7 outputs + inputs.
+
+The original NVIDIA ``gr00t`` package pins ``transformers==4.57.3`` (py3.10) and its
+model-config dataclasses are incompatible with the ``transformers==5.x`` that the
+LeRobot GR00T N1.7 integration requires. The two implementations therefore cannot be
+imported in the same Python process. To keep the parity comparison FAIR, we run the
+original model in its native env here and serialize, PER EMBODIMENT TAG:
+
+  * the exact pre-processed/collated model inputs (so the LeRobot side consumes the
+    byte-identical tensors -- same image preprocessing, tokenization, normalization),
+  * the random seed used right before the flow-matching sampler,
+  * the raw ``action_pred`` tensor returned by ``model.get_action`` (normalized space,
+    before any per-implementation action decoding).
+
+Inputs are built GENERICALLY from the checkpoint metadata (no per-tag hardcoding):
+state keys + dims come from ``statistics.json``; video + language keys come from the
+processor's per-embodiment modality configs. This lets us test many embodiment tags
+from the SAME checkpoint and confirm the LeRobot integration is not overfit to
+``libero_sim``.
+
+The companion pytest (run in the LeRobot env) loads each .npz, replays the identical
+inputs + seed through the LeRobot GR00T N1.7 model, and asserts the outputs match.
+
+Usage:
+    .venv-original/bin/python tests/policies/groot/utils/dump_original_n1_7.py \
+        --ckpt <path-to-GR00T-N1.7-LIBERO/libero_10> \
+        --out-dir tests/policies/groot/artifacts \
+        [--tags libero_sim,oxe_droid_relative_eef_relative_joint,...] \
+        [--device cuda] [--seed 42]
+
+If --tags is omitted, every embodiment present in the checkpoint statistics is dumped.
+"""
+
+import argparse
+import json
+import os
+from pathlib import Path
+
+import numpy as np
+import torch
+
+IMAGE_SIZE = 256
+BATCH_SIZE = 2
+PROMPT = "pick up the black bowl and place it on the plate"
+
+
+def load_statistics(ckpt: str) -> dict:
+    with open(os.path.join(ckpt, "statistics.json")) as f:
+        return json.load(f)
+
+
+def make_observation(seed: int, video_keys, lang_key, state_spec):
+    """Build a dummy observation dict generically from the embodiment metadata."""
+    rng = np.random.default_rng(seed)
+    video = {
+        k: rng.integers(0, 256, (BATCH_SIZE, 1, IMAGE_SIZE, IMAGE_SIZE, 3), dtype=np.uint8)
+        for k in video_keys
+    }
+    # One ndarray per state key, shape (B, T=1, key_dim); dim taken from statistics.
+    # Keys with dim 0 (e.g. disabled eef on some embodiments) are still emitted as
+    # present-but-empty so the processor's state transform finds every expected key.
+    state = {
+        k: rng.standard_normal((BATCH_SIZE, 1, dim)).astype(np.float32)
+        for k, dim in state_spec
+    }
+    language = {lang_key: [[PROMPT] for _ in range(BATCH_SIZE)]}
+    return {"video": video, "state": state, "language": language}
+
+
+def dump_one_tag(policy, fair_model, tag, modality_cfg, state_spec, args, out_path):
+    from gr00t.data.types import MessageType
+
+    video_keys = modality_cfg["video"].modality_keys
+    lang_key = modality_cfg["language"].modality_keys[0]
+    observation = make_observation(args.seed, video_keys, lang_key, state_spec)
+
+    # Point the policy preprocessing at this embodiment (mirrors Gr00tPolicy.__init__).
+    policy.embodiment_tag = type(policy.embodiment_tag)(tag)
+    policy.modality_configs = {
+        k: v for k, v in policy.processor.get_modality_configs()[tag].items() if k != "rl_info"
+    }
+    policy.language_key = policy.modality_configs["language"].modality_keys[0]
+
+    torch.manual_seed(args.seed)
+    np.random.seed(args.seed)
+
+    unbatched = policy._unbatch_observation(observation)
+    processed = []
+    for obs in unbatched:
+        vla = policy._to_vla_step_data(obs)
+        processed.append(policy.processor([{"type": MessageType.EPISODE_STEP.value, "content": vla}]))
+    collated = policy.collate_fn(processed)
+
+    def to_dev(x):
+        if isinstance(x, torch.Tensor) and torch.is_floating_point(x):
+            return x.to(args.device, torch.float32)
+        if isinstance(x, torch.Tensor):
+            return x.to(args.device)
+        if isinstance(x, dict):
+            return {k: to_dev(v) for k, v in x.items()}
+        return x
+
+    collated = {k: to_dev(v) for k, v in collated.items()}
+
+    torch.manual_seed(args.seed)
+    with torch.inference_mode():
+        out = fair_model.get_action(**collated)
+    action_pred = out["action_pred"].float().cpu().numpy()
+
+    flat, meta = {}, {}
+
+    def flatten(prefix, obj):
+        if isinstance(obj, torch.Tensor):
+            arr = obj.float().cpu().numpy() if torch.is_floating_point(obj) else obj.cpu().numpy()
+            flat[f"in::{prefix}"] = arr
+            meta[f"in::{prefix}"] = str(obj.dtype)
+        elif isinstance(obj, dict):
+            for k, v in obj.items():
+                flatten(f"{prefix}.{k}" if prefix else k, v)
+        elif isinstance(obj, (list, tuple)):
+            flat[f"in::{prefix}"] = np.array(obj, dtype=object)
+        else:
+            flat[f"in::{prefix}"] = np.array(obj)
+
+    flatten("", collated)
+
+    out_path.parent.mkdir(parents=True, exist_ok=True)
+    np.savez(
+        out_path,
+        action_pred=action_pred,
+        seed=np.array(args.seed),
+        device=np.array(args.device),
+        embodiment_tag=np.array(tag),
+        meta_keys=np.array(list(meta.keys()), dtype=object),
+        meta_dtypes=np.array(list(meta.values()), dtype=object),
+        **flat,
+    )
+    print(f"[{tag}] action_pred {action_pred.shape} -> {out_path.name} ({os.path.getsize(out_path)} B)")
+
+
+def main():
+    ap = argparse.ArgumentParser()
+    ap.add_argument("--ckpt", required=True)
+    ap.add_argument("--out-dir", required=True, help="directory for per-tag .npz files")
+    ap.add_argument("--tags", default="", help="comma-separated embodiment tags (default: all in stats)")
+    ap.add_argument("--device", default="cuda")
+    ap.add_argument("--seed", type=int, default=42)
+    args = ap.parse_args()
+
+    from gr00t.policy.gr00t_policy import Gr00tPolicy
+    from transformers import AutoConfig, AutoModel
+
+    stats = load_statistics(args.ckpt)
+    requested = [t.strip() for t in args.tags.split(",") if t.strip()] or list(stats.keys())
+
+    # Load the policy once (for its processor/preprocessing) on any valid tag.
+    bootstrap_tag = "libero_sim" if "libero_sim" in stats else requested[0]
+    policy = Gr00tPolicy(embodiment_tag=bootstrap_tag, model_path=args.ckpt, device=args.device)
+    all_modality = policy.processor.get_modality_configs()
+
+    # Load a FAIR model (SDPA + fp32) once and reuse across tags. Otherwise the
+    # original checkpoint default (flash_attention_2 + bf16) introduces kernel/rounding
+    # noise vs the LeRobot env (which has no flash_attn and runs SDPA).
+    cfg = AutoConfig.from_pretrained(args.ckpt, trust_remote_code=True)
+    cfg.use_flash_attention = False
+    cfg.load_bf16 = False
+    fair_model = AutoModel.from_pretrained(args.ckpt, config=cfg, trust_remote_code=True)
+    fair_model.to(device=args.device, dtype=torch.float32)
+    fair_model.eval()
+
+    out_dir = Path(args.out_dir)
+    done, skipped = [], []
+    for tag in requested:
+        if tag not in stats or tag not in all_modality:
+            print(f"[skip] {tag}: not present in checkpoint statistics/modality configs")
+            skipped.append(tag)
+            continue
+        state_spec = [(k, len(v["min"])) for k, v in stats[tag]["state"].items()]
+        try:
+            dump_one_tag(
+                policy, fair_model, tag, all_modality[tag], state_spec, args,
+                out_dir / f"original_n1_7_{tag}.npz",
+            )
+            done.append(tag)
+        except Exception as exc:  # noqa: BLE001
+            print(f"[fail] {tag}: {type(exc).__name__}: {exc}")
+            skipped.append(tag)
+
+    print(f"\nDumped {len(done)} tags: {done}")
+    if skipped:
+        print(f"Skipped/failed {len(skipped)} tags: {skipped}")
+
+
+if __name__ == "__main__":
+    main()

tests/processor/test_pipeline.py

@@ -24,7 +24,6 @@ from typing import Any
 import pytest
 import torch
 import torch.nn as nn
-from safetensors.torch import load_file
 
 pytest.importorskip("datasets", reason="datasets is required (install lerobot[dataset])")
 
@@ -175,53 +174,6 @@ class MockStepWithTensorState(ProcessorStep):
         return features
 
 
-class MockLazyTensorStateStep(ProcessorStep):
-    """Mock step whose tensor state is not present in constructor config."""
-
-    def __init__(
-        self, name: str = "lazy_tensor_step", scale: float = 1.0, initial_value: float | None = None
-    ):
-        self.name = name
-        self.scale = scale
-        self.tensor_state: torch.Tensor | None = None
-
-        if initial_value is not None:
-            self.tensor_state = torch.tensor([initial_value], dtype=torch.float32)
-
-    def __call__(self, transition: EnvTransition) -> EnvTransition:
-        """Return the transition unchanged."""
-        return transition
-
-    def get_config(self) -> dict[str, Any]:
-        """Return constructor config while intentionally omitting tensor state."""
-        return {
-            "name": self.name,
-            "scale": self.scale,
-        }
-
-    def state_dict(self) -> dict[str, torch.Tensor]:
-        """Return tensor state only after it has been initialized or loaded."""
-        if self.tensor_state is None:
-            return {}
-
-        return {"tensor_state": self.tensor_state}
-
-    def load_state_dict(self, state: dict[str, torch.Tensor]) -> None:
-        """Load tensor state."""
-        self.tensor_state = state["tensor_state"].clone()
-
-    def transform_features(
-        self, features: dict[PipelineFeatureType, dict[str, PolicyFeature]]
-    ) -> dict[PipelineFeatureType, dict[str, PolicyFeature]]:
-        """Return features unchanged."""
-        return features
-
-
-@ProcessorStepRegistry.register("registered_lazy_tensor_state_step")
-class RegisteredLazyTensorStateStep(MockLazyTensorStateStep):
-    """Registered lazy tensor state step for registry-based serialization tests."""
-
-
 def test_empty_pipeline():
     """Test pipeline with no steps."""
     pipeline = DataProcessorPipeline([], to_transition=identity_transition, to_output=identity_transition)
@@ -668,178 +620,6 @@ def test_mixed_json_and_tensor_state():
         assert torch.allclose(loaded_step.running_mean, step.running_mean)
 
 
-def test_get_config_matches_saved_json():
-    """Test that in-memory config matches the config written by save_pretrained."""
-    stateless_step = MockStep(name="stateless")
-    stateful_step = MockLazyTensorStateStep(name="stateful", initial_value=4.0)
-    pipeline = DataProcessorPipeline([stateless_step, stateful_step], name="Memory Pipeline")
-
-    in_memory_config = pipeline.get_config()
-
-    assert pipeline.get_config() == in_memory_config
-
-    with tempfile.TemporaryDirectory() as tmp_dir:
-        pipeline.save_pretrained(tmp_dir)
-
-        config_path = Path(tmp_dir) / "memory_pipeline.json"
-        with open(config_path) as file_pointer:
-            saved_config = json.load(file_pointer)
-
-    assert in_memory_config == saved_config
-    assert "state_file" not in in_memory_config["steps"][0]
-    assert in_memory_config["steps"][1]["state_file"] == "memory_pipeline_step_1.safetensors"
-
-
-def test_state_dict_matches_saved_safetensors():
-    """Test that in-memory state matches the safetensors written by save_pretrained."""
-    stateful_step = MockLazyTensorStateStep(initial_value=7.0)
-    pipeline = DataProcessorPipeline([stateful_step], name="Stateful Pipeline")
-
-    in_memory_state_dict = pipeline.state_dict()
-    state_filename = "stateful_pipeline_step_0.safetensors"
-    state_key = "stateful_pipeline_step_0"
-
-    assert set(in_memory_state_dict) == {state_key}
-    assert set(in_memory_state_dict[state_key]) == {"tensor_state"}
-
-    in_memory_state_dict[state_key]["tensor_state"].add_(1)
-    assert stateful_step.tensor_state is not None
-    assert torch.equal(stateful_step.tensor_state, torch.tensor([7.0]))
-
-    with tempfile.TemporaryDirectory() as tmp_dir:
-        pipeline.save_pretrained(tmp_dir)
-        saved_state_dict = load_file(Path(tmp_dir) / state_filename)
-
-    torch.testing.assert_close(saved_state_dict["tensor_state"], torch.tensor([7.0]))
-
-
-def test_save_pretrained_still_writes_expected_serialization_files():
-    """Test that save_pretrained keeps the existing config and state filenames."""
-    stateful_step = MockLazyTensorStateStep(initial_value=3.0)
-    pipeline = DataProcessorPipeline([stateful_step], name="Policy Preprocessor")
-
-    with tempfile.TemporaryDirectory() as tmp_dir:
-        pipeline.save_pretrained(tmp_dir)
-
-        save_path = Path(tmp_dir)
-        assert (save_path / "policy_preprocessor.json").exists()
-        assert (save_path / "policy_preprocessor_step_0.safetensors").exists()
-
-
-def test_from_config_round_trips_stateful_pipeline():
-    """Test that from_config rebuilds a stateful pipeline from in-memory artifacts."""
-    stateful_step = MockLazyTensorStateStep(name="roundtrip", initial_value=11.0)
-    pipeline = DataProcessorPipeline([stateful_step], name="Roundtrip Pipeline")
-    config = pipeline.get_config()
-    pipeline_state_dict = pipeline.state_dict()
-
-    loaded_pipeline = DataProcessorPipeline.from_config(config, state_dict=pipeline_state_dict)
-    loaded_step = loaded_pipeline.steps[0]
-
-    assert len(loaded_pipeline) == 1
-    assert isinstance(loaded_step, MockLazyTensorStateStep)
-    torch.testing.assert_close(loaded_step.tensor_state, torch.tensor([11.0]))
-
-
-def test_from_config_round_trips_registered_stateful_pipeline():
-    """Test that from_config resolves registry steps and loads their named tensor state."""
-    stateful_step = RegisteredLazyTensorStateStep(name="registered", initial_value=29.0)
-    pipeline = DataProcessorPipeline([stateful_step], name="Registry Pipeline")
-    config = pipeline.get_config()
-    pipeline_state_dict = pipeline.state_dict()
-    state_filename = "registry_pipeline_step_0_registered_lazy_tensor_state_step.safetensors"
-    state_key = "registry_pipeline_step_0_registered_lazy_tensor_state_step"
-
-    assert config["steps"][0]["registry_name"] == "registered_lazy_tensor_state_step"
-    assert config["steps"][0]["state_file"] == state_filename
-    assert set(pipeline_state_dict) == {state_key}
-
-    loaded_pipeline = DataProcessorPipeline.from_config(config, state_dict=pipeline_state_dict)
-    loaded_step = loaded_pipeline.steps[0]
-
-    assert isinstance(loaded_step, RegisteredLazyTensorStateStep)
-    assert loaded_step.tensor_state is not None
-    torch.testing.assert_close(loaded_step.tensor_state, torch.tensor([29.0]))
-
-
-def test_from_config_preserves_state_metadata_for_empty_initial_state():
-    """Test in-memory loading when rebuilt steps start without tensor state."""
-    stateful_step = MockLazyTensorStateStep(name="lazy", initial_value=13.0)
-    pipeline = DataProcessorPipeline([stateful_step], name="Lazy Pipeline")
-    config = pipeline.get_config()
-    pipeline_state_dict = pipeline.state_dict()
-
-    loaded_pipeline = DataProcessorPipeline.from_config(config)
-    loaded_step = loaded_pipeline.steps[0]
-
-    assert isinstance(loaded_step, MockLazyTensorStateStep)
-    assert loaded_step.state_dict() == {}
-    assert "state_file" not in loaded_pipeline.get_config()["steps"][0]
-
-    loaded_pipeline.load_state_dict(pipeline_state_dict)
-
-    torch.testing.assert_close(loaded_step.tensor_state, torch.tensor([13.0]))
-
-
-def test_from_config_applies_overrides_before_state_loading():
-    """Test that constructor overrides and tensor state loading are separate operations."""
-    stateful_step = MockLazyTensorStateStep(name="override", scale=1.0, initial_value=17.0)
-    pipeline = DataProcessorPipeline([stateful_step], name="Override Pipeline")
-    config = pipeline.get_config()
-    pipeline_state_dict = pipeline.state_dict()
-
-    loaded_pipeline = DataProcessorPipeline.from_config(
-        config,
-        state_dict=pipeline_state_dict,
-        overrides={"MockLazyTensorStateStep": {"scale": 5.0}},
-    )
-    loaded_step = loaded_pipeline.steps[0]
-
-    assert isinstance(loaded_step, MockLazyTensorStateStep)
-    assert loaded_step.scale == 5.0
-    torch.testing.assert_close(loaded_step.tensor_state, torch.tensor([17.0]))
-
-
-def test_load_state_dict_raises_on_missing_expected_state():
-    """Test loading raises when serialized config expects missing state."""
-    stateful_step = MockLazyTensorStateStep(initial_value=19.0)
-    pipeline = DataProcessorPipeline([stateful_step], name="Missing Pipeline")
-    loaded_pipeline = DataProcessorPipeline.from_config(pipeline.get_config())
-
-    with pytest.raises(KeyError, match="missing_pipeline_step_0"):
-        loaded_pipeline.load_state_dict({})
-
-
-def test_load_state_dict_raises_on_unexpected_extra_state():
-    """Test loading raises on unexpected top-level state keys."""
-    pipeline = DataProcessorPipeline([MockStep(name="stateless")], name="Unexpected Pipeline")
-
-    with pytest.raises(KeyError, match="extra"):
-        pipeline.load_state_dict({"extra": {"tensor_state": torch.tensor([1.0])}})
-
-
-def test_stateless_pipeline_in_memory_serialization_returns_empty_state():
-    """Test stateless in-memory serialization and loading."""
-    pipeline = DataProcessorPipeline([MockStep(name="stateless")], name="Stateless Pipeline")
-    config = pipeline.get_config()
-    config_without_name = {"steps": config["steps"]}
-
-    assert pipeline.state_dict() == {}
-    assert all("state_file" not in step_entry for step_entry in config["steps"])
-
-    loaded_pipeline = DataProcessorPipeline.from_config(config_without_name, state_dict={})
-
-    assert loaded_pipeline.name == "DataProcessorPipeline"
-    assert loaded_pipeline.state_dict() == {}
-
-
-@pytest.mark.parametrize("invalid_config", [None, [], "not config"])
-def test_from_config_rejects_non_dict_config(invalid_config):
-    """Test from_config reports invalid top-level config values cleanly."""
-    with pytest.raises(ValueError, match="not a valid processor configuration"):
-        DataProcessorPipeline.from_config(invalid_config)  # type: ignore[arg-type]
-
-
 class MockModuleStep(ProcessorStep, nn.Module):
     """Mock step that inherits from nn.Module to test state_dict handling of module parameters."""
 

tests/test_rollout.py

@@ -59,7 +59,6 @@ def test_strategy_config_types():
     from lerobot.rollout import (
         BaseStrategyConfig,
         DAggerStrategyConfig,
-        EpisodicStrategyConfig,
         HighlightStrategyConfig,
         SentryStrategyConfig,
     )
@@ -68,7 +67,6 @@ def test_strategy_config_types():
     assert SentryStrategyConfig().type == "sentry"
     assert HighlightStrategyConfig().type == "highlight"
     assert DAggerStrategyConfig().type == "dagger"
-    assert EpisodicStrategyConfig().type == "episodic"
 
 
 def test_dagger_config_invalid_input_device():
@@ -205,8 +203,6 @@ def test_create_strategy_dispatches():
         BaseStrategyConfig,
         DAggerStrategy,
         DAggerStrategyConfig,
-        EpisodicStrategy,
-        EpisodicStrategyConfig,
         SentryStrategy,
         SentryStrategyConfig,
         create_strategy,
@@ -215,7 +211,6 @@ def test_create_strategy_dispatches():
     assert isinstance(create_strategy(BaseStrategyConfig()), BaseStrategy)
     assert isinstance(create_strategy(SentryStrategyConfig()), SentryStrategy)
     assert isinstance(create_strategy(DAggerStrategyConfig()), DAggerStrategy)
-    assert isinstance(create_strategy(EpisodicStrategyConfig()), EpisodicStrategy)
 
 
 def test_create_strategy_unknown_raises():

uv.lock

@@ -1084,8 +1084,8 @@ wheels = [
 
 [[package]]
 name = "datasets"
-version = "5.0.1.dev0"
-source = { git = "https://github.com/huggingface/datasets.git?rev=2c45eab1bb975ac3d846f2aa6217b82adec8eba3#2c45eab1bb975ac3d846f2aa6217b82adec8eba3" }
+version = "4.8.5"
+source = { registry = "https://pypi.org/simple" }
 dependencies = [
     { name = "dill" },
     { name = "filelock" },
@@ -1102,6 +1102,10 @@ dependencies = [
     { name = "tqdm" },
     { name = "xxhash" },
 ]
+sdist = { url = "https://files.pythonhosted.org/packages/66/34/14cd8e76f907f7d4dca2334cfeec9f81d30fd15c25a015f99aaea694eaed/datasets-4.8.5.tar.gz", hash = "sha256:0f0c1c3d56ffff2c93b2f4c63c95bac94f3d7e8621aea2a2a576275233bba772", size = 605649, upload-time = "2026-04-27T15:43:57.384Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/65/99/00f3196036501b53032c4b1ab8337a0b978dee832ed276dae3815df4e8b5/datasets-4.8.5-py3-none-any.whl", hash = "sha256:5079900781719c0e063a8efdd2cd95a31ad0c63209178669cd23cf1b926149ff", size = 528973, upload-time = "2026-04-27T15:43:53.702Z" },
+]
 
 [[package]]
 name = "debugpy"
@@ -1460,17 +1464,6 @@ wheels = [
     { url = "https://files.pythonhosted.org/packages/81/47/dd9a212ef6e343a6857485ffe25bba537304f1913bdbed446a23f7f592e1/filelock-3.29.0-py3-none-any.whl", hash = "sha256:96f5f6344709aa1572bbf631c640e4ebeeb519e08da902c39a001882f30ac258", size = 39812, upload-time = "2026-04-19T15:39:08.752Z" },
 ]
 
-[[package]]
-name = "flash-attn"
-version = "2.8.3"
-source = { registry = "https://pypi.org/simple" }
-dependencies = [
-    { name = "einops", marker = "platform_machine != 'arm64' or sys_platform != 'darwin'" },
-    { name = "torch", version = "2.11.0", source = { registry = "https://pypi.org/simple" }, marker = "(platform_machine != 'arm64' and sys_platform == 'darwin') or (sys_platform != 'darwin' and sys_platform != 'linux')" },
-    { name = "torch", version = "2.11.0+cu128", source = { registry = "https://download.pytorch.org/whl/cu128" }, marker = "sys_platform == 'linux'" },
-]
-sdist = { url = "https://files.pythonhosted.org/packages/3b/b2/8d76c41ad7974ee264754709c22963447f7f8134613fd9ce80984ed0dab7/flash_attn-2.8.3.tar.gz", hash = "sha256:1e71dd64a9e0280e0447b8a0c2541bad4bf6ac65bdeaa2f90e51a9e57de0370d", size = 8447812, upload-time = "2025-08-15T08:28:12.911Z" }
-
 [[package]]
 name = "flatbuffers"
 version = "25.12.19"
@@ -1760,7 +1753,7 @@ wheels = [
 
 [[package]]
 name = "gym-aloha"
-version = "0.1.4"
+version = "0.1.3"
 source = { registry = "https://pypi.org/simple" }
 dependencies = [
     { name = "dm-control" },
@@ -1768,14 +1761,14 @@ dependencies = [
     { name = "imageio", extra = ["ffmpeg"] },
     { name = "mujoco" },
 ]
-sdist = { url = "https://files.pythonhosted.org/packages/4a/c5/a5b8bdbddfcadec0b52b50e6d1a70325e09e6b594e5f55929d67d9122e2c/gym_aloha-0.1.4.tar.gz", hash = "sha256:0dc4e645045aeb3e74e3c320872d28df6dc93a8751d6ab2f266a2ca11323131f", size = 443466, upload-time = "2026-06-10T09:13:25.525Z" }
+sdist = { url = "https://files.pythonhosted.org/packages/b5/5e/4bb7204730501c2f645e0532a2df4339206948b2882f77cbf0eaf75bc5fe/gym_aloha-0.1.3.tar.gz", hash = "sha256:b794b246a2e6da6ce5f75e152f553fbd4412704bc217fe6311d0ede3bb72a75e", size = 443468, upload-time = "2025-10-09T14:02:35.024Z" }
 wheels = [
-    { url = "https://files.pythonhosted.org/packages/35/e3/3afd0e517a503aabe255bf65f5136490acb79c43189e8d56a3aa63081a10/gym_aloha-0.1.4-py3-none-any.whl", hash = "sha256:d9044290fbccddf0be4246b5287cf0eb6b9ddee545a3d222ce8d78c93ce7125e", size = 447908, upload-time = "2026-06-10T09:13:23.868Z" },
+    { url = "https://files.pythonhosted.org/packages/57/6c/10da397177c48ce360efa66ec21b10b10ef5fa2766256fcd8d7d9b5fa6fc/gym_aloha-0.1.3-py3-none-any.whl", hash = "sha256:a94e5747e71307897ded7ae17ed97fab05e814dcb714a16d320f110444f9d0c3", size = 447908, upload-time = "2025-10-09T14:02:33.253Z" },
 ]
 
 [[package]]
 name = "gym-hil"
-version = "0.1.14"
+version = "0.1.13"
 source = { registry = "https://pypi.org/simple" }
 dependencies = [
     { name = "gymnasium" },
@@ -1785,9 +1778,9 @@ dependencies = [
     { name = "pygame" },
     { name = "pynput" },
 ]
-sdist = { url = "https://files.pythonhosted.org/packages/0c/64/b5cfe59d6a69d20497218f01ad2bdaa2a5a72b850bdb1a445d804ecc9948/gym_hil-0.1.14.tar.gz", hash = "sha256:aeee688dcb3ec72e7bcbe604df4a3f990cce49c8a2da469dd67c3a4eeb4c6bbb", size = 5667991, upload-time = "2026-06-10T09:16:38.98Z" }
+sdist = { url = "https://files.pythonhosted.org/packages/f3/41/e89c87b3c66fb2f8ab5818bff4aa552977911eabaee7c12a8a336dcc406f/gym_hil-0.1.13.tar.gz", hash = "sha256:b9eab7a0acc811f181254e3ad72865830fdbb292c236895f374135d3d62f1b27", size = 5668001, upload-time = "2025-10-21T09:57:24.01Z" }
 wheels = [
-    { url = "https://files.pythonhosted.org/packages/72/97/a7a9c3886306a89046ba5c989bc8b79008e7ec973228bad1fa20d7a94bba/gym_hil-0.1.14-py3-none-any.whl", hash = "sha256:9a2799d47a4561e0b0bb8d37fb3d84934657240be328d13991ea06758726533d", size = 5750805, upload-time = "2026-06-10T09:16:36.827Z" },
+    { url = "https://files.pythonhosted.org/packages/c2/8d/9e3ab53f9aac7bd542f339efd0a9283fa76e034474987e0705379274dfcf/gym_hil-0.1.13-py3-none-any.whl", hash = "sha256:b6444fc43ce1a68ce403df14f99100d9c903ae05d822959e9cd0b76a50b93320", size = 5750805, upload-time = "2025-10-21T09:57:22.068Z" },
 ]
 
 [[package]]
@@ -1877,7 +1870,7 @@ sdist = { url = "https://files.pythonhosted.org/packages/e6/3e/ffad88145b342d5a9
 
 [[package]]
 name = "hf-libero"
-version = "0.1.4"
+version = "0.1.3"
 source = { registry = "https://pypi.org/simple" }
 dependencies = [
     { name = "bddl", marker = "sys_platform == 'linux'" },
@@ -1898,10 +1891,7 @@ dependencies = [
     { name = "transformers", marker = "sys_platform == 'linux'" },
     { name = "wandb", marker = "sys_platform == 'linux'" },
 ]
-sdist = { url = "https://files.pythonhosted.org/packages/af/aa/4e9eb8715e0bff9cb6553db563a35d253393097d446f82bd53575e8b253d/hf_libero-0.1.4.tar.gz", hash = "sha256:c058d67ad5a2b589529c14d614282ef4cca3a7763dafa134f58a6c9039657e34", size = 2961319, upload-time = "2026-06-10T09:56:13.994Z" }
-wheels = [
-    { url = "https://files.pythonhosted.org/packages/2a/79/c286b894c051988d062241682834df915c945bcf51009ffdffbe5ecf69bf/hf_libero-0.1.4-py3-none-any.whl", hash = "sha256:207f76e2f28bff30f78132223d8592fe8f64b1f8fd90ce7024948ada0d7e2c27", size = 3169084, upload-time = "2026-06-10T09:56:12.441Z" },
-]
+sdist = { url = "https://files.pythonhosted.org/packages/7e/ca/7f1c90aedcd067d608681cf03469ae548990ba0806f68a67927dcc801f04/hf_libero-0.1.3.tar.gz", hash = "sha256:0d6b9a215a658db86f66c03d063d6d877d2e9f96d2d326cfa9f43ba4da4a6d5a", size = 2960521, upload-time = "2025-11-03T17:58:00.003Z" }
 
 [[package]]
 name = "hf-xet"
@@ -2689,8 +2679,10 @@ all = [
     { name = "contourpy" },
     { name = "datasets" },
     { name = "debugpy" },
+    { name = "decord", marker = "platform_machine == 'AMD64' or platform_machine == 'x86_64'" },
     { name = "deepdiff" },
     { name = "diffusers" },
+    { name = "dm-tree" },
     { name = "dynamixel-sdk" },
     { name = "faker" },
     { name = "fastapi" },
@@ -2738,6 +2730,7 @@ all = [
     { name = "scikit-image" },
     { name = "scipy" },
     { name = "teleop" },
+    { name = "timm" },
     { name = "torchcodec", marker = "(platform_machine == 'arm64' and sys_platform == 'darwin') or (platform_machine == 'AMD64' and sys_platform == 'linux') or (platform_machine == 'aarch64' and sys_platform == 'linux') or (platform_machine == 'arm64' and sys_platform == 'linux') or (platform_machine == 'x86_64' and sys_platform == 'linux') or sys_platform == 'win32'" },
     { name = "torchdiffeq" },
     { name = "transformers" },
@@ -2842,8 +2835,6 @@ groot = [
     { name = "decord", marker = "platform_machine == 'AMD64' or platform_machine == 'x86_64'" },
     { name = "diffusers" },
     { name = "dm-tree" },
-    { name = "flash-attn", marker = "sys_platform != 'darwin'" },
-    { name = "ninja" },
     { name = "peft" },
     { name = "timm" },
     { name = "transformers" },
@@ -3074,7 +3065,7 @@ requires-dist = [
     { name = "av", marker = "extra == 'av-dep'", specifier = ">=15.0.0,<16.0.0" },
     { name = "cmake", specifier = ">=3.29.0.1,<4.2.0" },
     { name = "contourpy", marker = "extra == 'matplotlib-dep'", specifier = ">=1.3.0,<2.0.0" },
-    { name = "datasets", marker = "extra == 'dataset'", git = "https://github.com/huggingface/datasets.git?rev=2c45eab1bb975ac3d846f2aa6217b82adec8eba3" },
+    { name = "datasets", marker = "extra == 'dataset'", specifier = ">=4.7.0,<5.0.0" },
     { name = "debugpy", marker = "extra == 'dev'", specifier = ">=1.8.1,<1.9.0" },
     { name = "decord", marker = "(platform_machine == 'AMD64' and extra == 'groot') or (platform_machine == 'x86_64' and extra == 'groot')", specifier = ">=0.6.0,<1.0.0" },
     { name = "deepdiff", marker = "extra == 'deepdiff-dep'", specifier = ">=7.0.1,<9.0.0" },
@@ -3086,15 +3077,14 @@ requires-dist = [
     { name = "faker", marker = "extra == 'sarm'", specifier = ">=33.0.0,<35.0.0" },
     { name = "fastapi", marker = "extra == 'phone'", specifier = "<1.0" },
     { name = "feetech-servo-sdk", marker = "extra == 'feetech'", specifier = ">=1.0.0,<2.0.0" },
-    { name = "flash-attn", marker = "sys_platform != 'darwin' and extra == 'groot'", specifier = ">=2.5.9,<3.0.0" },
     { name = "grpcio", marker = "extra == 'grpcio-dep'", specifier = "==1.73.1" },
     { name = "grpcio-tools", marker = "extra == 'dev'", specifier = "==1.73.1" },
-    { name = "gym-aloha", marker = "extra == 'aloha'", specifier = ">=0.1.4,<0.2.0" },
-    { name = "gym-hil", marker = "extra == 'hilserl'", specifier = ">=0.1.14,<0.2.0" },
+    { name = "gym-aloha", marker = "extra == 'aloha'", specifier = ">=0.1.2,<0.2.0" },
+    { name = "gym-hil", marker = "extra == 'hilserl'", specifier = ">=0.1.13,<0.2.0" },
     { name = "gym-pusht", marker = "extra == 'pusht'", specifier = ">=0.1.5,<0.2.0" },
     { name = "gymnasium", specifier = ">=1.1.1,<2.0.0" },
     { name = "hebi-py", marker = "extra == 'phone'", specifier = ">=2.8.0,<2.12.0" },
-    { name = "hf-libero", marker = "sys_platform == 'linux' and extra == 'libero'", specifier = ">=0.1.4,<0.2.0" },
+    { name = "hf-libero", marker = "sys_platform == 'linux' and extra == 'libero'", specifier = ">=0.1.3,<0.2.0" },
     { name = "hidapi", marker = "extra == 'gamepad'", specifier = ">=0.14.0,<0.15.0" },
     { name = "huggingface-hub", specifier = ">=1.0.0,<2.0.0" },
     { name = "ipykernel", marker = "extra == 'notebook'", specifier = ">=6.0.0,<7.0.0" },
@@ -3131,6 +3121,7 @@ requires-dist = [
     { name = "lerobot", extras = ["feetech"], marker = "extra == 'hopejr'" },
     { name = "lerobot", extras = ["feetech"], marker = "extra == 'lekiwi'" },
     { name = "lerobot", extras = ["gamepad"], marker = "extra == 'all'" },
+    { name = "lerobot", extras = ["groot"], marker = "extra == 'all'" },
     { name = "lerobot", extras = ["grpcio-dep"], marker = "extra == 'async'" },
     { name = "lerobot", extras = ["grpcio-dep"], marker = "extra == 'dev'" },
     { name = "lerobot", extras = ["grpcio-dep"], marker = "extra == 'hilserl'" },
@@ -3223,7 +3214,6 @@ requires-dist = [
     { name = "motorbridge", marker = "extra == 'motorbridge-dep'", specifier = ">=0.3.2,<0.4.0" },
     { name = "motorbridge-smart-servo", marker = "extra == 'motorbridge-smart-servo-dep'", specifier = ">=0.0.4,<0.1.0" },
     { name = "mypy", marker = "extra == 'dev'", specifier = ">=1.19.1" },
-    { name = "ninja", marker = "extra == 'groot'", specifier = ">=1.11.1,<2.0.0" },
     { name = "num2words", marker = "extra == 'smolvla'", specifier = ">=0.5.14,<0.6.0" },
     { name = "numpy", specifier = ">=2.0.0,<2.3.0" },
     { name = "onnx", marker = "extra == 'unitree-g1'", specifier = ">=1.16.0,<2.0.0" },
@@ -4011,32 +4001,6 @@ wheels = [
     { url = "https://files.pythonhosted.org/packages/9e/c9/b2622292ea83fbb4ec318f5b9ab867d0a28ab43c5717bb85b0a5f6b3b0a4/networkx-3.6.1-py3-none-any.whl", hash = "sha256:d47fbf302e7d9cbbb9e2555a0d267983d2aa476bac30e90dfbe5669bd57f3762", size = 2068504, upload-time = "2025-12-08T17:02:38.159Z" },
 ]
 
-[[package]]
-name = "ninja"
-version = "1.13.0"
-source = { registry = "https://pypi.org/simple" }
-sdist = { url = "https://files.pythonhosted.org/packages/43/73/79a0b22fc731989c708068427579e840a6cf4e937fe7ae5c5d0b7356ac22/ninja-1.13.0.tar.gz", hash = "sha256:4a40ce995ded54d9dc24f8ea37ff3bf62ad192b547f6c7126e7e25045e76f978", size = 242558, upload-time = "2025-08-11T15:10:19.421Z" }
-wheels = [
-    { url = "https://files.pythonhosted.org/packages/3c/74/d02409ed2aa865e051b7edda22ad416a39d81a84980f544f8de717cab133/ninja-1.13.0-py3-none-macosx_10_9_universal2.whl", hash = "sha256:fa2a8bfc62e31b08f83127d1613d10821775a0eb334197154c4d6067b7068ff1", size = 310125, upload-time = "2025-08-11T15:09:50.971Z" },
-    { url = "https://files.pythonhosted.org/packages/8e/de/6e1cd6b84b412ac1ef327b76f0641aeb5dcc01e9d3f9eee0286d0c34fd93/ninja-1.13.0-py3-none-manylinux2014_aarch64.manylinux_2_17_aarch64.whl", hash = "sha256:3d00c692fb717fd511abeb44b8c5d00340c36938c12d6538ba989fe764e79630", size = 177467, upload-time = "2025-08-11T15:09:52.767Z" },
-    { url = "https://files.pythonhosted.org/packages/c8/83/49320fb6e58ae3c079381e333575fdbcf1cca3506ee160a2dcce775046fa/ninja-1.13.0-py3-none-manylinux2014_i686.manylinux_2_17_i686.whl", hash = "sha256:be7f478ff9f96a128b599a964fc60a6a87b9fa332ee1bd44fa243ac88d50291c", size = 187834, upload-time = "2025-08-11T15:09:54.115Z" },
-    { url = "https://files.pythonhosted.org/packages/56/c7/ba22748fb59f7f896b609cd3e568d28a0a367a6d953c24c461fe04fc4433/ninja-1.13.0-py3-none-manylinux2014_ppc64le.manylinux_2_17_ppc64le.whl", hash = "sha256:60056592cf495e9a6a4bea3cd178903056ecb0943e4de45a2ea825edb6dc8d3e", size = 202736, upload-time = "2025-08-11T15:09:55.745Z" },
-    { url = "https://files.pythonhosted.org/packages/79/22/d1de07632b78ac8e6b785f41fa9aad7a978ec8c0a1bf15772def36d77aac/ninja-1.13.0-py3-none-manylinux2014_s390x.manylinux_2_17_s390x.whl", hash = "sha256:1c97223cdda0417f414bf864cfb73b72d8777e57ebb279c5f6de368de0062988", size = 179034, upload-time = "2025-08-11T15:09:57.394Z" },
-    { url = "https://files.pythonhosted.org/packages/ed/de/0e6edf44d6a04dabd0318a519125ed0415ce437ad5a1ec9b9be03d9048cf/ninja-1.13.0-py3-none-manylinux2014_x86_64.manylinux_2_17_x86_64.whl", hash = "sha256:fb46acf6b93b8dd0322adc3a4945452a4e774b75b91293bafcc7b7f8e6517dfa", size = 180716, upload-time = "2025-08-11T15:09:58.696Z" },
-    { url = "https://files.pythonhosted.org/packages/54/28/938b562f9057aaa4d6bfbeaa05e81899a47aebb3ba6751e36c027a7f5ff7/ninja-1.13.0-py3-none-manylinux_2_28_armv7l.manylinux_2_31_armv7l.whl", hash = "sha256:4be9c1b082d244b1ad7ef41eb8ab088aae8c109a9f3f0b3e56a252d3e00f42c1", size = 146843, upload-time = "2025-08-11T15:10:00.046Z" },
-    { url = "https://files.pythonhosted.org/packages/2a/fb/d06a3838de4f8ab866e44ee52a797b5491df823901c54943b2adb0389fbb/ninja-1.13.0-py3-none-manylinux_2_31_riscv64.whl", hash = "sha256:6739d3352073341ad284246f81339a384eec091d9851a886dfa5b00a6d48b3e2", size = 154402, upload-time = "2025-08-11T15:10:01.657Z" },
-    { url = "https://files.pythonhosted.org/packages/31/bf/0d7808af695ceddc763cf251b84a9892cd7f51622dc8b4c89d5012779f06/ninja-1.13.0-py3-none-musllinux_1_2_aarch64.whl", hash = "sha256:11be2d22027bde06f14c343f01d31446747dbb51e72d00decca2eb99be911e2f", size = 552388, upload-time = "2025-08-11T15:10:03.349Z" },
-    { url = "https://files.pythonhosted.org/packages/9d/70/c99d0c2c809f992752453cce312848abb3b1607e56d4cd1b6cded317351a/ninja-1.13.0-py3-none-musllinux_1_2_armv7l.whl", hash = "sha256:aa45b4037b313c2f698bc13306239b8b93b4680eb47e287773156ac9e9304714", size = 472501, upload-time = "2025-08-11T15:10:04.735Z" },
-    { url = "https://files.pythonhosted.org/packages/9f/43/c217b1153f0e499652f5e0766da8523ce3480f0a951039c7af115e224d55/ninja-1.13.0-py3-none-musllinux_1_2_i686.whl", hash = "sha256:5f8e1e8a1a30835eeb51db05cf5a67151ad37542f5a4af2a438e9490915e5b72", size = 638280, upload-time = "2025-08-11T15:10:06.512Z" },
-    { url = "https://files.pythonhosted.org/packages/8c/45/9151bba2c8d0ae2b6260f71696330590de5850e5574b7b5694dce6023e20/ninja-1.13.0-py3-none-musllinux_1_2_ppc64le.whl", hash = "sha256:3d7d7779d12cb20c6d054c61b702139fd23a7a964ec8f2c823f1ab1b084150db", size = 642420, upload-time = "2025-08-11T15:10:08.35Z" },
-    { url = "https://files.pythonhosted.org/packages/3c/fb/95752eb635bb8ad27d101d71bef15bc63049de23f299e312878fc21cb2da/ninja-1.13.0-py3-none-musllinux_1_2_riscv64.whl", hash = "sha256:d741a5e6754e0bda767e3274a0f0deeef4807f1fec6c0d7921a0244018926ae5", size = 585106, upload-time = "2025-08-11T15:10:09.818Z" },
-    { url = "https://files.pythonhosted.org/packages/c1/31/aa56a1a286703800c0cbe39fb4e82811c277772dc8cd084f442dd8e2938a/ninja-1.13.0-py3-none-musllinux_1_2_s390x.whl", hash = "sha256:e8bad11f8a00b64137e9b315b137d8bb6cbf3086fbdc43bf1f90fd33324d2e96", size = 707138, upload-time = "2025-08-11T15:10:11.366Z" },
-    { url = "https://files.pythonhosted.org/packages/34/6f/5f5a54a1041af945130abdb2b8529cbef0cdcbbf9bcf3f4195378319d29a/ninja-1.13.0-py3-none-musllinux_1_2_x86_64.whl", hash = "sha256:b4f2a072db3c0f944c32793e91532d8948d20d9ab83da9c0c7c15b5768072200", size = 581758, upload-time = "2025-08-11T15:10:13.295Z" },
-    { url = "https://files.pythonhosted.org/packages/95/97/51359c77527d45943fe7a94d00a3843b81162e6c4244b3579fe8fc54cb9c/ninja-1.13.0-py3-none-win32.whl", hash = "sha256:8cfbb80b4a53456ae8a39f90ae3d7a2129f45ea164f43fadfa15dc38c4aef1c9", size = 267201, upload-time = "2025-08-11T15:10:15.158Z" },
-    { url = "https://files.pythonhosted.org/packages/29/45/c0adfbfb0b5895aa18cec400c535b4f7ff3e52536e0403602fc1a23f7de9/ninja-1.13.0-py3-none-win_amd64.whl", hash = "sha256:fb8ee8719f8af47fed145cced4a85f0755dd55d45b2bddaf7431fa89803c5f3e", size = 309975, upload-time = "2025-08-11T15:10:16.697Z" },
-    { url = "https://files.pythonhosted.org/packages/df/93/a7b983643d1253bb223234b5b226e69de6cda02b76cdca7770f684b795f5/ninja-1.13.0-py3-none-win_arm64.whl", hash = "sha256:3c0b40b1f0bba764644385319028650087b4c1b18cdfa6f45cb39a3669b81aa9", size = 290806, upload-time = "2025-08-11T15:10:18.018Z" },
-]
-
 [[package]]
 name = "nodeenv"
 version = "1.10.0"