Deploy deathmatch from be2cd11

README.md

@@ -0,0 +1,40 @@
+---
+title: Celebrity Deathmatch
+emoji: 🥊
+colorFrom: red
+colorTo: yellow
+sdk: gradio
+sdk_version: "6.0.0"
+app_file: app.py
+pinned: false
+---
+
+# Celebrity Deathmatch
+
+Upload two photos, and an AI ring director books an MTV-style claymation brawl:
+a fight script with round-by-round announcer commentary, a rendered keyframe
+reel, a declared winner — and an optional **Animate** button that chains it into
+one continuous fight video with the commentary burned in as captions.
+
+> ⚠ **Parody.** All visuals are AI-generated claymation caricatures of public
+> figures, for comedic effect. Not real.
+
+## Models
+
+| Stage | Role | Model | GPU |
+|------|------|-------|-----|
+| 1 | Fight director (reads both photos) | MiniCPM-V-2_6 (OpenBMB) | A10G |
+| 2 | Claymation keyframes | FLUX.1-schnell (BFL) | L40S |
+| 3 | Image→video fight clip (opt-in) | LTX-Video (Lightricks) | H100 |
+
+## Architecture
+
+- **Frontend:** this Gradio Space.
+- **Backend:** Modal GPU app `deathmatch` — set `DEATHMATCH_API_URL` (the deploy
+  pipeline does this automatically).
+- **Mock mode:** run locally with `DEATHMATCH_MOCK=1` to exercise the full UX on
+  CPU (canned fight, placeholder frames, GIF stand-in for the video).
+
+```sh
+DEATHMATCH_MOCK=1 python app.py
+```

app.py

@@ -0,0 +1,253 @@
+"""Celebrity Deathmatch — Gradio frontend (HuggingFace Space).
+
+Upload two fighters -> FIGHT! runs Stage 1 (fight script) + Stage 2 (keyframe reel).
+The opt-in "Animate" button runs Stage 3 (chained, captioned fight video).
+Runs fully on CPU with DEATHMATCH_MOCK=1 (canned fight, placeholder frames).
+"""
+from __future__ import annotations
+
+import json
+import os
+import tempfile
+
+import gradio as gr
+
+from model_runtime import (
+    API_URL, MOCK, BackendError, animate, generate_fightcard,
+    generate_keyframes, health,
+)
+
+ARENAS = [
+    "Classic Deathmatch ring", "Rooftop at night", "Abandoned shopping mall",
+    "Volcano lair", "Suburban backyard", "Neon Tokyo street",
+]
+STYLES = ["Claymation", "Stop-motion", "Cartoon", "Comic book"]
+
+CSS = """
+@import url('https://fonts.googleapis.com/css2?family=Anton&family=DM+Sans:wght@400;600;800&family=JetBrains+Mono:wght@600&display=swap');
+:root {
+    --dm-bg: #0b0608; --dm-panel: rgba(24,12,16,0.86); --dm-red: #e0303c;
+    --dm-gold: #f2b030; --dm-text: #f4ede0; --dm-muted: #b09088;
+}
+body, .gradio-container {
+    background:
+        radial-gradient(circle at 15% 8%, rgba(224,48,60,0.18), transparent 32%),
+        radial-gradient(circle at 85% 4%, rgba(242,176,48,0.12), transparent 34%),
+        linear-gradient(160deg, #0b0608 0%, #140a0d 60%, #1c0e12 100%) !important;
+    color: var(--dm-text) !important; font-family: 'DM Sans', sans-serif !important;
+}
+.gradio-container { max-width: 1180px !important; margin: 0 auto !important; padding: 22px 20px 44px !important; }
+.dm-disclaimer {
+    margin: 0 0 16px; padding: 9px 14px; border: 1px dashed rgba(242,176,48,0.45);
+    border-radius: 12px; background: rgba(242,176,48,0.07); color: var(--dm-gold);
+    font-family: 'JetBrains Mono', monospace; font-size: 11.5px; letter-spacing: 0.04em; text-align: center;
+}
+.dm-hero {
+    position: relative; overflow: hidden; padding: 30px 32px; border-radius: 26px;
+    border: 1px solid rgba(224,48,60,0.3);
+    background: linear-gradient(120deg, rgba(28,12,16,0.95), rgba(12,6,8,0.9)),
+                radial-gradient(circle at 88% 20%, rgba(224,48,60,0.28), transparent 40%);
+    box-shadow: 0 22px 80px rgba(0,0,0,0.5);
+}
+.dm-hero h1 {
+    margin: 0; font-family: 'Anton', sans-serif; font-size: clamp(46px, 8vw, 92px);
+    line-height: 0.9; letter-spacing: 0.01em; text-transform: uppercase;
+    background: linear-gradient(90deg, #ffd27a, var(--dm-red) 60%, #ff5060);
+    -webkit-background-clip: text; -webkit-text-fill-color: transparent;
+}
+.dm-hero p { margin: 12px 0 0; color: var(--dm-muted); font-size: 16px; max-width: 640px; }
+.dm-status {
+    margin: 14px 0 4px; padding: 11px 14px; border-radius: 14px; font-size: 12px;
+    font-family: 'JetBrains Mono', monospace; border: 1px solid rgba(255,255,255,0.1);
+    background: rgba(10,6,8,0.7); color: var(--dm-muted);
+}
+.dm-status.ok { border-color: rgba(60,200,110,0.4); }
+.dm-status.mock { border-color: rgba(242,176,48,0.45); color: var(--dm-gold); }
+.dm-status.fail { border-color: rgba(224,48,60,0.5); color: #ff8a8a; }
+.tape { display: grid; grid-template-columns: 1fr auto 1fr; gap: 14px; align-items: stretch; margin-top: 6px; }
+.tape-card {
+    padding: 18px; border-radius: 20px; border: 1px solid rgba(255,255,255,0.09);
+    background: var(--dm-panel); box-shadow: 0 14px 44px rgba(0,0,0,0.34);
+}
+.tape-card.b { border-color: rgba(64,160,200,0.28); }
+.tape-card .nm { font-family: 'Anton', sans-serif; font-size: 30px; text-transform: uppercase; color: var(--dm-text); }
+.tape-card .tag { color: var(--dm-muted); font-size: 13px; margin: 6px 0 14px; }
+.tape-card .mv { color: var(--dm-gold); font-size: 13px; font-family: 'JetBrains Mono', monospace; margin-bottom: 14px; }
+.statrow { display:flex; align-items:center; gap:10px; margin:7px 0; font-size:11px; font-family:'JetBrains Mono',monospace; color:var(--dm-muted); }
+.statrow .lab { width: 96px; text-transform: uppercase; }
+.bar { flex:1; height:9px; border-radius:99px; background: rgba(255,255,255,0.08); overflow:hidden; }
+.bar > span { display:block; height:100%; background: linear-gradient(90deg, var(--dm-gold), var(--dm-red)); }
+.vs { display:flex; align-items:center; font-family:'Anton',sans-serif; font-size:40px; color:var(--dm-red); }
+.winner-banner {
+    margin-top: 4px; padding: 22px; border-radius: 22px; text-align: center;
+    border: 1px solid rgba(242,176,48,0.5);
+    background: radial-gradient(circle at 50% 0%, rgba(242,176,48,0.22), transparent 60%), var(--dm-panel);
+}
+.winner-banner .w { font-family:'Anton',sans-serif; font-size: 56px; text-transform: uppercase;
+    background: linear-gradient(90deg,#ffd27a,var(--dm-red)); -webkit-background-clip:text; -webkit-text-fill-color:transparent; }
+.winner-banner .r { color: var(--dm-muted); font-size: 14px; margin-top: 6px; }
+button.primary, .dm-primary button {
+    border: 0 !important; border-radius: 999px !important;
+    background: linear-gradient(135deg, #ffd27a, var(--dm-red) 55%, #a01820) !important;
+    color: #1a0608 !important; font-family:'Anton',sans-serif !important; letter-spacing:0.06em !important;
+    font-size: 18px !important; text-transform: uppercase !important;
+    box-shadow: 0 14px 40px rgba(224,48,60,0.32) !important;
+}
+.dm-commentary { padding: 16px 18px; border-radius: 18px; border: 1px solid rgba(255,255,255,0.08); background: var(--dm-panel); }
+label, .block label { color: var(--dm-muted) !important; font-family:'JetBrains Mono',monospace !important;
+    font-size: 11px !important; letter-spacing: 0.07em !important; text-transform: uppercase !important; }
+"""
+
+
+def _hero() -> str:
+    return ("<section class='dm-hero'><h1>Celebrity<br>Deathmatch</h1>"
+            "<p>Upload two fighters. Our AI ring director books the brawl, "
+            "renders the claymation reel, and crowns a winner. Then hit "
+            "<b>Animate</b> for the full fight.</p></section>")
+
+
+def _status() -> str:
+    h = health()
+    s = h.get("status")
+    if s == "mock":
+        return ("<div class='dm-status mock'>● MOCK MODE — canned fight, no GPU. "
+                "Set DEATHMATCH_MOCK=0 + deploy Modal for real models.</div>")
+    if s == "ok":
+        return (f"<div class='dm-status ok'>● BACKEND ONLINE / {h.get('stage1','?')} / "
+                f"{h.get('stage2','?')}</div>")
+    return (f"<div class='dm-status fail'>● BACKEND UNREACHABLE / {API_URL} / "
+            "deploy Modal or run with DEATHMATCH_MOCK=1</div>")
+
+
+def _statbar(label: str, value: int) -> str:
+    pct = max(0, min(100, int(value) * 10))
+    return (f"<div class='statrow'><span class='lab'>{label}</span>"
+            f"<span class='bar'><span style='width:{pct}%'></span></span>"
+            f"<span>{int(value)}/10</span></div>")
+
+
+def _fighter_card(f: dict, side: str) -> str:
+    stats = f.get("stats", {})
+    bars = "".join(_statbar(k, stats.get(k, 5)) for k in ("power", "speed", "showmanship"))
+    return (f"<div class='tape-card {side}'>"
+            f"<div class='nm'>{f.get('name','?')}</div>"
+            f"<div class='tag'>{f.get('persona','')}</div>"
+            f"<div class='mv'>★ {f.get('signature_move','')}</div>"
+            f"{bars}</div>")
+
+
+def _tale_html(card: dict) -> str:
+    return ("<div class='tape'>"
+            + _fighter_card(card["fighter_a"], "a")
+            + "<div class='vs'>VS</div>"
+            + _fighter_card(card["fighter_b"], "b")
+            + "</div>")
+
+
+def _commentary_md(card: dict) -> str:
+    lines = ["### Ringside commentary"]
+    for beat in card["beats"]:
+        lines.append(f"**Round {beat['id']} — {beat['title']}**  \n"
+                     f"_{beat['commentary']}_")
+    return "\n\n".join(lines)
+
+
+def _winner_html(card: dict) -> str:
+    w = card["fighter_a"] if str(card.get("winner", "A")).upper() == "A" else card["fighter_b"]
+    return (f"<div class='winner-banner'><div style='font-family:JetBrains Mono;color:#b09088;"
+            f"font-size:12px;letter-spacing:0.2em'>WINNER BY KNOCKOUT</div>"
+            f"<div class='w'>{w.get('name','?')}</div>"
+            f"<div class='r'>{card.get('winner_reason','')}</div></div>")
+
+
+def run_fight(image_a, image_b, storyline, arena, style):
+    if image_a is None or image_b is None:
+        raise gr.Error("Upload a photo for BOTH fighters first.")
+    try:
+        card = generate_fightcard(image_a, image_b, storyline, arena, style)
+        frames = generate_keyframes(card, style)
+    except (RuntimeError, BackendError) as e:
+        raise gr.Error(f"Fight booking failed: {e}")
+    gallery = [(img, f"Round {beat['id']}: {beat['title']}")
+               for img, beat in zip(frames, card["beats"])]
+    return (card, frames, _tale_html(card), gallery, _commentary_md(card),
+            gr.update(interactive=True), gr.update(selected="brawl"))
+
+
+def run_animate(card, frames, style):
+    if not card or not frames:
+        raise gr.Error("Book a fight first (press FIGHT!).")
+    try:
+        path = animate(card, frames, style)
+    except (RuntimeError, BackendError) as e:
+        raise gr.Error(f"Animation failed: {e}")
+    return path, _winner_html(card), gr.update(selected="knockout")
+
+
+def export_card(card):
+    if not card:
+        raise gr.Error("Nothing to export yet.")
+    fd, path = tempfile.mkstemp(prefix="deathmatch_fightcard_", suffix=".json")
+    with os.fdopen(fd, "w") as f:
+        json.dump(card, f, indent=2, ensure_ascii=False)
+    return path
+
+
+with gr.Blocks(title="Celebrity Deathmatch") as demo:
+    gr.HTML("<div class='dm-disclaimer'>⚠ PARODY — AI-generated claymation caricatures "
+            "of public figures for comedic effect. Not real. No real people were harmed.</div>")
+    gr.HTML(_hero())
+    gr.HTML(_status())
+
+    card_state = gr.State(None)
+    frames_state = gr.State(None)
+
+    with gr.Tabs(selected="tape") as tabs:
+        with gr.Tab("01 Tale of the Tape", id="tape"):
+            with gr.Row():
+                img_a = gr.Image(label="Fighter A", type="pil")
+                img_b = gr.Image(label="Fighter B", type="pil")
+            with gr.Row():
+                storyline = gr.Textbox(label="Backstory / beef (optional)", max_lines=2,
+                                       placeholder="e.g. They feuded over a sampled hook")
+                arena = gr.Dropdown(ARENAS, value=ARENAS[0], label="Arena")
+                style = gr.Dropdown(STYLES, value=STYLES[0], label="Visual style")
+            fight_btn = gr.Button("FIGHT!", variant="primary", elem_classes=["dm-primary"])
+            tale = gr.HTML()
+
+        with gr.Tab("02 The Brawl", id="brawl"):
+            gr.Markdown("### The keyframe reel")
+            reel = gr.Gallery(label="Fight reel", columns=5, height=320,
+                              object_fit="cover")
+            commentary = gr.Markdown()
+            animate_btn = gr.Button("🎬 Animate the full fight", variant="primary",
+                                    interactive=False, elem_classes=["dm-primary"])
+            gr.Markdown("_Animate chains the keyframes into one continuous, "
+                        "caption-burned fight clip (Stage 3 — opt-in, GPU-heavy)._")
+
+        with gr.Tab("03 Knockout", id="knockout"):
+            winner = gr.HTML()
+            fight_video = gr.Video(label="The fight", autoplay=True)
+            export_btn = gr.Button("Download fight card (JSON)")
+            export_file = gr.File(label="Fight card")
+
+    fight_btn.click(
+        run_fight, [img_a, img_b, storyline, arena, style],
+        [card_state, frames_state, tale, reel, commentary, animate_btn, tabs],
+    )
+    animate_btn.click(
+        run_animate, [card_state, frames_state, style],
+        [fight_video, winner, tabs],
+    )
+    export_btn.click(export_card, [card_state], [export_file])
+
+    demo_a = os.path.join(os.path.dirname(__file__), "examples", "fighter_a.png")
+    demo_b = os.path.join(os.path.dirname(__file__), "examples", "fighter_b.png")
+    if os.path.exists(demo_a) and os.path.exists(demo_b):
+        gr.Examples(examples=[[demo_a, demo_b, "", ARENAS[0], STYLES[0]]],
+                    inputs=[img_a, img_b, storyline, arena, style],
+                    label="Try a demo matchup")
+
+
+if __name__ == "__main__":
+    demo.launch(max_file_size="10mb", ssr_mode=False, css=CSS)

mock.py

@@ -0,0 +1,162 @@
+"""Celebrity Deathmatch — mock data + CPU placeholder renderers (DEATHMATCH_MOCK=1).
+
+Lets the whole UX run on CPU in seconds with no backend: a canned fight card,
+labelled placeholder keyframes, and a mock "fight video" (animated GIF cycling
+the keyframes with commentary captions burned in — proving the captions decision).
+Real models swap in behind the same model_runtime signatures.
+"""
+from __future__ import annotations
+
+import os
+import tempfile
+import textwrap
+
+from PIL import Image, ImageDraw, ImageFont
+
+# Canned Stage-1 output — the marquee matchup. Same shape as the backend FightCard.
+MOCK_FIGHTCARD = {
+    "fighter_a": {
+        "name": "Britney Spears",
+        "appearance": "blonde clay figure with a high ponytail, sparkly red bodysuit, "
+                      "headset microphone, confident pop-diva pose",
+        "persona": "Unbothered pop royalty who turns every hit into choreography",
+        "signature_move": "The Toxic Spin Kick",
+        "stats": {"power": 6, "speed": 9, "showmanship": 10},
+    },
+    "fighter_b": {
+        "name": "Eminem",
+        "appearance": "lanky clay figure with bleached buzzcut, white tank top, baggy jeans, "
+                      "permanent scowl, fists raised",
+        "persona": "Rapid-fire trash-talker who fights to a 140 BPM flow",
+        "signature_move": "The Rap God Combo",
+        "stats": {"power": 8, "speed": 8, "showmanship": 7},
+    },
+    "arena": "Classic Deathmatch ring",
+    "beats": [
+        {"id": 1, "title": "The stare-down / entrances",
+         "action": "Britney moonwalks into the ring under a glitter cannon while Eminem "
+                   "stomps in from the opposite corner, cracking his clay knuckles",
+         "commentary": "Welcome to Deathmatch! Pop royalty versus the Rap God — "
+                       "and the glitter is already in Slim's eyes, Johnny!",
+         "video_prompt": "two clay fighters enter a wrestling ring, glitter falling, slow zoom"},
+        {"id": 2, "title": "First blood",
+         "action": "Eminem fires off a flurry of word-bullet punches; Britney back-flips "
+                   "away and flicks her ponytail like a whip",
+         "commentary": "Ohh! Rapid-fire jabs from Eminem — but Britney's ponytail "
+                       "snaps back like a bullwhip! That's gotta sting!",
+         "video_prompt": "fast punches, clay fighter dodges with a backflip, motion blur"},
+        {"id": 3, "title": "Signature move",
+         "action": "Britney launches the Toxic Spin Kick, a neon-green tornado of legs "
+                   "that sends Eminem bouncing off the ropes",
+         "commentary": "THE TOXIC SPIN KICK! It's a green tornado of doom, Nick! "
+                       "Slim Shady is ping-ponging off the ropes!",
+         "video_prompt": "spinning kick, green energy tornado, opponent flung into ropes"},
+        {"id": 4, "title": "Comeback / turning point",
+         "action": "Eminem shakes it off and unleashes the Rap God Combo — fists moving "
+                   "so fast they blur into a clay smear",
+         "commentary": "But here comes the Rap God Combo! His hands are a BLUR! "
+                       "Britney's tiara just got rearranged!",
+         "video_prompt": "blurred rapid punch combo, clay smear trails, dramatic angle"},
+        {"id": 5, "title": "Finishing move + KO",
+         "action": "Britney counters mid-combo, drops the beat AND Eminem with one final "
+                   "spin, then strikes a victory pose on his flattened clay body",
+         "commentary": "She drops the beat — and drops EMINEM! It's all over! "
+                       "Britney Spears wins the Deathmatch!",
+         "video_prompt": "final spin counter, opponent flattened, victory pose, confetti"},
+    ],
+    "winner": "A",
+    "winner_reason": "Britney's showmanship and speed turned every hit into a dance "
+                     "finale — Eminem never found the off-beat.",
+}
+
+_PALETTE = [
+    (210, 60, 70), (240, 160, 48), (64, 160, 200), (120, 90, 200), (60, 170, 110),
+]
+
+
+def _font(size: int):
+    for path in (
+        "/usr/share/fonts/truetype/dejavu/DejaVuSans-Bold.ttf",
+        "/usr/share/fonts/truetype/dejavu/DejaVuSans.ttf",
+    ):
+        if os.path.exists(path):
+            return ImageFont.truetype(path, size)
+    try:
+        return ImageFont.load_default(size)  # Pillow >= 10
+    except TypeError:
+        return ImageFont.load_default()
+
+
+def _wrap(draw, text, font, max_w):
+    words, lines, cur = text.split(), [], ""
+    for w in words:
+        trial = f"{cur} {w}".strip()
+        if draw.textlength(trial, font=font) <= max_w:
+            cur = trial
+        else:
+            if cur:
+                lines.append(cur)
+            cur = w
+    if cur:
+        lines.append(cur)
+    return lines
+
+
+def placeholder_keyframe(card: dict, beat: dict, size=(1024, 576)) -> Image.Image:
+    """A labelled placeholder panel standing in for a FLUX render."""
+    w, h = size
+    idx = (beat["id"] - 1) % len(_PALETTE)
+    base = _PALETTE[idx]
+    img = Image.new("RGB", size, base)
+    draw = ImageDraw.Draw(img)
+
+    # Vignette-ish darkening band at the bottom for caption legibility.
+    draw.rectangle([0, h - 150, w, h], fill=(0, 0, 0))
+
+    title_f = _font(40)
+    body_f = _font(26)
+    small_f = _font(20)
+
+    a = card["fighter_a"]["name"]
+    b = card["fighter_b"]["name"]
+    draw.text((36, 28), f"ROUND {beat['id']}", font=_font(24), fill=(255, 255, 255))
+    draw.text((36, 60), f"{a}  vs  {b}", font=title_f, fill=(255, 255, 255))
+
+    for i, line in enumerate(_wrap(draw, beat["action"], body_f, w - 72)[:4]):
+        draw.text((36, 150 + i * 34), line, font=body_f, fill=(245, 245, 245))
+
+    for i, line in enumerate(_wrap(draw, beat["commentary"], small_f, w - 72)[:3]):
+        draw.text((36, h - 140 + i * 26), line, font=small_f, fill=(255, 220, 120))
+
+    draw.text((w - 150, 28), "MOCK", font=_font(28), fill=(255, 255, 255))
+    return img
+
+
+def placeholder_reel(card: dict, size=(1024, 576)) -> list[Image.Image]:
+    return [placeholder_keyframe(card, beat, size) for beat in card["beats"]]
+
+
+def mock_fight_video(frames: list[Image.Image], seconds_per_beat: float = 1.6,
+                     fps: int = 24) -> str:
+    """Stitch keyframes into an MP4 — the mock stand-in for the LTX fight video.
+
+    Commentary is already drawn onto each placeholder frame, so this mirrors the
+    real Stage-3 output type (an MP4 for gr.Video) without a GPU. Real mode swaps
+    in the chained, caption-burned clip from the deathmatch-video service.
+    """
+    import imageio.v2 as imageio
+    import numpy as np
+
+    fd, path = tempfile.mkstemp(prefix="deathmatch_mock_", suffix=".mp4")
+    os.close(fd)
+    reps = max(1, int(seconds_per_beat * fps))
+    writer = imageio.get_writer(path, fps=fps, codec="libx264",
+                                macro_block_size=8)
+    try:
+        for f in frames:
+            arr = np.asarray(f.convert("RGB"))
+            for _ in range(reps):
+                writer.append_data(arr)
+    finally:
+        writer.close()
+    return path

model_runtime.py

@@ -0,0 +1,118 @@
+"""Celebrity Deathmatch — runtime client.
+
+Talks to the Modal backend (modal.App("deathmatch")) over HTTP, OR serves canned
+data when DEATHMATCH_MOCK is set — same function signatures either way, so the UI
+never branches on mode. The HF Space deploy injects DEATHMATCH_API_URL.
+"""
+from __future__ import annotations
+
+import base64
+import io
+import os
+import tempfile
+
+import httpx
+
+API_URL = os.environ.get(
+    "DEATHMATCH_API_URL",
+    "https://rafalbogusdxc--deathmatch-api.modal.run",
+).rstrip("/")
+
+MOCK = os.environ.get("DEATHMATCH_MOCK", "").strip().lower() in ("1", "true", "yes", "on")
+
+TIMEOUT_S = 900
+
+
+class BackendError(RuntimeError):
+    """Inference backend unreachable or returned an error."""
+
+
+def _pil_to_b64(img) -> str:
+    buf = io.BytesIO()
+    img.convert("RGB").save(buf, format="PNG")
+    return base64.b64encode(buf.getvalue()).decode()
+
+
+def _b64_to_pil(data: str):
+    from PIL import Image
+    return Image.open(io.BytesIO(base64.b64decode(data))).convert("RGB")
+
+
+def _post(path: str, payload: dict, timeout: float = TIMEOUT_S) -> dict:
+    url = f"{API_URL}{path}"
+    try:
+        resp = httpx.post(url, json=payload, timeout=timeout, follow_redirects=True)
+        resp.raise_for_status()
+        return resp.json()
+    except httpx.ConnectError as e:
+        raise BackendError(
+            f"Cannot reach the Deathmatch backend at {API_URL} — is the Modal app "
+            f"deployed? ({e})"
+        ) from e
+    except httpx.ReadTimeout as e:
+        raise BackendError(
+            "Backend timed out — likely a GPU cold start pulling weights. "
+            "Try again in ~1 minute."
+        ) from e
+    except httpx.HTTPStatusError as e:
+        raise BackendError(
+            f"Backend error {e.response.status_code}: {e.response.text[:300]}"
+        ) from e
+
+
+def health() -> dict:
+    if MOCK:
+        return {"status": "mock", "service": "deathmatch (mock mode — no GPU)"}
+    try:
+        resp = httpx.get(f"{API_URL}/health", timeout=10, follow_redirects=True)
+        resp.raise_for_status()
+        return resp.json()
+    except Exception as e:  # noqa: BLE001 — banner only, never crash the UI
+        return {"status": "unreachable", "error": str(e), "url": API_URL}
+
+
+def generate_fightcard(image_a, image_b, storyline: str, arena: str, style: str) -> dict:
+    """Stage 1 — two photos -> validated fight card dict."""
+    if MOCK:
+        import copy
+        from mock import MOCK_FIGHTCARD
+        card = copy.deepcopy(MOCK_FIGHTCARD)
+        card["arena"] = arena or card["arena"]
+        return card
+    data = _post("/fightcard", {
+        "image_a_b64": _pil_to_b64(image_a),
+        "image_b_b64": _pil_to_b64(image_b),
+        "storyline": (storyline or "")[:500],
+        "arena": arena,
+        "style": style,
+    })
+    return data["fightcard"]
+
+
+def generate_keyframes(card: dict, style: str, aspect: str = "16:9") -> list:
+    """Stage 2 — fight card -> list of 5 keyframe PIL images."""
+    if MOCK:
+        from mock import placeholder_reel
+        return placeholder_reel(card)
+    data = _post("/keyframes", {"fightcard": card, "style": style, "aspect": aspect})
+    return [_b64_to_pil(b) for b in data["images_b64"]]
+
+
+def animate(card: dict, keyframes: list, style: str) -> str:
+    """Stage 3 — keyframes -> one chained, captioned fight clip. Returns a file path.
+
+    Mock: an animated GIF cycling the keyframes with captions burned in.
+    Real: an MP4 from LTX-Video (Slice 4) written to a temp file.
+    """
+    if MOCK:
+        from mock import mock_fight_video
+        return mock_fight_video(keyframes)
+    data = _post("/animate", {
+        "fightcard": card,
+        "keyframes_b64": [_pil_to_b64(f) for f in keyframes],
+        "style": style,
+    })
+    fd, path = tempfile.mkstemp(prefix="deathmatch_", suffix=".mp4")
+    os.write(fd, base64.b64decode(data["video_b64"]))
+    os.close(fd)
+    return path

requirements.txt

@@ -0,0 +1,4 @@
+gradio>=6.0
+httpx>=0.27
+Pillow>=10.0
+imageio[ffmpeg]>=2.34