[yuecideng]

Description

Provide reusable numeric online/offline datasets and a self-contained Franka behavior-cloning demo at examples/ods/simple_bc_demo/. The demo owns its environment, configuration, model, training loop, checkpoints, evaluation, direct LeRobot writing and experiment reports. Shared sampling/loading contracts remain in embodichain.data_pipeline.

Refs #788. This is the independent showcase milestone before RLinf integration.

Implemented scope

• Core ODS documentation owns the process/control/data-flow architecture, runtime/source contracts, throughput/profile configuration, runtime verification and statistics. Experiment design remains with the BC example; the standalone evaluation guide has been consolidated. A compact runtime diagram shows expert production, the shared cache, live/resident sources, application control and independent student evaluation. The BC documentation retains its task binding, CLI/artifact names, comparison protocol and historical evidence; it links to those reusable guides.
• A local Franka PickPlace task with randomized resets, real contact-based grasping, and one measured lift/place/release/retreat/stability predicate for expert acceptance and student evaluation. The task and its YAML deployment are colocated with the example.
• ODS independent action width, manual refill generations, provenance/statistics and strict per-source delivery budgets. Selection, continuity checks, copies and budget debit retain the producer-lock boundary.
• Throughput-derived cache/pacing/refill settings from measured supply and training demand, runtime metadata and a bounded-reuse profile. Learning-safe bounds remain provisional.
• A common SequenceDataset/BatchSource/SequenceSpecCfg contract for OnlineDataSource, TensorDataSource and LeRobotDataSource; OfflineDataset remains a compatibility alias and OnlineDataset retains its chunk interface. Sources share temporal-window, padding and quota helpers while preserving their own lifecycle, locking and ledger ownership.
• Shared schema validation/fingerprints, explicit action semantics and control period, typed unavailable/budget-exhausted errors, and bounded official-SDK numeric loading. Standard numeric LeRobot data does not require the example sidecar. Imports defer the SDK and simulation until needed.
• One ChunkBC learner using two measured 51-feature observations, a 512×2 MLP, 64 absolute TCP/gripper predictions and 16-step execution through bounded DLS control. One trainer supports live, frozen, offline32 and full-offline controls, with frozen normalization, immutable checkpoints, optimizer/RNG recovery, independent student evaluation and optional Viser/TensorBoard/video.

Runtime and reporting fixes preserve resident validity during segment sampling, bound refill waits while draining events and checking worker health, select deferred policies only from checkpoint saves completed within the original wall-time budget, and attempt every owned-resource cleanup even when reports fail. Direct-file startup no longer shadows the LeRobot SDK. Comparisons validate development/test scene identity before supporting efficiency claims.

The example consumes the public data sources and has no duplicate resident sampler/SDK loading loop. Superseded model alternatives and learning-example unit suites remain removed. Maintained unit tests target production contracts; runnable experiments validate the local model, writing and orchestration. Historical golden batches, optimizer alignment, physical runs and learning regressions are retained under the local docs/ directory with their original revisions/hashes.

Validation

Latest relocation candidate: d54cfc8a, based on the existing PR head 929fd94c. Function/body and configuration comparisons preserve the current ChunkBC, geometry, checkpoint, trainer, physical environment and public data implementations apart from ownership/import/source-recording changes.

• 482 passed: complete data-pipeline package, API-doc tooling and context tests. Coverage includes sequence/source/RNG parity, schema contracts, continuity, language ownership, quotas, worker boundaries, numeric LeRobot loading and errors.
• Fresh conda py311 runtime validation: online training completed 10 updates/40 chunks across two generations; cold LeRobot collection wrote/read four episodes (1,330 frames) and stopped after one update/four chunks under one-selection source quotas; resume restored the exact starting model and sampler RNG, kept normalization frozen and advanced step 10 to 25 with a new ODS run ID; the independent evaluator loaded a retained trained checkpoint and succeeded on two reused development scenes. All observed owned child processes exited normally. Module/file entry points, throughput configuration and existing-run comparison also pass.
• Black 26.3.1, whitespace and local-link checks pass; 2,691/2,691 public exports are documented. The affected documentation guide renders in a scoped Sphinx dummy build with warnings treated as errors. The complete repository suite and full Sphinx site were not built.

Documentation-only follow-up: 49 focused context/documentation checks pass; configuration snippets and a memory-constrained plan were executed against the public API. Scoped Sphinx dummy and HTML builds pass with warnings treated as errors, including the new guide navigation. No runtime implementation changed.

Latest documentation follow-up: removed the standalone evaluation page, retained a compact runtime-verification checklist in the configuration guide and documented statistics in the ODS user guide. Detailed comparison methodology remains in the BC example. All 69 local links, scoped ODS Sphinx HTML with warnings treated as errors, 40 focused context tests, Black 26.3.1, whitespace and public API coverage (2,691/2,691) pass. The scoped build stubs unrelated reference targets; the full site was not built. Context links were revised for the consolidated ownership. No runtime behavior changed or new training experiment was run.

Review-fix validation: the complete data-pipeline package passes 437 tests, including a four-case regression proving segment filtering cannot mutate resident validity. On this host, five native-import checks require the already documented matching /tmp/ods-dexsim-runtime overlay; the initial run without it retained five import failures and 432 passes. Four generation-wait cases pass under both Python 3.10 and py311; 33 cleanup fault cases pass under both, including real CPU children that ignore SIGTERM and must be killed/reaped. Twelve complete-run checkpoint-selection scenarios (two baseline reproductions and ten fixed cases) execute real CPU ChunkBC optimization, resident sampling, and atomic checkpoint save/reload with deterministic simulator/evaluator doubles. Twelve comparison cases cover missing/mismatched evaluation panels. Direct-file SDK validation imports the installed package in spawn/forkserver children, reads 1,330 frames and round-trips 332 frames through the real writer; all children and the writer exit. These are fault/integration checks, not new physical-task learning results. Black 26.3.1, changed-file Python 3.10 syntax, local example links, context-map validation and API coverage pass. Existing context remains accurate: source immutability and application-owned waits/evaluation/cleanup are preserved.

