Add composable $import system for recipe YAML configs

[shengliangxu]

What does this PR do?

Type of change: New feature

Introduce a composable import system for recipe YAML files, allowing reusable config snippets to be defined once and referenced across multiple recipes via explicit $import markers.

Problem

The 6 built-in PTQ recipes duplicated the same numeric format definitions (e.g., FP8 E4M3, NVFP4 E2M1 blockwise) and the same 14-entry standard exclusion list across every file. Changing a shared pattern required editing all recipes.

Solution

Recipes can now declare an imports section mapping short names to config snippet files. The {$import: name} marker is resolved at load time:

imports:
  base_disable_all: configs/ptq/base_disable_all
  fp8: configs/numerics/fp8

quantize:
  algorithm: max
  quant_cfg:
    - $import: base_disable_all         # list splice
    - quantizer_name: '*weight_quantizer'
      cfg:
        $import: fp8                    # dict value replacement
        axis: 0                         # extend with extra keys
    - $import: default_disabled         # multi-entry list splice

$import semantics:
- Dict value: replaced with snippet content. Supports multiple imports ($import: [a, b]) and inline extension keys. Key conflicts raise errors.
- List element: snippet (must be a YAML list) is spliced into the surrounding list.
- Recursive: snippets can themselves have imports. Circular imports are detected.
- Scoped: each file's import names are independent — no cross-file name conflicts.

recipes docs are updated too


Testing

tests/unit/recipe/test_loader.py

15+ new tests covering: basic resolution, reuse, multiple snippets, inline cfg unaffected, unknown reference, empty path, not-a-dict, single-element list splice, multi-entry list splice, non-list error, entry sibling key error, cfg extend, cfg conflict, multi-import, multi-import conflict, multi-import with extend, recursive resolution, circular import detection, cross-file name scoping, directory format

All new tests pass. Existing recipe loader tests and built-in recipe smoke tests continue to pass with the converted recipes.

Before your PR is "Ready for review"

- Is this change backward compatible?: ✅ (recipes without imports load unchanged)
- Did you write any new necessary tests?: ✅
- Did you update Changelog?: ✅ (should be added before merge)

[copy-pr-bot]

Auto-sync is disabled for draft pull requests in this repository. Workflows must be run manually.

Contributors can view more details about this message here.

[coderabbitai]

Important

Review skipped

Draft detected.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro Plus

Run ID: 0ced2ebe-2d6b-4c9e-858c-bd7683a4027e

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch shengliangx/composable-recipes

---

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[github-actions]

PR Preview Action v1.8.1
🚀 View preview at https://NVIDIA.github.io/Model-Optimizer/pr-preview/pr-1253/
Built to branch gh-pages at 2026-04-14 22:25 UTC. Preview will be ready when the GitHub Pages deployment is complete.