Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
19 commits
Select commit Hold shift + click to select a range
15ef004
refactor(packaging)!: namespace the official extensions
yuecideng Nov 18, 2026
8cbaf1b
docs(architecture): refresh extension namespace references
yuecideng Nov 18, 2026
3b719d6
test(ci): stage extension fixtures as nested packages
yuecideng Nov 18, 2026
f1a22b6
Merge main and fix extension namespace regressions
yuecideng Nov 18, 2026
be260e7
docs(architecture): refresh the snapshot after syncing main
yuecideng Nov 18, 2026
c247197
Merge main and migrate the bundled VLP-16 preset
yuecideng Nov 19, 2026
75fc5a1
docs(architecture): refresh the snapshot after merging main
yuecideng Nov 19, 2026
b3bad38
Merge main and migrate the incoming task configurations
yuecideng Nov 19, 2026
fe10605
docs(architecture): refresh after syncing main
yuecideng Nov 19, 2026
a79dd9b
Merge latest main and migrate incoming RL tasks
yuecideng Nov 19, 2026
66fe833
docs(architecture): refresh after syncing the incoming RL tasks
yuecideng Nov 19, 2026
5c2ebdb
fix(packaging): address extension migration review feedback
yuecideng Nov 19, 2026
318da3e
Merge main and update the packaged task catalog fixture
yuecideng Nov 19, 2026
c38aa69
docs(architecture): refresh after syncing the task catalog
yuecideng Nov 19, 2026
dabd052
Merge main and package the incoming cable routing deployment
yuecideng Nov 19, 2026
cb7b27c
docs(architecture): refresh after syncing cable routing
yuecideng Nov 19, 2026
bca6e91
Merge main and stabilize the dual-arm handover release
yuecideng Nov 20, 2026
2e80a1e
docs(architecture): refresh after syncing v0.3.3
yuecideng Nov 20, 2026
b519786
fix(packaging): honor dry-run and correct legacy uninstall
yuecideng Nov 20, 2026
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
The table of contents is too big for display.
Diff view
Diff view
  •  
  •  
  •  
4 changes: 2 additions & 2 deletions .agents/skills/add-embodiment-component/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -13,7 +13,7 @@ configuration serve many tasks.
An embodiment component belongs at:

```text
extensions/embodichain_tasks/configs/components/embodiments/<embodiment_id>.yaml
embodichain/extensions/tasks/configs/components/embodiments/<embodiment_id>.yaml
```

It owns exactly:
Expand All @@ -37,7 +37,7 @@ Read `agent_context/MAP.yaml`, then resolve:
- `task-programs` when a `skill_profile` is requested.

Inspect the closest current component under
`extensions/embodichain_tasks/configs/components/embodiments/` and the intended runnable
`embodichain/extensions/tasks/configs/components/embodiments/` and the intended runnable
task deployment.

## Reuse or add the robot
Expand Down
12 changes: 6 additions & 6 deletions .agents/skills/add-robot/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -33,7 +33,7 @@ return merge_robot_cfg(cfg, init_dict)

## Two Layouts

Concrete configs live in the `extensions/embodichain_robots/` import package, bundled
Concrete configs live in the `embodichain/extensions/robots/` import package, bundled
with the core distribution/version. Generic robot runtime, configuration,
solvers, and composition stay in `embodichain/lab/sim/`.

Expand Down Expand Up @@ -109,12 +109,12 @@ must match the matching `control_parts` entry (the test stub asserts this).

5. **Keep `from_dict` as the 3-line template** — do not reimplement it.
6. **Add `__all__` and register** the class in
`extensions/embodichain_robots/_catalog.py`, then add its lazy export to
`extensions/embodichain_robots/__init__.py` (`_EXPORTS` and `__all__`):
`embodichain/extensions/robots/_catalog.py`, then add its lazy export to
`embodichain/extensions/robots/__init__.py` (`_EXPORTS` and `__all__`):

```python
# Catalog entry; importing the catalog must not import the robot module.
"MyRobot": {"class_path": "embodichain_robots.my_vendor.my_robot:MyRobotCfg"}
"MyRobot": {"class_path": "embodichain.extensions.robots.my_vendor.my_robot:MyRobotCfg"}
```

The main wheel already advertises this catalog through `embodichain.robots`.
Expand Down Expand Up @@ -213,8 +213,8 @@ Do not copy those semantic declarations into the robot class.

