fix(data): clamp history delta_indices at episode start instead of wrapping to the episode tail

[elbourne12345]

Fixes #771

Changes proposed in this pull request:

• extract_step_data no longer passes negative positions to DataFrame.iloc when allow_padding=False. Observation history that reaches before the first frame is clamped to frame 0; any other out-of-range index raises IndexError naming the modality and index. allow_padding=True is unchanged, as is the sharder's step schedule.
• Documented the allow_padding=False semantics on DataConfig.allow_padding and in the ShardedSingleStepDataset docstring.
• getting_started/data_config.md no longer states that no N1.7 embodiment config uses negative indices (embodiment_configs.py:30 ships [-15, 0]), and now describes the start-of-episode padding.
• New tests/gr00t/data/test_extract_step_data_history.py (10 tests, CPU-only).

The bug

indices_to_load = [step_index + delta ...] went straight to DataFrame.iloc. pandas treats negative positions as offsets from the end of the frame, so history offsets at the start of an episode returned frames from its tail.

DataConfig.allow_padding defaults to False and launch_finetune.py never changes it, so this is the default training path. The in-repo oxe_droid_relative_eef_relative_joint config has video: delta_indices=[-15, 0] and examples/DROID/README.md documents finetuning with that tag: for every DROID episode, steps 0–14 were trained with a "previous frame" taken from the last 15 frames of the episode. The sharder schedules all of them — get_effective_episode_length only subtracts the action horizon.

Measured on demo_data/droid_sample episode 1 (266 frames) at 51d4c89, mirroring the video offsets onto the state stream so the repro needs no torchcodec (the index list is computed once per modality and applied identically to all of them):

step  0: history idx -15 -> row 251 of 266
step  5: history idx -10 -> row 256
step 14: history idx  -1 -> row 265
step 15: history idx   0 -> row 0

Both in-tree deployment paths pad history by repeating the first observation (MultiStepWrapper.reset, the DROID client's frame_buffer), so this was also a train/inference mismatch. Offline eval hits the same wrong frame at step 0 (open_loop_eval.py, standalone_inference_script.py, export_onnx_n1d7.py use the default; benchmark_inference.py and the two inference notebooks pass allow_padding=False explicitly).

This is a regression: N1.5's gr00t/data/dataset.py padded front indices with frame 0 via retrieve_data_and_pad(..., "first_last"); 4e62473 (#456) replaced it with the unguarded iloc path.

Behaviour changes, stated explicitly

With allow_padding=False:

1. Negative observation indices: episode-tail frame → frame 0. This is the fix.
2. Episodes shorter than |min(delta)|: previously raised (pandas out-of-bounds), now clamp to frame 0 like every other early step. Unreachable from the sharder (effective length would be 0), reachable from the eval scripts.
3. Negative action indices: previously wrapped silently, now raise. No in-tree config has them, and gr00t/eval/_horizon_contract.py already rejects them at inference.
4. Non-negative out-of-range indices already raised IndexError in pandas; only the message changes. benchmark_inference.py's except Exception trajectory loop stops at the same step as before.

Alternatives

Defaulting DataConfig.allow_padding to True is a one-line change that gives identical results on every sharder-scheduled step. I did not take it because it would also silently clamp action windows past the episode end, which the eval scripts currently rely on failing loudly. Happy to switch if you prefer the one-liner, or to drop the doc commit if you would rather change the shipped oxe_droid_relative_eef_relative_joint config to video: [0] (matching the released nvidia/GR00T-N1.7-DROID checkpoint) — though that would leave custom history configs affected.

Interaction with #743

LeRobotEpisodeLoaderFaster._get_video_indices_from_steps passes negative frame indices through when allow_padding=False, and test_no_padding_keeps_negative_indices asserts that. If #743 lands, that loader needs the same clamp — otherwise the clamped step-0 history would reference a frame it never decoded (None). Happy to rebase in whichever order suits you.

Testing

• New tests/gr00t/data/test_extract_step_data_history.py:
  • regression — history before the episode start clamps to frame 0 for steps 0 / 7 / 14, checked on both array (state) and list (video) modalities; fails on main (returns the episode-tail rows);
  • end to end — through ShardedSingleStepDataset.get_shard with a mocked episode loader and the default allow_padding: the early steps are still scheduled and now get frame 0 as history;
  • in-range history untouched; episode shorter than the history window clamps; negative action index raises; out-of-range future index raises (pins the pre-existing pandas behaviour with the new message); allow_padding=True still clamps both ends.
• python -m pytest tests/gr00t/data/test_extract_step_data_history.py tests/gr00t/data/test_sharded_datasets.py -q → 30 passed.
• Re-ran the demo_data/droid_sample reproduction from Negative delta_indices (history frames) silently read from the end of the episode during training #771 after the fix: all four steps return row 0 as the history frame; the sharder schedule is unchanged.
• ruff check and ruff format --check clean on the touched files.

I could not run the GPU suite or measure the effect on a finetuned policy — that needs a DROID training run.

Before submitting

• I've read and followed all steps in the Making a pull request
  section of the CONTRIBUTING docs. _{(FYI: CONTRIBUTING.md currently has no "Making a pull request" section, so that template link 404s to the top of the file.)}
• I've updated or added any relevant docstrings.
• If this PR fixes a bug, I've added a test that will fail without my fix.
• If this PR adds a new feature, I've added tests that sufficiently cover my new functionality. _{(n/a — bugfix)}

Generated with assistance from Claude Code