license headers + more doc

shengliangxu · shengliangxu · commit 5901aae50998 · 2026-04-14T15:19:46.000-07:00
Signed-off-by: Shengliang Xu &lt;shengliangx@nvidia.com&gt;
diff --git a/docs/source/guides/10_recipes.rst b/docs/source/guides/10_recipes.rst
@@ -173,7 +173,16 @@ lists are authored once and referenced by name across recipes.
 
 The ``imports`` section is a dict mapping short names to config file paths.
 References use the explicit ``{$import: name}`` marker so they are never
-confused with literal values.  The marker can appear anywhere in the recipe:
+confused with literal values.
+
+.. note::
+
+   ``imports`` (no ``$``) is a **top-level structural section** — like
+   ``metadata`` or ``quantize``, it declares the recipe's dependencies.
+   ``$import`` (with ``$``) is an **inline directive** that appears inside
+   data values and gets resolved at load time.
+
+The ``$import`` marker can appear anywhere in the recipe:
 
 - As a **dict value** — the marker is replaced with the snippet content.
 - As a **list element** — the snippet (which must itself be a list) is spliced
@@ -250,6 +259,35 @@ section.  Each file's imports are scoped to that file — the same name can be
 used in different files without conflict.  Circular imports are detected and
 raise ``ValueError``.
 
+Multi-document snippets
+^^^^^^^^^^^^^^^^^^^^^^^
+
+Dict-valued snippets (e.g., numeric format definitions) can use ``imports``
+directly because the ``imports`` key and the snippet content are both part of
+the same YAML mapping.  List-valued snippets have a problem: YAML only allows
+one root node per document, so a file cannot be both a mapping (for
+``imports``) and a list (for entries) at the same time.
+
+The solution is **multi-document YAML**: the first document holds the
+``imports``, and the second document (after ``---``) holds the list content.
+The loader parses both documents, resolves ``$import`` markers in the content,
+and returns the resolved list:
+
+.. code-block:: yaml
+
+   # configs/ptq/fp8_kv.yaml — list snippet that imports a dict snippet
+   imports:
+     fp8: configs/numerics/fp8
+   ---
+   - quantizer_name: '*[kv]_bmm_quantizer'
+     cfg:
+       $import: fp8
+
+This enables full composability — list snippets can reference dict snippets,
+dict snippets can reference other dict snippets, and recipes can reference
+any of them.  All import resolution happens at load time with the same
+precedence rules.
+
 Built-in config snippets
 ^^^^^^^^^^^^^^^^^^^^^^^^
 
@@ -271,6 +309,8 @@ Reusable snippets are stored under ``modelopt_recipes/configs/``:
      - Disable all quantizers (deny-all-then-configure pattern)
    * - ``configs/ptq/default_disabled_quantizers``
      - Standard exclusions (LM head, routers, BatchNorm, etc.)
+   * - ``configs/ptq/fp8_kv``
+     - FP8 E4M3 KV cache quantization (multi-document, imports ``fp8``)
 
 
 Metadata section
diff --git a/modelopt_recipes/configs/numerics/fp8.yml b/modelopt_recipes/configs/numerics/fp8.yml
@@ -1,2 +1,17 @@
+# SPDX-FileCopyrightText: Copyright (c) 2024 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+# SPDX-License-Identifier: Apache-2.0
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
 # FP8 E4M3 quantizer attributes (no axis — used for KV cache, etc.).
 num_bits: e4m3
diff --git a/modelopt_recipes/configs/numerics/nvfp4_dynamic.yml b/modelopt_recipes/configs/numerics/nvfp4_dynamic.yml
@@ -1,3 +1,18 @@
+# SPDX-FileCopyrightText: Copyright (c) 2024 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+# SPDX-License-Identifier: Apache-2.0
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
 # NVFP4 E2M1 blockwise with dynamic calibration and FP8 E4M3 scales.
 num_bits: e2m1
 block_sizes:
diff --git a/modelopt_recipes/configs/numerics/nvfp4_static.yml b/modelopt_recipes/configs/numerics/nvfp4_static.yml
@@ -1,3 +1,18 @@
+# SPDX-FileCopyrightText: Copyright (c) 2024 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+# SPDX-License-Identifier: Apache-2.0
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
 # NVFP4 E2M1 blockwise with static calibration and FP8 E4M3 scales.
 num_bits: e2m1
 block_sizes:
diff --git a/modelopt_recipes/configs/ptq/base_disable_all.yaml b/modelopt_recipes/configs/ptq/base_disable_all.yaml
@@ -1,3 +1,18 @@
+# SPDX-FileCopyrightText: Copyright (c) 2024 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+# SPDX-License-Identifier: Apache-2.0
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
 # Disable all quantizers by default (deny-all-then-configure pattern).
 
   - quantizer_name: '*'
diff --git a/modelopt_recipes/configs/ptq/default_disabled_quantizers.yaml b/modelopt_recipes/configs/ptq/default_disabled_quantizers.yaml
@@ -1,3 +1,18 @@
+# SPDX-FileCopyrightText: Copyright (c) 2024 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+# SPDX-License-Identifier: Apache-2.0
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
 # Standard quantizer exclusions: layers that should not be quantized.
 
   - quantizer_name: '*block_sparse_moe.gate*'
diff --git a/modelopt_recipes/configs/ptq/fp8_kv.yaml b/modelopt_recipes/configs/ptq/fp8_kv.yaml
@@ -1,4 +1,25 @@
+# SPDX-FileCopyrightText: Copyright (c) 2024 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+# SPDX-License-Identifier: Apache-2.0
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
 # FP8 E4M3 KV cache quantization.
+#
+# This snippet uses multi-document YAML (separated by ---) because it is a
+# list-valued snippet that also needs to $import another snippet.  YAML only
+# allows one root node per document, so a file cannot be both a mapping
+# (for imports) and a list (for entries).  The first document holds the
+# imports, the second holds the list content that references them.
 imports:
   fp8: configs/numerics/fp8
 ---