**File locations:**

- Config: `extensions/embodichain_robots/<vendor>/<model>.py` or `<vendor>/<model>/`
- Catalog / lazy exports: `extensions/embodichain_robots/_catalog.py`, `extensions/embodichain_robots/__init__.py`
- Config: `embodichain/extensions/robots/<vendor>/<model>.py` or `<vendor>/<model>/`
- Catalog / lazy exports: `embodichain/extensions/robots/_catalog.py`, `embodichain/extensions/robots/__init__.py`
- Shared resolver: `embodichain/robot_registry.py`
- Docs: `docs/source/resources/robot/<vendor>/<model>.md` and the owning index
- Tests: `tests/sim/objects/test_robot_cfg.py`
Expand Down
6 changes: 3 additions & 3 deletions .agents/skills/add-task-env/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -62,8 +62,8 @@ Resolve from the prompt or nearby conventions:
Organize by task identity, never by solution method. Use:

```text
extensions/embodichain_tasks/embodichain_tasks/<category_path>/<task_name>.py
extensions/embodichain_tasks/configs/tasks/<category_path>/<task_name>/
embodichain/extensions/tasks/<category_path>/<task_name>.py
embodichain/extensions/tasks/configs/tasks/<category_path>/<task_name>/
```

Keep a single task Python entry point flat at `<task_name>.py`. Do not create a
Expand Down Expand Up @@ -127,7 +127,7 @@ deployment. Use separate environment files for backend-specific settings.
### Optional Python entry point

Create
`extensions/embodichain_tasks/embodichain_tasks/<category_path>/<task_name>.py` when the
`embodichain/extensions/tasks/<category_path>/<task_name>.py` when the
route requires import-owned behavior or registration:

- an environment-only registered Gym task;
Expand Down
8 changes: 4 additions & 4 deletions .agents/skills/add-task-env/references/handwritten-expert.md
Original file line number Diff line number Diff line change
Expand Up @@ -8,8 +8,8 @@ scripted/handwritten demonstration.
## Owned files

```text
extensions/embodichain_tasks/embodichain_tasks/<category_path>/<task_name>.py
extensions/embodichain_tasks/configs/tasks/<category_path>/<task_name>/
embodichain/extensions/tasks/<category_path>/<task_name>.py
embodichain/extensions/tasks/configs/tasks/<category_path>/<task_name>/
tests/gym/envs/tasks/test_<task_name>.py
```

Expand Down Expand Up @@ -97,6 +97,6 @@ use the project's resource markers and clean up `SimulationManager`.

Reference implementations:

- `extensions/embodichain_tasks/embodichain_tasks/manipulation/tableware/blocks_ranking_rgb.py`
- `extensions/embodichain_tasks/embodichain_tasks/manipulation/tableware/stack_blocks_two.py`
- `embodichain/extensions/tasks/manipulation/tableware/blocks_ranking_rgb.py`
- `embodichain/extensions/tasks/manipulation/tableware/stack_blocks_two.py`
- `embodichain/lab/gym/envs/demo.py`
4 changes: 2 additions & 2 deletions .agents/skills/add-task-env/references/rl.md
Original file line number Diff line number Diff line change
Expand Up @@ -56,7 +56,7 @@ Select it from the training config with:

```yaml
trainer:
gym_config: extensions/embodichain_tasks/configs/tasks/<category_path>/<task_name>/<deployment>.yaml
gym_config: embodichain/extensions/tasks/configs/tasks/<category_path>/<task_name>/<deployment>.yaml
```

Simulator environments use standard rollouts. PPO and GRPO are current
Expand All @@ -67,7 +67,7 @@ standard examples.
Keep the task entry point flat:

```text
extensions/embodichain_tasks/embodichain_tasks/<category_path>/<task_name>.py
embodichain/extensions/tasks/<category_path>/<task_name>.py
```

Register the factory with `@register_learning_env` and implement the
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -10,7 +10,7 @@ only the surrounding task/environment decisions.
## Canonical layout

