Hebbian-Robotics / Hebbian-Robotics/hflow
LeRobot: add a reproducible real-camera import, quality, curate, and export example
- Dominant language
- Python
- Stars
- 269
- Forks
- 150
- Avg merge
- 8h 18m
- Merged PRs (30d)
- 246
Description
## Goal
Provide one reproducible real-camera workflow that proves the LeRobot adapter works beyond a simulated PushT fixture: import source episodes, run HFlow quality checks, curate from recorded evidence, and export a standard LeRobot Dataset v3 selection.
## Current behavior
Rewritten 2026-08-28, after #189 landed as #230. The original text described a PushT-only converter, which is no longer what the repository has.
`examples/lerobot/prepare.py` now converts any LeRobot Dataset v3 repository, reading the feature schema, frame rate, episode boundaries, and video paths from `meta/info.json` rather than constants, and converting every selected camera into its own channel. `examples/README.md:98-113` documents the supported subset and both commands. So import is solved, and this issue no longer needs to argue for it.
What is still missing is the rest of the workflow. Converting one episode is a command; there is no bounded run that a contributor can execute from a clean checkout to go from a pinned source revision through quality checks and a curation query to an exported selection, and reproduce the same result twice. That composition is what this issue is for, and it is the only place the pieces are shown working together.
## Dependencies
- #189 provides general LeRobot v3 import and multi-camera conversion. **Done**, merged as #230.
- #190 provides export of an HFlow curation result back to LeRobot Dataset v3. Still open and unassigned, and it is the one thing blocking this.
Do not duplicate either implementation in this example. This issue composes their public callables and commands.
## Acceptance corpus
Use this pinned public dataset:
- Repository: lerobot/svla_so101_pickplace
- Revision: f641879e22172be7e8161d5e6c1503c2d2feb657
- License: Apache-2.0
- Shape: 50 real SO-100 episodes, 30 frames per second, two 640 by 480 cameras, and six-dimensional state and action
- Total download: about 86 MB
Process a bounded, explicitly listed episode subset. The workflow must make the subset easy to change without embedding this repository or its feature names into shared adapter code.
## What to build
Add a focused runnable example under examples/lerobot that:
1. Downloads the pinned source revision and verifies the resolved commit.
2. Converts an explicitly listed episode subset to canonical MCAP with every declared camera.
3. Runs hflow doctor on the converted inputs.
4. Processes the episodes through an HFlow App using the applicable default checks and contact-sheet enrichment.
5. Cuts a training selection with an explicit SQL query over recorded quality evidence.
6. Exports the selected episodes as both an HFlow dataset snapshot and a local LeRobot Dataset v3 repository.
7. Verifies the exported LeRobot dataset in a clean process.
8. Prints the source episode count, processed count, status counts, selected count, output paths, and immutable source revision.
Do not inject artificial faults into the source media. The example must report the measurements found in the recordings and apply a documented curation policy. If the pinned subset contains no rejected episodes under a reasonable policy, say so instead of manufacturing a failure.
## Reproducibility and data handling
- Keep all downloaded media and generated artifacts under the gitignored data directory.
- Commit scripts, SQL, a small source manifest, and documentation only.
- Pin every external source by immutable revision and record hashes for any independently downloaded files.
- Do not upload data, create a Hugging Face repository, or require organization credentials.
- State network, ffmpeg, disk, and approximate runtime requirements before the command.
## Definition of done
- One documented command runs the bounded workflow from a clean checkout.
- Every converted input passes hflow doctor.
- Both source cameras appear in the canonical episodes and quality results.
- The catalog records the expected source dataset, source revision, and source episode indexes.
- The curation query reports coverage denominators and produces a deterministic selected episode set.
- The HFlow snapshot contains standard Parquet tables plus the documented copied media.
- The exported LeRobot v3 repository loads through LeRobotDataset and contains exactly the selected episodes.
- Re-running without source or configuration changes is safe and produces the same selection.
- examples/README.md documents prerequisites, the exact command, external effects, and observable outputs.
Tests should cover the example orchestration and deterministic selection using a small local fixture. The pinned network corpus is a documented validation run, not a required default test-suite download.
## Validation
uv sync --locked --all-extras
uv run ruff check --fix
uv run ruff format
uv run ty check
uv run pytest -q
Run the full pinned example once and include its summary, hflow doctor result, and clean-process LeRobot load result in the PR body. Run the Markdown link check from CONTRIBUTING.md for documentation changes.
## Notes
This is not a good first issue. It depends on #189 and #190 and exercises network data, video conversion, quality checks, curation, snapshots, and LeRobot output validation. Comment here after both dependencies land if you want to take it and I will assign it.
Contributor guide
Research direction
Read the existing LeRobot entry points in examples/lerobot/prepare.py and the documented commands in examples/README.md, then review dependency #190 and the merged import work from #230. Build the runnable orchestration around the pinned dataset and bounded manifest, covering doctor, processing, curation, snapshot export, and clean-process LeRobot validation. Confirm completion with the listed validation commands and the documented pinned-run summary.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- python
- Domain
- data-engineering
- Issue type
- Feature
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Active
- Clarity
- Clearly specified
- Newbie friendliness
- 25/100