Add NeRD model extension and an SL training showcase

.github/workflows/main.yml

@@ -569,6 +569,7 @@ jobs:
               "embodichain_tasks/configs/tasks/manipulation/tableware/pour_water/env.yaml",
               "embodichain_robots/__init__.py",
               "embodichain_robots/_catalog.py",
+              "embodichain_models/__init__.py",
               "embodichain_robots/_asset_catalog.py",
               "embodichain/data/_asset_registry.py",
               "embodichain_robots/franka/assets.py",
@@ -607,6 +608,7 @@ jobs:
                       "embodichain_tasks/",
                       "embodichain_robots/",
                       "embodichain_benchmarks/",
+                      "embodichain_models/",
                       f"embodichain-{version}.data/data/share/embodichain/examples/",
                       dist_info,
                   )

agent_context/MAP.yaml

@@ -268,6 +268,25 @@ topics:
     tests/gym/envs/task_program/test_simulation_environment.py]
   related_topics: [scene-services, simulation-system, task-programs, robot-workspace, motion-planning, gen-sim, data-pipeline]
   status: active
+- id: neural-dynamics
+  title: Neural Dynamics Models and Training
+  aliases: [neural dynamics, neural robot dynamics, NeRD, 神经动力学, 动力学模型训练, NeRD 示例]
+  keywords: [NeRDStateCodec, NeRDModel, DynamicsGenerationCfg,
+    DynamicsShardWriter, DynamicsWindowDataset, DynamicsTrainer, embodichain_models,
+    learning/nerd, nerd reference assets,
+    官方训练精度对比]
+  paths: [topics/neural-dynamics/neural-dynamics.md]
+  source_of_truth:
+  - extensions/embodichain_models/embodichain_models/dynamics/nerd/
+  - examples/learning/nerd/__main__.py
+  - examples/learning/nerd/_resources.py
+  - examples/learning/nerd/_support/
+  - examples/learning/nerd/configs/
+  watch_paths: [extensions/embodichain_models/, examples/learning/nerd/,
+    docs/source/features/neural_dynamics.md,
+    docs/source/api_reference/model_catalogs.rst]
+  related_topics: [supervised-learning, learning-layers, data-pipeline, data-assets]
+  status: active
 - id: learning-layers
   title: Differentiable Learning Layers
   aliases: [learning layers, differentiable IK layer, 可微 IK, 训练层, 学习模块分层]
@@ -485,7 +504,7 @@ topics:
     embodichain/lab/gym/envs/managers/async_datasets.py, embodichain/lab/gym/envs/embodied_env.py, embodichain/lab/scripts/run_task.py,
     tests/data_pipeline/, embodichain/cli/dataset.py, tools/lerobot_export/, examples/ods/simple_bc_demo/,
     docs/source/features/online_data.md, docs/source/features/ods/, docs/architecture/dataset-loading-design.md]
-  related_topics: [manager-functor, env-framework, task-programs, sensor-system]
+  related_topics: [manager-functor, env-framework, task-programs, sensor-system, neural-dynamics, supervised-learning]
   status: active
 - id: robot-workspace
   title: Robot Workspace
@@ -525,3 +544,15 @@ topics:
   watch_paths: [embodichain/data/asset_catalog/, tests/data/asset_catalog/, embodichain/lab/task_program/semantics/asset_requirements.py, tests/lab/task_program/semantics/test_asset_requirements.py, embodichain/lab/task_program/semantics/asset_matching.py, tests/lab/task_program/semantics/test_asset_matching.py, embodichain/lab/task_program/integrations/asset_materialization.py, tests/gym/envs/task_program/test_asset_materialization.py, embodichain/lab/gym/envs/asset_generalization.py, tests/gym/envs/test_asset_generalization.py, examples/expansion/asset_generalization/, examples/expansion/asset_catalog/, examples/expansion/README.md]
   related_topics: [data-assets, task-programs, gen-sim, scene-services, manager-functor, env-framework]
   status: active
+
+- id: supervised-learning
+  title: Supervised Learning
+  aliases: [supervised learning, SL learning, 监督学习, 统一监督学习]
+  keywords: [train-sl, SupervisedBatch, LossResult, SupervisedObjective, SupervisedLearner, SupervisedTrainer, TensorBatchSource]
+  paths: [topics/supervised-learning/supervised-learning.md]
+  source_of_truth:
+  - embodichain/learning/sl/
+  - embodichain/cli/main.py
+  watch_paths: [embodichain/learning/sl/, tests/learning/sl/]
+  related_topics: [learning-layers, data-pipeline, rl-learning, neural-dynamics]
+  status: active

agent_context/topics/data-pipeline/data-pipeline.md

@@ -23,6 +23,7 @@ belongs to [data-assets](../data-assets/data-assets.md).
 | Offline collection retries and final partial batch | `embodichain/lab/scripts/run_task.py` |
 | File-only validation and grouped quality splits | `embodichain/data_pipeline/datasets/inspection.py`; `embodichain dataset validate\|split` |
 | Durable commit diagnostics and metadata repair | `embodichain/data_pipeline/recording/journal.py`; `embodichain dataset recover` |
+| NeRD-specific HDF5 windows and teacher collection | `extensions/embodichain_models/embodichain_models/dynamics/nerd/data.py` and `examples/learning/nerd/_support/_generation.py`; contracts in [neural dynamics](../neural-dynamics/neural-dynamics.md) |
 | Isolated LeRobot 0.6.1 language/depth conversion | `tools/lerobot_export/` (Python >=3.12, independent dependencies) |
 
 Read [online sampling](online-sampling.md) for worker states, refill, shared

agent_context/topics/learning-layers/learning-layers.md

@@ -9,8 +9,13 @@ returns TCP poses and geometric Jacobians from one FK pass, retaining dJ/dq.
 
 `learning/layers/` owns `KinematicsLayer` and `DifferentiableIKLayer` Torch
 module interfaces. `learning/models/` owns general MLPs, feature normalization
-and configuration-driven MLP construction. These components do not import RL,
-TensorDict or simulation. RL policy interfaces, actor-critic composition and
+and configuration-driven MLP construction. These shared components do not import
+RL, TensorDict or simulation. Concrete NeRD models, codecs and the shared-SL
+recipe live in the bundled `embodichain_models.dynamics.nerd` extension;
+teacher collection, historical training and research belong to
+`examples/learning/nerd/`. See
+[neural dynamics](../neural-dynamics/neural-dynamics.md) for model, SL integration,
+dataset and checkpoint ownership. RL policy interfaces, actor-critic composition and
 policy registration/builders belong to `learning/rl/policies/`; RL code consumes
 the shared networks and normalizer. See [RL learning](../rl-learning/rl-learning.md)
 for those contracts.
@@ -21,6 +26,9 @@ There is no registered Robot solver adapter: callers provide root-frame targets
 and explicitly configure the layer's TCP and limits. Existing Robot solver binding
 and arena conversion remain in [IK solvers](../ik-solvers/ik-solvers.md).
 
+Supervised optimizer and offline-run ownership belongs to
+[supervised learning](../supervised-learning/supervised-learning.md).
+
 ## Gradient and state boundaries
 
 Targets are root-frame TCP matrices; seed batch axes match the target or contain

agent_context/topics/neural-dynamics/neural-dynamics.md

