Skip to content

Move official extensions under embodichain.extensions - #1229

Open
yuecideng wants to merge 18 commits into
mainfrom
codex/extension-namespace
Open

yuecideng wants to merge 18 commits into
mainfrom
codex/extension-namespace

Conversation

@yuecideng

Copy link
Copy Markdown
Contributor

Description

Move the official tasks, robots, models, solvers, and benchmarks packages into embodichain/extensions/. Update Python imports, bundled YAML references, plugin entry points, package-data checks, examples, and documentation to use the new layout.

Motivation

All five extensions already ship in the same EmbodiChain wheel. A shared Python namespace makes their ownership visible and lets an import path identify its source directory directly. Placing extension code and resources under the same package also removes the custom editable source mappings that can mix the core from one worktree with extensions from another.

Migration

  • Import official extensions through embodichain.extensions.<name> and use those module names in YAML factory and class references.
  • Reference bundled task YAML under embodichain/extensions/tasks/configs/.
  • Use embodichain show-task embodichain.extensions.tasks:pour_water for a qualified task key. The command also accepts an unqualified key such as pour_water.
  • Reinstall editable checkouts to refresh their entry-point metadata.

Type of change

  • Breaking change (existing callers must update extension imports and task configuration paths)

Validation

  • Built a wheel from the sdist and installed it in a clean Python 3.12 environment. Installed the checkout in a separate editable environment. Verified all five imports, removal of the old top-level imports, robot and asset catalogs, solver entry points, packaged resources, and both show-task and list-task from outside the checkout.
  • Compared the wheel against the main build and matched all 707 original extension files at their new paths, including the long-horizon Drawer Storage deployment.
  • Ran focused package, task catalog, config loader, robot registry, benchmark, workflow, and agent-context tests. Extended the existing installed-wheel test to exercise the qualified show-task command and adapted the Drawer Storage README test to check the actual packaged files.
  • Regenerated and validated the architecture snapshot. The API documentation checker covered 4,996 of 4,996 exports. The Sphinx dummy build completed and reported documentation warnings.

Checklist

  • Ran black . using Black 26.10.1.
  • Updated affected documentation and agent context.
  • Reflected the new public import paths in the API docs.
  • Verified focused behavioral coverage and reviewed the changes to existing tests.

@yuecideng yuecideng added refactor Structural changes; add breaking when user-visible compatibility changes. ci Continuous integration, build automation and release automation. breaking User-visible incompatible changes requiring migration. labels Nov 18, 2026
Migrate the incoming blind assembly and robot resources into the canonical extensions. Accept qualified task packages in official policy indexes and repair wheel staging and inspector test paths.
@yuecideng
yuecideng requested a review from han-xudong November 19, 2026 04:46
@greptile-apps

greptile-apps Bot commented Nov 19, 2026 •

Copy link
Copy Markdown

RetriggerView in GreptileConfidence Score: 5/5

[High impact] The PR appears safe to merge, with the previously reported cleanup-command documentation issue still outstanding.

Fix All in CodexFindings

  1. P2 Legacy task installs remain. ▶
Fix with agent prompt
### Issue 1
docs/source/quick_start/install.md:238-243
The upgrade command now uninstalls `embodichain.extensions.tasks`, but the old distribution is named `embodichain_tasks`. Pip treats these as different names, so the command skips the package this section is meant to remove. Keep the old distribution name and historical install path in these cleanup instructions; use the new namespace for current imports.

---

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

Summary

Moves the six bundled extension packages under embodichain.extensions.

  • Official extensions now live under the embodichain.extensions namespace.
  • Task discovery and config loading now use the relocated task package.
  • Package builds and plugin entries now point to the shared extension tree.
  • Runtime catalogs and tools now load extension modules from the shared namespace.

No new actionable findings were established.

Diagram

%%{init: {'theme': 'neutral'}}%%
flowchart LR
  A["embodichain wheel"] --> B["embodichain.extensions"]
  B --> C["tasks and configs"]
  B --> D["robots and assets"]
  B --> E["models"]
  B --> F["solvers"]
  B --> G["sensors"]
  B --> H["benchmarks"]
  I["Plugin entry points"] --> B
Loading

Reviews (5) · Last reviewed commit: "docs(architecture): refresh after syncin..." · Reviewed by Greptile

@han-xudong han-xudong left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Please address the three P2 findings before merging. The inline comments cover compatibility with existing ACT artifacts and NeRD checkouts, incremental wheel contents, and three smaller migration issues.

Comment thread examples/learning/act/_environment.py Outdated
IDENTITY_FILES = {
"extensions/embodichain_tasks/configs/tasks/manipulation/push_cube/task.franka.visual.yaml": TASK,
"extensions/embodichain_tasks/configs/tasks/manipulation/push_cube/env.visual.yaml": TASK.parent
"embodichain/extensions/tasks/configs/tasks/manipulation/push_cube/task.franka.visual.yaml": TASK,

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

[P2] Preserve compatibility with saved ACT task identities

task_identity() uses these repository paths as persisted dictionary keys. I compared the base and PR head and confirmed that all four file hashes are identical. Using the identity generated on the base, I reproduced both the training report validator rejecting the collection as a different task revision and the evaluation validator rejecting the checkpoint for a task mismatch. Please keep the persisted keys stable or normalize both key formats before comparing the hashes.

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Fixed in 5c2ebdbaf. The four keys in saved ACT task identities now retain their original spelling and hash the relocated files. I generated the prior identity from fb96705b0 and verified that both the collection report validator and the checkpoint evaluation validator accept it.

source
/ "extensions/embodichain_models/embodichain_models/dynamics/nerd/model.py"
).is_file():
if (source / "embodichain/extensions/models/dynamics/nerd/model.py").is_file():

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

