[OMNIML-3744] recipes doc

[shengliangxu]

What does this PR do?

Added an extensive guide for the ModelOpt recipe system: recipe structure, YAML schema (quantization-focused), built-in discovery and path resolution, floating-point shorthand conversion, example usage (Python/CLI), authoring guidance, repository layout, and future directions.

Summary by CodeRabbit

• Documentation
  • Added comprehensive guide for ModelOpt recipes, introducing declarative YAML-based optimization specifications. Documents recipe structure, configuration loading, path resolution, and the three-layer system architecture. Includes built-in recipe discovery conventions and detailed instructions for authoring custom recipes with practical examples.

[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]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro Plus

Run ID: 8fae78b9-ce75-483e-b2bb-06b2d70ce8fa

📥 Commits

Reviewing files that changed from the base of the PR and between db044b2 and e3e933f.

📒 Files selected for processing (1)

• docs/source/guides/10_recipes.rst

✅ Files skipped from review due to trivial changes (1)

• docs/source/guides/10_recipes.rst

---

📝 Walkthrough

Walkthrough

The PR adds comprehensive documentation for ModelOpt recipes, a YAML-based optimization specification system. It explains the three-layer architecture (recipe sources, config loading, recipe loading), required metadata sections, type-specific configurations with PTQ guidance, ExMy notation conversion, and usage examples via Python and CLI.

Changes

Cohort / File(s)	Summary
Documentation for Recipes docs/source/guides/10_recipes.rst	Introduces recipes as declarative YAML-based optimization specifications. Documents the three-layer system (sources, config loading, recipe loading), required metadata, PTQ quantization configuration details, ExMy floating-point notation conversion, path resolution semantics, and CLI/Python usage patterns.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~15 minutes

🚥 Pre-merge checks | ✅ 2 | ❌ 2

❌ Failed checks (1 warning, 1 inconclusive)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 50.00% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.
Title check	❓ Inconclusive	The title 'recipes doc' is vague and generic, using minimal descriptive language that doesn't convey meaningful information about the extensive guide being added to the documentation.	Consider using a more descriptive title such as 'Add comprehensive guide for ModelOpt recipe system' or 'Document ModelOpt recipes: YAML-based optimization specifications' to better communicate the scope and content.

✅ Passed checks (2 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Security Anti-Patterns	✅ Passed	Documentation-only PR with no Python code, dependency, or example changes. Security anti-patterns check does not apply to Sphinx documentation files.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

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

---

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

[github-actions]

PR Preview Action v1.8.1
Preview removed because the pull request was closed.
2026-04-13 20:57 UTC

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 76.91%. Comparing base (0b42c14) to head (e3e933f).
⚠️ Report is 1 commits behind head on main.

Additional details and impacted files

@@           Coverage Diff           @@
##             main    #1165   +/-   ##
=======================================
  Coverage   76.91%   76.91%           
=======================================
  Files         350      350           
  Lines       40481    40481           
=======================================
  Hits        31137    31137           
  Misses       9344     9344           

Flag	Coverage Δ
unit	55.53% <ø> (ø)

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[coderabbitai]

Actionable comments posted: 1

🤖 Prompt for all review comments with AI agents

Verify each finding against the current code and only fix it if needed.

Inline comments:
In `@docs/source/guides/10_recipes.rst`:
- Around line 175-177: Update the PTQ algorithm list in the recipe docs to
include the missing supported options by adding "local_hessian" and "svdquant"
to the enumerated values and mention they correspond to the
LocalHessianCalibConfig and SVDQuantConfig implementations; ensure the sentence
reads that valid values include "max" (default), "mse", "smoothquant",
"awq_lite", "awq_full", "awq_clip", "gptq", "local_hessian", "svdquant", or null
for formats needing no calibration, so readers can map doc values to the
LocalHessianCalibConfig and SVDQuantConfig symbols.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

Run ID: 4d1d9f8d-e7dd-4adf-8b50-bc9c3cb065f0

📥 Commits

Reviewing files that changed from the base of the PR and between 9050188 and a0aff78.

📒 Files selected for processing (2)

• docs/source/guides/10_recipes.rst
• modelopt/torch/quantization/config.py

[coderabbitai]

Actionable comments posted: 1

🤖 Prompt for all review comments with AI agents

Verify each finding against the current code and only fix it if needed.

Inline comments:
In `@modelopt/torch/quantization/config.py`:
- Around line 1578-1580: The normalization logic that processes per-quantizer
entries (around the block at lines ~1656-1668 in
modelopt/torch/quantization/config.py) currently accepts "enabled" entries with
invalid cfg shapes (e.g., integers, empty lists, or lists of empty dicts), which
lets bad configs reach set_quantizer_attributes and later tensor_quantizer code;
update the normalizer to validate that when an entry is enabled (enable truthy
or missing and treated as enabled) its cfg is either a non-empty dict or a
non-empty list/tuple of non-empty dicts, and raise a ValueError otherwise
(include a clear message referencing the quantizer name/entry); ensure this
validation sits inside the same normalization function so invalid shapes are
rejected at parse time before calling set_quantizer_attributes and the
tensor_quantizer modules.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

Run ID: c18ef7e6-9eb1-49bd-8eaa-2c73d29549e2

📥 Commits

Reviewing files that changed from the base of the PR and between a0aff78 and db044b2.

📒 Files selected for processing (1)

• modelopt/torch/quantization/config.py