@@ -0,0 +1,95 @@
+# Neural dynamics models and training
+
+## Entry points and ownership
+
+The main wheel bundles `embodichain_models` with the same version and dependencies.
+It is an import package under `extensions/`, not a separate distribution or a
+runtime registry. Shared MLPs and feature normalization stay in core
+`embodichain.learning.models`; generic supervised orchestration stays in
+[SL](../supervised-learning/supervised-learning.md).
+
+The [model catalog contract](../../../extensions/embodichain_models/README.md)
+owns domain and public-import naming. Policy models predict actions; dynamics
+models predict future state or geometry. RWM and RigidFormer follow-ups use
+`dynamics.rwm` and `dynamics.rigidformer`; only `dynamics.nerd` is implemented here.
+World-model naming does not introduce a parallel `world_models` domain.
+
+| Request | Owner |
+|---|---|
+| NeRD network, portable checkpoint, physical codec | `extensions/embodichain_models/embodichain_models/dynamics/nerd/{model,checkpoint,codec}.py` |
+| Committed HDF5 shards and bounded windows | Model package `data.py`, private `_resident.py` |
+| Encoding, frozen moments and offline errors | Model package `integration.py` |
+| Objective and common trainer factory | Model package `supervised.py`, `sl_recipe.py` |
+| Prepare/train/export/eval/generate commands | `examples/learning/nerd/__main__.py`; `embodichain run-example learning/nerd` |
+| Pinned datasets, exports and reference assets | Example `_resources.py`; explicit `prepare` command |
+| Analytical teacher and physical profile | Example `_support/{_generation,_newton,_reference_assets}.py` |
+| Historical trainer and checkpoint workflow | Example `_support/{_trainer,_workflow}.py` |
+| Original-repository comparison and acceptance | Example `_support/` runners; protocol in `research/` |
+
+The showcase defaults to `sl.train.yaml` and the installable
+`embodichain_models.dynamics.nerd.sl_recipe:build_supervised_trainer` factory.
+Direct `embodichain train-sl --config FILE` works independently of example
+bootstrap. An explicitly selected `dynamics.train.*.yaml` uses the historical
+trainer for controlled comparisons and its legacy checkpoint contract.
+
+The extension imports neither examples nor simulation. Generation uses Newton's
+built-in Featherstone/MuJoCo solvers directly without a DexSim custom solver or
+Scene API. Native learned-solver deployment and functional Gym integration are
+separate consumers. There are no NeRD-specific core `compute/dynamics`,
+`data_pipeline/dynamics`, `learning/dynamics` modules or core `dynamics` command.
+
+## Resource and physical identity
+
+`prepare --robot cartpole|ant --resource-root DIR` downloads the pinned dataset,
+portable model and raw reference assets. Revisions and SHA256 checks are owned by
+`_resources.py`; `--assets-only` skips data/model downloads and
+`--local-files-only` forbids network access. The default resource root is
+`EMBODICHAIN_NERD_RESOURCE_ROOT`, otherwise the showcase cache under
+`XDG_CACHE_HOME` or `~/.cache`. Downloads do not live in Git or the wheel; model
+third-party licensing remains in the model package.
+
+A trajectory has T+1 states and T effort/contact inputs. Splits belong to whole
+trajectories; windows never cross episodes or splits. Only manifest-committed
+shards are visible. Generation commits its cursor and rejection evidence with
+shards; rejection-only progress preserves data fingerprints. Legacy progress
+sidecars remain readable, while collector source and physical identity still
+must match to continue collection. A path move does not authorize cross-version
+resume or reconstruct missing historical rejection evidence.
+
+The direct teacher records importer profile, asset/physical-array hashes, solver
+settings and actual Newton/Warp versions. Its `nerd-direct-newton-builder-v1`
+signature differs from published Scene-generated data, which remains readable
+without simulation. `warp_reference` reconstructs historical asset parameters
+and Ant friction mapping; matching that name does not prove identical physics
+across model-building paths, versions or solvers.
+
+The codec owns COM-to-spatial-twist transport and relative targets in the frame
+at t. Ant uses 25 ordered plane-contact slots; Cartpole is contact-free. Controls
+are generalized efforts with zero free-base force. Frozen train-only moments
+are reused for evaluation, and supplied statistics must bind the training data
+fingerprint. Do not relabel physical records or replace their normalizers.
+
+## Training and validation
+
+SL checkpoints use the common trainer format and resume through the same
+recipe/signature. The historical trainer keeps `embodichain.nerd.training.v1`:
+`last.pt` retains optimizer, scheduler, RNG, committed sampling state and one
+owned CPU snapshot of the selected best model; automatic `best.pt` is export-only.
+Both trainers use shared run-directory/history admission from SL. Common `train`
+does not turn its final `last.pt` into a validation-selected model.
+
+The showcase `export` accepts common SL and historical NeRD checkpoints and
+writes the same portable tensor/JSON model format. Precision, ordered feature
+layout, normalization and attention policy are part of recovery/export identity.
+Historical fine-tuning and shared sample-order options require a historical
+configuration. Only explicitly trusted legacy conversion unpickles model objects.
+
+Frozen source revisions, budgets and gates live in the
+[acceptance protocol](../../../examples/learning/nerd/research/acceptance.md).
+Historical evidence remains bound to its recorded source, data and runtime;
+relocating code does not rerun it. NeRD validation uses the runnable showcase
+and its reference/acceptance workflows; `tests/learning/sl/` covers the common
+training contracts. The [feature guide](../../../docs/source/features/neural_dynamics.md)
+owns user commands; the [model API](../../../docs/source/api_reference/model_catalogs.rst)
+owns exported definitions. Transition error, accumulated rollout error and
+paper-scale accuracy remain separate claims.

