[Levius-Fubuki]

What does this PR do?

Add an optional config-driven PEFT hook to training model setup. Configured adapters are applied to model chunks before distributed wrapping and optimizer construction. The hook preserves user-owned hooks and places requested freeze hooks after adapter insertion. Config export rejects PEFT objects whose constructor state cannot be serialized.

Issue tracking

Related to #7269. This PR provides the training integration seam; the migrated performant LoRA, canonical LoRA, and DoRA components are tracked by #7271, so it does not close #7269.

Validation

Rebased onto main at 728ef1414008ce4b51ce1c0db86993c3eb871601. The conflict resolution retains the upstream batch, scheduler, RL, and configuration-finalization methods. The model-setup regression test now uses the current native config container and TrainState.

• 2026-10-22 local CPU validation: 266 tests passed across PEFT/freezing, configuration serialization/instantiation/finalization, model-config serialization, and distributed-model lifecycle helpers.
• Environment: Linux/arm64 Docker, Python 3.12.15, PyTorch 2.14.1+cpu, pytest 9.1.1, transformers 5.19.0. Tests ran through one-process torch.distributed.run with --noconftest; only the upstream run_config fixture was supplied separately to avoid GPU/data session fixtures. This is not a CUDA or CI-parity run.
• tools/autoformat.sh in check-only mode passed, including Black, isort, Pylint, Ruff, and mypy for the selected test file. Additional scoped isort/Black/Ruff/Pylint checks and git diff --check passed.
• Historical GPU validation on the original revision 7a5c6b224: A100-PCIE-40GB, one-rank NCCL/DDP forward/backward/AdamW step; adapter weights changed while base weights stayed unchanged. GPU validation has not been rerun on this rebased revision.

NVIDIA CI remains pending vetter authorization.

[copy-pr-bot]

This pull request requires additional validation before any workflows can run on NVIDIA's runners.

Pull request vetters can view their responsibilities here.

Contributors can view more details about this message here.

[Levius-Fubuki]

@maanug-nv @NVIDIA/mcore-oncall Following up on the scope/interface question from #7269.

I have rebased this PR onto current main (728ef1414), resolved the container conflict while preserving upstream configuration finalization, and updated the setup regression test to use the current config container and TrainState. Local Linux CPU validation passed 266 tests, and the repository formatting/lint checks passed. CUDA/NCCL validation of this rebased revision still needs NVIDIA CI; the earlier A100 result is explicitly recorded as historical in the description.

The proposed adapter contract is peft(model_chunks, training=True) -> list[nn.Module], invoked before DDP/FSDP wrapping and optimizer construction. Could you confirm whether this hook-only PR can proceed independently of #7271, or specify the interface/ordering changes needed?

Could a vetter also authorize NVIDIA CI for the latest signed commit, 44f136fd48d4a7d18be45c8823988420d51012a1? I am keeping the PR in draft pending CI and guidance on the scope. Thanks.