[Fix] Make generated template projects import without Kit (no eager omni.ext)

[hujc7]

1. Summary

• Generated template projects could not be imported headless (e.g. Gym registration before SimulationApp): import <project> failed with ModuleNotFoundError: No module named 'omni.ext'. The package root no longer imports the example UI extension, so it stays omni-free. (NVBug 6251247)
• Hardened the generator to fail loudly when a requested agent-config template is missing, instead of silently emitting a project whose Gym registration points at a non-existent config.
• Self-contained on develop. Includes the template-generator test scaffolding (also proposed in Adds CI tests for template generator #5885, commit preserved) plus new regression coverage — 15 tests.

2. Changes

2.1 Generator (tools/template)

• templates/extension/__init__ext: drop the eager from .ui_extension_example import * from the package root.
• templates/extension/config/extension.toml: register <name>.ui_extension_example as its own [[python.module]] so Kit still loads the UI extension (Kit imports each python.module by name and scans it for omni.ext.IExt).
• templates/extension/ui_extension_example.py: add the missing import omni.ui.
• generator.py: raise (instead of silently continue-ing) when an agents/<rl_library>_<algorithm>_cfg template is missing.

2.2 Tests

• Existing scaffolding: algorithm discovery, single/multi-agent registry entry points, launch configs.
• New regressions: omni/pxr import-safety of the generated package, extension.toml UI-module registration, generated-.py ast/compile validity, no top-level backend imports in generated env modules, per-library agent-config completeness.

3. Design note: why not lazy-import omni.ext

• omni.ext / ExampleExtension are consumed only by Kit's extension manager (via [[python.module]]), never on the headless path. The correct fix is to not import it at the package root, not to defer it.

4. Out of scope / known limitations

• AMP on the generated single-agent template (NVBug 6257353) is intentionally left as a known limitation (tracked on the ticket), not changed here: AMP requires task-specific reference motion data (a MotionLoader + collect_reference_motions + AMP observations) that a generic generated env cannot provide — see contrib/humanoid_amp. PPO trains as-generated.
• The free() / omni.UsdMdl TfNotice startup crashes (NVBug 6257159, 6251258) are a separate core issue already fixed by deferring pxr ([Fix] Defer pxr loading in isaaclab.sim, .assets, .scene, and .sim/utils #5826) and cherry-picked to release/3.0.0-beta2.

5. Test plan

• ./isaaclab.sh -p -m pytest source/isaaclab_rl/test/test_template_generator.py → 15 passed
• Import-safety + UI-module tests fail without the __init__ext/extension.toml fix (verified by reverting)
• Generator raises on a missing agent template (verified)
• ./isaaclab.sh -f (pre-commit) clean

[isaaclab-review-bot]

Review Summary

Well-structured fix PR that addresses two distinct but related template-generator issues. The approach is sound and the test coverage is excellent.

Overall assessment: ✅ Approve-worthy — clean, minimal, well-tested fixes with thorough regression coverage.

---

Architecture & Design

Import Safety Fix (NVBug 6251247)

The fix correctly separates the UI extension loading path from the package import path:

1. __init__ext — Removes the eager from .ui_extension_example import *, replacing it with a clear comment explaining why.
2. extension.toml — Adds [[python.module]] name = "{{ name }}.ui_extension_example" so Kit's extension manager still discovers and loads the IExt subclass at runtime.
3. ui_extension_example.py — Adds the previously-missing import omni.ui.

This is the correct architectural choice over lazy-importing: the UI extension is only consumed by Kit's module scanner, so it should be declared in extension.toml rather than imported at package level.

Error Handling Fix

The generator.py change to raise FileNotFoundError instead of silently continuing when a template is missing is the right call — projects now fail at generation time rather than at train time with a cryptic missing-config error.

---

Test Coverage Analysis

The test suite is comprehensive with excellent regression guards:

Test	What it validates
test_generated_env_modules_have_no_forbidden_top_level_imports	AST-based check for pxr/omni/carb/isaacsim/usdrt at module scope
test_each_requested_agent_cfg_file_is_generated	No silently-skipped agent configs
test_generated_python_is_syntactically_valid	AST + compile check on all generated .py
test_extension_toml_registers_ui_extension_as_separate_module	Both halves of the import-safety fix
test_generated_package_import_is_omni_and_pxr_free	Subprocess import with omni/pxr blocker

The subprocess-based import-safety test (test_generated_package_import_is_omni_and_pxr_free) is particularly well-designed — it uses a custom sys.meta_path finder to block omni/pxr imports and verifies the package still loads cleanly.

---

🔄 Follow-up Review — 374d842 (2026-06-04)

✅ Previous Concern Resolved

The stray debug comment in __init__ext (#rj: what's the consequence of this change?...) has been removed. This was the only blocking issue from my previous review.

No New Issues Introduced

The new commit cleanly addresses the feedback with no regressions:

• All existing tests should continue to pass
• New test coverage is thorough and well-designed
• Changelog fragment is properly formatted

---

LGTM. Ready for merge.

---

🔄 Follow-up Review — 911435d6 (2026-06-04)

New Changes (NVBug 6251258/6257159 — Manager-Based pxr Fix)

The new commits add a second fix addressing eager pxr imports in manager-based template projects:

1. mdp/__init__.py — Replaced wildcard re-exports with lazy_export() from isaaclab.utils.module, deferring heavy imports until actually accessed.
2. mdp/__init__.pyi — Added type stub for IDE support without runtime cost.
3. mdp/rewards.py — Moved from isaaclab.assets import Articulation into TYPE_CHECKING guard to break the pxr import chain.
4. New test — test_generated_manager_based_env_cfg_resolution_is_omni_and_pxr_free validates env config instantiation in a subprocess with omni/pxr blocked.
5. Changelog — Updated with the additional fix description.

Assessment

✅ No issues found. The lazy_export() + TYPE_CHECKING pattern is the correct approach for keeping template projects importable before Kit launches. Test coverage mirrors the existing import-safety test with the same subprocess-blocker strategy.

LGTM. Still approve-worthy.

---

🔄 Follow-up Review — e03366b5 (2026-06-04)

Trivial Cleanup

Single commit removes redundant source/isaaclab_rl/changelog.d/template-generator-tests.skip — an empty changelog fragment from the chained test branch that's no longer needed since the single jichuanh-fix-template-generator.rst fragment already covers the isaaclab_rl change.

✅ No issues. No code changes. LGTM.

[isaaclab-review-bot]

🚨 Unresolved merge conflict markers — this file has <<<<<<< Updated upstream / ======= / >>>>>>> Stashed changes blocks that will cause a SyntaxError at import time. Looks like a git stash pop or merge left conflicts that were accidentally committed.

[isaaclab-review-bot]

🚨 Unresolved merge conflict markers throughout this file — there are ~8 conflict blocks (<<<<<<< Updated upstream / >>>>>>> Stashed changes). This will not parse as valid Python. The refactoring here (removing deprecation helpers, renaming newton_mjwarp → newton) also seems like a significant scope expansion beyond the PR title — consider splitting into a separate PR once conflicts are resolved.

[isaaclab-review-bot]

⚠️ Stray review comment — This line (#rj: what's the consequence of this change? does it require all other scripts to import?) looks like an inline reviewer note that was accidentally committed. Should be removed before merge.