fix(deploy): switch to CPU inference for ZeroGPU compatibility

ZeroGPU's CUDA emulation is PyTorch-specific — llama-cpp-python links
directly against libcudart.so.12 which does not exist in the container.

- Remove --extra-index-url cu124 (installs CPU-only llama-cpp-python)
- Set python_version to 3.12 (ZeroGPU only supports 3.10/3.12)
- Detect SPACE_ID to force n_gpu_layers=0 on HF Spaces
- Remove @spaces.GPU from text-only LLM functions
- Keep @spaces.GPU on detection functions (PyTorch YOLO benefits)
- Add libopenblas-dev for CPU BLAS acceleration
- Remove Python 3.13 unraisablehook patch (no longer needed)
- Update README with local GPU install instructions

All hackathon badges preserved: Off the Grid, Llama Champion, Tiny Titan.
See docs/18-zerogpu-cpu-inference.md for full ADR.

Co-authored-by: Cursor <cursoragent@cursor.com>

README.md

@@ -5,7 +5,7 @@ colorFrom: green
 colorTo: blue
 sdk: gradio
 sdk_version: 6.17.3
-python_version: "3.13"
+python_version: "3.12"
 app_file: app.py
 pinned: false
 license: mit
@@ -61,16 +61,20 @@ Total parameters: **4 billion** — fits comfortably on a T4 GPU with Q4 quantiz
 
 ### On HuggingFace Spaces
 
-The app runs on a T4 GPU Space. On first use:
-1. Click **"Obtener Dataset"** to load a sample wardrobe from a HuggingFace dataset (takes ~2-5 minutes as it processes each garment through the VLM).
+The app runs on ZeroGPU with CPU-based LLM inference (llama.cpp). On first use:
+1. Click **"Obtener Dataset"** to load a sample wardrobe from a HuggingFace dataset (takes ~5-10 minutes on CPU).
 2. Or upload your own clothes photos in the **Captura** tab.
 3. Explore combinations in **Combina** and ask questions in **Pregunta**.
 
-### Local Development
+### Local Development (GPU accelerated)
 
 ```bash
 cd packages/wardrobe-us
 python -m venv .venv && source .venv/bin/activate
+
+# Install with CUDA 12.4 GPU acceleration (recommended):
+pip install llama-cpp-python \
+  --extra-index-url https://abetlen.github.io/llama-cpp-python/whl/cu124
 pip install -r requirements.txt
 
 # Custom minimal frontend (default — gr.Server + Alpine.js):
@@ -80,7 +84,7 @@ python app.py
 python app.py --default
 ```
 
-Requires a CUDA GPU with at least 8GB VRAM. Set `HF_TOKEN` in `.env` for model downloads.
+Requires a CUDA GPU with at least 8GB VRAM for GPU mode. Without CUDA, the app falls back to CPU inference automatically. Set `HF_TOKEN` in `.env` for model downloads.
 
 The default mode (`--ui`) uses `gradio.Server` with a vanilla HTML/CSS/JS + Alpine.js interface designed for non-technical users. Pass `--default` for the full Gradio Blocks UI with all advanced features (manual bounding box annotation, detection backend settings, etc.).
 

app.py

@@ -9,24 +9,8 @@ Built for the Build Small Hackathon (HuggingFace x Gradio, June 2026).
 import io
 import logging
 import os
-import sys
 from pathlib import Path
 
-# Python 3.13 raises spurious ValueError during event-loop GC when httpx
-# (used internally by Gradio) creates and discards temporary loops.
-# Suppress the noise — it has no functional impact.
-if sys.version_info >= (3, 13):
-    _original_unraisablehook = sys.unraisablehook
-
-    def _quiet_unraisablehook(unraisable):
-        if isinstance(unraisable.exc_value, ValueError) and "file descriptor" in str(
-            unraisable.exc_value
-        ):
-            return
-        _original_unraisablehook(unraisable)
-
-    sys.unraisablehook = _quiet_unraisablehook
-
 from dotenv import load_dotenv
 
 load_dotenv(Path(__file__).resolve().parent / ".env")
