fn_registry/python/functions/ml/lora_ref.py

"""LoraRef — referencia a un adaptador LoRA para generacion de imagenes."""

from __future__ import annotations

try:
    from pydantic import BaseModel, ConfigDict

    class LoraRef(BaseModel):
        """Referencia a un adaptador LoRA (Low-Rank Adaptation).

        Un LoRA modifica el comportamiento de un modelo base sin cambiar
        sus pesos originales. Se aplica multiplicando matrices de rango bajo
        durante la inferencia.

        Attributes:
            path:   Ruta al archivo .safetensors o .bin del adaptador LoRA.
                    Puede ser absoluta o relativa al directorio de modelos.
            weight: Factor de escala global del LoRA. 1.0 aplica el LoRA
                    con su fuerza original. 0.0 lo desactiva completamente.
                    Rango tipico: 0.0 a 1.5.
            scale:  Override del alpha del LoRA (escala de rango). None usa
                    el alpha del propio archivo. Util para ajuste fino sin
                    reentrenar.
        """

        model_config = ConfigDict(frozen=True)

        path: str
        weight: float = 1.0
        scale: float | None = None

except ImportError:
    from dataclasses import dataclass

    @dataclass(frozen=True)
    class LoraRef:  # type: ignore[no-redef]
        """Referencia a un adaptador LoRA (fallback dataclass).

        Attributes:
            path:   Ruta al archivo del adaptador LoRA (.safetensors o .bin).
            weight: Factor de escala global. Rango tipico 0.0-1.5. Por defecto 1.0.
            scale:  Override del alpha. None usa el alpha del archivo.
        """

        path: str
        weight: float = 1.0
        scale: float | None = None