ModelOpt config system documentation

[shengliangxu]

What does this PR do?

Type of change: documentation

Adds a new Sphinx guide for the ModelOpt config system at docs/source/guides/11_config_system.rst. The guide documents the general config contract and semantics rather than any single consumer:

• ModeloptBaseConfig schemas and validation boundaries
• YAML loading and persistence
• Checkpoint persistence and schema evolution / backward compatibility
• Composable YAML via imports / $import

It also explains why ModelOpt uses a small YAML DSL for composition: config files stay self-describing, reusable fragments can be authored as YAML, and resolved values are still validated against the Python schemas. Recipes are presented as one of the main applications of the shared config system; recipe-specific authoring continues to live in the existing recipes guide.

Usage

load_config resolves YAML composition (imports / $import) and returns plain data, which is then validated against the owning schema:

from modelopt.recipe import load_config
from modelopt.torch.quantization.config import QuantizeConfig

# YAML composition is resolved inside load_config before validation.
data = load_config("configs/ptq/presets/model/fp8", schema_type=QuantizeConfig)
cfg = QuantizeConfig.model_validate(data)
resolved = cfg.model_dump()

Testing

• Docs-only change; no code paths touched.
• Ran git diff --cached --check — no whitespace issues.
• Confirmed the guide uses ModeloptBaseConfig / Pydantic terminology consistently (no leftover TypedDict references).
• Did not run a full Sphinx build because sphinx is unavailable in this environment; will render locally before flipping out of draft.

Before your PR is "Ready for review"

Make sure you read and follow Contributor guidelines and your commits are signed (git commit -s -S).

Make sure you read and follow the Security Best Practices (e.g. avoiding hardcoded trust_remote_code=True, torch.load(..., weights_only=False), pickle, etc.). Docs-only change — no executable code paths affected.

• Is this change backward compatible?: ✅
• If you copied code from any other sources or added a new PIP dependency, did you follow guidance in CONTRIBUTING.md: N/A
• Did you write any new necessary tests?: N/A (docs-only)
• Did you update Changelog?: N/A (docs-only)
• Did you get Claude approval on this PR?: ✅

Additional Information

N/A

[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: Enterprise

Run ID: 5559985d-17a5-4e92-823b-188cbd79ef9d

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/modelopt-config

Tip

💬 Introducing Slack Agent: The best way for teams to turn conversations into code.

Slack Agent is built on CodeRabbit's deep understanding of your code, so your team can collaborate across the entire SDLC without losing context.

• Generate code and open pull requests
• Plan features and break down work
• Investigate incidents and troubleshoot customer tickets together
• Automate recurring tasks and respond to alerts with triggers
• Summarize progress and report instantly

Built for teams:

• Shared memory across your entire org—no repeating context
• Per-thread sandboxes to safely plan and execute work
• Governance built-in—scoped access, auditability, and budget controls

One agent for your entire SDLC. Right inside Slack.

👉 Get started

---

_{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-1472/
Built to branch gh-pages at 2026-05-15 18:59 UTC. Preview will be ready when the GitHub Pages deployment is complete.

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 76.85%. Comparing base (21d2b35) to head (d8c4bb7).
⚠️ Report is 5 commits behind head on shengliangx/schematize-cfg.

Additional details and impacted files

@@                     Coverage Diff                     @@
##           shengliangx/schematize-cfg    #1472   +/-   ##
===========================================================
  Coverage                       76.85%   76.85%           
===========================================================
  Files                             473      473           
  Lines                           51429    51429           
===========================================================
  Hits                            39524    39524           
  Misses                          11905    11905           

Flag	Coverage Δ
unit	52.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.