Rename modelopt_recipes/huggingface to model_type with backward-compat alias

[shengliangxu]

What does this PR do?

Type of change: Refactor + deprecation (recipe-library restructure, backward compatible), plus an unrelated transformers-compat test fix.

Rename the architecture-specific recipe tier modelopt_recipes/huggingface/ to
modelopt_recipes/model_type/, making explicit that it holds recipes shared across
every checkpoint of a Hugging Face model_type — as opposed to the checkpoint-mirror
models/<org>/<model_id>/ tier. The old huggingface/ path keeps working as a
deprecated backward-compat alias (a source-tree symlink plus a loader alias), so no
saved --recipe path breaks.

• Loader alias (modelopt/recipe/loader.py): generalized so saved
  --recipe huggingface/<model_type>/... paths rewrite to model_type/..., alongside
  the existing huggingface/models/... -> models/... rewrite (checked first as the more
  specific prefix). This keeps old paths resolving for pip-installed wheels, where the
  source-tree symlinks don't survive.
• Internal $imports: rewritten from huggingface/... -> model_type/... inside the
  shipped recipes so they resolve without the symlink — mandatory for wheels, since
  $import resolution goes through config_loader (no alias there).
• Packaging (pyproject.toml, MANIFEST.in): extended the symlink-exclusion globs
  so the recursive **/*.yaml package-data glob doesn't double-ship recipes through the
  huggingface -> model_type and model_type/models -> ../models symlinks.
• Docs / examples / skills / tests: migrated all internal references to the canonical
  model_type/; huggingface/ remains only in the deprecated-alias tests and explanatory
  notes.
• Unrelated fix (2nd commit): tests/unit/torch/export/test_quant_aware_conversion.py
  failed on transformers>=5.9, which dropped base_model_prefix from
  WeightTransform.__slots__ (the scoped-rule tests assigned it on the now-slotted
  object). Production _scope_prefixes already reads it via getattr(..., None) and
  degrades correctly, so there is no runtime change — the tests now set it through a
  helper that suppresses AttributeError across the supported transformers range.

Usage

# New canonical path
python examples/hf_ptq/hf_ptq.py --model <ckpt> \
    --recipe model_type/qwen3_vl/ptq/fp8_vision-kv_none

# Old path still works (deprecated backward-compat alias)
python examples/hf_ptq/hf_ptq.py --model <ckpt> \
    --recipe huggingface/qwen3_vl/ptq/fp8_vision-kv_none

from modelopt.recipe import load_recipe

load_recipe("model_type/vit/ptq/fp8")    # canonical
load_recipe("huggingface/vit/ptq/fp8")   # deprecated alias, resolves to the same recipe

Testing

• tests/unit/recipe/ — 336 passed, including the new
  test_load_recipe_huggingface_arch_backward_compat_alias and the updated
  structural/doc tests (test_recipe_docs.py).
• tests/unit/torch/export/test_quant_aware_conversion.py — 16 passed (was 4 failed
  on transformers 5.9.0).
• Built an sdist and a wheel and inspected both manifests: each recipe ships exactly
  once (27 model_type/, 11 models/, 153 total) with zero huggingface/ or
  model_type/models/ duplicates and no build error on the symlinks.
• Simulated a wheel install (symlink-free extracted tree) and confirmed
  huggingface/<arch>/..., model_type/..., and huggingface/models/... all resolve via
  the loader alias — including a recipe that pulls internal $imports.

Before your PR is "Ready for review"

• Is this change backward compatible?: ✅ — old huggingface/... recipe paths keep resolving via the symlink + loader alias.
• 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?: ✅ — backward-compat alias test added; structural/doc tests updated to the new layout.
• Did you update Changelog?: ✅ — Deprecations entry under 0.48.0. (The transformers-compat test fix is not changelog-worthy.)
• Did you get Claude approval on this PR?: ❌ — not yet.

Additional Information

The model_type/models -> ../models symlink is kept purely as a backward-compat alias for
old huggingface/models/<org>/<model_id>/... paths; model_type/ is otherwise
architecture-only. If we ever want it strictly architecture-only, that symlink can be
dropped later without breaking anything, since the loader rewrites huggingface/models/...
straight to the top-level models/ tier.

[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

Draft PR not reviewed

Draft PRs are not automatically reviewed by default.

• Trigger a manual review

To automatically review draft PRs, update your CodeRabbit configuration:

reviews:
  auto_review:
    drafts: true

---

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

[github-actions]

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

[codecov]

Codecov Report

❌ Patch coverage is 88.46154% with 3 lines in your changes missing coverage. Please review.
✅ Project coverage is 79.29%. Comparing base (bfd52b3) to head (e5e5ce7).
⚠️ Report is 1 commits behind head on main.

Files with missing lines	Patch %	Lines
modelopt/torch/opt/config_loader.py	80.00%	3 Missing ⚠️

Additional details and impacted files

@@           Coverage Diff           @@
##             main    #2328   +/-   ##
=======================================
  Coverage   79.28%   79.29%           
=======================================
  Files         527      527           
  Lines       61482    61491    +9     
=======================================
+ Hits        48748    48758   +10     
+ Misses      12734    12733    -1     

Flag	Coverage Δ
unit	55.88% <88.46%> (+<0.01%)	⬆️

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

☔ View full report in Codecov by Harness.
📢 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.