agent_context/topics/supervised-learning/supervised-learning.md

@@ -0,0 +1,45 @@
+# Supervised learning (SL)
+
+`embodichain.learning.sl` owns common supervised optimizer updates and offline
+training orchestration. Shared MLPs and feature normalization remain in
+`learning.models`; concrete model families and their model-specific adapters live
+in the bundled `embodichain_models` extension. Generic numerical state and geometry
+operations remain in `compute`; source storage belongs to data adapters.
+
+## Entry points
+
+- `SupervisedBatch` and `LossResult` in `learning/sl/types.py` preserve structured
+  inputs, targets, masks and objective-specific reductions.
+- `SupervisedLearner.update()` in `learning/sl/learner.py` owns a finite optimizer
+  update. Its optional numerical context covers forward, backward and clipping.
+- `TensorBatchSource` snapshots fixed CPU tensor trees and returns owned samples
+  under the caller's explicit CPU generator.
+- `SupervisedTrainer` in `learning/sl/trainer.py` composes a source and learner,
+  saving optimizer, RNG, sampling progress, source identity and recipe semantics.
+- `embodichain train-sl --config FILE [--resume FILE]` lazily resolves a
+  `factory: module:function`. The factory receives the full model/data/objective/
+  optimizer/trainer/evaluation configuration and returns a `SupervisedTrainer`.
+- The [NeRD recipe](../neural-dynamics/neural-dynamics.md) is an installable factory
+  at `embodichain_models.dynamics.nerd.sl_recipe:build_supervised_trainer`.
+  The core does not import the model extension or example helpers. The NeRD
+  showcase's default `train` command uses this same common recipe.
+
+Objectives own loss masks, normalization, integration and multi-step graph
+construction. The optimizer does not infer action semantics or detach histories.
+Schema, action/frame/timestep and numerical-policy identifiers belong in each
+recipe's checkpoint signature. Tensor sources additionally bind content identity.
+`learning/sl/_artifacts.py` owns run identities and output-history admission for
+both SL and historical NeRD trainers. A fresh run claims `run.json`; resuming an
+occupied directory requires the checkpoint's matching run identity. Checkpoints
+without an identity require an artifact-free destination. Newer or incomplete
+metric history is retained and requires a fresh resume destination.
+Validation callbacks preserve RNG, sampling state and model buffers, including
+checkpoints saved inside a callback. Only development data may select checkpoints.
+Acquisition and producer lifecycles remain application-owned.
+
+## Validation
+
+`tests/learning/sl/` checks independent masked updates, graph propagation,
+nonfinite update boundaries, owned samples, simulator-free imports and exact
+CPU recovery with dropout, optimizer and sampling state. Model-specific
+qualification belongs to each model's acceptance recipe.