refactor(recipe)!: flatten Nemotron example directories by cuichenx · Pull Request #6371 · NVIDIA-NeMo/Megatron-Bridge

cuichenx · 2026-10-09T06:43:31Z

What does this PR do ?

Flatten Nemotron example directories so each model has a direct, importable path under examples/models/nemotron/.

Changelog

Use Nano, Nano Omni, Super, Ultra, Lightning, Super VL order consistently in example tables, model indexes, navigation, and generated catalog listings.
Move Nano, Nano Omni, Super, Ultra, Lightning, and Super VL into their model-specific directories. Lightning and Super VL use nemotron_3_5_* names.
Remove the deprecated Nano v2 VL example script and two YAML overrides. Current docs point to the verified v0.6.0 guide for those historical examples; public model and recipe APIs are unchanged.
Move the family index up one level and document the intentional example-path break. Public recipes and model conversion entry points are unchanged; all 35 examples for the six requested model families are retained.
Update current documentation, commands, test discovery, the verification card/catalog, and the skill card. Preserve verified historical branch links and correct archived 0.4.2 commands against that release's actual tree.
Add package-discovery and repository/link regression checks.

GitHub Actions CI

Primary area: area:recipe.

269 targeted Nemotron example, recipe, and model unit tests passed in an existing NeMo container using this checkout's pinned Megatron-Core.
15 lightweight layout, import-discovery, source-link, and Ultra packing checks passed; independently rerun by the reviewer.
Repository-wide pre-commit passed; strict mypy passed for the new test.
Generated verification catalog freshness check and git diff --check passed.
Move integrity check: all 35 retained example files accounted for, with unchanged executable Python syntax trees; only the three requested deprecated files were removed.
Full Sphinx HTML build passed without warnings; final-page rendering reuses the generated API sources.
Rendered link checks cover all Nemotron pages and the landing page. The unrelated landing-page examples/conversion/compare_models.py link is already broken on the base revision and is outside this refactor.
Fresh independent review of the complete final diff completed before publication with no actionable findings.

Before your PR is "Ready for review"

Pre checks:

Make sure you read and followed Contributor guidelines
Did you write any new necessary tests?
Did you add or update any necessary documentation?
Does the PR affect components that are optional to install? (Ex: Numba, Pynini, Apex etc)
- Reviewer: Does the PR have correct import guards for all optional libraries?

Additional Information

Breaking path change: saved commands and examples.models.nemotron.* imports must use the new model directories. No compatibility aliases were added. Historical release checkouts retain their own layouts.

Signed-off-by: Chen Cui <chcui@nvidia.com>

svcnvidia-nemo-ci · 2026-10-09T06:43:41Z

/nvskills-ci

github-actions · 2026-10-09T06:43:48Z

Automatic Claude reviews have been retired. To request a pull-request review, post a comment containing:

/review

Add model=claude to use a Claude reviewer (the default is model=codex). mode=light|strict selects the review depth; for example, /review model=claude mode=strict. Comment /review help for all options.

github-actions · 2026-10-09T06:44:46Z

🌿 Preview your docs: https://nvidia-preview-pr-6371-7c09d6486c08.docs.buildwithfern.com/nemo/megatron-bridge

Signed-off-by: nvskills-svc-account <svc-nvskills-signing@nvidia.com>

copy-pr-bot · 2026-10-09T06:54:55Z

This pull request requires additional validation before any workflows can run on NVIDIA's runners.

Pull request vetters can view their responsibilities here.

Contributors can view more details about this message here.

Signed-off-by: Chen Cui <chcui@nvidia.com>

svcnvidia-nemo-ci · 2026-10-09T16:19:20Z

/nvskills-ci

Signed-off-by: nvskills-svc-account <svc-nvskills-signing@nvidia.com>

cuichenx · 2026-10-09T17:28:39Z

/ok to test ad4b24f

Signed-off-by: Chen Cui <chcui@nvidia.com>

cuichenx · 2026-10-09T17:30:33Z

/ok to test 5dd4bb0