[P2] Keep accepting NeRD checkouts with the previous extension layout

Passing a checkout of the base commit as the reference source now selects the older core-module fallback. I ran the worker against the same base checkout with both runners. The base runner completed the imports, while the PR runner failed on ModuleNotFoundError: No module named 'embodichain.compute.dynamics'. Please retain detection of the extensions/embodichain_models/embodichain_models/ layout and use the corresponding import paths and source files when launching workers and recording source hashes.

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Fixed in 5c2ebdbaf. The runner detects both extension layouts and selects the module names, import roots, and source hash paths for the requested checkout. I verified the worker imports and recorded model path against a separate checkout of fb96705b0.

Comment thread setup.py
"embodichain_tasks.configs",
]
)
find_namespace_packages(where=str(THIS_DIR), include=PACKAGE_PATTERNS)

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

[P2] Keep stale extension files out of incremental wheels

I built the base wheel, replaced the source tree with the PR head while retaining build/, and rebuilt with pip wheel . --no-deps --no-build-isolation. The new wheel contained the six migrated packages alongside 841 files in the retired embodichain_* namespaces. Package discovery selects the new layout, but setuptools still copies the existing build staging tree into the wheel. Please isolate wheel build staging or remove the retired extension staging directories before packaging.

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Fixed in 5c2ebdbaf. The build command clears the six retired extension directories from reused build staging. I built the base wheel and then the patched wheel with pip wheel . --no-deps --no-build-isolation while retaining build/. The rebuilt wheel excludes all 841 retired paths from the base wheel.

new environment implementations. Test the Hub boundary with fake downloads and
validate a real selected-model download separately.
new environment implementations. The index's `task_package` accepts a qualified
module name. Published official policy indexes declaring `embodichain.extensions.tasks`

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

[P3] Document the legacy task package name used by published policy indexes

All 12 models in the pinned official index declare embodichain_tasks. The loader maps that value to embodichain.extensions.tasks. Please document the actual old-to-new mapping here so the compatibility requirement is clear.

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Corrected in 5c2ebdbaf. The documentation now states that published indexes declaring embodichain_tasks resolve their package requirement to embodichain.extensions.tasks.

candidates = [
Path(__file__).resolve().parents[4]
/ "extensions/embodichain_models"
/ "embodichain/extensions/models"

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

[P3] Fix default codec discovery when running the NeRD script by path

relative already starts with embodichain/extensions/models, so this candidate duplicates that directory. I invoked the resolver from outside the checkout with the checkout absent from sys.path. The base found its codec and the PR head raised ValueError: Set transport_root to a frozen NeRD codec directory. This also affects script invocations that omit the optional transport_root. Please use Path(__file__).resolve().parents[4] / relative for the checkout candidate.

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Fixed in 5c2ebdbaf. The checkout candidate is now the repository root joined with the full relative codec path. I verified discovery from outside the checkout with its root removed from sys.path.

Comment thread tests/test_benchmark_package.py Outdated
assert name not in sys.modules, name

class ConcreteImportsForbidden(importlib.abc.MetaPathFinder):
def find_spec(self, fullname, path=None, target=None):
if fullname.split('.')[0] in {'embodichain_models', 'embodichain_solvers'}:
if fullname.split('.')[0] in {'embodichain.extensions.models', 'embodichain.extensions.solvers'}:

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

[P3] Restore the wheel test's concrete extension import guard

fullname.split('.')[0] produces embodichain for both migrated packages, so it can never match either dotted name. A direct probe confirmed that the old finder blocked a NeRD provider import and this finder allows the migrated equivalent. Please match the full package name or the package name followed by . so this test continues to detect forbidden imports from the core.

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Fixed in 5c2ebdbaf. The import finder now checks the full dotted package name and its descendants. The installed-wheel solver entry-point and core import-boundary test passed.

Comment on lines +238 to +243
If an older checkout was installed with `pip install -e embodichain/extensions/tasks/`,
remove that legacy editable distribution once before reinstalling the main
project:

```bash
pip uninstall -y embodichain_tasks
pip uninstall -y embodichain.extensions.tasks

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P2 Legacy task installs remain. The upgrade command now uninstalls embodichain.extensions.tasks, but the old distribution is named embodichain_tasks. Pip treats these as different names, so the command skips the package this section is meant to remove. Keep the old distribution name and historical install path in these cleanup instructions; use the new namespace for current imports.

Prompt To Fix With AI
This is a comment left during a code review.
Path: docs/source/quick_start/install.md
Line: 238-243

Comment:
**Legacy task installs remain.** The upgrade command now uninstalls `embodichain.extensions.tasks`, but the old distribution is named `embodichain_tasks`. Pip treats these as different names, so the command skips the package this section is meant to remove. Keep the old distribution name and historical install path in these cleanup instructions; use the new namespace for current imports.

---

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

Fix in Codex Fix in Claude Code

@yuecideng
yuecideng requested a review from han-xudong November 20, 2026 05:12

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

breaking User-visible incompatible changes requiring migration. ci Continuous integration, build automation and release automation. refactor Structural changes; add breaking when user-visible compatibility changes.

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants