Skip to content
BranchesTags

Repository files navigation

OpenBot Data

Inspect, catalog, and prepare robot video data for embodied AI and robot learning.

Library documentation · API reference · Data product · Source repository

OpenBot Data is an early Python toolkit for working with robot data — especially egocentric video and teleoperation data collected from wrist cameras, head-mounted cameras, and robot demonstrators.

Use it to inspect local video directories and LeRobot v2.1/v3 datasets, audit revision-pinned Hub sources, compare dataset snapshots, gate declared training profiles, and plan and verify conservative repairs or official merges. It also extracts previews and exports robot dataset catalogs (JSON/CSV).

Install

pip install openbot-data

PyPI provides the released 0.0.3 package (checked 2026-10-02). Requires Python 3.9+; the supported test matrix is Python 3.9–3.12. LeRobot Parquet validation requires pip install 'openbot-data[lerobot]'; Hub access additionally requires the hub extra.

The source checkout still declares version 0.0.3 but contains additions made after that release, including the local Review workbench. Install the checkout to use those additions; pip install openbot-data does not include them.

Runnable demo

Clone the repository, install the package, and run the complete local preflight against a video directory or local LeRobot repository:

pip install -e .
python examples/local_preflight.py ./robot_videos --out ./openbot-preflight --integrity sample

The demo uses the public Python API and writes inspection/metadata/manifest.json, inspection/metadata/report.json, and audit.json. Add --format lerobot for a local LeRobot v2.1/v3 repository, --integrity full to decode every frame, or --no-checksum to skip SHA-256 duplicate detection. The demo discovers and hashes the dataset once, then shares one immutable DatasetSnapshot across both renderers. Install pip install -e '.[lerobot]' before running the LeRobot demo.

What it does

  • Scan robot video directories — recursively find .mp4, .mov, .avi, .mkv, .webm files.
  • Read video metadata — duration, fps, resolution, frame count, file size, validity.
  • Extract preview frames — uniformly sample frames for quick human inspection.
  • Generate manifests — manifest.json with per-video metadata and preview paths.
  • Generate quality reports — report.json with aggregate duration, size, and resolutions.
  • Export dataset catalogs — JSON or CSV for dataset registries, documentation, and SEO-friendly catalog pages.
  • Discover local LeRobot data — read-only episode and video-stream discovery for v2.1/v3 layouts.
  • Audit before training or upload — stable error/warning codes without an uncalibrated quality score.
  • Snapshot and diff datasets — portable component fingerprints and semantic change classes.
  • Gate ACT and SmolVLA readiness — distinguish READY, BLOCKED, and incomplete PARTIAL evidence.
  • Audit pinned Hub revisions — resolve branches/tags to immutable commits under hard download budgets.
  • Repair conservatively — plan and apply only unambiguous derived metadata changes to a new copy.
  • Verify official merges — check compatibility before merge, then reconcile lineage, loader, audit, and diff evidence.
  • Hand off score-free Catalog evidence — emit versioned facts, coverage, findings, and unresolved checks for server-side evaluation.
  • Review local LeRobot v3 episodes (source checkout) — browse camera segments, sampled motion traces, audit findings, and skipped-check evidence.

CLI

Scan videos

openbot-data scan ./robot_videos
openbot-data scan ./robot_videos --output scan.json

Inspect a dataset

openbot-data inspect ./robot_videos --out ./openbot_dataset
openbot-data inspect ./lerobot_dataset --format lerobot --out ./openbot_dataset
openbot-data audit ./robot_videos --out ./audit.json --fail-on error

Output structure:

openbot_dataset/
  previews/
  metadata/
    manifest.json
    report.json

Export a robot dataset catalog

# JSON catalog for dataset registries and documentation
openbot-data catalog ./robot_videos --out ./catalog.json --format json

# CSV catalog for spreadsheets or Hugging Face dataset cards
openbot-data catalog ./robot_videos --out ./catalog.csv --format csv

The catalog is designed to be checked into GitHub or linked from a dataset registry page such as OpenBot.ai Datasets.

Build Catalog evidence from a completed local audit