```text
extensions/embodichain_tasks/configs/tasks/<category_path>/<task_name>/
embodichain/extensions/tasks/configs/tasks/<category_path>/<task_name>/
├── env.yaml
├── task.<embodiment>.yaml
└── task_program/
Expand Down
2 changes: 1 addition & 1 deletion .agents/skills/add-task-program/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -118,7 +118,7 @@ Run the bundled read-only inspector for complete configured deployments:

```bash
python .agents/skills/add-task-program/scripts/inspect_deployment.py \
extensions/embodichain_tasks/configs/tasks/<category_path>/<task_name>/task.<embodiment>.yaml
embodichain/extensions/tasks/configs/tasks/<category_path>/<task_name>/task.<embodiment>.yaml
```

This command performs levels 1-4 without constructing a simulator. It does not
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -11,7 +11,7 @@ programmatic composition, reuse in code, or a typed tutorial/test.
Serialized programs belong at:

```text
extensions/embodichain_tasks/configs/tasks/<category_path>/<task_name>/task_program/program.yaml
embodichain/extensions/tasks/configs/tasks/<category_path>/<task_name>/task_program/program.yaml
```

The public Python API is `embodichain.lab.task_program`. A provider-independent
Expand Down
2 changes: 1 addition & 1 deletion .agents/skills/add-test/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -50,7 +50,7 @@ Tests mirror the source tree under `tests/`:
embodichain/lab/sim/motion/solvers/pytorch_solver.py → tests/sim/motion/solvers/test_pytorch_solver.py
embodichain/lab/gym/envs/managers/rewards.py → tests/gym/envs/managers/test_reward_functors.py
embodichain/toolkits/graspkit/pg_grasp/foo.py → tests/toolkits/test_pg_grasp.py
extensions/embodichain_tasks/embodichain_tasks/manipulation/push_cube.py → tests/gym/envs/tasks/test_push_cube.py
embodichain/extensions/tasks/manipulation/push_cube.py → tests/gym/envs/tasks/test_push_cube.py
```

Rules:
Expand Down
6 changes: 3 additions & 3 deletions .agents/skills/review-pr/references/review-matrix.md
Original file line number Diff line number Diff line change
Expand Up @@ -20,7 +20,7 @@ and current source code when this matrix and the repository diverge.
## Common checks

- Preserve the distribution name `embodichain`, the core import package
`embodichain`, and the bundled task import package `embodichain_tasks`.
`embodichain`, and the bundled task import package `embodichain.extensions.tasks`.
- Check the complete call or configuration-resolution path, not only the
changed definition. Inspect its closest tests and at least one caller or
consumer.
Expand Down Expand Up @@ -212,7 +212,7 @@ tests. Run GPU/distributed tests serially and only when justified.

## Official tasks and configuration packages

**Paths:** `extensions/embodichain_tasks/**` and reusable task components.
**Paths:** `embodichain/extensions/tasks/**` and reusable task components.

Check:

Expand All @@ -230,7 +230,7 @@ Check:
composition, not only `yaml.safe_load`. Relative files and scene targets must
resolve after wheel installation.
- New or moved config/assets are present in wheel contents; deleted files are
not retained accidentally. Imports use `embodichain_tasks`, not a repository
not retained accidentally. Imports use `embodichain.extensions.tasks`, not a repository
folder assumption.

