feat: add GPU/CUDA acceleration support (:cuda Docker tag)

Add a :cuda Docker image tag that auto-detects NVIDIA GPU at runtime
and falls back gracefully to CPU. Same pattern as Immich.

- New gpu.py shared utility for cached CUDA detection
- Background removal (rembg): pass CUDAExecutionProvider to ONNX Runtime
- Upscaling (Real-ESRGAN): use CUDA device + FP16 when GPU available
- OCR (PaddleOCR): enable use_gpu when CUDA detected
- Dispatcher reports GPU status at startup via readiness signal
- Admin health endpoint exposes GPU availability
- Dockerfile uses ARG GPU=false with conditional NVIDIA CUDA base image
- docker-compose.gpu.yml override for GPU users
- CI/CD workflows build and publish :cuda tag (amd64 only)

Three tags: :latest (CPU), :lite (no AI), :cuda (GPU with CPU fallback)

packages/ai/python/dispatcher.py

@@ -39,6 +39,7 @@ def _try_import(name, import_fn):
 _try_import("PIL", lambda: __import__("PIL"))
 _try_import("cv2", lambda: __import__("cv2"))
 _try_import("numpy", lambda: __import__("numpy"))
+_try_import("gpu", lambda: __import__("gpu"))
 
 # Heavy ML libraries - import but don't fail if unavailable
 _try_import("rembg", lambda: __import__("rembg"))
@@ -123,8 +124,14 @@ def _run_script_main(script_name, args):
 
 
 def main():
-    # Signal readiness
-    print(json.dumps({"ready": True}), file=sys.stderr, flush=True)
+    # Signal readiness with GPU status
+    gpu = False
+    try:
+        from gpu import gpu_available
+        gpu = gpu_available()
+    except ImportError:
+        pass
+    print(json.dumps({"ready": True, "gpu": gpu}), file=sys.stderr, flush=True)
 
     for line in sys.stdin:
         line = line.strip()

packages/ai/python/gpu.py

@@ -0,0 +1,34 @@
+"""Runtime GPU/CUDA detection utility."""
+import functools
+import os
+
+
+@functools.lru_cache(maxsize=1)
+def gpu_available():
+    """Return True if a usable CUDA GPU is present at runtime."""
+    override = os.environ.get("STIRLING_GPU")
+    if override is not None:
+        return override.lower() in ("1", "true", "yes")
+
+    try:
+        import onnxruntime
+        if "CUDAExecutionProvider" in onnxruntime.get_available_providers():
+            return True
+    except ImportError:
+        pass
+
+    try:
+        import torch
+        if torch.cuda.is_available():
+            return True
+    except ImportError:
+        pass
+
+    return False
+
+
+def onnx_providers():
+    """Return ONNX Runtime execution providers in priority order."""
+    if gpu_available():
+        return ["CUDAExecutionProvider", "CPUExecutionProvider"]
+    return ["CPUExecutionProvider"]

packages/ai/python/ocr.py

@@ -34,9 +34,10 @@ def run_paddleocr(input_path, language):
     """Run PaddleOCR."""
     os.environ["PADDLE_PDX_DISABLE_MODEL_SOURCE_CHECK"] = "True"
     from paddleocr import PaddleOCR
+    from gpu import gpu_available
 
     emit_progress(20, "Loading")
-    ocr = PaddleOCR(lang=language)
+    ocr = PaddleOCR(lang=language, use_gpu=gpu_available())
     emit_progress(30, "Scanning")
     result = ocr.ocr(input_path)
     emit_progress(70, "Extracting text")

packages/ai/python/remove_bg.py

@@ -24,11 +24,12 @@ def main():
 
     try:
         from rembg import remove, new_session
+        from gpu import onnx_providers
         import io
 
         emit_progress(10, "Loading model")
 
-        session = new_session(model)
+        session = new_session(model, providers=onnx_providers())
 
         emit_progress(25, "Model loaded")
 

packages/ai/python/requirements-gpu.txt

@@ -0,0 +1,10 @@
+rembg==2.0.62
+realesrgan==0.3.0
+lama-cleaner==1.2.5
+paddleocr==2.9.1
+paddlepaddle-gpu==3.0.0
+mediapipe==0.10.21
+onnxruntime-gpu==1.20.1
+numpy==1.26.4
+Pillow==11.1.0
+opencv-python-headless==4.10.0.84

packages/ai/python/upscale.py

@@ -26,7 +26,12 @@ def main():
         try:
             from basicsr.archs.rrdbnet_arch import RRDBNet
             from realesrgan import RealESRGANer
+            from gpu import gpu_available
             import numpy as np
+            import torch
+
+            use_gpu = gpu_available()
+            device = torch.device("cuda" if use_gpu else "cpu")
 
             model = RRDBNet(
                 num_in_ch=3,
@@ -40,7 +45,8 @@ def main():
                 scale=scale,
                 model_path=None,
                 model=model,
-                half=False,
+                half=use_gpu,
+                device=device,
             )
             emit_progress(20, "Model ready")
             img_array = np.array(img.convert("RGB"))