openbot-data catalog-evidence ./robot_videos \
  --dataset-id org/dataset \
  --checked-at 2026-07-28T12:00:00Z \
  --out ./catalog-evidence.json

The artifact contains no Overall score or normalized dimension score. OpenBot Catalog remains responsible for evaluation, review, and publication.

Snapshot, diff, and readiness

openbot-data snapshot ./lerobot_dataset \
  --format lerobot --integrity full --out ./dataset.snapshot.json

openbot-data diff ./baseline.snapshot.json ./dataset.snapshot.json \
  --out ./dataset.diff.json --fail-on breaking

openbot-data readiness ./lerobot_dataset \
  --profile lerobot-smolvla --integrity full \
  --out ./readiness.json --markdown ./readiness.md

Local episode review (source checkout)

pip install -e '.[lerobot]'
openbot-data review ./lerobot_dataset
openbot-data review ./lerobot_dataset --port 8766 --no-open

The local workbench shows LeRobot v3 episodes, camera segments, sampled state and action traces, and the existing audit findings in one place. It binds to 127.0.0.1 and never writes to the source dataset. ffmpeg on PATH enables on-demand H.264 browser previews; preview files are temporary and removed when the server stops. The review reflects a metadata-level audit taken at startup. The page shows skipped audit rules and their reasons. Zero reported errors or warnings does not establish frame-level integrity, task success, or motion quality. Restart the reviewer after changing the dataset. Shared-file findings appear under every affected episode; the summary counts each audit finding once. An unreadable motion shard leaves the episode's video and findings accessible. Previews show at most the first 180 seconds per camera. Cached previews are evicted above 256 MiB or 32 files; active streams can temporarily exceed this budget until their requests finish. Open the printed localhost URL, rather than opening the HTML asset directly. This command is in the source tree and is not part of the released PyPI 0.0.3. See the Review guide for installation, limits, and troubleshooting.

Repair and merge verification

openbot-data repair plan ./dataset --integrity full --out ./repair.plan.json
openbot-data repair apply ./dataset \
  --plan ./repair.plan.json --output ./dataset.repaired

openbot-data merge-check ./dataset-a ./dataset-b --out ./merge.plan.json
openbot-data verify-merge ./merged \
  --input ./dataset-a.snapshot.json \
  --input ./dataset-b.snapshot.json \
  --operation-record ./official-operation.json \
  --out ./merge.receipt.json

Physical merge stays with lerobot-edit-dataset from lerobot[dataset]==0.6.0; OpenBot only plans and verifies it.

Python API

from openbot_data import (
    audit_dataset,
    build_catalog_evidence,
    build_dataset_snapshot,
    diff_dataset_snapshots,
    evaluate_dataset_readiness,
    export_catalog,
    inspect_dataset,
    prepare_dataset,
    read_lerobot,
    scan_directory,
    schema_path,
)

# Scan a directory
scan = scan_directory("./robot_videos")
print(scan["valid_videos"])

# Inspect and extract previews
result = inspect_dataset(
    video_dir="./robot_videos",
    output_dir="./openbot_dataset",
)
print(result["manifest_path"])
print(result["report_path"])

# Export a catalog for documentation / SEO
export_catalog(
    video_dir="./robot_videos",
    output_path="./catalog.json",
    fmt="json",
)

# Discover/hash once and reuse the immutable snapshot across renderers
snapshot = prepare_dataset("./robot_videos", checksum="sha256", integrity="sample")
inspection = inspect_dataset("./robot_videos", "./inspection", snapshot=snapshot)
audit = audit_dataset("./robot_videos", snapshot=snapshot)

# Discover episodes and camera streams in a local LeRobot repository
lerobot = read_lerobot("./lerobot_dataset")

# Produce score-free evidence for server-side Catalog evaluation
evidence = build_catalog_evidence(
    "./robot_videos",
    dataset_id="org/dataset",
    checked_at="2026-07-28T12:00:00Z",
    output_path="./catalog-evidence.json",
)