svcnvidia-nemo-ci · 2026-10-09T17:30:37Z

/nvskills-ci

Signed-off-by: nvskills-svc-account <svc-nvskills-signing@nvidia.com>

kamran-nvidia

One blocking issue outside the diff, plus an inline note on the new layout test.

tests/unit_tests/doc_consistency/test_readme_consistency.py still points at the old Nano layout:

Megatron-Bridge/tests/unit_tests/doc_consistency/test_readme_consistency.py

Lines 430 to 437 in 8919acf

    
           MODEL_EXAMPLES / "nemotron" / "nemotron_3" / "nano" / "slurm_sft.sh": ( 
        
               "${MODEL_NAME}_sft_config", 
        
               "nemotron_3_nano_finetune_config", 
        
           ), 
        
           MODEL_EXAMPLES / "nemotron" / "nemotron_3" / "nano" / "slurm_peft.sh": ( 
        
               "${MODEL_NAME}_peft_config", 
        
               "nemotron_3_nano_finetune_config", 
        
           ),

test_nemotron_and_qwen2_audio_finetune_launchers_use_exported_recipes raises FileNotFoundError for nemotron_3/nano/slurm_sft.sh on this branch. It passes on the base commit, and it runs in Launch_Unit_Tests_Core (passing on main here), so this will fail the L0 unit tests and Nemo_CICD_Test. The new reference scanner can't catch it because the path is assembled from separate Path components rather than a contiguous examples/models/nemotron/... string.

Fix:

