new conflict semantic

Signed-off-by: Shengliang Xu <shengliangx@nvidia.com>

Author: shengliangxu

CHANGELOG.rst

@@ -14,7 +14,7 @@ Changelog
 - Enable PTQ workflow for the Step3.5-Flash MoE model with NVFP4 W4A4 + FP8 KV cache quantization. See `modelopt_recipes/models/Step3.5-Flash/nvfp4-mlp-only.yaml <https://github.com/NVIDIA/Model-Optimizer/blob/main/modelopt_recipes/models/Step3.5-Flash/nvfp4-mlp-only.yaml>`_ for more details.
 - Add support for vLLM fakequant reload using ModelOpt state for HF models. See `examples/vllm_serve/README.md <https://github.com/NVIDIA/Model-Optimizer/tree/main/examples/vllm_serve#load-qatptq-model-and-serve-in-vllm-wip>`_ for more details.
 - [Early Testing] Add Claude Code PTQ skill (``.claude/skills/ptq/``) for agent-assisted post-training quantization. The skill guides the agent through environment detection, model support checking, format selection, and execution via the launcher or manual SLURM/Docker/bare GPU paths. Includes handling for unlisted models with custom module patching. This feature is in early testing — use with caution.
-- Add composable ``$import`` system for recipe YAML configs. Recipes can now declare an ``imports`` section mapping names to reusable config snippet files. The ``{$import: name}`` marker resolves at load time — as a dict value it replaces the content (with optional extend and multi-import via ``$import: [a, b]``), as a list element it splices the snippet entries. Key conflicts between imports or inline keys raise errors. Resolution is recursive with circular import detection. All built-in PTQ recipes converted to use imports with shared snippets under ``modelopt_recipes/configs/``. See :ref:`composable-imports` for the full specification.
+- Add composable ``$import`` system for recipe YAML configs. Recipes can now declare an ``imports`` section mapping names to reusable config snippet files. The ``{$import: name}`` marker resolves at load time — as a dict value it replaces the content with ordered override precedence (later imports override earlier, inline keys override all), as a list element it splices the snippet entries. Supports multi-import (``$import: [a, b]``) and inline extension/override. Resolution is recursive with circular import detection. All built-in PTQ recipes converted to use imports with shared snippets under ``modelopt_recipes/configs/``. See :ref:`composable-imports` for the full specification.
 
 **Backward Breaking Changes**
 

docs/source/guides/10_recipes.rst

@@ -179,33 +179,38 @@ confused with literal values.  The marker can appear anywhere in the recipe:
 - As a **list element** — the snippet (which must itself be a list) is spliced
   into the surrounding list.
 
-As a **dict value**, ``$import`` supports three composition modes:
+As a **dict value**, ``$import`` supports composition with clear override
+precedence (lowest to highest):
 
-- **Single import:** ``$import: name`` — replaced with the snippet content.
-- **Multiple imports:** ``$import: [name1, name2]`` — snippets are merged into
-  one dict.  The snippets must not have overlapping keys.
-- **Import + extend:** extra keys alongside ``$import`` are merged in after the
-  import(s).  Extra keys must not conflict with any imported key.
+1. **Imports in list order** — ``$import: [base, override]``: later snippets
+   override earlier ones on key conflicts.
+2. **Inline keys** — extra keys alongside ``$import`` override all imported
+   values.
+
+This is equivalent to calling ``dict.update()`` in order: imports first (in
+list order), then inline keys last.
 
 .. code-block:: yaml
 
    # Single import
    cfg:
-     $import: fp8
+     $import: nvfp4
 
-   # Multiple imports — merge two non-overlapping snippets
+   # Import + override — import nvfp4_dynamic, then override type inline
    cfg:
-     $import: [bits, scale]
+     $import: nvfp4    # imports {num_bits: e2m1, block_sizes: {-1: 16, type: dynamic, ...}}
+     block_sizes:
+       -1: 16
+       type: static    # overrides type: dynamic → static calibration
 
-   # Import + extend — add axis on top of imported fp8
+   # Multiple imports — later snippet overrides earlier on conflict
    cfg:
-     $import: fp8
-     axis: 0          # result: {num_bits: e4m3, axis: 0}
+     $import: [base_format, kv_tweaks]   # kv_tweaks wins on shared keys
 
-Key conflicts are never allowed — whether between imported snippets or between
-imports and inline keys.  If a key appears in more than one source, the loader
-raises an error.  This avoids ambiguous merge semantics.  If you need different
-values for an existing key, create a new snippet instead.
+   # All three: multi-import + inline override
+   cfg:
+     $import: [bits, scale]
+     axis: 0            # highest precedence
 
 As a **list element**, ``$import`` must be the only key — extra keys alongside
 a list splice are not supported.

modelopt/recipe/loader.py