Evidence surfaces: the task-named module, deployment/component files,
Expand Down
4 changes: 2 additions & 2 deletions .ci/test-impact.toml
Original file line number Diff line number Diff line change
Expand Up @@ -275,7 +275,7 @@ risk = "medium"
[[rules]]
id = "robot-system"
paths = [
"extensions/embodichain_robots/**",
"embodichain/extensions/robots/**",
"embodichain/lab/sim/robots/**",
"embodichain/lab/sim/objects/robot.py",
]
Expand Down Expand Up @@ -327,7 +327,7 @@ id = "task-program"
paths = [
"embodichain/lab/task_program/**",
"embodichain/lab/gym/envs/task_program/**",
"extensions/embodichain_tasks/**",
"embodichain/extensions/tasks/**",
]
tests = [
"tests/lab/task_program/**",
Expand Down
2 changes: 1 addition & 1 deletion .github/workflows/dataset-tooling.yml
Original file line number Diff line number Diff line change
Expand Up @@ -14,7 +14,7 @@ on:
- 'tests/data_pipeline/**'
- 'tests/test_lerobot_compatibility.py'
- 'tests/models/policy/**'
- 'extensions/embodichain_models/embodichain_models/policy/act/**'
- 'embodichain/extensions/models/policy/act/**'
- 'examples/learning/act/**'
- 'tests/gym/envs/managers/**'
- 'embodichain/lab/scripts/preview_lerobot_data.py'
Expand Down
51 changes: 24 additions & 27 deletions .github/workflows/main.yml
Original file line number Diff line number Diff line change
Expand Up @@ -66,7 +66,6 @@ jobs:
docs:
- 'docs/**'
- 'embodichain/**'
- 'extensions/**'
- 'examples/**'
- 'README.md'
- 'pyproject.toml'
Expand Down Expand Up @@ -617,17 +616,19 @@ jobs:
required = {
"embodichain/VERSION",
"embodichain/gen_sim/asset_engine/configs/gen_config.json",
"embodichain_tasks/__init__.py",
"embodichain_tasks/configs/tasks/manipulation/tableware/pour_water/env.yaml",
"embodichain_robots/__init__.py",
"embodichain_robots/_catalog.py",
"embodichain_models/__init__.py",
"embodichain_sensors/__init__.py",
"embodichain_solvers/__init__.py",
"embodichain_robots/_asset_catalog.py",
"embodichain/extensions/__init__.py",
"embodichain/extensions/benchmarks/__init__.py",
"embodichain/extensions/solvers/__init__.py",
"embodichain/extensions/sensors/__init__.py",
"embodichain/extensions/tasks/__init__.py",
"embodichain/extensions/tasks/configs/tasks/manipulation/tableware/pour_water/env.yaml",
"embodichain/extensions/robots/__init__.py",
"embodichain/extensions/robots/_catalog.py",
"embodichain/extensions/models/__init__.py",
"embodichain/extensions/robots/_asset_catalog.py",
"embodichain/data/_asset_registry.py",
"embodichain_robots/franka/assets.py",
"embodichain_robots/dexforce/w1/assets.py",
"embodichain/extensions/robots/franka/assets.py",
"embodichain/extensions/robots/dexforce/w1/assets.py",
}
with ZipFile(wheels[0]) as wheel:
members = set(wheel.namelist())
Expand All @@ -643,14 +644,14 @@ jobs:
)

source_task_configs = {
path.relative_to("extensions").as_posix()
for path in Path("extensions/embodichain_tasks/configs").rglob("*")
path.as_posix()
for path in Path("embodichain/extensions/tasks/configs").rglob("*")
if path.suffix in {".json", ".yaml", ".yml"}
}
wheel_task_configs = {
member
for member in members
if member.startswith("embodichain_tasks/configs/")
if member.startswith("embodichain/extensions/tasks/configs/")
and member.endswith((".json", ".yaml", ".yml"))
}
unexpected = sorted(
Expand All @@ -659,12 +660,6 @@ jobs:
if not member.startswith(
(
"embodichain/",
"embodichain_tasks/",
"embodichain_robots/",
"embodichain_benchmarks/",
"embodichain_models/",
"embodichain_sensors/",
"embodichain_solvers/",
f"embodichain-{version}.data/data/share/embodichain/examples/",
dist_info,
)
Expand All @@ -674,7 +669,7 @@ jobs:
)
missing = sorted(required - members)
retired_robot_modules = {
f"embodichain_robots/{name}.py"
f"embodichain/extensions/robots/{name}.py"
for name in (
"arx5", "aloha_mini", "cobotmagic", "franka_panda",
"flexiv_rizon4s", "tianji_marvin", "ur_robot", "so101",
Expand All @@ -683,24 +678,26 @@ jobs:
stale_robot_modules = sorted(
member for member in members
if member in retired_robot_modules
or member.startswith("embodichain_robots/dexforce_w1/")
or member.startswith("embodichain/extensions/robots/dexforce_w1/")
)
missing_task_configs = sorted(source_task_configs - wheel_task_configs)
unexpected_task_configs = sorted(wheel_task_configs - source_task_configs)
task_entry_point = "embodichain_tasks = embodichain_tasks"
task_entry_point = entry_point_config.get(
"embodichain.tasks", "official_tasks", fallback=None
) == "embodichain.extensions.tasks"
robot_entry_point = entry_point_config.get(
"embodichain.robots", "official", fallback=None
) == "embodichain_robots._catalog:ROBOT_CONFIGS"
) == "embodichain.extensions.robots._catalog:ROBOT_CONFIGS"
asset_entry_point = entry_point_config.get(
"embodichain.assets", "official_robots", fallback=None
) == "embodichain_robots._asset_catalog:ROBOT_ASSETS"
) == "embodichain.extensions.robots._asset_catalog:ROBOT_ASSETS"
if (
unexpected
or missing
or stale_robot_modules
or missing_task_configs
or unexpected_task_configs
or task_entry_point not in entry_points
or not task_entry_point
or not robot_entry_point
or not asset_entry_point
):
Expand All @@ -710,7 +707,7 @@ jobs:
f"stale_robot_modules={stale_robot_modules}, "
f"missing_task_configs={missing_task_configs}, "
f"unexpected_task_configs={unexpected_task_configs}, "
f"task_entry_point={task_entry_point in entry_points}, "
f"task_entry_point={task_entry_point}, "
f"robot_entry_point={robot_entry_point}, "
f"asset_entry_point={asset_entry_point}"
)
Expand Down
22 changes: 11 additions & 11 deletions AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -16,11 +16,10 @@ Canonical skills live under `.agents/skills/`. `.claude/skills/` and
## Package and architecture

