Modal-backed Space: run models on Modal GPU endpoints, Space is a thin HTTP client

- modal_app.py: MiniCPM (cards) + Nemotron (boss) as OpenAI-compatible chat
endpoints, SDXL-Turbo (art) returning a data URI; warm A10G containers + a
cached HF volume.
- art.py/clients.py: ModalArtClient + a 'modal' art backend.
- app_hf.py: endpoint-based backends (card/boss over HTTP, art via modal);
endpoint URLs come from Space variables. No GPU on the Space.
- requirements: slim to gradio only; README -> cpu-basic, Modal-backed.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

README.md

@@ -6,7 +6,7 @@ colorTo: indigo
 sdk: gradio
 sdk_version: 6.17.3
 app_file: app_hf.py
-suggested_hardware: zero-a10g
+suggested_hardware: cpu-basic
 pinned: false
 license: mit
 tags:
@@ -64,7 +64,7 @@ All listed models are under the hackathon's 32B parameter limit.
 | Boss AI | `nvidia/Nemotron-Mini-4B-Instruct` | Enemy play decisions |
 | Art | `stabilityai/sdxl-turbo` | Fast card illustration |
 
-The Hugging Face Space entry point is [app_hf.py](app_hf.py). It defaults to Transformers/Diffusers backends and wraps model loading/inference with Hugging Face ZeroGPU so GPU work runs only inside allocated calls, without requiring a local llama.cpp server.
+The Hugging Face Space entry point is [app_hf.py](app_hf.py). The Space is a thin client: MiniCPM (cards), Nemotron (boss), and SDXL-Turbo (art) run on dedicated Modal GPU endpoints (see [modal_app.py](modal_app.py)), which the Space calls over HTTP. This keeps heavy compute off the Space (free CPU hardware) and gives each model its own autoscaled GPU.
 
 ## Running Locally
 

app_hf.py

@@ -1,33 +1,40 @@
-"""Hugging Face Space entry point for Tabras.
+"""Hugging Face Space entry point for Tabras (Modal-backed).
 