-        MODEL_EXAMPLES / "nemotron" / "nemotron_3" / "nano" / "slurm_sft.sh": (
+        MODEL_EXAMPLES / "nemotron" / "nemotron_3_nano" / "slurm_sft.sh": (
 ...
-        MODEL_EXAMPLES / "nemotron" / "nemotron_3" / "nano" / "slurm_peft.sh": (
+        MODEL_EXAMPLES / "nemotron" / "nemotron_3_nano" / "slurm_peft.sh": (

With that change all 23 tests in the file pass.

kamran-nvidia · 2026-10-09T18:03:17Z

+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""Check example discovery and links without importing GPU dependencies."""


This file won't run in CI. pyproject.toml lists "examples" in norecursedirs, and pytest matches those patterns against directory names at any depth. So pytest tests/unit_tests (Launch_Unit_Tests_Core.sh) never enters tests/unit_tests/examples/. None of the three unit-test shards for this PR's base commit on main (run 37890877242) collected anything from that folder. It only passes when invoked by explicit path.

Could you move it to tests/unit_tests/doc_consistency/, next to test_readme_consistency.py? It's the same depth, so parents[3] still resolves to the repo root. I tried the move locally: it gets collected from tests/unit_tests and passes there.

The two existing tests this PR updates in tests/unit_tests/examples/ have the same problem, but that's pre-existing and probably needs its own fix.

Signed-off-by: Chen Cui <chcui@nvidia.com>

cuichenx · 2026-10-09T18:15:05Z

/ok to test e289c9f

svcnvidia-nemo-ci · 2026-10-09T18:15:09Z

/nvskills-ci

Signed-off-by: nvskills-svc-account <svc-nvskills-signing@nvidia.com>

cuichenx · 2026-10-09T19:56:07Z

/ok to test 03303a7

Signed-off-by: Chen Cui <chcui@nvidia.com>

svcnvidia-nemo-ci · 2026-10-09T21:44:04Z

/nvskills-ci

cuichenx · 2026-10-09T21:44:31Z

/ok to test 7c09d64

refactor(recipe)!: flatten Nemotron example directories

e77129a

Signed-off-by: Chen Cui <chcui@nvidia.com>

cuichenx added feature New capabilities, enhancements, or enablement work breaking-change Public behavior or API compatibility changes area:recipe Training recipes and launch configs needs-review PR is ready for code review and waiting on a reviewer labels Oct 9, 2026

copy-pr-bot Bot deployed to test October 9, 2026 06:44 Active

Attach NVSkills validation signatures

c3f63b0

Signed-off-by: nvskills-svc-account <svc-nvskills-signing@nvidia.com>

docs(recipe): use canonical Nemotron model order

f98d5fc

Signed-off-by: Chen Cui <chcui@nvidia.com>

Attach NVSkills validation signatures

ad4b24f

Signed-off-by: nvskills-svc-account <svc-nvskills-signing@nvidia.com>

copy-pr-bot Bot had a problem deploying to test October 9, 2026 17:29 Error

fix(tests): add missing Nemotron layout copyright header

5dd4bb0

Signed-off-by: Chen Cui <chcui@nvidia.com>

copy-pr-bot Bot had a problem deploying to test October 9, 2026 17:31 Error

Attach NVSkills validation signatures

8919acf

Signed-off-by: nvskills-svc-account <svc-nvskills-signing@nvidia.com>

kamran-nvidia self-requested a review October 9, 2026 17:54

kamran-nvidia reviewed Oct 9, 2026

View reviewed changes

fix(tests): repair Nemotron paths and CI discovery

e289c9f

Signed-off-by: Chen Cui <chcui@nvidia.com>

copy-pr-bot Bot had a problem deploying to test October 9, 2026 18:16 Error

Attach NVSkills validation signatures

03303a7

Signed-off-by: nvskills-svc-account <svc-nvskills-signing@nvidia.com>

kamran-nvidia previously approved these changes Oct 9, 2026

View reviewed changes

cuichenx added ready-to-merge PR is approved, current, and only waiting for CI to pass before merge and removed needs-review PR is ready for code review and waiting on a reviewer labels Oct 9, 2026

copy-pr-bot Bot had a problem deploying to test October 9, 2026 19:57 Error

chore: merge main into Nemotron examples layout branch

7c09d64

Signed-off-by: Chen Cui <chcui@nvidia.com>

cuichenx dismissed kamran-nvidia’s stale review via 7c09d64 October 9, 2026 21:43

copy-pr-bot Bot deployed to test October 9, 2026 21:45 Active

cuichenx merged commit ae22c0d into main Oct 9, 2026
24 of 26 checks passed

cuichenx deleted the chcui/leo/flatten-nemotron-examples branch October 9, 2026 21:46

	MODEL_EXAMPLES / "nemotron" / "nemotron_3" / "nano" / "slurm_sft.sh": (
	"${MODEL_NAME}_sft_config",
	"nemotron_3_nano_finetune_config",
	),
	MODEL_EXAMPLES / "nemotron" / "nemotron_3" / "nano" / "slurm_peft.sh": (
	"${MODEL_NAME}_peft_config",
	"nemotron_3_nano_finetune_config",
	),

Conversation

cuichenx commented Oct 9, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

What does this PR do ?

Changelog

GitHub Actions CI

Before your PR is "Ready for review"

Additional Information

Uh oh!

svcnvidia-nemo-ci commented Oct 9, 2026

Uh oh!

github-actions Bot commented Oct 9, 2026

Uh oh!

github-actions Bot commented Oct 9, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

copy-pr-bot Bot commented Oct 9, 2026

Uh oh!

svcnvidia-nemo-ci commented Oct 9, 2026

Uh oh!

cuichenx commented Oct 9, 2026

Uh oh!

cuichenx commented Oct 9, 2026

Uh oh!

svcnvidia-nemo-ci commented Oct 9, 2026

Uh oh!

kamran-nvidia left a comment

Choose a reason for hiding this comment

Uh oh!

kamran-nvidia Oct 9, 2026

Choose a reason for hiding this comment

Uh oh!

cuichenx commented Oct 9, 2026

Uh oh!

svcnvidia-nemo-ci commented Oct 9, 2026

Uh oh!

cuichenx commented Oct 9, 2026

Uh oh!

svcnvidia-nemo-ci commented Oct 9, 2026

Uh oh!

cuichenx commented Oct 9, 2026

Uh oh!

Uh oh!

This branch was successfully deployed

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

cuichenx commented Oct 9, 2026 •

edited

Loading

github-actions Bot commented Oct 9, 2026 •

edited

Loading