space: ZeroGPU port — Gradio SDK runtime, on-Space Warden inference

app.py keeps the custom surface (CRT landing, xterm /play, raw /pty
websocket) and adds: 4-bit on-Space model load when `spaces` is present,
an OpenAI-style /v1/chat/completions SSE endpoint guarded by a per-boot
token (game subprocesses speak the existing api backend at loopback),
and a minimal gr.Blocks engine room at /engine. Frontmatter flips
sdk: docker -> gradio; requirements.txt feeds the Space runtime.
Without `spaces` everything degrades to operator env or scripted.

README.md

@@ -3,8 +3,9 @@ title: SCRYPT
 emoji: 🕯️
 colorFrom: green
 colorTo: gray
-sdk: docker
-app_port: 7860
+sdk: gradio
+python_version: "3.12"
+app_file: space/app.py
 pinned: false
 ---
 

requirements.txt

@@ -0,0 +1,11 @@
+# HF Space (Gradio SDK / ZeroGPU) dependencies. The scrypt package itself is
+# imported from the repo checkout via sys.path — see space/app.py.
+textual>=1.0
+rich>=13.0
+pyyaml>=6.0
+httpx>=0.27
+uvicorn[standard]>=0.30
+torch
+transformers>=4.57
+accelerate
+bitsandbytes

space/app.py

@@ -1,10 +1,10 @@
-"""SCRYPT on the web — a custom frontend riding gradio.Server's backend.
+"""SCRYPT on the web — a custom frontend riding gradio's backend, ZeroGPU brain.
 
 The prize brief: push past the default Gradio look. So Gradio here is the
-*engine room*, not the face. The app IS a `gradio.Server` (a FastAPI app
-with Gradio's machinery available); we drive it with uvicorn so our own
-routes — including a raw PTY websocket Gradio's launcher would refuse —
-take full priority. Nothing of the default Gradio UI is ever rendered.
+*engine room*, not the face. We build our own FastAPI surface (landing page,
+xterm.js terminal, raw PTY websocket) and mount a minimal gr.Blocks at
+/engine — it exists so the ZeroGPU machinery has a Gradio app to hang onto,
+and as a bare smoke-test console for the model.
 
   GET  /            a hand-built Osaka-Jade CRT landing page (static)
   GET  /api/whisper the Warden mutters a line, in voice, so the landing
@@ -13,6 +13,17 @@ take full priority. Nothing of the default Gradio UI is ever rendered.
   WS   /pty         a pseudo-terminal bridge: each visitor gets their own
                     `python -m scrypt.app` subprocess — their own sandbox,
                     their own Warden — streamed to the browser byte for byte
+  POST /v1/chat/completions
+                    OpenAI-style SSE endpoint backed by a @spaces.GPU
+                    generator. Game subprocesses can't hold a ZeroGPU slot
+                    themselves, so they speak the existing `api` backend
+                    protocol at this loopback URL. Guarded by a per-boot
+                    token: visitors can't burn GPU quota directly.
+
+On ZeroGPU the model loads 4-bit at startup (CUDA is emulated until a
+@spaces.GPU call attaches a real slice). Anywhere else — local Docker,
+a laptop — there is no `spaces` package, no model, and the game falls back
+to operator-supplied API env or the scripted Warden. The game never stalls.
 """
 
 from __future__ import annotations
@@ -21,16 +32,101 @@ import asyncio
 import json
 import os
 import random
+import secrets
+import sys
 import tempfile
 from pathlib import Path
+from threading import Thread
+
+REPO_ROOT = Path(__file__).resolve().parent.parent
+if str(REPO_ROOT) not in sys.path:
+    sys.path.insert(0, str(REPO_ROOT))
+
+# ZeroGPU contract: `import spaces` must precede any CUDA-touching import.
+try:
+    import spaces  # noqa: F401  (present on HF Spaces, absent elsewhere)
+except ImportError:
+    spaces = None
 
-from fastapi import WebSocket, WebSocketDisconnect
-from fastapi.responses import FileResponse
+from fastapi import Request, WebSocket, WebSocketDisconnect
+from fastapi.responses import FileResponse, JSONResponse, StreamingResponse
 from fastapi.staticfiles import StaticFiles
 from gradio import Server
 
 STATIC = Path(__file__).parent / "static"
 
+# ------------------------------------------------------------ the Warden brain
+
+MODEL_ID = os.environ.get("WARDEN_MODEL", "nvidia/NVIDIA-Nemotron-3-Nano-30B-A3B-BF16")
+INTERNAL_KEY = os.environ.get("SCRYPT_INTERNAL_KEY") or secrets.token_hex(16)
+
+tok = None
+model = None
+WARDEN_ERR = "spaces package not present (not on a ZeroGPU Space)"
+
+if spaces is not None:
+    try:
+        import torch
+        from transformers import (
+            AutoModelForCausalLM,
+            AutoTokenizer,
+            BitsAndBytesConfig,
+        )
+
+        tok = AutoTokenizer.from_pretrained(MODEL_ID, trust_remote_code=True)
+        # 4-bit fits the `large` (48GB) slice and matches the Q4 GGUF the
+        # local game ships — quality parity, not a downgrade.
+        model = AutoModelForCausalLM.from_pretrained(
+            MODEL_ID,
+            trust_remote_code=True,
+            quantization_config=BitsAndBytesConfig(
+                load_in_4bit=True,
+                bnb_4bit_quant_type="nf4",
+                bnb_4bit_compute_dtype=torch.bfloat16,
+            ),
+            device_map="cuda",
+        )
+        WARDEN_ERR = ""
+    except Exception as err:  # model is optional: the game survives without it
+        WARDEN_ERR = f"{type(err).__name__}: {err}"
+
+WARDEN_READY = not WARDEN_ERR
+
+
+def _generate_stream(messages, max_tokens, temperature, enable_thinking):
+    """Token generator. Wrapped by @spaces.GPU when on a Space."""
+    from transformers import TextIteratorStreamer
+
+    inputs = tok.apply_chat_template(
+        messages,
+        add_generation_prompt=True,
+        return_tensors="pt",
+        enable_thinking=enable_thinking,
+    ).to(model.device)
+    streamer = TextIteratorStreamer(tok, skip_prompt=True, skip_special_tokens=True)
+    thread = Thread(
+        target=model.generate,
+        kwargs=dict(
+            input_ids=inputs,
+            max_new_tokens=max_tokens,
+            do_sample=temperature > 0,
+            temperature=max(temperature, 1e-3),
+            top_p=0.95,
+            streamer=streamer,
+        ),
+        daemon=True,
+    )
+    thread.start()
+    yield from streamer
+
+
+if spaces is not None:
+    # ~1.5K-token prefill + short generations on a 3.5B-active MoE: seconds.
+    _generate_stream = spaces.GPU(duration=90)(_generate_stream)
+
+
+# ----------------------------------------------------------------- the surface
+
 # Curated in-voice teasers for the landing page. Scripted on purpose: the
 # greeter must never cost an API call or wake the model.
 WHISPERS = [
@@ -65,17 +161,58 @@ def play() -> FileResponse:
     return FileResponse(STATIC / "play.html")
 
 
+# ------------------------------------------------- the loopback inference API
+
+
+@app.post("/v1/chat/completions")
+async def chat_completions(request: Request):
+    """OpenAI-compatible SSE, just enough for scrypt.inference.api. Only the
+    game's own subprocesses hold the per-boot bearer; everyone else gets 401
+    rather than a lever on our GPU quota."""
+    if request.headers.get("authorization") != f"Bearer {INTERNAL_KEY}":
+        return JSONResponse({"error": "unauthorized"}, status_code=401)
+    if not WARDEN_READY:
+        return JSONResponse({"error": f"warden offline: {WARDEN_ERR}"}, status_code=503)
+
+    body = await request.json()
+    messages = body.get("messages", [])
+    max_tokens = int(body.get("max_tokens", 256))
+    temperature = float(body.get("temperature", 0.6))
+    thinking = bool(body.get("chat_template_kwargs", {}).get("enable_thinking", False))
+
+    def sse():
+        for chunk in _generate_stream(messages, max_tokens, temperature, thinking):
+            payload = {"choices": [{"delta": {"content": chunk}}]}
+            yield f"data: {json.dumps(payload)}\n\n"
+        yield "data: [DONE]\n\n"
+
+    return StreamingResponse(sse(), media_type="text/event-stream")
+
+
 # ----------------------------------------------------------- the PTY bridge
 
-GAME_ENV = {
-    "TERM": "xterm-256color",
-    "COLORTERM": "truecolor",
-    "PYTHONUNBUFFERED": "1",
-    # The cloud Warden talks over the API; the Space secret carries the key.
-    # No key -> the game falls back to scripted lines and says so. Sandboxes
-    # are always fabricated here; a hosted box never mirrors a real home.
-    "SCRYPT_BACKEND": os.environ.get("SCRYPT_BACKEND", "api"),
-}
+
+def game_env() -> dict:
+    """Environment for one visitor's game process. Sandboxes are always
+    fabricated here; a hosted box never mirrors a real home."""
+    env = {
+        "TERM": "xterm-256color",
+        "COLORTERM": "truecolor",
+        "PYTHONUNBUFFERED": "1",
+        "PYTHONPATH": str(REPO_ROOT),
+    }
+    if WARDEN_READY:
+        env |= {
+            "SCRYPT_BACKEND": "api",
+            "SCRYPT_API_BASE": "http://127.0.0.1:7860/v1",
+            "SCRYPT_API_KEY": INTERNAL_KEY,
+            "SCRYPT_MODEL": MODEL_ID,
+        }
+    elif os.environ.get("SCRYPT_API_KEY"):
+        env["SCRYPT_BACKEND"] = os.environ.get("SCRYPT_BACKEND", "api")
+    else:
+        env["SCRYPT_BACKEND"] = "scripted"
+    return env
 
 
 async def _pump_pty_to_ws(master_fd: int, ws: WebSocket) -> None:
@@ -104,7 +241,7 @@ async def pty_bridge(ws: WebSocket) -> None:
     home = tempfile.mkdtemp(prefix="scrypt-")
     pid, master_fd = pty.fork()
     if pid == 0:  # child: become the game
-        env = {**os.environ, **GAME_ENV, "SCRYPT_HOME": home}
+        env = {**os.environ, **game_env(), "SCRYPT_HOME": home}
         os.execvpe("python", ["python", "-m", "scrypt.app"], env)
         os._exit(127)  # unreachable unless exec fails
 
@@ -144,6 +281,39 @@ async def pty_bridge(ws: WebSocket) -> None:
 app.mount("/static", StaticFiles(directory=STATIC), name="static")
 
 
+# ------------------------------------------------------------ the engine room
+
+import gradio as gr  # noqa: E402
+
+
+def _probe(text: str):
+    """Manual smoke test: one message in, the Warden's line streamed back."""
+    if not WARDEN_READY:
+        yield f"warden offline: {WARDEN_ERR}"
+        return
+    acc = ""
+    for chunk in _generate_stream(
+        [{"role": "user", "content": text}], 80, 0.6, False
+    ):
+        acc += chunk
+        yield acc
+
+
+with gr.Blocks(title="SCRYPT engine room") as engine:
+    gr.Markdown(
+        "# SCRYPT engine room\n"
+        f"model: `{MODEL_ID}`\n\n"
+        f"status: {'**ready**' if WARDEN_READY else f'offline — {WARDEN_ERR}'}\n\n"
+        "The game lives at [/](/) — this page only exists to keep the "
+        "machinery warm and let us poke the model directly."
+    )
+    box = gr.Textbox(label="say something to the Warden")
+    out = gr.Textbox(label="the Warden")
+    box.submit(_probe, box, out)
+
+gr.mount_gradio_app(app, engine, path="/engine")
+
+
 if __name__ == "__main__":
     import uvicorn