models/zero_gpu.py

"""
ZeroGPU integration helper.

Hugging Face's free tier now only offers ZeroGPU hardware for compute
Spaces (CPU Basic requires a paid plan as of mid-2026). ZeroGPU has a hard
platform requirement: a Space will fail to start if it contains ZERO
functions decorated with @spaces.GPU, even if none of them strictly need
CUDA to run.

This module provides `gpu_decorator`, which is:
  - the real `spaces.GPU` decorator when the `spaces` package is present
    (i.e. when actually running on a Hugging Face Space)
  - a transparent no-op decorator everywhere else (local dev, this sandbox,
    CI) so the exact same code runs unmodified off-platform

Per Hugging Face's own documentation, `spaces.GPU` is itself "designed to
be effect-free in non-ZeroGPU environments" — this wrapper extends that
same safety to environments where the `spaces` package isn't installed
at all.

Our models are intentionally small enough that they do not need GPU
acceleration to produce a convincing demo; this decorator exists to
satisfy the platform requirement, not because the workload demands it.
"""

from __future__ import annotations
import logging

logger = logging.getLogger("zero_gpu")

try:
    import spaces  # type: ignore
    gpu_decorator = spaces.GPU
    ZERO_GPU_AVAILABLE = True
    logger.info("Running with real Hugging Face `spaces` module — @spaces.GPU is active.")
except ImportError:
    ZERO_GPU_AVAILABLE = False

    def gpu_decorator(*decorator_args, **decorator_kwargs):
        """No-op replacement for spaces.GPU so code runs unmodified off-Spaces."""
        def wrapper(func):
            return func
        # Support both @gpu_decorator and @gpu_decorator(duration=30) call styles
        if len(decorator_args) == 1 and callable(decorator_args[0]) and not decorator_kwargs:
            return decorator_args[0]
        return wrapper

    logger.info("`spaces` module not found (expected in local/sandbox environments) — "
                "@spaces.GPU calls are no-ops here.")