Source code for nvalchemi.training.peft.registry

# SPDX-FileCopyrightText: Copyright (c) 2026 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.
"""Registration and lookup for parameter-efficient fine-tuning methods."""

from __future__ import annotations

from collections.abc import Callable, Mapping
from dataclasses import dataclass
from typing import TYPE_CHECKING, Any, Protocol

if TYPE_CHECKING:
    from torch import nn

    from nvalchemi.training.peft.config import PeftConfig

__all__ = [
    "PeftMethodRegistration",
    "available_peft_methods",
    "register_peft_method",
]


class _ApplyPeftFromCheckpointMetadata(Protocol):
    """Callable that recreates PEFT structure from checkpoint metadata."""

    def __call__(
        self,
        model: nn.Module,
        strategy_metadata: Mapping[str, Any],
        *,
        model_name: str,
        import_path_validator: Callable[[str, str], None] | None = None,
    ) -> None: ...


[docs] @dataclass(frozen=True) class PeftMethodRegistration: """Operations and configuration type associated with one PEFT method. Attributes ---------- peft_method Stable and unique PEFT method discriminator stored in serialized metadata. config_cls Configuration class associated with the method. build_peft_setup_hooks Callable that builds the hooks needed to configure PEFT before training. apply_peft_from_checkpoint_metadata Callable that recreates the PEFT structure described by checkpoint metadata on a model. merge_peft Callable that merges PEFT parameters into a model. """ peft_method: str config_cls: type[PeftConfig] build_peft_setup_hooks: Callable[[PeftConfig, Mapping[str, Any]], list[Any]] apply_peft_from_checkpoint_metadata: _ApplyPeftFromCheckpointMetadata merge_peft: Callable[..., nn.Module]
_REGISTRATIONS_BY_METHOD: dict[str, PeftMethodRegistration] = {} _REGISTRATIONS_BY_CONFIG: dict[type[PeftConfig], PeftMethodRegistration] = {}
[docs] def register_peft_method( method: str, *, config_cls: type[PeftConfig], build_peft_setup_hooks: Callable[[PeftConfig, Mapping[str, Any]], list[Any]], apply_peft_from_checkpoint_metadata: _ApplyPeftFromCheckpointMetadata, merge_peft: Callable[..., nn.Module], ) -> PeftMethodRegistration: """Register all behavior required to use one PEFT method. Parameters ---------- method Stable method name used in serialized PEFT metadata. config_cls Configuration class associated with the method. build_peft_setup_hooks Callable that builds the hooks needed to configure PEFT before training. apply_peft_from_checkpoint_metadata Callable that recreates the PEFT structure described by checkpoint metadata on a model. merge_peft Callable that merges PEFT parameters into a model. Returns ------- PeftMethodRegistration The installed registration. Raises ------ ValueError If ``method`` is empty or the method or configuration class is already registered. TypeError If ``config_cls`` is not a :class:`PeftConfig` subclass. """ from nvalchemi.training.peft.config import PeftConfig if not isinstance(method, str) or not method: raise ValueError("PEFT method name must be a non-empty string.") if not isinstance(config_cls, type) or not issubclass(config_cls, PeftConfig): raise TypeError("PEFT config_cls must be a PeftConfig subclass.") if method in _REGISTRATIONS_BY_METHOD: raise ValueError(f"PEFT method {method!r} is already registered.") if config_cls in _REGISTRATIONS_BY_CONFIG: raise ValueError( f"PEFT config class {config_cls.__module__}.{config_cls.__qualname__} " "is already registered." ) registration = PeftMethodRegistration( peft_method=method, config_cls=config_cls, build_peft_setup_hooks=build_peft_setup_hooks, apply_peft_from_checkpoint_metadata=apply_peft_from_checkpoint_metadata, merge_peft=merge_peft, ) _REGISTRATIONS_BY_METHOD[method] = registration _REGISTRATIONS_BY_CONFIG[config_cls] = registration return registration
# --------------------------------------------------------------------------- # Built-in integrations # --------------------------------------------------------------------------- def _register_builtin_peft_methods() -> None: """Lazily register bundled PEFT methods. New built-in PEFT integrations must add their registration callback here. External integrations should call :func:`register_peft_method` directly. """ from nvalchemi.training.peft.lora import ( LORA_PEFT_METHOD, register_lora_method, ) if LORA_PEFT_METHOD not in _REGISTRATIONS_BY_METHOD: register_lora_method() def get_peft_registration_by_method(method: Any) -> PeftMethodRegistration: """Return the registration identified by a PEFT method name. Parameters ---------- method Method name read from serialized PEFT metadata. Returns ------- PeftMethodRegistration The matching registration. Raises ------ ValueError If no PEFT method is registered under ``method``. """ _register_builtin_peft_methods() try: return _REGISTRATIONS_BY_METHOD[method] except (KeyError, TypeError): pass raise ValueError(f"Unsupported PEFT method {method!r}.") from None def get_peft_registration_by_config(config: PeftConfig) -> PeftMethodRegistration: """Return the registration associated with a PEFT config object. Parameters ---------- config PEFT configuration whose method registration should be resolved. Returns ------- PeftMethodRegistration The registration for the nearest registered class in the configuration's method resolution order. Raises ------ ValueError If the configuration class has no registered PEFT method. """ _register_builtin_peft_methods() for config_cls in type(config).__mro__: registration = _REGISTRATIONS_BY_CONFIG.get(config_cls) if registration is not None: return registration raise ValueError(f"Unsupported PEFT config type: {type(config).__name__}.")
[docs] def available_peft_methods() -> tuple[str, ...]: """Return registered and built-in PEFT method names. Returns ------- tuple[str, ...] Available method names in sorted order. """ _register_builtin_peft_methods() return tuple(sorted(_REGISTRATIONS_BY_METHOD))