Tests used Python 3.11/Torch 2.7, LeRobot 0.4.4 and one OMP/MKL/OpenBLAS thread. On this host, deep native imports require the existing matching DexSim runtime overlay and CUDA visibility because the unmodified installed facade/Open3D CPU package is inconsistent. README instructions and the new validation record disclose that prerequisite and retain failed setup attempts.

Earlier public-source validation retained exact pre-extraction golden batches/RNG and paired CPU loss/gradient/model/optimizer updates against SDK-persisted data. Scoped resident-sampler measurements preserve exact output/RNG; they do not qualify full-path instrumentation cost or establish a training speedup.

Retained learning evidence and limits

The historical four-arm pilot used 3cd6379a, one learner seed, 2,500 updates per arm and 20 fixed development scenes. No final-test scenes were opened in that pilot.

Arm	Latest development successes	First evaluated qualifying checkpoint save	Full process time
Offline32 unrestricted	20/20	92.79 s	1,018.34 s
ODS256 protected	19/20	131.28 s	1,279.13 s
Offline256 unrestricted	19/20	326.96 s	1,238.62 s
Offline256 protected	19/20	333.53 s	1,246.67 s

Checkpoint qualification is retrospective, not online certification or the true threshold-crossing time. The offline256 cap never bound; the strong offline32 baseline reached a qualifying checkpoint earlier. This pilot establishes no general ODS efficiency/quality advantage. Earlier 99/100 feasibility and later 65/100 refresh regression remain recorded separately.

Remaining work: qualify complete instrumentation overhead and reuse profiles, then freeze a balanced multi-seed comparison with fresh held-out verification. Image/video sequence decoding, out-of-core loading, distributed quota ledgers, feedback-driven acquisition, DAgger, RLinf and exact replay-cache recovery are outside this change. The resident-allocation limit excludes SDK caches, auditing and bounded staging.

Evidence and reproduction

• ODS architecture and control/data-flow diagram
• ODS runtime and source guide
• ODS configuration and runtime verification
• BC offline comparison protocol
• Demo and reproduction commands
• Fresh py311 validation
• Public Dataset/source design
• Demo packet/CLI binding
• Historical evidence index

Type of change

• New feature
• Enhancement
• Documentation update

Checklist

• Run black ..
• Review/update affected documentation and project context.
• Verify public API documentation coverage.
• Retain focused production-contract tests and validate example behavior with real runs.
• Document optional dependencies, runtime prerequisites and experimental limits.

[greptile-apps]

Confidence Score: 5/5

[High impact] The PR appears safe to merge, with one non-blocking logging issue on Python 3.10.

Findings

1.  Secondary errors disappear ▶

Fix with agent prompt

### Issue 1
examples/ods/simple_bc_demo/trainer.py:201-205
On supported Python 3.10, `_add_error_note()` now stores secondary errors only in `__notes__`, which that version does not show in tracebacks. Report-writing and cleanup errors therefore disappear from terminal logs. If the report files also cannot be written, users lose those details entirely.

Keep the stored notes, but also print them to stderr in this fallback.

Note: If this suggestion doesn't match your team's coding style, reply to this and let me know. I'll remember it for next time!

---

For each issue above, determine whether it is valid and should be fixed. If so, fix it directly.

Summary

Adds shared numeric datasets for live ODS, resident tensors and LeRobot files, plus a self-contained Franka behavior-cloning demo.

• Live and stored numeric data can supply the same causal training batches.
• ODS tracks source delivery and can plan refill and pacing from measured rates.
• The local Franka demo collects, trains, and tests a chunk-based policy.

Diagram

%%{init: {'theme': 'neutral'}}%%
flowchart LR
    Producer[Expert producer] --> Cache[Shared ODS cache]
    Cache --> Live[OnlineDataSource]
    Tensors[Resident tensors] --> Resident[TensorDataSource]
    Files[LeRobot files] --> Stored[LeRobotDataSource]
    Live --> Contract[BatchSource]
    Resident --> Contract
    Stored --> Contract
    Contract --> Dataset[SequenceDataset or direct sampling]
    Dataset --> Trainer[Demo trainer]
    Trainer --> Checkpoint[Saved checkpoint]
    Checkpoint --> Evaluation[Independent student evaluation]

Loading

_{Reviews (9) · Last reviewed commit: "fix(ods): preserve legacy cleanup notes ..." · Reviewed by Greptile}

[greptile-apps]

Secondary errors disappear

On supported Python 3.10, _add_error_note() now stores secondary errors only in __notes__, which that version does not show in tracebacks. Report-writing and cleanup errors therefore disappear from terminal logs. If the report files also cannot be written, users lose those details entirely.

Keep the stored notes, but also print them to stderr in this fallback.

Prompt To Fix With AI

This is a comment left during a code review.
Path: examples/ods/simple_bc_demo/trainer.py
Line: 201-205

Comment:
**Secondary errors disappear**

On supported Python 3.10, `_add_error_note()` now stores secondary errors only in `__notes__`, which that version does not show in tracebacks. Report-writing and cleanup errors therefore disappear from terminal logs. If the report files also cannot be written, users lose those details entirely.

Keep the stored notes, but also print them to stderr in this fallback.

---

For each issue above, determine whether it is valid and should be fixed. If so, fix it directly.

Note: If this suggestion doesn't match your team's coding style, reply to this and let me know. I'll remember it for next time!