@@ -116,12 +116,15 @@ def _lookup(ref_name: str, context: str) -> Any:
                     and isinstance(entry.get("cfg"), dict)
                     and _IMPORT_KEY in entry["cfg"]
                 ):
-                    # cfg: {$import: name_or_list, ...extra} → import, merge, extend
+                    # cfg: {$import: name_or_list, ...inline} → import then override
+                    #
+                    # Precedence (lowest → highest):
+                    #   1. Imports in list order (later imports override earlier)
+                    #   2. Inline keys (override all imports)
                     ref = entry["cfg"].pop(_IMPORT_KEY)
-                    extra_keys = dict(entry["cfg"])  # remaining inline keys
+                    inline_keys = dict(entry["cfg"])  # remaining inline keys
                     ref_names = ref if isinstance(ref, list) else [ref]
 
-                    # Merge all imported snippets, detecting conflicts between them
                     merged: dict[str, Any] = {}
                     for name in ref_names:
                         snippet = _lookup(name, f"cfg of {entry}")
@@ -130,25 +133,9 @@ def _lookup(ref_name: str, context: str) -> Any:
                                 f"$import {name!r} in cfg must resolve to a dict, "
                                 f"got {type(snippet).__name__}."
                             )
-                        conflicts = set(snippet) & set(merged)
-                        if conflicts:
-                            raise ValueError(
-                                f"$import {name!r} conflicts with keys from prior imports: "
-                                f"{sorted(conflicts)}. Imported snippets must not overlap."
-                            )
                         merged.update(snippet)
 
-                    # Extend with inline keys, detecting conflicts with imports
-                    if extra_keys:
-                        conflicts = set(extra_keys) & set(merged)
-                        if conflicts:
-                            raise ValueError(
-                                f"Inline keys {sorted(conflicts)} conflict with imported "
-                                f"values. Cannot override imported values — create a new "
-                                f"snippet instead."
-                            )
-                        merged.update(extra_keys)
-
+                    merged.update(inline_keys)
                     entry["cfg"] = merged
                     resolved_cfg.append(entry)
                 else:

tests/unit/recipe/test_loader.py

@@ -532,9 +532,9 @@ def test_import_cfg_extend(tmp_path):
     assert cfg == {"num_bits": (4, 3), "axis": 0}
 
 
-def test_import_cfg_conflict_raises(tmp_path):
-    """$import in cfg with conflicting keys raises ValueError."""
-    (tmp_path / "fp8.yml").write_text("num_bits: e4m3\n")
+def test_import_cfg_inline_overrides_import(tmp_path):
+    """Inline keys override imported values (highest precedence)."""
+    (tmp_path / "fp8.yml").write_text("num_bits: e4m3\naxis:\n")
     recipe_file = tmp_path / "recipe.yml"
     recipe_file.write_text(
         f"imports:\n"
@@ -549,8 +549,12 @@ def test_import_cfg_conflict_raises(tmp_path):
         f"        $import: fp8\n"
         f"        num_bits: 8\n"
     )
-    with pytest.raises(ValueError, match="conflict with imported"):
-        load_recipe(recipe_file)
+    recipe = load_recipe(recipe_file)
+    cfg = recipe.quantize["quant_cfg"][0]["cfg"]
+    # inline num_bits: 8 overrides imported num_bits: e4m3 → (4,3)
+    assert cfg["num_bits"] == 8
+    # imported axis: None is preserved (no inline override)
+    assert cfg["axis"] is None
 
 
 def test_import_cfg_multi_import(tmp_path):
@@ -576,9 +580,9 @@ def test_import_cfg_multi_import(tmp_path):
     assert cfg == {"num_bits": (4, 3), "axis": 0}
 
 
-def test_import_cfg_multi_import_conflict_raises(tmp_path):
-    """$import with a list of names raises when snippets have overlapping keys."""
-    (tmp_path / "a.yml").write_text("num_bits: e4m3\n")
+def test_import_cfg_multi_import_later_overrides_earlier(tmp_path):
+    """In $import list, later snippets override earlier ones on key conflicts."""
+    (tmp_path / "a.yml").write_text("num_bits: e4m3\naxis: 0\n")
     (tmp_path / "b.yml").write_text("num_bits: 8\n")
     recipe_file = tmp_path / "recipe.yml"
     recipe_file.write_text(
@@ -594,8 +598,11 @@ def test_import_cfg_multi_import_conflict_raises(tmp_path):
         f"      cfg:\n"
         f"        $import: [a, b]\n"
     )
-    with pytest.raises(ValueError, match="conflicts with keys from prior imports"):
-        load_recipe(recipe_file)
+    recipe = load_recipe(recipe_file)
+    cfg = recipe.quantize["quant_cfg"][0]["cfg"]
+    # b overrides a's num_bits; a's axis is preserved
+    assert cfg["num_bits"] == 8
+    assert cfg["axis"] == 0
 
 
 def test_import_cfg_multi_import_with_extend(tmp_path):