fn_registry/python/functions/ml/image_generator.py

"""ImageGenerator — Protocol para backends de generacion de imagenes."""

from __future__ import annotations

from typing import TYPE_CHECKING, Protocol, runtime_checkable

if TYPE_CHECKING:
    from generation_config import GenerationConfig
    from image_gen_result import ImageGenResult


@runtime_checkable
class ImageGenerator(Protocol):
    """Interfaz comun para backends de generacion de imagenes con difusion.

    Cualquier clase que implemente `generate(config) -> ImageGenResult`
    satisface este Protocol sin herencia explicita (structural subtyping).

    Backends de ejemplo que satisfacen esta interfaz:
    - DiffusersGenerator: usa HuggingFace diffusers + torch.
    - SdCppGenerator: wrapper sobre stable-diffusion.cpp via ctypes/subprocess.
    - ComfyUIGenerator: cliente HTTP a ComfyUI API.
    - MockGenerator: implementacion de prueba sin GPU.

    El Protocol es `runtime_checkable`, por lo que se puede usar con isinstance():
        assert isinstance(my_backend, ImageGenerator)

    Nota: `isinstance()` con Protocol runtime_checkable solo verifica la presencia
    del metodo `generate`, no la firma completa. Para verificacion estricta usar mypy.
    """

    def generate(self, config: "GenerationConfig") -> "ImageGenResult":
        """Genera una imagen a partir de la configuracion de difusion.

        Args:
            config: Parametros de generacion. Ver GenerationConfig.

        Returns:
            Resultado con la imagen PIL, metadata de la generacion,
            duracion total y pico de VRAM. Ver ImageGenResult.

        Raises:
            Exception: El tipo concreto de error depende del backend.
                       Los backends deben documentar sus excepciones propias.
        """
        ...