Refactor: Docker+llama.cpp -> Gradio SDK + ZeroGPU transformers backend

.dockerignore

@@ -1,29 +0,0 @@
-# Keep the build context (and the pushed Space repo) small. Multi-GB vendored
-# trees, the local model runtime, and Windows-only launchers are excluded.
-.git
-.venv
-venv
-runtime/
-tools/
-__pycache__/
-**/__pycache__/
-*.pyc
-tmp/
-*.log
-*.err.log
-
-# Heavy / local-only data. The maps, processed graph and voices are kept;
-# backups, saved games and the smoke screenshot are not needed in the image.
-data/backups/
-data/games/
-data/archives/
-data/raw/archives/
-data/*.log
-data/*.png
-
-# Windows launchers — not used on Linux.
-run_game.ps1
-run_game.cmd
-
-# Build artifact placeholders
-C:*

Dockerfile

@@ -1,52 +0,0 @@
-# Phantom Grid — Docker Hugging Face Space (Linux, CPU).
-#
-# The image bakes in a prebuilt llama.cpp OpenAI-compatible server
-# (llama-cpp-python) and the MiniCPM4.1-8B Q4_K_M GGUF (text backend, <32B),
-# so there is NO build-from-source or model download at container startup.
-FROM python:3.12-slim
-
-ENV PYTHONUNBUFFERED=1 \
-    PIP_NO_CACHE_DIR=1 \
-    HF_HOME=/app/.hfcache \
-    MODEL_DIR=/app/models \
-    MODEL_PATH=/app/models/MiniCPM4.1-8B-Q4_K_M.gguf
-
-# Minimal OS deps. libgomp1 is needed by the llama.cpp OpenMP runtime.
-RUN apt-get update \
-    && apt-get install -y --no-install-recommends libgomp1 curl ca-certificates \
-    && rm -rf /var/lib/apt/lists/*
-
-WORKDIR /app
-
-# --- Python deps -----------------------------------------------------------
-COPY requirements-space.txt ./
-RUN pip install --upgrade pip \
-    && pip install -r requirements-space.txt \
-    # Prebuilt CPU wheel for the OpenAI-compatible llama.cpp server (no compile).
-    && pip install "llama-cpp-python[server]" \
-        --extra-index-url https://abetlen.github.io/llama-cpp-python/whl/cpu
-
-# --- Bake the model at BUILD time -----------------------------------------
-# Downloaded into the image so the Space boots without a multi-GB pull.
-RUN python -c "from huggingface_hub import hf_hub_download; \
-hf_hub_download(repo_id='openbmb/MiniCPM4.1-8B-GGUF', \
-filename='MiniCPM4.1-8B-Q4_K_M.gguf', local_dir='/app/models')"
-
-# --- App code --------------------------------------------------------------
-COPY . .
-
-# Writable dirs for HF's runtime user (Spaces run as uid 1000).
-RUN mkdir -p /app/data/games /app/.hfcache \
-    && chmod -R 777 /app/data /app/.hfcache /app/models
-
-# Point the app at the in-container llama.cpp server (text-only, no voice).
-ENV PHANTOM_GRID_LLM_PROVIDER=external_llama_cpp_server \
-    PHANTOM_GRID_LLAMACPP_BASE_URL=http://127.0.0.1:8080/v1 \
-    PHANTOM_GRID_LLM_MODEL=MiniCPM4.1-8B-Q4_K_M.gguf \
-    PHANTOM_GRID_WITNESS_CHAT_TTS=0 \
-    PHANTOM_GRID_HOST=0.0.0.0 \
-    PORT=7860
-
-EXPOSE 7860
-
-ENTRYPOINT ["bash", "entrypoint.sh"]

README.md

@@ -3,16 +3,25 @@ title: Phantom Grid
 emoji: 🕵️
 colorFrom: indigo
 colorTo: gray
-sdk: docker
-app_port: 7860
+sdk: gradio
+sdk_version: 6.17.3
+app_file: app.py
+python_version: "3.10"
 pinned: false
 license: mit
+hf_oauth: false
 tags:
   - thousand-token-wood
   - delightful
   - game
   - agent
   - minicpm
+env:
+  - PHANTOM_GRID_LLM_PROVIDER=zerogpu_transformers
+  - PHANTOM_GRID_ZEROGPU_MODEL_ID=openbmb/MiniCPM4.1-8B
+  - PHANTOM_GRID_ZEROGPU_DURATION=90
+  - PHANTOM_GRID_HOST=0.0.0.0
+  - PHANTOM_GRID_WITNESS_CHAT_TTS=0
 ---
 
 # 🕵️ Phantom Grid
@@ -33,17 +42,16 @@ in a custom `gr.Server` HTML/JS board interface (no stock Gradio components).
 ## 🤖 Model & inference
 
 - **Model:** [`openbmb/MiniCPM4.1-8B`](https://huggingface.co/openbmb/MiniCPM4.1-8B)
-  (text, Q4_K_M GGUF) — ~8B params, well under the 32B cap.
-- **Inference:** the blessed llama.cpp path — an OpenAI-compatible
-  `llama.cpp` server (`llama-cpp-python`) on `:8080/v1`, with the app pointing at it via
-  `PHANTOM_GRID_LLAMACPP_BASE_URL`. The model is **baked into the image at build time**, so the
-  Space boots without any multi-GB download or build-from-source.
+  (text, bf16 transformers) — ~8B params, well under the 32B cap.
+- **Inference:** in-process Hugging Face `transformers`. The model lives in CPU
+  RAM and is moved to cuda inside a `@spaces.GPU`-decorated function, so the
+  H200 is only held while the model is actually generating.
 
 ## 🖥️ Hardware
 
-Runs on **CPU** (the model is Q4_K_M, ~5 GB RAM). Witness replies are slow on the free
-CPU tier; an upgraded CPU or a GPU Space makes interviews snappy. The text backend has no
-voice path (`PHANTOM_GRID_WITNESS_CHAT_TTS=0`).
+Runs on **ZeroGPU** (H200, free 40 min/day for org members). Each generation is
+capped at `PHANTOM_GRID_ZEROGPU_DURATION` seconds (default 90). No voice path
+on this Space (`PHANTOM_GRID_WITNESS_CHAT_TTS=0`).
 
 ## 🎥 Demo video
 

entrypoint.sh

@@ -1,43 +0,0 @@
-#!/usr/bin/env bash
-# Linux entrypoint for the Phantom Grid Docker Space.
-# 1. Start the baked-in llama.cpp OpenAI-compatible server on :8080.
-# 2. Wait until it reports healthy (/v1/models).
-# 3. Launch the gr.Server app, bound to 0.0.0.0:$PORT for the Space.
-set -euo pipefail
-
-MODEL_PATH="${MODEL_PATH:-/app/models/MiniCPM4.1-8B-Q4_K_M.gguf}"
-LLAMA_PORT="${LLAMA_PORT:-8080}"
-CTX="${PHANTOM_GRID_LLAMACPP_CONTEXT_LENGTH:-8192}"
-APP_PORT="${PORT:-7860}"
-
-echo "[entrypoint] Starting llama.cpp server on :${LLAMA_PORT} with ${MODEL_PATH}"
-# llama_cpp.server's pydantic Settings reads HOST/PORT from env and they
-# override the CLI flags — so on HF Spaces (PORT=7860) the server would bind
-# 7860 and collide with Gradio. Scope HOST/PORT to just this subprocess.
-HOST=127.0.0.1 PORT="${LLAMA_PORT}" python -m llama_cpp.server \
-    --model "${MODEL_PATH}" \
-    --host 127.0.0.1 \
-    --port "${LLAMA_PORT}" \
-    --n_ctx "${CTX}" \
-    --n_gpu_layers "${LLAMA_N_GPU_LAYERS:-0}" \
-    &
-LLAMA_PID=$!
-
-cleanup() { kill "${LLAMA_PID}" 2>/dev/null || true; }
-trap cleanup EXIT INT TERM
-
-echo "[entrypoint] Waiting for llama.cpp /v1/models to become ready..."
-for i in $(seq 1 180); do
-    if curl -sf "http://127.0.0.1:${LLAMA_PORT}/v1/models" >/dev/null 2>&1; then
-        echo "[entrypoint] llama.cpp server is ready."
-        break
-    fi
-    if ! kill -0 "${LLAMA_PID}" 2>/dev/null; then
-        echo "[entrypoint] llama.cpp server exited unexpectedly." >&2
-        exit 1
-    fi
-    sleep 2
-done
-
-echo "[entrypoint] Launching Phantom Grid app on 0.0.0.0:${APP_PORT}"
-exec python app.py

llm/omni_client.py

@@ -35,6 +35,9 @@ class OmniClient:
         return cls(load_settings())
 
     def health(self, timeout: float = 0.75) -> dict[str, Any]:
+        if self.settings.llm_provider == "zerogpu_transformers":
+            from llm import zerogpu_backend
+            return zerogpu_backend.health()
         if self.settings.llm_provider in {"llama_cpp_server", "external_llama_cpp_server"}:
             base_url = self.settings.llamacpp_base_url.rstrip("/")
             try:
@@ -358,6 +361,14 @@ class OmniClient:
             {"role": "system", "content": system_prompt},
             {"role": "user", "content": user_prompt},
         ])]
+        if self.settings.llm_provider == "zerogpu_transformers":
+            from llm import zerogpu_backend
+            return zerogpu_backend.chat_completion(
+                content,
+                temperature=temperature,
+                max_tokens=max_tokens,
+                json_mode=json_mode,
+            )
         if self.settings.llm_provider in {"llama_cpp_server", "external_llama_cpp_server"}:
             text_url = f"{self.settings.llamacpp_base_url.rstrip('/')}/chat/completions"
             model = self.settings.llm_model or (self.settings.llamacpp_model_path.name if self.settings.llamacpp_model_path else "local")

llm/zerogpu_backend.py

@@ -0,0 +1,163 @@
+"""In-process transformers backend for HF Spaces ZeroGPU.
+
+Loaded only when PHANTOM_GRID_LLM_PROVIDER=zerogpu_transformers. Model weights
+live in CPU RAM and are moved to cuda inside the @spaces.GPU function, which is
+how ZeroGPU's per-call GPU acquisition expects PyTorch models to behave.
+"""
+from __future__ import annotations
+
+import json
+import os
+import re
+import threading
+from typing import Any
+
+_MODEL_ID = os.getenv("PHANTOM_GRID_ZEROGPU_MODEL_ID", "openbmb/MiniCPM4.1-8B")
+_DEFAULT_DURATION = int(os.getenv("PHANTOM_GRID_ZEROGPU_DURATION", "90"))
+
+_lock = threading.Lock()
+_model = None
+_tokenizer = None
+_loaded_to_cuda = False
+
+
+def _ensure_loaded() -> None:
+    """Load the model + tokenizer onto CPU. Called once at module init."""
+    global _model, _tokenizer
+    if _model is not None and _tokenizer is not None:
+        return
+    import torch
+    from transformers import AutoModelForCausalLM, AutoTokenizer
+
+    with _lock:
+        if _tokenizer is None:
+            _tokenizer = AutoTokenizer.from_pretrained(_MODEL_ID, trust_remote_code=True)
+        if _model is None:
+            _model = AutoModelForCausalLM.from_pretrained(
+                _MODEL_ID,
+                torch_dtype=torch.bfloat16,
+                trust_remote_code=True,
+                low_cpu_mem_usage=True,
+            )
+            _model.eval()
+
+
+try:
+    import spaces  # type: ignore
+
+    _spaces_gpu = spaces.GPU
+except ImportError:  # pragma: no cover — local dev without `spaces` installed
+    def _spaces_gpu(*_args, **_kwargs):
+        def _wrap(fn):
+            return fn
+        return _wrap
+
+
+@_spaces_gpu(duration=_DEFAULT_DURATION)
+def _generate_on_gpu(
+    messages: list[dict[str, Any]],
+    max_new_tokens: int,
+    temperature: float,
+    json_mode: bool,
+) -> str:
+    """Runs on the H200 only when ZeroGPU has granted the slot."""
+    import torch
+
+    global _loaded_to_cuda
+    _ensure_loaded()
+    assert _model is not None and _tokenizer is not None
+
+    if not _loaded_to_cuda:
+        _model.to("cuda")
+        _loaded_to_cuda = True
+
+    prompt = _tokenizer.apply_chat_template(
+        messages,
+        tokenize=False,
+        add_generation_prompt=True,
+    )
+    inputs = _tokenizer(prompt, return_tensors="pt").to("cuda")
+
+    do_sample = temperature > 0
+    gen_kwargs = {
+        "max_new_tokens": max_new_tokens,
+        "do_sample": do_sample,
+        "pad_token_id": _tokenizer.eos_token_id,
+    }
+    if do_sample:
+        gen_kwargs["temperature"] = temperature
+        gen_kwargs["top_p"] = 0.9
+
+    with torch.inference_mode():
+        outputs = _model.generate(**inputs, **gen_kwargs)
+
+    new_tokens = outputs[0][inputs["input_ids"].shape[1]:]
+    text = _tokenizer.decode(new_tokens, skip_special_tokens=True).strip()
+
+    if json_mode:
+        text = _extract_json(text)
+    return text
+
+
+def _extract_json(text: str) -> str:
+    """Strip code fences and isolate the first JSON object."""
+    cleaned = text.strip()
+    if cleaned.startswith("```"):
+        cleaned = cleaned.strip("`")
+        if cleaned.lower().startswith("json"):
+            cleaned = cleaned[4:].strip()
+    start = cleaned.find("{")
+    end = cleaned.rfind("}")
+    if start >= 0 and end > start:
+        return cleaned[start : end + 1]
+    return text
+
+
+_NO_THINK_HINTS = ("minicpm4", "minicpm-4", "minicpm_4", "qwen3", "qwen-3")
+
+
+def _maybe_inject_no_think(messages: list[dict[str, Any]]) -> list[dict[str, Any]]:
+    """MiniCPM4 / Qwen3 emit hidden <think> blocks that eat the token budget on
+    small max_new_tokens. Append '/no_think' to the system turn so the model
+    skips it. Mirrors llm/omni_client.py:_ensure_no_think."""
+    if not any(hint in _MODEL_ID.lower() for hint in _NO_THINK_HINTS):
+        return messages
+    directive = "/no_think"
+    for item in messages:
+        if item.get("role") == "system" and isinstance(item.get("content"), str):
+            if directive not in item["content"]:
+                item["content"] = f"{item['content'].rstrip()} {directive}".strip()
+            return messages
+    return [{"role": "system", "content": directive}, *messages]
+
+
+def chat_completion(
+    messages: list[dict[str, Any]],
+    *,
+    temperature: float = 0.4,
+    max_tokens: int = 512,
+    json_mode: bool = False,
+) -> str:
+    """Synchronous, drop-in replacement for an OpenAI chat-completions POST."""
+    messages = _maybe_inject_no_think([dict(m) for m in messages])
+    return _generate_on_gpu(messages, max_tokens, temperature, json_mode)
+
+
+def health() -> dict[str, Any]:
+    """Cheap probe — does NOT touch the GPU. Reflects whether the module imported."""
+    return {
+        "reachable": True,
+        "ready": _tokenizer is not None,
+        "detail": {"model_id": _MODEL_ID, "loaded_to_cuda": _loaded_to_cuda},
+    }
+
+
+# Kick off the CPU-side load eagerly so the first user turn doesn't pay for it.
+# Wrapped in try/except so an import failure (e.g. during local dev without the
+# huge model cache) doesn't crash app startup — the health probe will report it.
+try:
+    _ensure_loaded()
+except Exception as exc:  # pragma: no cover
+    _LOAD_ERROR = f"{exc.__class__.__name__}: {exc}"
+else:
+    _LOAD_ERROR = None

requirements.txt

@@ -0,0 +1,17 @@
+# Runtime dependencies for the Gradio SDK / ZeroGPU Hugging Face Space.
+# Read by HF Spaces' Gradio runner at build time.
+
+gradio>=6.17.3
+spaces>=0.30.0
+huggingface_hub>=1.2
+pydantic>=2.7
+websockets>=14.0
+fastapi
+uvicorn
+
+# Text LLM backend: HF transformers + PyTorch, MiniCPM4.1-8B is loaded
+# CPU-side at import and moved to cuda inside the @spaces.GPU function.
+torch>=2.4.0
+transformers>=4.46.0
+accelerate>=1.0.0
+sentencepiece