Deploy Forager's Field Station

app.py

@@ -17,6 +17,7 @@ import gradio as gr
 
 from pipeline.convergence import build_result
 from pipeline.infer import Pipeline
+from game.ui import build_game_tab
 
 HERE = os.path.dirname(os.path.abspath(__file__))
 EXAMPLES_DIR = os.path.join(HERE, "examples")
@@ -285,6 +286,57 @@ button.eink-scan:hover { background:var(--copper) !important; border-color:var(-
   padding:10px 14px; margin-top:10px; font-size:.74rem !important; line-height:1.55 !important;
   color:var(--ink2) !important; }
 #notice * { font-size:.74rem !important; color:var(--ink2) !important; }
+
+/* ── tabs ───────────────────────────────────────────────────── */
+.gradio-container .tab-nav { border-bottom:2px solid var(--bronze) !important; gap:0 !important; }
+.gradio-container .tab-nav button { color:var(--ink2) !important; font-weight:700 !important;
+  letter-spacing:.14em !important; font-size:.8rem !important; background:transparent !important;
+  border:none !important; border-radius:0 !important; padding:10px 16px !important; }
+.gradio-container .tab-nav button.selected { color:var(--copper) !important;
+  border-bottom:3px solid var(--copper) !important; background:var(--panel) !important; }
+
+/* ── Beat the Machine ───────────────────────────────────────── */
+.gm-intro { border:2px solid var(--bronze); background:var(--panel); padding:12px 16px;
+  margin-bottom:12px; box-shadow:5px 5px 0 rgba(122,63,26,.4); }
+.gm-intro-h { font-size:1.05rem; font-weight:700; letter-spacing:.16em; color:var(--copper); }
+.gm-intro-b { font-size:.82rem; line-height:1.55; color:var(--ink2); margin-top:6px; }
+
+.gm-btn { border-radius:0 !important; font-weight:700 !important; letter-spacing:.12em !important;
+  border:3px solid var(--ink2) !important; background:var(--panel) !important; color:var(--ink) !important;
+  box-shadow:4px 4px 0 rgba(122,63,26,.3) !important; }
+.gm-safe { border-color:#2f6b2b !important; color:#2f6b2b !important; }
+.gm-caut { border-color:#87671c !important; color:#87671c !important; }
+.gm-dead { border-color:#8c1d14 !important; color:#8c1d14 !important; }
+.gm-btn:hover { background:#efe9dc !important; }
+
+.gm-score { text-align:center; margin-top:12px; padding:10px; border:2px dashed var(--bronze);
+  background:var(--panel); font-size:1rem; letter-spacing:.08em; color:var(--ink); }
+.gm-score b { font-size:1.3rem; color:var(--copper); }
+.gm-vs { color:var(--ink2); font-size:.8rem; margin:0 6px; }
+
+.gm-idle { min-height:330px; display:flex; align-items:center; justify-content:center;
+  text-align:center; color:var(--ink2); font-size:.9rem; letter-spacing:.06em; }
+.gm-reveal { padding:28px 18px; min-height:330px; }
+.gm-truth-h { font-size:.66rem; letter-spacing:.24em; color:var(--ink2); }
+.gm-truth { font-size:2rem; font-weight:700; letter-spacing:.06em; line-height:1.1; }
+.gm-species { font-size:.9rem; color:var(--ink2); margin-top:4px; }
+.gm-species i { color:var(--ink2); }
+.gm-chips { display:flex; gap:12px; margin-top:18px; }
+.gm-chip { flex:1; border:2px solid; padding:8px 10px; text-align:center; }
+.gm-chip-h { display:block; font-size:.6rem; letter-spacing:.18em; opacity:.8; }
+.gm-chip-t { display:block; font-size:1.05rem; font-weight:700; margin-top:3px; }
+.gm-flav { margin-top:18px; padding-top:12px; border-top:2px dashed var(--ink2);
+  font-size:.95rem; font-weight:700; color:var(--ink); }
+.gm-abst { margin-top:8px; font-size:.8rem; line-height:1.5; color:var(--ink2); }
+
+.gm-divider { margin-top:18px; padding:6px 0; border-top:2px solid var(--bronze);
+  font-size:.7rem; letter-spacing:.2em; color:var(--copper); font-weight:700; }
+.gm-lb { border:2px solid var(--bronze) !important; }
+.gm-refresh { font-size:.7rem !important; color:var(--ink2) !important; background:transparent !important;
+  border:none !important; box-shadow:none !important; }
+.gm-warn { color:#8c1d14; font-weight:700; font-size:.85rem; padding:6px 0; }
+.gm-ok { color:#2f6b2b; font-weight:700; font-size:.85rem; padding:6px 0; }
+.gm-note { color:var(--ink2); font-weight:400; }
 """
 
 with gr.Blocks(title="Forager's Field Station") as demo:
@@ -297,26 +349,31 @@ with gr.Blocks(title="Forager's Field Station") as demo:
         "      <span>REFUSES BY DEFAULT</span></div>"
         "</div>"
     )
-    gr.HTML(EXPERTS_PANEL)
-    with gr.Row():
-        with gr.Column(scale=1):
-            img = gr.Image(type="pil", label="SPECIMEN", sources=["upload", "webcam"],
-                           elem_classes="eink-input", height=300)
-            btn = gr.Button("▸ SCAN SPECIMEN", variant="primary", elem_classes="eink-scan")
-            if os.path.isdir(EXAMPLES_DIR):
-                samples = [[os.path.join(EXAMPLES_DIR, f)] for f in (
-                    "chanterelle.jpg", "lions_mane.jpg", "wild_blueberry.jpg",
-                    "yarrow.jpg", "poison_hemlock.jpg") if os.path.exists(os.path.join(EXAMPLES_DIR, f))]
-                if samples:
-                    gr.Examples(examples=samples, inputs=img,
-                                label="No specimen handy? Try a sample:")
-        with gr.Column(scale=1, elem_classes="eink-screen"):
-            out = gr.HTML(_idle())
-    gr.HTML(QUOTE_BAR)
-    gr.Markdown(SAFETY_NOTICE, elem_id="notice")
-
-    btn.click(identify, inputs=img, outputs=out)
-    img.change(identify, inputs=img, outputs=out)
+    with gr.Tabs():
+        with gr.Tab("◧ FIELD STATION"):
+            gr.HTML(EXPERTS_PANEL)
+            with gr.Row():
+                with gr.Column(scale=1):
+                    img = gr.Image(type="pil", label="SPECIMEN", sources=["upload", "webcam"],
+                                   elem_classes="eink-input", height=300)
+                    btn = gr.Button("▸ SCAN SPECIMEN", variant="primary", elem_classes="eink-scan")
+                    if os.path.isdir(EXAMPLES_DIR):
+                        samples = [[os.path.join(EXAMPLES_DIR, f)] for f in (
+                            "chanterelle.jpg", "lions_mane.jpg", "wild_blueberry.jpg",
+                            "yarrow.jpg", "poison_hemlock.jpg") if os.path.exists(os.path.join(EXAMPLES_DIR, f))]
+                        if samples:
+                            gr.Examples(examples=samples, inputs=img,
+                                        label="No specimen handy? Try a sample:")
+                with gr.Column(scale=1, elem_classes="eink-screen"):
+                    out = gr.HTML(_idle())
+            gr.HTML(QUOTE_BAR)
+            gr.Markdown(SAFETY_NOTICE, elem_id="notice")
+
+            btn.click(identify, inputs=img, outputs=out)
+            img.change(identify, inputs=img, outputs=out)
+
+        with gr.Tab("⚔ BEAT THE MACHINE"):
+            build_game_tab(PIPE)
 
 if __name__ == "__main__":
     # theme/css belong in launch() in Gradio 6. ssr_mode=False is also enforced via

game/__init__.py

@@ -0,0 +1 @@
+"""Beat the Machine — the You-vs-AI duel game tab and its data flywheel."""

game/datastore.py

@@ -0,0 +1,127 @@
+"""
+game/datastore.py — persistence to the public sightings dataset.
+
+Two responsibilities:
+  * leaderboard read/write   (Phase 1)
+  * append_sighting()        (Phase 2 — the upload flywheel)
+
+Both write to HomesteaderLabs/forager-sightings via huggingface_hub, authenticated
+by the HF_TOKEN Space secret. When no token is present (local dev, or the secret
+isn't set yet) everything falls back to in-memory so the game still runs — the
+leaderboard just won't persist across restarts until the secret is added.
+
+Concurrency note: the leaderboard is a read-modify-write on one jsonl file, so
+simultaneous posts can race (last write wins). Fine at demo scale; revisit with a
+queue or per-row append if it ever matters.
+"""
+
+import datetime
+import json
+import os
+
+DATASET_REPO = "HomesteaderLabs/forager-sightings"
+LICENSE = "CC-BY-4.0"
+
+_TOKEN = os.environ.get("HF_TOKEN")
+
+# in-memory fallback: contributor -> aggregated score row
+_mem_leaderboard: dict[str, dict] = {}
+
+
+def persistence_enabled() -> bool:
+    return bool(_TOKEN)
+
+
+def _now() -> str:
+    return datetime.datetime.now(datetime.timezone.utc).isoformat(timespec="seconds")
+
+
+def load_leaderboard() -> list[dict]:
+    """Return all aggregated score rows (from the dataset if a token is set, else memory)."""
+    if _TOKEN:
+        try:
+            from huggingface_hub import hf_hub_download
+            path = hf_hub_download(DATASET_REPO, "leaderboard.jsonl", repo_type="dataset",
+                                   token=_TOKEN, force_download=True)
+            with open(path) as f:
+                return [json.loads(line) for line in f if line.strip()]
+        except Exception:
+            pass
+    return list(_mem_leaderboard.values())
+
+
+def post_score(contributor: str, you_correct: int, total: int, machine_correct: int) -> list[dict]:
+    """Add this session's tally to the contributor's cumulative row; persist; return all rows."""
+    rows = {r["contributor"]: r for r in load_leaderboard()}
+    r = rows.get(contributor, {
+        "contributor": contributor, "skill_correct": 0, "skill_total": 0,
+        "machine_correct": 0, "contributions": 0,
+    })
+    r["skill_correct"] += int(you_correct)
+    r["skill_total"] += int(total)
+    r["machine_correct"] += int(machine_correct)
+    r["updated"] = _now()
+    rows[contributor] = r
+
+    if _TOKEN:
+        try:
+            from huggingface_hub import HfApi
+            body = "\n".join(json.dumps(x) for x in rows.values())
+            HfApi(token=_TOKEN).upload_file(
+                path_or_fileobj=body.encode("utf-8"), path_in_repo="leaderboard.jsonl",
+                repo_id=DATASET_REPO, repo_type="dataset",
+                commit_message=f"score: {contributor}",
+            )
+        except Exception:
+            _mem_leaderboard.update(rows)
+    else:
+        _mem_leaderboard.update(rows)
+    return list(rows.values())
+
+
+def append_sighting(image, user_label: str, machine: dict, contributor: str) -> bool:
+    """
+    Phase 2: commit one contributed photo + metadata row to the dataset.
+    `machine` carries the model's call (prediction/confidence/abstained/safety/domain).
+    Returns True on persisted write. Stub raises if no token so callers gate on
+    persistence_enabled() first.
+    """
+    if not _TOKEN:
+        return False
+    from io import BytesIO
+    from huggingface_hub import CommitOperationAdd, HfApi
+
+    ts = _now()
+    fname = f"images/{contributor}_{ts.replace(':', '').replace('-', '')}.jpg"
+    buf = BytesIO()
+    image.convert("RGB").save(buf, format="JPEG", quality=90)
+    row = {
+        "file_name": fname, "user_label": user_label,
+        "machine_prediction": machine.get("species", "unknown"),
+        "machine_confidence": round(float(machine.get("confidence", 0.0)), 4),
+        "machine_abstained": bool(machine.get("abstained", True)),
+        "machine_safety": machine.get("safety", "UNKNOWN"),
+        "routed_domain": machine.get("domain", "unknown"),
+        "contributor": contributor, "consent": True, "license": LICENSE, "timestamp": ts,
+    }
+    api = HfApi(token=_TOKEN)
+    # append the metadata line to the existing jsonl
+    existing = ""
+    try:
+        from huggingface_hub import hf_hub_download
+        with open(hf_hub_download(DATASET_REPO, "metadata.jsonl", repo_type="dataset",
+                                  token=_TOKEN, force_download=True)) as f:
+            existing = f.read().rstrip("\n")
+    except Exception:
+        pass
+    new_meta = (existing + "\n" if existing else "") + json.dumps(row) + "\n"
+    api.create_commit(
+        repo_id=DATASET_REPO, repo_type="dataset",
+        commit_message=f"sighting: {row['machine_prediction']} by {contributor}",
+        operations=[
+            CommitOperationAdd(path_in_repo=fname, path_or_fileobj=buf.getvalue()),
+            CommitOperationAdd(path_in_repo="metadata.jsonl",
+                               path_or_fileobj=new_meta.encode("utf-8")),
+        ],
+    )
+    return True

game/deck.json

@@ -0,0 +1,7 @@
+[
+  {"file": "chanterelle.jpg",    "species": "chanterelles_edible"},
+  {"file": "lions_mane.jpg",     "species": "lions_mane"},
+  {"file": "wild_blueberry.jpg", "species": "blueberry_wild"},
+  {"file": "yarrow.jpg",         "species": "yarrow"},
+  {"file": "poison_hemlock.jpg", "species": "poison_hemlock_deadly"}
+]

game/deck.py

@@ -0,0 +1,45 @@
+"""
+game/deck.py — the curated duel deck (cards with real ground truth).
+
+Phase-1 deck reuses the bundled validated example photos; each card's truth tier
+is resolved from the same SPECIES_METADATA the live pipeline uses, so the game and
+the model are graded against one source of truth. Grow the deck by dropping more
+labelled images in examples/ and adding rows to deck.json.
+"""
+
+import json
+import os
+import random
+
+from pipeline.metadata import SPECIES_METADATA, UNKNOWN_META
+
+_HERE = os.path.dirname(__file__)
+_EXAMPLES_DIR = os.path.join(_HERE, "..", "examples")
+
+
+def _load_deck() -> list[dict]:
+    with open(os.path.join(_HERE, "deck.json")) as f:
+        raw = json.load(f)
+    deck = []
+    for c in raw:
+        path = os.path.join(_EXAMPLES_DIR, c["file"])
+        if not os.path.exists(path):
+            continue
+        meta = SPECIES_METADATA.get(c["species"], UNKNOWN_META)
+        deck.append({
+            "file": c["file"],
+            "path": path,
+            "species": c["species"],
+            "tier": meta["safety"],            # SAFE | CAUTION | DEADLY
+            "scientific": meta["scientific"],
+        })
+    return deck
+
+
+DECK = _load_deck()
+
+
+def random_card(exclude_file: str | None = None) -> dict:
+    """Return a random card; avoid repeating the immediately-previous one when possible."""
+    pool = [c for c in DECK if c["file"] != exclude_file] or DECK
+    return random.choice(pool)

game/ui.py

@@ -0,0 +1,172 @@
+"""
+game/ui.py — "Beat the Machine" duel tab.
+
+A card from the curated deck is dealt; you call its safety tier (SAFE / CAUTION /
+DEADLY) and the same on-device pipeline calls it at the same instant. Score
+accrues per session; post it to the leaderboard. The machine's edge is that it
+refuses when unsure — so the deadly cards punish overconfidence in both players.
+Stay sharper than the machine you built.
+"""
+
+from functools import partial
+
+import gradio as gr
+import pandas as pd
+from PIL import Image
+
+from pipeline.convergence import build_result
+
+from . import datastore
+from . import deck as deck_mod
+
+TIER_COLOR = {"SAFE": "#2f6b2b", "CAUTION": "#87671c", "DEADLY": "#8c1d14", "UNKNOWN": "#57544c"}
+_LB_COLS = ["Player", "You %", "Machine %", "Rounds"]
+
+
+def _machine_call(pipe, path: str):
+    res = build_result(pipe.identify(Image.open(path)))
+    tier = "UNKNOWN" if res.abstained else res.safety
+    return tier, res
+
+
+def _scoreboard(score: dict) -> str:
+    return (
+        f"<div class='gm-score'>"
+        f"<span class='gm-you'>YOU&nbsp;<b>{score['you']}</b></span>"
+        f"<span class='gm-vs'>/&nbsp;{score['total']}&nbsp;·&nbsp;vs&nbsp;·</span>"
+        f"<span class='gm-mach'>MACHINE&nbsp;<b>{score['machine']}</b></span>"
+        f"</div>"
+    )
+
+
+def _pretty(species: str) -> str:
+    return species.replace("_toxic", "").replace("_deadly", "").replace("_", " ").title()
+
+
+def _chip(label: str, tier: str, right: bool) -> str:
+    c = TIER_COLOR.get(tier, "#57544c")
+    mark = "✓" if right else "✕"
+    return (
+        f"<div class='gm-chip' style='border-color:{c};color:{c}'>"
+        f"<span class='gm-chip-h'>{label}</span>"
+        f"<span class='gm-chip-t'>{tier} {mark}</span></div>"
+    )
+
+
+def _reveal_html(card: dict, you_tier: str, you_right: bool, mtier: str, mach_right: bool) -> str:
+    tc = TIER_COLOR[card["tier"]]
+    if you_right and not mach_right:
+        flav = "🏆 You beat the machine on this one."
+    elif mach_right and not you_right:
+        flav = "The machine got you. Study the look-alike."
+    elif you_right and mach_right:
+        flav = "Dead heat — both correct."
+    else:
+        flav = "Neither nailed it. The woods don't grade on a curve."
+    abst = ""
+    if mtier == "UNKNOWN":
+        abst = ("<div class='gm-abst'>The machine refused to commit — that's its whole "
+                "point. A refusal beats a confident wrong call.</div>")
+    return (
+        f"<div class='gm-reveal'>"
+        f"<div class='gm-truth-h'>TRUTH</div>"
+        f"<div class='gm-truth' style='color:{tc}'>{card['tier']}</div>"
+        f"<div class='gm-species'>{_pretty(card['species'])} · <i>{card['scientific']}</i></div>"
+        f"<div class='gm-chips'>{_chip('YOUR CALL', you_tier, you_right)}"
+        f"{_chip('MACHINE', mtier, mach_right)}</div>"
+        f"<div class='gm-flav'>{flav}</div>{abst}</div>"
+    )
+
+
+def _lb_df() -> pd.DataFrame:
+    data = []
+    for r in datastore.load_leaderboard():
+        t = int(r.get("skill_total", 0) or 0)
+        if t == 0:
+            continue
+        data.append([
+            r.get("contributor", "?"),
+            round(100 * r.get("skill_correct", 0) / t),
+            round(100 * r.get("machine_correct", 0) / t),
+            t,
+        ])
+    data.sort(key=lambda x: (-x[1], -x[3]))
+    return pd.DataFrame(data, columns=_LB_COLS)
+
+
+def build_game_tab(pipe) -> None:
+    """Build the duel tab inside the current gr.Blocks context."""
+    gr.HTML(
+        "<div class='gm-intro'>"
+        "<div class='gm-intro-h'>CAN YOU BEAT THE MACHINE?</div>"
+        "<div class='gm-intro-b'>We built the machine. Now try to out-forage it. "
+        "A card is dealt — call its tier before it does. Remember: the machine's "
+        "trick is knowing when <i>not</i> to guess. Every round you play sharpens you "
+        "and sharpens the open dataset behind it.</div></div>"
+    )
+
+    score_state = gr.State({"you": 0, "machine": 0, "total": 0})
+    card_state = gr.State(None)
+
+    with gr.Row():
+        with gr.Column(scale=1):
+            card_img = gr.Image(type="filepath", show_label=False, interactive=False,
+                                elem_classes="eink-input", height=300)
+            deal_btn = gr.Button("▸ DEAL A CARD", variant="primary", elem_classes="eink-scan")
+            with gr.Row():
+                safe_b = gr.Button("SAFE", elem_classes="gm-btn gm-safe")
+                caut_b = gr.Button("CAUTION", elem_classes="gm-btn gm-caut")
+                dead_b = gr.Button("DEADLY", elem_classes="gm-btn gm-dead")
+        with gr.Column(scale=1, elem_classes="eink-screen"):
+            reveal = gr.HTML("<div class='gm-idle'>Deal a card to start the duel.</div>")
+
+    score_html = gr.HTML(_scoreboard({"you": 0, "machine": 0, "total": 0}))
+
+    gr.HTML("<div class='gm-divider'>▌ LEADERBOARD</div>")
+    with gr.Row():
+        nick = gr.Textbox(label="Name for the leaderboard", placeholder="handle",
+                          scale=2, elem_classes="eink-input")
+        post_btn = gr.Button("POST MY SCORE", elem_classes="eink-scan", scale=1)
+    lb_status = gr.HTML("")
+    lb = gr.Dataframe(value=_lb_df(), headers=_LB_COLS, interactive=False,
+                      elem_classes="gm-lb", wrap=True)
+    refresh_btn = gr.Button("⟳ refresh", elem_classes="gm-refresh")
+
+    # ── handlers (closures capture `pipe`) ───────────────────────────────────
+    def _deal(score, card):
+        prev = card["file"] if card else None
+        c = deck_mod.random_card(exclude_file=prev)
+        new = {**c, "answered": False}
+        return c["path"], new, "<div class='gm-idle'>Your call?</div>", _scoreboard(score)
+
+    def _guess(tier, card, score):
+        if not card or card.get("answered"):
+            return gr.update(), card, score  # ignore double-taps / no card yet
+        mtier, _ = _machine_call(pipe, card["path"])
+        you_right = tier == card["tier"]
+        mach_right = mtier == card["tier"]
+        score = {
+            "you": score["you"] + int(you_right),
+            "machine": score["machine"] + int(mach_right),
+            "total": score["total"] + 1,
+        }
+        card = {**card, "answered": True}
+        return _reveal_html(card, tier, you_right, mtier, mach_right), card, score
+
+    def _post(nickname, score):
+        name = (nickname or "").strip()
+        if not name:
+            return "<div class='gm-warn'>Enter a name first.</div>", gr.update()
+        if score["total"] == 0:
+            return "<div class='gm-warn'>Play at least one round first.</div>", gr.update()
+        datastore.post_score(name, score["you"], score["total"], score["machine"])
+        note = "" if datastore.persistence_enabled() else \
+            " <span class='gm-note'>(session-only until the dataset token is set)</span>"
+        return f"<div class='gm-ok'>Posted, {name}.{note}</div>", _lb_df()
+
+    deal_btn.click(_deal, [score_state, card_state], [card_img, card_state, reveal, score_html])
+    for b, t in [(safe_b, "SAFE"), (caut_b, "CAUTION"), (dead_b, "DEADLY")]:
+        b.click(partial(_guess, t), [card_state, score_state], [reveal, card_state, score_state]) \
+         .then(_scoreboard, [score_state], [score_html])
+    post_btn.click(_post, [nick, score_state], [lb_status, lb])
+    refresh_btn.click(lambda: _lb_df(), None, [lb])