portable = build_dataset_snapshot(
    "./lerobot_dataset",
    input_format="lerobot",
    integrity="full",
)
readiness = evaluate_dataset_readiness(
    "./lerobot_dataset",
    profile="lerobot-act",
    integrity="full",
    dataset_snapshot=portable,
)
change = diff_dataset_snapshots(portable, portable)

# Packaged JSON Schemas are stable independently of the package version
with schema_path("manifest") as manifest_schema:
    print(manifest_schema)

Use cases

  • Prepare teleoperation data collected from ALOHA, Mobile ALOHA, VR, or SpaceMouse setups.
  • Inspect egocentric video datasets before converting to LeRobot, RLDS, or HDF5.
  • Build a robot dataset catalog that links back to your project website or Hugging Face collection.
  • Validate video integrity before running robot policy training or VLA pre-training.

Development

pip install -e ".[dev,lerobot,hub]"
python scripts/check_version.py
pytest
scripts/test_matrix.sh
python -m build
python -m twine check dist/*

The local matrix script requires uv and tests Python 3.9–3.12 without requiring a repository CI workflow. Install ffmpeg for Review video-preview tests and Node.js for its browser-logic tests. The test suite explicitly skips those checks when the executables are absent. Official LeRobot loader conformance runs separately on Python 3.12 with lerobot[dataset]==0.6.0 and OPENBOT_DATA_OFFICIAL_CONFORMANCE=1.

VERSION is the package version source of truth. To release, update VERSION and CHANGELOG.md, verify locally, then publish a GitHub Release whose tag is v<version>. The release workflow validates the tag before publishing to PyPI.

Status

As of 2026-10-02, the latest published PyPI package is 0.0.3. v0.0.3 points to commit 7c4974c0ce53a93ea101529e6bd9565146da0d78; the GitHub Release workflow published its wheel and source distribution to PyPI. The current checkout uses the same version string but includes later code; the release tag and installed package version alone do not establish whether review is available. The published wheel has no Review module or CLI command.

OpenBot Data remains an early Python toolkit for local processing and explicit Hub downloads. It does not provide platform authentication, billing, remote jobs, or server infrastructure. The main OpenBot repository is an API-first platform framework, and the separate openbot-sdk package calls only APIs that the platform has actually published. Future robot/ego-data API adapters are research directions, not current package or platform promises.

Roadmap

  • Video scanning and metadata extraction
  • Preview frame extraction
  • Manifest and report generation
  • JSON/CSV catalog export
  • 0.0.2: local dataset preflight, including a versioned manifest, deterministic audit findings, and local LeRobot discovery
  • 0.0.3: LeRobot compatibility and dataset change control, with correctness closure, explicit v2.1/v3 adapters, layered validation, portable snapshots, semantic diff, revision-pinned Hub audit, readiness profiles, evidence triage, conservative repair, and merge verification. P0 interfaces, clean install, Python matrix, artifacts, and official conformance passed before the public 0.0.3 release.
  • Local LeRobot v3 Review workbench: implemented in the source checkout after 0.0.3; not yet published to PyPI
  • 0.0.4: read-only robomimic/HDF5 preflight, with file-source detection, bounded structural and payload validation, portable snapshot/diff/readiness evidence, and optional P1 Rerun handoff
  • 0.0.5: read-only RLDS/Open X adapter
  • Later: advanced episode-quality signals and any aggregate score only after labeled downstream validation exists

Audit codes are documented in docs/audit-findings.md. The research and differentiation decisions behind 0.0.3 are documented in docs/reference-libraries.md. Canonical manifests use explicit path_base/path_bases fields; they never serialize private source paths. Symlinks are skipped by default, and even when follow_symlinks=True a target outside the dataset root is rejected.

License

MIT

Citation

If you use OpenBot Data in research or production, cite the project repository:

@software{openbot_data,
  title = {OpenBot Data},
  author = {OpenBot},
  year = {2026},
  url = {https://github.com/openbotai/openbot-data}
}

Related

About

No description, website, or topics provided.

Resources

Readme
MIT license
Activity
Custom properties

Stars

0 stars

Watchers

0 watching

Forks

1 fork
Report repository

Releases

Packages

Contributors

Languages