-Runs the game with on-device Transformers/Diffusers backends (no MLX and no
-llama-server subprocess), so it works on a CUDA GPU Space. Every model id and
-generation setting below is a default that a Space variable/secret can override.
+The Space is a thin client: MiniCPM (cards), Nemotron (boss), and SDXL (art) all
+run on Modal GPU endpoints (see modal_app.py). Set these Space variables to the
+URLs printed by `modal deploy modal_app.py`:
+
+    TABRAS_CARD_ENDPOINT  -> CardModel.chat  URL
+    TABRAS_BOSS_ENDPOINT  -> BossModel.chat  URL
+    TABRAS_ART_ENDPOINT   -> ArtModel.generate URL
+
+No GPU is needed on the Space itself, so it runs on free CPU hardware.
 """
 
 import os
 
-# MiniCPM authors the cards through its Transformers chat method.
-os.environ.setdefault("TABRAS_CARD_BACKEND", "transformers")
-os.environ.setdefault("TABRAS_CARD_MODEL", "openbmb/MiniCPM-V-4")
+# Cards via the Modal MiniCPM endpoint (OpenAI-compatible chat over HTTP).
+os.environ.setdefault("TABRAS_CARD_BACKEND", "llamacpp")
+os.environ.setdefault("TABRAS_CARD_MODEL", "minicpm")
 os.environ.setdefault("TABRAS_CARD_MAX_TOKENS", "192")
+os.environ.setdefault("TABRAS_CARD_TEMPERATURE", "0.7")
+os.environ.setdefault("TABRAS_CARD_TIMEOUT", "120")
 
-# Nemotron plays the boss.
+# Boss via the Modal Nemotron endpoint (LocalChatClient HTTP path).
 os.environ.setdefault("TABRAS_AI_BOSS", "1")
-os.environ.setdefault("TABRAS_BOSS_BACKEND", "transformers")
-os.environ.setdefault("TABRAS_BOSS_MODEL", "nvidia/Nemotron-Mini-4B-Instruct")
+os.environ.setdefault("TABRAS_BOSS_BACKEND", "openai")
+os.environ.setdefault("TABRAS_BOSS_MODEL", "nemotron")
 os.environ.setdefault("TABRAS_BOSS_MAX_TOKENS", "96")
+os.environ.setdefault("TABRAS_BOSS_TIMEOUT", "120")
 
-# SDXL-Turbo illustrates the cards and the run backgrounds.
-os.environ.setdefault("TABRAS_ART_BACKEND", "diffusers")
-os.environ.setdefault("TABRAS_ART_MODEL", "stabilityai/sdxl-turbo")
+# Art via the Modal SDXL endpoint.
+os.environ.setdefault("TABRAS_ART_BACKEND", "modal")
 os.environ.setdefault("TABRAS_ART_STEPS", "4")
 
 from app import CSS, HEAD, build_app  # noqa: E402  (import after env is configured)
 
-# Module-level `demo` so Hugging Face's launcher can find the Blocks. The CSS/JS
-# are applied via launch() below; that requires the Space to run this file
-# normally (Dev Mode OFF), not Gradio reload mode.
+# Module-level `demo` so Hugging Face's launcher finds the Blocks; css/head are
+# applied via launch() below (keep the Space's Dev Mode off so this runs).
 demo = build_app()
 demo.queue()
 

art.py

@@ -1,8 +1,10 @@
 import base64
+import json
 import threading
 from dataclasses import dataclass, field, replace
 from io import BytesIO
 from typing import Any, Callable, Protocol, Sequence
+from urllib import request
 
 from budget import Card
 from zerogpu import gpu
@@ -13,6 +15,37 @@ NEGATIVE_ART_PROMPT = (
 )
 
 
+@dataclass(frozen=True)
+class ModalArtClient:
+    """Generate card art by calling a Modal SDXL endpoint; returns a data URI."""
+
+    endpoint: str
+    steps: int = 4
+    guidance_scale: float = 0.0
+    width: int = 512
+    height: int = 320
+    timeout_seconds: int = 120
+
+    # POST one prompt to the Modal art endpoint and return its image data URI.
+    def create_art(self, prompt: str) -> str:
+        payload = {
+            "prompt": prompt,
+            "steps": self.steps,
+            "guidance": self.guidance_scale,
+            "width": self.width,
+            "height": self.height,
+            "negative_prompt": NEGATIVE_ART_PROMPT,
+        }
+        req = request.Request(
+            self.endpoint,
+            data=json.dumps(payload).encode("utf-8"),
+            headers={"Content-Type": "application/json"},
+            method="POST",
+        )
+        with request.urlopen(req, timeout=self.timeout_seconds) as response:
+            return str(json.loads(response.read().decode("utf-8"))["image"])
+
+
 class ArtClient(Protocol):
     # Return a browser-renderable image URI for one prompt.
     def create_art(self, prompt: str) -> str:  # pragma: no cover

clients.py

@@ -1,6 +1,6 @@
 import os
 
-from art import ArtClient, DiffusersImageClient, LazyArtClient
+from art import ArtClient, DiffusersImageClient, LazyArtClient, ModalArtClient
 from boss import BossClient, NemotronBossClient
 from generator import CardPackClient, LlamaCppCardClient, MiniCPMCardClient
 from local_llm import (
@@ -107,7 +107,18 @@ def boss_client_from_env() -> BossClient | None:
 # Build an art-generation client from environment variables.
 def art_client_from_env() -> ArtClient | None:
     global _art_client_cache
-    if os.environ.get("TABRAS_ART_BACKEND") != "diffusers":
+    backend = os.environ.get("TABRAS_ART_BACKEND")
+    if backend == "modal":
+        if _art_client_cache is None:
+            _art_client_cache = ModalArtClient(
+                endpoint=os.environ["TABRAS_ART_ENDPOINT"],
+                steps=int(os.environ.get("TABRAS_ART_STEPS", "4")),
+                guidance_scale=float(os.environ.get("TABRAS_ART_GUIDANCE", "0.0")),
+                width=int(os.environ.get("TABRAS_ART_WIDTH", "512")),
+                height=int(os.environ.get("TABRAS_ART_HEIGHT", "320")),
+            )
+        return _art_client_cache
+    if backend != "diffusers":
         return None
     if _art_client_cache is None:
         model_id = os.environ.get("TABRAS_ART_MODEL", DEFAULT_ART_MODEL)

modal_app.py

@@ -0,0 +1,131 @@
+"""Modal GPU endpoints for Tabras: MiniCPM card authoring, Nemotron boss play,
+and SDXL-Turbo art. The Gradio Space calls these over HTTP, so all heavy compute
+runs on dedicated, autoscaled Modal GPUs instead of the Space.
+
+Deploy:  modal deploy modal_app.py
+Then set the printed URLs as Space variables:
+  TABRAS_CARD_ENDPOINT  -> CardModel.chat URL
+  TABRAS_BOSS_ENDPOINT  -> BossModel.chat URL
+  TABRAS_ART_ENDPOINT   -> ArtModel.generate URL
+"""
+
+import modal
+
+CACHE = "/cache"
+hf_cache = modal.Volume.from_name("tabras-hf-cache", create_if_missing=True)
+
+MINICPM = "openbmb/MiniCPM-V-4"
+NEMOTRON = "nvidia/Nemotron-Mini-4B-Instruct"
+SDXL = "stabilityai/sdxl-turbo"
+
+llm_image = (
+    modal.Image.debian_slim(python_version="3.11")
+    .pip_install(
+        "torch", "transformers==4.49.0", "accelerate", "sentencepiece",
+        "torchvision", "einops", "pillow", "fastapi[standard]",
+    )
+    .env({"HF_HOME": CACHE})
+)
+art_image = (
+    modal.Image.debian_slim(python_version="3.11")
+    .pip_install(
+        "torch", "diffusers", "transformers==4.49.0", "accelerate",
+        "safetensors", "pillow", "fastapi[standard]",
+    )
+    .env({"HF_HOME": CACHE})
+)
+
+app = modal.App("tabras-models")
+
+
+# ---- MiniCPM: card authoring (OpenAI-compatible chat) ----
+@app.cls(image=llm_image, gpu="A10G", volumes={CACHE: hf_cache}, min_containers=1, max_containers=2, scaledown_window=600, timeout=600)
+class CardModel:
+    @modal.enter()
+    def load(self) -> None:
+        import torch
+        from transformers import AutoModel, AutoTokenizer
+
+        self.tok = AutoTokenizer.from_pretrained(MINICPM, trust_remote_code=True)
+        self.model = (
+            AutoModel.from_pretrained(MINICPM, trust_remote_code=True, attn_implementation="sdpa", torch_dtype=torch.float16)
+            .eval()
+            .cuda()
+        )
+
+    @modal.fastapi_endpoint(method="POST")
+    def chat(self, item: dict) -> dict:
+        msgs = item.get("messages", [])
+        system = " ".join(m["content"] for m in msgs if m.get("role") == "system")
+        user = " ".join(m["content"] for m in msgs if m.get("role") == "user")
+        temp = float(item.get("temperature", 0.7))
+        text = str(
+            self.model.chat(
+                msgs=[{"role": "user", "content": user}],
+                image=None,
+                tokenizer=self.tok,
+                system_prompt=system,
+                sampling=temp > 0,
+                temperature=max(temp, 0.01),
+                max_new_tokens=int(item.get("max_tokens", 192)),
+            )
+        )
+        return {"choices": [{"message": {"role": "assistant", "content": text}}]}
+
+
+# ---- Nemotron: boss play (OpenAI-compatible chat) ----
+@app.cls(image=llm_image, gpu="A10G", volumes={CACHE: hf_cache}, min_containers=1, max_containers=2, scaledown_window=600, timeout=600)
+class BossModel:
+    @modal.enter()
+    def load(self) -> None:
+        import torch
+        from transformers import AutoModelForCausalLM, AutoTokenizer
+
+        self.tok = AutoTokenizer.from_pretrained(NEMOTRON)
+        self.model = AutoModelForCausalLM.from_pretrained(NEMOTRON, torch_dtype=torch.float16).eval().cuda()
+
+    @modal.fastapi_endpoint(method="POST")
+    def chat(self, item: dict) -> dict:
+        import torch
+
+        msgs = item.get("messages", [])
+        inputs = self.tok.apply_chat_template(msgs, tokenize=True, add_generation_prompt=True, return_tensors="pt").to("cuda")
+        temp = float(item.get("temperature", 0.2))
+        with torch.no_grad():
+            out = self.model.generate(
+                inputs,
+                max_new_tokens=int(item.get("max_tokens", 96)),
+                do_sample=temp > 0,
+                temperature=max(temp, 0.01),
+            )
+        text = self.tok.decode(out[0][inputs.shape[-1]:], skip_special_tokens=True)
+        return {"choices": [{"message": {"role": "assistant", "content": text}}]}
+
+
+# ---- SDXL-Turbo: card art (returns a JPEG data URI) ----
+@app.cls(image=art_image, gpu="A10G", volumes={CACHE: hf_cache}, min_containers=1, max_containers=2, scaledown_window=600, timeout=600)
+class ArtModel:
+    @modal.enter()
+    def load(self) -> None:
+        import torch
+        from diffusers import AutoPipelineForText2Image
+
+        self.pipe = AutoPipelineForText2Image.from_pretrained(SDXL, torch_dtype=torch.float16).to("cuda")
+        self.pipe.set_progress_bar_config(disable=True)
+
+    @modal.fastapi_endpoint(method="POST")
+    def generate(self, item: dict) -> dict:
+        import base64
+        from io import BytesIO
+
+        result = self.pipe(
+            prompt=item["prompt"],
+            num_inference_steps=int(item.get("steps", 4)),
+            guidance_scale=float(item.get("guidance", 0.0)),
+            width=int(item.get("width", 512)),
+            height=int(item.get("height", 320)),
+            negative_prompt=item.get("negative_prompt"),
+        )
+        buffer = BytesIO()
+        result.images[0].save(buffer, format="JPEG", quality=85)
+        return {"image": "data:image/jpeg;base64," + base64.b64encode(buffer.getvalue()).decode("ascii")}

requirements.txt

@@ -1,11 +1 @@
 gradio==6.17.3
-diffusers
-torch
-transformers==4.49.0
-accelerate
-safetensors
-pillow
-sentencepiece
-torchvision
-einops
-spaces