promote ZeroGPU local-first build: Nemotron via llama.cpp + FLUX.2 via diffusers

app.py

@@ -11,6 +11,15 @@ CPU box (no torch/diffusers), consistent with Globe.
 """
 from __future__ import annotations
 
+# IMPORT ORDER MATTERS: `spaces` must be imported BEFORE gradio (and before torch)
+# so it can patch Gradio for ZeroGPU. If gradio loads first, ZeroGPU never
+# initialises and the Space boots then immediately gets SIGTERM ("Shutting down").
+try:
+    import spaces
+    _HAS_SPACES = True
+except Exception:
+    _HAS_SPACES = False
+
 import base64
 import html
 import json
@@ -26,12 +35,32 @@ from fastapi.staticfiles import StaticFiles
 
 from arcana.build import (DECKS_DIR, build_deck, deck_dir, list_decks, load_deck,
                           save_deck, slugify)
+from arcana.llm import get_llm
 from arcana.reader import (SPREADS, card_partial, draw_spread, final_synthesis)
 from arcana.styles import CUSTOM_PLACEHOLDER, STYLE_CHOICES
 
 ROOT = os.path.dirname(os.path.abspath(__file__))
 DEFAULT_THEME = "thermodynamics"
 
+# ---- ZeroGPU (local-first build) ------------------------------------------
+# When LLM/IMAGE backends are local, the heavy work runs on the Space's GPU and
+# must be wrapped in @spaces.GPU. Off-Space (or endpoint mode) @GPU is a no-op.
+LOCAL_GPU = (os.environ.get("LLM_BACKEND", "").lower() == "local"
+             or os.environ.get("IMAGE_BACKEND", "").lower() == "local")
+if _HAS_SPACES:
+    def GPU(duration=120):
+        return spaces.GPU(duration=duration)
+else:
+    def GPU(duration=120):
+        def _deco(fn):
+            return fn
+        return _deco
+
+
+# NOTE: no startup prefetch — downloading the 24GB GGUF in a startup thread made
+# the Space crash on boot (and is unnecessary: the in-@spaces.GPU download path is
+# fast, ~20s). Models load lazily on the first GPU call and cache on disk after.
+
 WELCOME = ("Welcome, traveler. Every world has its hidden archetypes. "
            "Name one, and I shall draw out its fortune.")
 EXAMPLE_THEMES = ["Physics", "Birds", "Lord of the Rings Characters", "Breakfast Foods"]
@@ -45,7 +74,10 @@ def _abs(art_path: str | None):
 
 
 def url_for(art_path: str | None) -> str:
-    return ("/" + art_path) if art_path else ""
+    # Served by Gradio's own static-file route (demo.launch + allowed_paths). This
+    # replaces the FastAPI /decks mount, which is incompatible with ZeroGPU (ZeroGPU
+    # needs gradio's native launch, not a custom uvicorn-mounted app).
+    return f"/gradio_api/file={_abs(art_path)}" if art_path else ""
 
 
 def disp_url(c: dict) -> str:
@@ -58,11 +90,16 @@ def full_url(c: dict) -> str:
     return url_for(c.get("full_path") or c.get("art_path"))
 
 
+with open(os.path.join(ROOT, "frontend", "deckview.html"), encoding="utf-8") as _f:
+    _DECKVIEW_HTML = _f.read()
+
+
 def deck_iframe(deck: dict | None, nonce: int = 0) -> str:
-    """The deck browser — a self-contained coverflow/overhead widget (served at
-    /viewer/deckview.html) embedded in an iframe, with the deck's image URLs +
-    names injected as base64 JSON. All swipe/flip/fade/toggle/lightbox is handled
-    client-side in the widget (smooth, no server round-trips)."""
+    """The deck browser — a self-contained coverflow/overhead widget embedded via an
+    iframe ``srcdoc`` (the whole widget HTML is inlined, with the deck's image URLs +
+    names injected as base64 JSON in a global). Using srcdoc instead of a /viewer
+    static mount keeps everything inside gradio's native server (ZeroGPU-compatible).
+    All swipe/flip/fade/toggle/lightbox is handled client-side in the widget."""
     if not deck or not deck.get("cards"):
         return "<div class='spread-empty'>No deck to show.</div>"
     data = {
@@ -72,8 +109,10 @@ def deck_iframe(deck: dict | None, nonce: int = 0) -> str:
                   for c in deck["cards"]],
     }
     b64 = base64.b64encode(json.dumps(data).encode("utf-8")).decode()
-    src = f"/viewer/deckview.html?d={b64}&n={nonce}"
-    return (f"<iframe src='{html.escape(src)}' title='Deck' "
+    inject = f"<script>window.DECK_B64={json.dumps(b64)};</script>"
+    doc = _DECKVIEW_HTML.replace("</head>", inject + "</head>", 1)
+    srcdoc = html.escape(doc, quote=True)
+    return (f"<iframe srcdoc='{srcdoc}' title='Deck' "
             "style='width:100%;height:74vh;min-height:520px;border:0;display:block;"
             "background:transparent;'></iframe>")
 
@@ -177,36 +216,53 @@ def _next_btn(label: str | None):
     return gr.update(value=label, visible=True) if label else gr.update(visible=False)
 
 
+@GPU(duration=300)
+def _gpu_reading(deck, question, drawn):
+    """Compute ALL card readings + the synthesis in ONE GPU session (the Nemotron
+    GGUF can't be cached across separate ZeroGPU calls). Revealed progressively
+    client-side afterwards. Returns (partials, synthesis)."""
+    llm = get_llm()
+    partials = []
+    for i in range(len(drawn)):
+        try:
+            partials.append(card_partial(deck, question, drawn, i, llm=llm))
+        except Exception:
+            partials.append("")
+    try:
+        synth = final_synthesis(deck, question, drawn, partials, llm=llm)
+    except Exception as e:
+        synth = f"(the synthesis slips away — {type(e).__name__})"
+    return partials, synth
+
+
 def _reveal_card(sess):
-    """Flip the card at sess['i'] into the active area and stream its reading.
-    Yields (stage_html, sess, next_button_update)."""
-    deck, drawn, back, i = sess["deck"], sess["drawn"], sess["back"], sess["i"]
+    """Flip the card at sess['i'] into the active area and reveal its (already
+    computed) reading. Yields (stage_html, sess, next_button_update)."""
+    drawn, back, i = sess["drawn"], sess["back"], sess["i"]
     d, completed = drawn[i], sess["completed"]
     label = "Next card  ▸" if i + 1 < len(drawn) else "Reveal the verdict  ▸"
-    # flip + essence AND Next show immediately — the reader is never stuck waiting
-    # on the model (which can be slow/overloaded); the deeper reading fades in after.
+    # flip + essence show first, then the deeper reading fades in a beat later
     yield _stage(back, completed, active=(d, "", True)), sess, _next_btn(label)
     time.sleep(FLIP_BEAT)
-    try:
-        p = card_partial(deck, sess["question"], drawn, i)
-    except Exception:
-        p = ""  # model unavailable — the essence above stands as the reading
+    p = sess["partials_pre"][i] if i < len(sess.get("partials_pre", [])) else ""
     sess["last_p"] = p
-    sess["partials"].append(p)
     body = _fade(p) if p else ""
     yield _stage(back, completed, active=(d, body, False)), sess, _next_btn(label)
 
 
 def do_draw(deck, question, spread, reversals):
-    """Begin a reading: draw the spread and reveal the first card. From here the
-    reader clicks Next to advance — nothing auto-advances."""
+    """Begin a reading: draw the spread, compute every card's reading on the GPU in
+    one pass, then reveal card by card as the reader clicks Next."""
     if not deck:
         yield "<div class='spread-empty'>Conjure or open a deck first.</div>", None, _next_btn(None)
         return
     drawn = draw_spread(deck, spread=spread, reversals=reversals)
+    yield ("<div class='spread-empty'>…the oracle contemplates the spread…</div>",
+           None, _next_btn(None))
+    partials, synth = _gpu_reading(deck, question, drawn)
     sess = {"deck": deck, "drawn": drawn, "question": question,
             "back": deck.get("back_disp") or deck.get("back_path"), "i": 0, "completed": [],
-            "partials": [], "last_p": "", "phase": "card"}
+            "partials_pre": partials, "synth_pre": synth, "last_p": "", "phase": "card"}
     yield from _reveal_card(sess)
 
 
@@ -230,10 +286,8 @@ def do_next(sess):
     yield (_stage(back, sess["completed"],
                   synth_html="<div class='syn-load'>…the oracle gathers the threads…</div>"),
            sess, _next_btn(None))
-    try:
-        synth = final_synthesis(sess["deck"], sess["question"], sess["drawn"], sess["partials"])
-    except Exception as e:
-        synth = f"(the synthesis slips away — {type(e).__name__})"
+    time.sleep(FLIP_BEAT)
+    synth = sess.get("synth_pre") or "(the synthesis slips away)"
     sess["phase"] = "done"
     yield (_stage(back, sess["completed"],
                   synth_html=f"<h3>✦ The cards together</h3><div class='syn-body'>{_fade(synth)}</div>"),
@@ -254,6 +308,26 @@ def do_conjure(theme, style, custom):
     theme = (theme or "").strip()
     if not theme:
         yield stay("Name a theme to begin."); return
+    deck = None
+    for kind, payload, frac in _gpu_build(theme, style, custom):
+        if kind == "progress":
+            yield stay(f"### ✦ {payload}\n\n**{int(frac * 100)}%** — conjuring *{theme}*")
+        elif kind == "error":
+            yield stay(f"⚠️ The conjuring faltered ({payload}). Try again."); return
+        elif kind == "done":
+            deck = payload
+    if not deck:
+        yield stay("⚠️ The conjuring faltered (no deck). Try again."); return
+    # open the freshly-made deck in the coverflow deck browser
+    yield ("", deck, deck, deck_iframe(deck, _next_nonce()), zip_deck(deck), *show("view"))
+
+
+@GPU(duration=600)
+def _gpu_build(theme, style, custom):
+    """Build the whole deck (local Nemotron mapping + local FLUX.2 art) in ONE GPU
+    session, streaming (kind, payload, frac) progress events. The build runs in a
+    thread so this generator can keep yielding progress; the thread shares the
+    process's attached GPU."""
     st = {"msg": "Consulting the deck designer…", "frac": 0.0,
           "done": False, "deck": None, "err": None}
 
@@ -268,17 +342,13 @@ def do_conjure(theme, style, custom):
 
     threading.Thread(target=run, daemon=True).start()
     while not st["done"]:
-        pct = int(min(st["frac"], 0.99) * 100)
-        yield stay(f"### ✦ {st['msg']}\n\n**{pct}%** — conjuring *{theme}*")
+        yield ("progress", st["msg"], min(st["frac"], 0.99))
         time.sleep(0.4)
-
     if st["err"] or not st["deck"]:
-        why = type(st["err"]).__name__ if st["err"] else "no deck"
-        yield stay(f"⚠️ The conjuring faltered ({why}). Try again."); return
-
-    deck = st["deck"]
-    # open the freshly-made deck in the coverflow deck browser
-    yield ("", deck, deck, deck_iframe(deck, _next_nonce()), zip_deck(deck), *show("view"))
+        why = f"{type(st['err']).__name__}: {st['err']}" if st["err"] else "no deck"
+        yield ("error", why[:300], 0.0)
+    else:
+        yield ("done", st["deck"], 1.0)
 
 
 def toggle_custom(style):
@@ -671,19 +741,16 @@ def build_demo() -> gr.Blocks:
     return demo
 
 
-def build_app() -> FastAPI:
-    app = FastAPI()
-    os.makedirs(DECKS_DIR, exist_ok=True)
-    app.mount("/decks", StaticFiles(directory=DECKS_DIR), name="decks")
-    app.mount("/viewer", StaticFiles(directory=os.path.join(ROOT, "frontend")), name="viewer")
-    demo = build_demo()
-    demo.queue(default_concurrency_limit=4)
-    return gr.mount_gradio_app(app, demo, path="/", css=CSS,
-                               theme=gr.themes.Soft(), ssr_mode=False)
-
-
-app = build_app()
+os.makedirs(DECKS_DIR, exist_ok=True)
+demo = build_demo()
+demo.queue(default_concurrency_limit=4)
 
+# ZeroGPU requires gradio's NATIVE launch — a custom uvicorn-mounted FastAPI app
+# boots then immediately gets SIGTERM (ZeroGPU never registers). Card images are
+# served via gradio's own static-file route (allowed_paths) instead of a /decks
+# mount; the deck-view widget is inlined via iframe srcdoc instead of a /viewer
+# mount. ssr_mode=False (ssr tries to bind a 2nd port and crashes here).
 if __name__ == "__main__":
-    import uvicorn
-    uvicorn.run(app, host="0.0.0.0", port=int(os.environ.get("PORT", 7860)))
+    demo.launch(server_name="0.0.0.0", server_port=int(os.environ.get("PORT", 7860)),
+                allowed_paths=[DECKS_DIR, os.path.join(ROOT, "frontend")],
+                css=CSS, theme=gr.themes.Soft(), ssr_mode=False)

arcana/designer.py

@@ -148,23 +148,30 @@ def design_deck(theme: str, llm: LLM | None = None) -> dict:
     system = designer_system_prompt()
     user = designer_user_prompt(theme)
 
+    # Fresh full generations first — structural slips (a duplicated concept, a
+    # dropped card) are largely random per draw, so re-rolling beats trying to
+    # surgically repair a bad draw (the repair often returns a partial deck).
+    import os as _os
+    attempts = int(_os.environ.get("DESIGN_ATTEMPTS", "4"))
     first_err = None
-    raw = llm.complete(system, user, json_mode=True)
-    try:
-        return validate_deck(extract_json(raw), theme)
-    except DeckError as e:
-        first_err = e
+    for _ in range(attempts):
+        try:
+            raw = llm.complete(system, user, json_mode=True)
+            return validate_deck(extract_json(raw), theme)
+        except DeckError as e:
+            first_err = first_err or e
 
-    # one repair attempt, told exactly what was wrong
+    # last resort: one targeted repair, told exactly what was wrong
     repair = (
         f"{user}\n\nYour previous reply was rejected: {first_err}. "
         "Return ONLY the corrected strict JSON object with exactly 22 cards "
-        "covering arcana 0 through 21, each with non-empty concept, "
-        "justification, upright_meaning, reversed_meaning and art_prompt. "
+        "covering arcana 0 through 21, each with a DISTINCT non-empty concept, "
+        "plus justification, upright_meaning, reversed_meaning and art_prompt. "
         "No prose, no code fences."
     )
     raw2 = llm.complete(system, repair, json_mode=True)
     try:
         return validate_deck(extract_json(raw2), theme)
     except DeckError as e:
-        raise DeckError(f"deck invalid after repair (first: {first_err}) -> {e}") from e
+        raise DeckError(f"deck invalid after {attempts} tries + repair "
+                        f"(first: {first_err}) -> {e}") from e

arcana/gpu_models.py

@@ -0,0 +1,102 @@
+"""On-Space GPU model singletons for the ZeroGPU (local-first) build.
+
+Both heavy models — the Nemotron GGUF (via llama.cpp) and FLUX.2 (via diffusers)
+— are loaded LAZILY and cached process-wide here. They MUST be constructed inside
+an ``@spaces.GPU`` context (that's the only time the GPU is attached on ZeroGPU),
+so nothing here runs at import; the first call from inside a decorated function
+does the load. CUDA must not initialise at import either (the process forks).
+
+Hard-won ZeroGPU facts (June 2026, RTX PRO 6000 Blackwell / CUDA 13 / torch cu130):
+  * llama-cpp-python must be the **cu130** prebuilt wheel; its libllama.so needs
+    the CUDA-13 runtime libs which live under site-packages/nvidia/cu13/lib and
+    are NOT on LD_LIBRARY_PATH — preload them RTLD_GLOBAL before importing llama_cpp.
+  * The Nemotron GGUF reasons unless the assistant turn is seeded with an empty
+    ``<think></think>`` block — so we hand-build a ChatML prompt + create_completion.
+"""
+from __future__ import annotations
+
+import ctypes
+import glob
+import os
+
+# fast, robust multi-connection downloads from the Hub (the 24GB GGUF + FLUX
+# weights crawl at ~8MB/s otherwise). Set before any huggingface_hub import.
+os.environ.setdefault("HF_HUB_ENABLE_HF_TRANSFER", "1")
+
+# ---- model selection (overridable via env) --------------------------------
+# Nemotron via llama.cpp. We use Llama-3.1-Nemotron-Nano-8B (NVIDIA, dense
+# Llama-arch) rather than the 30B-A3B MoE: at Q4 the 30B-MoE reliably left some
+# 'concept' fields EMPTY in the 22-card mapping JSON and took ~5min/deck, whereas
+# the dense 8B follows the structured prompt cleanly and fast. Still a Nemotron
+# model (prize-qualifying) + llama.cpp + local-first.
+LLM_REPO = os.environ.get("LOCAL_LLM_REPO", "bartowski/nvidia_Llama-3.1-Nemotron-Nano-8B-v1-GGUF")
+LLM_FILE = os.environ.get("LOCAL_LLM_FILE", "nvidia_Llama-3.1-Nemotron-Nano-8B-v1-Q4_K_M.gguf")
+IMAGE_MODEL = os.environ.get("LOCAL_IMAGE_MODEL", "black-forest-labs/FLUX.2-klein-base-4B")
+LLM_N_CTX = int(os.environ.get("LOCAL_LLM_N_CTX", "16384"))
+
+_llm = None
+_pipe = None
+_cuda_preloaded = False
+
+
+def _preload_cuda() -> None:
+    """Preload CUDA runtime libs so llama.cpp's CUDA .so can dlopen its deps."""
+    global _cuda_preloaded
+    if _cuda_preloaded:
+        return
+    names = ["libcudart.so.13", "libcublas.so.13", "libcublasLt.so.13",
+             "libcudart.so.12", "libcublas.so.12", "libcublasLt.so.12"]
+    roots = ["/usr/local/lib/python3.10/site-packages",
+             "/usr/local/lib/python3.11/site-packages"]
+    for name in names:
+        for root in roots:
+            hits = glob.glob(f"{root}/nvidia/*/lib/{name}")
+            if hits:
+                try:
+                    ctypes.CDLL(hits[0], mode=ctypes.RTLD_GLOBAL)
+                except OSError:
+                    pass
+                break
+    _cuda_preloaded = True
+
+
+def get_llama():
+    """Lazily load + cache the Nemotron GGUF on the GPU (call inside @spaces.GPU)."""
+    global _llm
+    if _llm is None:
+        _preload_cuda()
+        from huggingface_hub import hf_hub_download
+        from llama_cpp import Llama
+        path = hf_hub_download(LLM_REPO, LLM_FILE, token=os.environ.get("HF_TOKEN"))
+        _llm = Llama(model_path=path, n_gpu_layers=-1, n_ctx=LLM_N_CTX, verbose=False)
+    return _llm
+
+
+def llama_chat(system: str, user: str, json_mode: bool = False,
+               max_tokens: int = 4096, temperature: float = 0.7) -> str:
+    """Generate via create_chat_completion (applies the GGUF's own chat template —
+    correct for the 8B's Llama-3 format). 'detailed thinking off' is Nemotron's
+    control to skip the reasoning trace for clean prose; json_mode adds a JSON
+    grammar (response_format) so the mapping output is always parseable."""
+    llm = get_llama()
+    sysmsg = ("detailed thinking off\n\n" + system) if not json_mode else system
+    kwargs = dict(
+        messages=[{"role": "system", "content": sysmsg},
+                  {"role": "user", "content": user}],
+        max_tokens=max_tokens, temperature=temperature)
+    if json_mode:
+        kwargs["response_format"] = {"type": "json_object"}
+    out = llm.create_chat_completion(**kwargs)
+    return (out["choices"][0]["message"]["content"] or "").strip()
+
+
+def get_pipe():
+    """Lazily load + cache the FLUX.2 pipeline on the GPU (call inside @spaces.GPU)."""
+    global _pipe
+    if _pipe is None:
+        import torch
+        from diffusers import Flux2KleinPipeline
+        _pipe = Flux2KleinPipeline.from_pretrained(
+            IMAGE_MODEL, torch_dtype=torch.bfloat16, token=os.environ.get("HF_TOKEN"))
+        _pipe.to("cuda")
+    return _pipe

arcana/imagegen.py

@@ -91,16 +91,34 @@ class EndpointImageGen:
 
 
 class LocalImageGen:
-    """STRETCH stub — diffusers SDXL/FLUX on a local GPU (SPEC §7, §14)."""
+    """FLUX.2 [klein] on the Space's GPU via diffusers (local-first, §7/§14).
+
+    Generation MUST run inside an ``@spaces.GPU`` context — the pipeline loads on
+    first use (see gpu_models.get_pipe). klein-base-4B is sharp at just 4 steps.
+    """
+
+    def __init__(self, deck_style: str | None = None, size: int = 1024,
+                 steps: int | None = None):
+        self.deck_style = deck_style
+        self.size = int(os.environ.get("IMAGE_SIZE_PX", size))
+        self.steps = int(os.environ.get("IMAGE_STEPS", steps or 4))
 
     def generate(self, prompt: str, seed: int | None = None) -> Image.Image:
-        raise NotImplementedError(
-            "local image backend needs a GPU + diffusers; use the endpoint backend."
-        )
+        import torch
+        from .gpu_models import get_pipe
+        pipe = get_pipe()
+        gen = None
+        if seed is not None:
+            gen = torch.Generator(device="cuda").manual_seed(int(seed))
+        img = pipe(prompt=_style(prompt, self.deck_style),
+                   height=self.size, width=self.size,
+                   num_inference_steps=self.steps, guidance_scale=4.0,
+                   generator=gen).images[0]
+        return img.convert("RGB")
 
 
 def get_imagegen(deck_style: str | None = None) -> ImageGen:
     backend = os.environ.get("IMAGE_BACKEND", "endpoint").lower()
     if backend == "local":
-        return LocalImageGen()
+        return LocalImageGen(deck_style=deck_style)
     return EndpointImageGen(deck_style=deck_style)

arcana/llm.py

@@ -132,19 +132,30 @@ class FallbackLLM:
 
 
 class LocalLLM:
-    """STRETCH stub for a GPU-local Qwen-32B (transformers/vLLM/llama.cpp).
+    """In-process Nemotron GGUF via llama.cpp on the Space's GPU — local-first,
+    llama.cpp badge, and the Nemotron prize all at once. Generation MUST run inside
+    an ``@spaces.GPU`` context (the model loads on first use); see gpu_models.
 
-    Point EndpointLLM at a local OpenAI-compatible server
-    (LLM_BASE_URL=http://127.0.0.1:8080/v1) and that path already works today; a
-    truly in-process backend would slot in here. Unimplemented so v1 doesn't
-    block on GPU access (SPEC §6, §12, §14).
+    json_mode is honoured by nudging the prompt to emit only JSON — designer/
+    loremaster already extract+repair JSON, and the GGUF's reasoning trace is
+    suppressed (gpu_models.llama_complete) so the output starts at the JSON.
     """
 
+    def __init__(self, max_tokens: int = 14000, temperature: float = 0.7):
+        self.model = os.environ.get("LOCAL_LLM_FILE", "Nemotron-3-Nano-30B-A3B (llama.cpp)")
+        self.max_tokens = int(os.environ.get("QWEN_MAX_TOKENS", max_tokens))
+        self.temperature = float(os.environ.get("QWEN_TEMPERATURE", temperature))
+
     def complete(self, system: str, user: str, json_mode: bool = False,
                  timeout: float | None = None) -> str:
-        raise NotImplementedError(
-            "local backend needs a GPU; use LLM_BACKEND=endpoint (default) for dev."
-        )
+        from .gpu_models import llama_chat
+        if json_mode:
+            # mapping: lower temp → fewer duplicate concepts (fewer retries);
+            # cap tokens → no runaway generation (22-card JSON fits in ~7k).
+            return llama_chat(system, user, json_mode=True, max_tokens=10000,
+                              temperature=0.4)
+        return llama_chat(system, user, json_mode=False,
+                          max_tokens=self.max_tokens, temperature=self.temperature)
 
 
 def get_llm() -> LLM:

frontend/deckview.html

@@ -83,8 +83,7 @@
 (function () {
   function parseDeck() {
     try {
-      const u = new URL(window.location.href);
-      const d = u.searchParams.get('d');
+      const d = window.DECK_B64 || new URL(window.location.href).searchParams.get('d');
       if (!d) return {back:'', cards:[]};
       return JSON.parse(decodeURIComponent(escape(atob(d))));
     } catch (e) { return {back:'', cards:[]}; }

requirements.txt

@@ -1,6 +1,22 @@
-gradio==6.14.0
+# Gradio is provided by the Space SDK (do NOT pin it — causes a resolver conflict).
+# torch is preinstalled on ZeroGPU (cu130) — do NOT add it.
+spaces
 openai>=1.40,<3
 fastapi>=0.110
 uvicorn>=0.30
 pillow>=10
 requests>=2.31
+huggingface_hub
+hf_transfer
+
+# LLM — Nemotron GGUF via llama.cpp on the GPU. Install the cu130 prebuilt wheel
+# by DIRECT URL (an --extra-index-url here makes pip backtrack on every other
+# package and the build hangs); the direct ref keeps resolution clean.
+llama_cpp_python @ https://github.com/abetlen/llama-cpp-python/releases/download/v0.3.28-cu130/llama_cpp_python-0.3.28-py3-none-linux_x86_64.whl
+
+# Image — FLUX.2 [klein] via diffusers (Flux2KleinPipeline needs diffusers-from-git)
+git+https://github.com/huggingface/diffusers.git
+transformers
+accelerate
+sentencepiece
+protobuf