The distribution and primary import package are **`embodichain`**, lowercase
and one word. The repository directory is `EmbodiChain`; the same wheel
bundles official tasks as **`embodichain_tasks`** and concrete robot presets as
**`embodichain_robots`**, with the same version and distribution metadata.
Their sources live under **`extensions/`**, a repository container rather than
a Python namespace. Keep the `embodichain_` prefix for bundled extension modules.
and one word. The repository directory is `EmbodiChain`. The same wheel bundles
the official `tasks`, `robots`, `models`, `solvers`, `sensors`, and
`benchmarks` packages under `embodichain.extensions`. Put their sources and resources in
`embodichain/extensions/<name>/` and import them as `embodichain.extensions.<name>`.

| Area | Owner |
|---|---|
Expand All @@ -36,16 +35,17 @@ a Python namespace. Keep the `embodichain_` prefix for bundled extension modules
| RL algorithms, policies, collectors and trainers | `embodichain/learning/rl/` |
| Real-device controllers / standalone tools | `embodichain/lab/devices/`, `embodichain/toolkits/` |
| Shared config and math utilities | `embodichain/utils/` |
| Official task entry points / components / deployments | `extensions/embodichain_tasks/` |
| Concrete robot configurations / model-owned asset definitions / calibrated defaults | `extensions/embodichain_robots/` |
| Official task entry points / components / deployments | `embodichain/extensions/tasks/` |
| Official sensor presets | `embodichain/extensions/sensors/` |
| Concrete robot configurations / model-owned asset definitions / calibrated defaults | `embodichain/extensions/robots/` |

Generic robot runtime/configuration and dual-arm composition remain in
`embodichain/lab/sim/`; lightweight catalog resolution lives in
`embodichain/robot_registry.py`. Concrete robot presets register
through the `embodichain.robots` catalog entry point. Concrete presets and migrated model-owned asset definitions use vendor/model
namespaces in `embodichain_robots`. Shared download/cache machinery stays in
namespaces in `embodichain.extensions.robots`. Shared download/cache machinery stays in
`embodichain/data`; the `embodichain.assets` entry point registers robot assets.
Concrete presets import from `embodichain_robots`; `embodichain.lab.sim.robots` owns only generic
Concrete presets import from `embodichain.extensions.robots`; `embodichain.lab.sim.robots` owns only generic
dual-arm composition.

Shared numerical algorithms belong to `compute/<domain>/`, with Warp kernels
Expand Down Expand Up @@ -73,8 +73,8 @@ asset-defined spelling. Capabilities come from explicit configuration, not names

Organize official tasks by family, optional subdomain and task identity.
Keep import registration in the task-named module at
`extensions/embodichain_tasks/embodichain_tasks/<category-path>/<task>.py`; configs belong
under `extensions/embodichain_tasks/configs/tasks/<category-path>/<task>/`. Do not add a
`embodichain/extensions/tasks/<category-path>/<task>.py`; configs belong
under `embodichain/extensions/tasks/configs/tasks/<category-path>/<task>/`. Do not add a
same-named Python package for one entry point or `scenario` / `mdp` modules when
existing config fields and manager functors express the task.

Expand Down
Loading
Loading