@@ -146,7 +130,6 @@ def auto_detect(annotation, mode, progress=gr.Progress(track_tqdm=False)):
     return _format_results(added)
 
 
-@spaces.GPU(duration=120)
 def process_manual_selection(annotation, progress=gr.Progress(track_tqdm=False)):
     """Process manually drawn bounding boxes from the annotator.
 
@@ -453,7 +436,6 @@ def clear_all():
 # Chat handlers
 # ---------------------------------------------------------------------------
 
-@spaces.GPU(duration=90)
 def chat_respond(message, history):
     """Handle chat messages with streaming responses."""
     if not message:
@@ -496,7 +478,6 @@ def _get_combo_display(combo: dict | None) -> tuple[str | None, str | None, str,
     return top_img, bottom_img, top_text, bottom_text
 
 
-@spaces.GPU(duration=60)
 def init_combinations(state, context):
     """Initialize or refresh the combination queue, optionally ranked by context."""
     combos = generate_combinations()
@@ -852,7 +833,6 @@ def _build_custom_server():
         return {"garments": catalog, "count": len(catalog)}
 
     @server.api(name="add_photo")
-    @spaces.GPU(duration=120)
     def api_add_photo(image_path) -> dict:
         if isinstance(image_path, dict):
             image_path = image_path.get("path") or image_path.get("url", "")
@@ -865,7 +845,6 @@ def _build_custom_server():
         return {"garments": added, "count": len(added)}
 
     @server.api(name="get_combinations")
-    @spaces.GPU(duration=60)
     def api_get_combinations(context: str = "") -> dict:
         combos = generate_combinations()
         if not combos:
@@ -890,14 +869,12 @@ def _build_custom_server():
         return {"status": "ok", "liked": liked}
 
     @server.api(name="ask_question")
-    @spaces.GPU(duration=90)
     def api_ask_question(question: str) -> str:
         if not question or not question.strip():
             return "Please ask a question about your wardrobe."
         return ask(question.strip())
 
     @server.api(name="load_dataset")
-    @spaces.GPU(duration=300)
     def api_load_dataset(dataset_key: str) -> dict:
         from datasets import load_dataset as hf_load
 

packages.txt

@@ -1,2 +1,3 @@
 cmake
 build-essential
+libopenblas-dev

requirements.txt

@@ -1,4 +1,3 @@
---extra-index-url https://abetlen.github.io/llama-cpp-python/whl/cu124
 spaces
 gradio==6.17.3
 llama-cpp-python>=0.3.28

src/model_loader.py

@@ -1,10 +1,10 @@
-"""Singleton model loader with VRAM management.
+"""Singleton model loader for GGUF models.
 
-Handles loading/unloading of GGUF models. Only one model is kept in
-memory at a time to fit within available VRAM.
-
-Supports ZeroGPU (dynamic GPU allocation on HF Spaces) by detecting
-CUDA availability at load time rather than import time.
+Keeps one model loaded at a time. Supports dual-mode deployment:
+- HF Spaces (ZeroGPU): CPU-only inference (n_gpu_layers=0) because
+  ZeroGPU's CUDA emulation is PyTorch-specific and llama.cpp links
+  against the system CUDA runtime which is not available.
+- Local: Full GPU offload via CUDA when libcudart.so.12 is present.
 """
 
 import gc
@@ -96,7 +96,15 @@ class _ModelManager:
 
     @staticmethod
     def _detect_gpu_layers() -> int:
-        """Return -1 (all layers on GPU) if CUDA is available, else 0 (CPU)."""
+        """Detect whether to offload layers to GPU.
+
+        On HF Spaces the CUDA runtime is unavailable to llama.cpp
+        (ZeroGPU only exposes CUDA through PyTorch emulation).
+        Locally, probe for libcudart.so.12 to confirm real CUDA.
+        """
+        if os.environ.get("SPACE_ID"):
+            logger.info("Running on HF Spaces — using CPU inference")
+            return 0
         if os.environ.get("CUDA_VISIBLE_DEVICES") == "":
             return 0
         try: