Deploy doodle-decoder

Dockerfile

@@ -0,0 +1,9 @@
+FROM python:3.12-slim
+RUN useradd -m -u 1000 user
+WORKDIR /home/user/app
+COPY --chown=user requirements.txt .
+RUN pip install --no-cache-dir -r requirements.txt
+COPY --chown=user . .
+USER user
+EXPOSE 7860
+CMD ["uvicorn", "app:app", "--host", "0.0.0.0", "--port", "7860", "--no-proxy-headers"]

README.md

@@ -1,10 +1,26 @@
 ---
 title: Doodle Decoder
-emoji: 🐨
+emoji: ✏️
 colorFrom: yellow
-colorTo: blue
+colorTo: pink
 sdk: docker
+app_port: 7860
 pinned: false
+license: apache-2.0
+short_description: You draw, Rune guesses from the pixels, live.
+models:
+  - surogate/rune-26b-a4b-GGUF
+tags:
+  - surogate
+  - rune
+  - decision-model
+  - vision
 ---
 
-Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference
+# Doodle Decoder
+
+Draw the word you're given. Every time you lift the pen, [Surogate Rune](https://huggingface.co/surogate/rune-26b-a4b-GGUF),
+an open decision model, looks at the canvas and gives a probability for each of 50 words, so you watch it change its
+mind stroke by stroke.
+
+Nothing you draw is stored.

app.py

@@ -0,0 +1,19 @@
+from pathlib import Path
+
+import live
+
+HERE = Path(__file__).parent
+WORDS = ["cat", "dog", "fish", "bird", "house", "tree", "flower", "sun", "moon", "star", "car", "bicycle",
+         "boat", "airplane", "train", "rocket", "cup", "chair", "table", "lamp", "clock", "key", "umbrella",
+         "hat", "shoe", "glasses", "guitar", "pizza", "apple", "banana", "ice cream", "cake", "heart",
+         "smiley face", "snake", "spider", "butterfly", "mountain", "cloud", "lightning", "snowman",
+         "ghost", "crown", "sword", "light bulb", "phone", "envelope", "scissors", "pencil", "eye"]
+
+
+def questions(context):
+    return ("A sketch drawn by a person in a guessing game.", {"guess": {
+        "type": "choice", "instructions": "What is this sketch meant to be?",
+        "criteria": {w: w for w in WORDS}}})
+
+
+app = live.make_app(questions, HERE / "static")

live.py

@@ -0,0 +1,49 @@
+"""FastAPI app for the live Rune Labs demos: a static page plus /decide.
+
+deploy.py copies this file into the Docker Spaces. Edit it here, never in a Space.
+"""
+from fastapi import FastAPI, HTTPException, Request
+from fastapi.responses import JSONResponse
+from fastapi.staticfiles import StaticFiles
+from pydantic import BaseModel
+
+import rune
+
+MAX_BODY = rune.MAX_DATA_URL + 64 * 1024
+
+
+class Ask(BaseModel):
+    image: str
+    context: dict = {}
+
+
+def make_app(build_questions, static_dir):
+    """build_questions(context) -> (state, questions) for one decision about the posted image."""
+    app = FastAPI(docs_url=None, redoc_url=None, openapi_url=None)
+
+    @app.middleware("http")
+    async def refuse_oversized(request: Request, call_next):
+        # Checked before FastAPI reads and parses the body; a data URL plus the JSON around it.
+        size = request.headers.get("content-length")
+        if request.method == "POST" and (size is None or not size.isdigit() or int(size) > MAX_BODY):
+            return JSONResponse({"detail": "Request too large."}, status_code=413 if size else 411)
+        return await call_next(request)
+
+    @app.post("/decide")
+    def ask(a: Ask):
+        try:
+            img = rune.from_data_url(a.image)
+        except ValueError as e:
+            raise HTTPException(400, str(e))
+        state, questions = build_questions(a.context)
+        body = rune.request_body(state, questions, [rune.image_data_url(img)])
+        try:
+            answers = rune.decide(body)
+        except rune.Busy as e:
+            raise HTTPException(503, str(e))
+        except rune.RuneError as e:
+            raise HTTPException(502, str(e))
+        return {"labels": {k: rune.as_label(v) for k, v in answers.items()}}
+
+    app.mount("/", StaticFiles(directory=static_dir, html=True), name="static")
+    return app

requirements.txt

@@ -0,0 +1,3 @@
+fastapi==0.141.1
+uvicorn==0.54.0
+pillow==12.3.0

rune.py

@@ -0,0 +1,120 @@
+"""Shared by every Rune Labs Space: the Rune client, its concurrency cap, and image handling.
+
+deploy.py copies this file into each Space. Edit it here, never in a Space.
+"""
+import base64
+import binascii
+import http.client
+import io
+import json
+import logging
+import os
+import threading
+import time
+import urllib.error
+import urllib.request
+
+from PIL import Image
+
+MODEL = "rune-v3"
+MAX_SIDE = 1024
+MAX_TEXT = 4000
+MAX_DATA_URL = 6 * 1024 * 1024
+MAX_PIXELS = 25_000_000  # checked from the header, before any pixel is decoded
+BUSY = "Rune is busy right now. Try again in a few seconds."
+FAILED = "Rune could not answer that one. Try again in a moment."
+
+log = logging.getLogger("rune")
+
+# One cap for every caller in the process, Gradio handler or FastAPI route alike.
+_slots = threading.BoundedSemaphore(2)
+
+
+class RuneError(Exception):
+    """Rune did not answer. str() is safe to show to a user."""
+
+
+class Busy(RuneError):
+    pass
+
+
+def request_body(state, questions, images=None):
+    if isinstance(state, str):
+        state = state[:MAX_TEXT]
+    body = {"model": MODEL, "state": state, "questions": questions}
+    if images:
+        body["images"] = images
+    return body
+
+
+def decide(body, *, opener=urllib.request.urlopen, sleep=time.sleep):
+    req = urllib.request.Request(
+        os.environ["RUNE_URL"], json.dumps(body).encode(),
+        {"Authorization": "Bearer " + os.environ["RUNE_API_KEY"], "Content-Type": "application/json"})
+    with _slots:
+        for attempt in (0, 1):
+            try:
+                with opener(req, timeout=60) as r:
+                    reply = json.load(r)
+                if not isinstance(reply, dict) or not isinstance(reply.get("answers"), dict):
+                    raise ValueError("reply has no answers")
+                return reply["answers"]
+            except urllib.error.HTTPError as e:
+                e.close()
+                if e.code not in (429, 503):
+                    log.warning("rune call failed: HTTP %s", e.code)
+                    raise RuneError(FAILED) from None
+                if attempt == 0:
+                    sleep(1.5)
+            except (OSError, http.client.HTTPException, ValueError) as e:
+                # Logged by type only: the request carries user content, the log never does.
+                log.warning("rune call failed: %s", type(e).__name__)
+                raise RuneError(FAILED) from None
+    log.warning("rune busy after one retry")
+    raise Busy(BUSY)
+
+
+def image_data_url(img):
+    img = img.copy()
+    img.thumbnail((MAX_SIDE, MAX_SIDE))
+    png = img.mode in ("RGBA", "LA", "P")
+    buf = io.BytesIO()
+    if png:
+        img.save(buf, "PNG")
+    else:
+        img.convert("RGB").save(buf, "JPEG", quality=90)
+    return f"data:image/{'png' if png else 'jpeg'};base64," + base64.b64encode(buf.getvalue()).decode()
+
+
+def from_data_url(url):
+    """Decode an untrusted data URL from a browser into a resized image. Raises ValueError."""
+    if len(url) > MAX_DATA_URL or not url.startswith(("data:image/png;base64,", "data:image/jpeg;base64,")):
+        raise ValueError("expected a PNG or JPEG data URL under 6 MB")
+    try:
+        img = Image.open(io.BytesIO(base64.b64decode(url.split(",", 1)[1], validate=True)))
+        if img.width * img.height > MAX_PIXELS:
+            raise ValueError("image too large")
+        img.load()
+    except (binascii.Error, OSError, Image.DecompressionBombError) as e:
+        raise ValueError("not a readable image") from e
+    img.thumbnail((MAX_SIDE, MAX_SIDE))
+    return img
+
+
+def as_label(answer, names=None):
+    """Rune answer -> {label: probability}, the shape gr.Label and the live pages draw.
+
+    names maps a choice's option keys to what to show instead, usually its criteria.
+    """
+    if "noul" in answer:
+        return {"yes": answer["noul"], "no": 1 - answer["noul"]}
+    names = names or answer.get("legend") or {}
+    return {names.get(k, k): p for k, p in answer["probabilities"].items()}
+
+
+def curl(body):
+    shown = dict(body)
+    if "images" in shown:
+        shown["images"] = [u[:40] + "…" for u in shown["images"]]
+    return (f"curl {os.environ.get('RUNE_URL', '')} \\\n  -H 'Authorization: Bearer $RUNE_API_KEY' \\\n"
+            f"  -H 'Content-Type: application/json' \\\n  -d '{json.dumps(shown, ensure_ascii=False)}'")

static/client.js

@@ -0,0 +1,28 @@
+/* Rune Labs: the two helpers both static Spaces use. Plain globals, loaded before the page's own script. */
+
+/* POST JSON to the Space and return the reply, or throw with the server's message. */
+async function post(path, body) {
+  const r = await fetch(path, { method: "POST", headers: { "Content-Type": "application/json" }, body: JSON.stringify(body || {}) });
+  const data = await r.json().catch(() => ({}));
+  if (!r.ok) throw new Error(data.detail || "Something went wrong. Try again in a moment.");
+  return data;
+}
+
+/* One probability row: label, bar, percentage. Built with textContent, never HTML. */
+function bar(label, p, top) {
+  const row = document.createElement("div");
+  row.className = top ? "bar top" : "bar";
+  const name = document.createElement("span");
+  name.textContent = label;
+  const track = document.createElement("div");
+  track.className = "track";
+  const fill = document.createElement("div");
+  fill.className = "fill";
+  fill.style.width = `${(p * 100).toFixed(1)}%`;
+  track.append(fill);
+  const pct = document.createElement("span");
+  pct.className = "pct";
+  pct.textContent = `${Math.round(p * 100)}%`;
+  row.append(name, track, pct);
+  return row;
+}

static/embed.js

@@ -0,0 +1,37 @@
+/* Rune Labs: inside surogate.ai a demo drops its own header (the page row already names it) and
+   reports its height, so the page sizes the frame to fit and nothing scrolls inside it.
+
+   The height is the bottom of main's children, not of main itself: Gradio stretches <main> to fill
+   the frame, so measuring it would grow the frame, which grows main, forever.
+
+   surogate.ai asks for this with ?embed=surogate. Being in a frame is not enough: huggingface.co
+   shows every Space in one too, and there the header and footer should stay. */
+(() => {
+  if (window.self === window.top || !new URLSearchParams(location.search).has("embed")) return;
+  document.documentElement.classList.add("rune-embedded");
+  let last = 0;
+  const contentBottom = (main) => {
+    let bottom = 0;
+    for (const child of main.children) bottom = Math.max(bottom, child.getBoundingClientRect().bottom);
+    return bottom + window.scrollY + parseFloat(getComputedStyle(main).paddingBottom || "0");
+  };
+  const send = () => {
+    const main = document.querySelector("main");
+    if (!main) return;
+    const height = Math.ceil(contentBottom(main) + 28);
+    if (Math.abs(height - last) < 2) return;
+    last = height;
+    window.parent.postMessage({ type: "rune-labs:height", height }, "*");
+  };
+  const start = () => {
+    const main = document.querySelector("main");  // Gradio mounts it after the script runs
+    if (!main || !main.children.length) return setTimeout(start, 150);
+    const watch = new ResizeObserver(send);
+    for (const child of main.children) watch.observe(child);
+    new MutationObserver(() => { for (const child of main.children) watch.observe(child); send(); })
+      .observe(main, { childList: true });
+    send();
+  };
+  if (document.readyState === "loading") addEventListener("DOMContentLoaded", start);
+  else start();
+})();

static/index.html

@@ -0,0 +1,202 @@
+<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<title>Doodle Decoder</title>
+<meta name="description" content="Draw the word you're given. Surogate Rune looks at your pixels and guesses, live.">
+<link rel="preconnect" href="https://fonts.googleapis.com">
+<link href="https://fonts.googleapis.com/css2?family=Fraunces:opsz,wght@9..144,600&family=Inter:wght@400;600;700&display=swap" rel="stylesheet">
+<style>
+  :root {
+    --ink: #2a102d; --ink-2: #52504c; --ink-3: #8c847a; --paper: #ffffff; --card: #ffffff;
+    --amber: #ffaf10; --amber-soft: rgba(255, 175, 16, 0.14); --line: #ece6da; --good: #22c55e;
+  }
+  * { box-sizing: border-box; }
+  body { margin: 0; font: 16px/1.5 Inter, ui-sans-serif, system-ui, -apple-system, "Segoe UI", sans-serif;
+         background: var(--paper); color: var(--ink); -webkit-font-smoothing: antialiased; }
+  main { max-width: 1040px; margin: 0 auto; padding: 24px 20px 40px; display: grid; gap: 24px;
+         grid-template-columns: minmax(0, 1fr) 320px; }
+  @media (max-width: 800px) { main { grid-template-columns: minmax(0, 1fr); } }
+  header { grid-column: 1 / -1; }
+  h1 { margin: 0; font-family: Fraunces, Georgia, serif; font-weight: 600; font-size: clamp(30px, 5vw, 44px); letter-spacing: -0.02em; line-height: 1.05; }
+  .rune-embedded header, .rune-embedded footer { display: none; }
+  .rune-embedded main { padding-top: 8px; }
+  .sub { margin: 6px 0 0; color: var(--ink-2); }
+  .prompt { display: flex; align-items: baseline; gap: 10px; margin: 0 0 12px; font-size: 20px; color: var(--ink-2); }
+  .prompt b { font-size: 30px; color: var(--ink); background: var(--amber-soft); padding: 0 10px; border-radius: 8px; }
+  canvas { display: block; width: 100%; aspect-ratio: 1; background: #fff; border: 1px solid var(--line);
+           border-radius: 16px; touch-action: none; cursor: crosshair; box-shadow: 0 24px 50px -30px rgba(42, 16, 45, 0.35); }
+  .tools { display: flex; gap: 10px; margin-top: 12px; flex-wrap: wrap; }
+  button { font: inherit; font-weight: 600; padding: 9px 16px; border-radius: 10px; border: 2px solid var(--ink);
+           background: var(--card); color: var(--ink); cursor: pointer; }
+  button.primary { background: var(--amber); border-color: var(--amber); }
+  button:focus-visible { outline: 3px solid var(--amber); outline-offset: 3px; }
+  aside { background: var(--card); border: 1px solid var(--line); border-radius: 16px; padding: 18px 18px 14px;
+          align-self: start; position: sticky; top: 16px; }
+  .head { margin: 0 0 12px; font-family: Fraunces, Georgia, serif; font-weight: 600; font-size: 26px; min-height: 1.4em; }
+  .bar { display: grid; grid-template-columns: 96px 1fr 42px; gap: 8px; align-items: center; margin: 7px 0; font-size: 15px; }
+  .bar .track { height: 12px; background: var(--line); border-radius: 6px; overflow: hidden; }
+  .bar .fill { height: 100%; background: var(--amber); border-radius: 6px; transition: width 0.3s ease; }
+  .bar.top .fill { background: var(--ink); }
+  .bar .pct { text-align: right; font-variant-numeric: tabular-nums; color: var(--ink-2); }
+  .status { color: var(--ink-3); font-size: 14px; min-height: 1.5em; margin: 10px 0 0; }
+  .win { display: none; margin-top: 14px; padding: 14px; border-radius: 12px; background: var(--ink); color: #fff; }
+  .win.show { display: block; animation: pop 0.35s cubic-bezier(.2, 1.4, .4, 1); }
+  .win p { margin: 0 0 10px; }
+  .win button { border-color: var(--amber); background: var(--amber); color: var(--ink); }
+  @keyframes pop { from { transform: scale(0.92); opacity: 0; } to { transform: none; opacity: 1; } }
+  footer { grid-column: 1 / -1; color: var(--ink-3); font-size: 14px; }
+  footer a { color: var(--ink); }
+  @media (prefers-reduced-motion: reduce) { .bar .fill { transition: none; } .win.show { animation: none; } }
+</style>
+<script src="embed.js"></script>
+<script src="client.js"></script>
+</head>
+<body>
+<main>
+  <header>
+    <h1>Doodle Decoder</h1>
+    <p class="sub">Draw the word. Every time you lift the pen, Rune looks at your pixels and guesses.</p>
+  </header>
+
+  <section>
+    <p class="prompt">Draw <b id="word"></b></p>
+    <canvas id="canvas" width="512" height="512" aria-label="Drawing canvas"></canvas>
+    <div class="tools">
+      <button id="clear" type="button">Clear</button>
+      <button id="next" type="button" class="primary">New word</button>
+    </div>
+  </section>
+
+  <aside aria-live="polite">
+    <h2 class="head" id="head">Rune is watching…</h2>
+    <div id="bars"></div>
+    <p class="status" id="status">Start drawing.</p>
+    <div class="win" id="win">
+      <p id="win-text"></p>
+      <button id="share" type="button">Share</button>
+    </div>
+  </aside>
+
+  <footer>
+    Powered by <a href="https://huggingface.co/surogate/rune-26b-a4b-GGUF" target="_blank" rel="noopener">Surogate Rune</a>,
+    an open decision model. <a href="https://surogate.ai/labs/rune-examples/" target="_blank" rel="noopener">More demos</a>.
+    Nothing you draw is stored.
+  </footer>
+</main>
+
+<script>
+const WORDS = ["cat", "dog", "fish", "bird", "house", "tree", "flower", "sun", "moon", "star", "car", "bicycle",
+  "boat", "airplane", "train", "rocket", "cup", "chair", "table", "lamp", "clock", "key", "umbrella",
+  "hat", "shoe", "glasses", "guitar", "pizza", "apple", "banana", "ice cream", "cake", "heart",
+  "smiley face", "snake", "spider", "butterfly", "mountain", "cloud", "lightning", "snowman",
+  "ghost", "crown", "sword", "light bulb", "phone", "envelope", "scissors", "pencil", "eye"];
+
+const canvas = document.getElementById("canvas");
+const ctx = canvas.getContext("2d");
+ctx.lineWidth = 8; ctx.lineCap = "round"; ctx.lineJoin = "round"; ctx.strokeStyle = "#111";
+const $ = (id) => document.getElementById(id);
+let strokes = 0, drawing = false, busy = false, pending = false, target = "", won = false;
+let round = 0;
+let last = null;  // the previous pointer position; each move draws only the new segment  // bumped by Clear and New word; an answer from an earlier round is dropped
+
+function clearCanvas() {
+  ctx.fillStyle = "#fff";
+  ctx.fillRect(0, 0, canvas.width, canvas.height);
+  strokes = 0; won = false; pending = false; round++;
+  $("bars").replaceChildren();
+  $("win").classList.remove("show");
+  $("head").textContent = "Rune is watching…";
+  $("status").textContent = "Start drawing.";
+}
+
+function newWord(asked) {
+  let next = WORDS.includes(asked) ? asked : null;
+  while (!next || next === target) next = WORDS[Math.floor(Math.random() * WORDS.length)];
+  target = next;
+  $("word").textContent = target;
+  clearCanvas();
+}
+
+function point(e) {
+  const r = canvas.getBoundingClientRect();
+  return [(e.clientX - r.left) * canvas.width / r.width, (e.clientY - r.top) * canvas.height / r.height];
+}
+
+canvas.addEventListener("pointerdown", (e) => {
+  drawing = true;
+  canvas.setPointerCapture(e.pointerId);
+  last = point(e);
+});
+canvas.addEventListener("pointermove", (e) => {
+  if (!drawing) return;
+  const p = point(e);
+  ctx.beginPath();
+  ctx.moveTo(...last);
+  ctx.lineTo(...p);
+  ctx.stroke();
+  last = p;
+});
+function endStroke() {
+  if (!drawing) return;
+  drawing = false;
+  strokes++;
+  guess();
+}
+canvas.addEventListener("pointerup", endStroke);
+canvas.addEventListener("pointercancel", endStroke);
+
+
+
+function setBusy(on) {
+  busy = on;
+  if (on) document.body.dataset.busy = "1"; else delete document.body.dataset.busy;
+}
+
+async function guess() {
+  if (won) return;
+  if (busy) { pending = true; return; }  // one request at a time; the latest drawing is sent next
+  setBusy(true);
+  const mine = round;
+  try {
+    const t = performance.now();
+    const out = await post("decide", { image: canvas.toDataURL("image/png"), context: {} });
+    if (mine !== round) return;
+    const probs = Object.entries(out.labels.guess).sort((a, b) => b[1] - a[1]);
+    const [top, p] = probs[0];
+    $("head").textContent = p < 0.5 ? `Hmm… a ${top}?` : `It's a ${top}!`;
+    $("bars").replaceChildren(...probs.slice(0, 5).map(([w, q], i) => bar(w, q, i === 0)));
+    $("status").textContent = `${Math.round(performance.now() - t)} ms · stroke ${strokes}`;
+    if (top === target && p >= 0.5) {
+      won = true;
+      $("win-text").textContent = `Rune got it in ${strokes} stroke${strokes === 1 ? "" : "s"}, ${Math.round(p * 100)}% sure it's a ${target}.`;
+      $("win").classList.add("show");
+    }
+  } catch (err) {
+    if (mine === round) $("status").textContent = err.message;
+  } finally {
+    setBusy(false);
+    if (pending && !won) { pending = false; guess(); }
+  }
+}
+
+$("share").addEventListener("click", async () => {
+  const url = new URL(location.href);
+  url.searchParams.set("word", target);  // the link challenges a friend to draw the same word
+  const text = `${$("win-text").textContent} Can you beat it? ${url}`;
+  const copy = async () => { await navigator.clipboard.writeText(text); $("share").textContent = "Copied!"; };
+  try {
+    if (navigator.share) await navigator.share({ text }); else await copy();
+  } catch (err) {
+    // AbortError: the visitor closed the share sheet. Anything else (a frame without web-share): copy instead.
+    if (err.name !== "AbortError") await copy().catch(() => { $("share").textContent = "Copy the address bar to share"; });
+  }
+});
+$("clear").addEventListener("click", clearCanvas);
+$("next").addEventListener("click", () => newWord());
+const asked = new URLSearchParams(location.search).get("word");
+newWord(asked);
+</script>
+</body>
+</html>