Create main.py

main.py

@@ -0,0 +1,715 @@
+# app.py — Hidden Stroke (AI Noir Investigation) with Internet Archive ingestion
+# Flask + Firebase Realtime DB + Firebase Storage + Gemini (exact model names)
+# Runs on Hugging Face like your reference app (same envs & init flow)
+
+import os, io, uuid, json, time, hmac, hashlib, random, traceback, requests
+from datetime import datetime, timedelta, timezone
+from typing import Dict, Any, Tuple, List, Optional
+
+from flask import Flask, request, jsonify
+from flask_cors import CORS
+from PIL import Image
+
+# ---------------- Firebase Admin (Realtime DB + Storage) ----------------
+import firebase_admin
+from firebase_admin import credentials, db, storage
+
+# ---------------- Gemini (exact client & model names) -------------------
+from google import genai
+from google.genai import types
+
+# -----------------------------------------------------------------------------
+# 1) CONFIG & INIT  (env names EXACTLY as your reference code)
+# -----------------------------------------------------------------------------
+app = Flask(__name__)
+CORS(app)
+
+# --- Firebase ---
+try:
+    credentials_json_string = os.environ.get("FIREBASE")
+    if not credentials_json_string:
+        raise ValueError("The FIREBASE environment variable is not set.")
+
+    credentials_json = json.loads(credentials_json_string)
+    firebase_db_url = os.environ.get("Firebase_DB")
+    firebase_storage_bucket = os.environ.get("Firebase_Storage")
+    if not firebase_db_url or not firebase_storage_bucket:
+        raise ValueError("Firebase_DB and Firebase_Storage environment variables must be set.")
+
+    cred = credentials.Certificate(credentials_json)
+    firebase_admin.initialize_app(cred, {
+        'databaseURL': firebase_db_url,
+        'storageBucket': firebase_storage_bucket
+    })
+    bucket = storage.bucket()
+    db_root = db.reference("/")
+    print("Firebase Realtime DB + Storage initialized.")
+except Exception as e:
+    print(f"FATAL: Firebase init failed: {e}")
+    raise
+
+# --- Gemini ---
+try:
+    GEMINI_API_KEY = os.environ.get("Gemini")
+    if not GEMINI_API_KEY:
+        raise ValueError("The 'Gemini' environment variable is not set.")
+    client = genai.Client(api_key=GEMINI_API_KEY)
+    print("Gemini client initialized.")
+except Exception as e:
+    print(f"FATAL: Gemini init failed: {e}")
+    raise
+
+# --- Models (exact names) ---
+CATEGORY_MODEL = "gemini-2.5-flash"
+GENERATION_MODEL = "gemini-2.0-flash-exp-image-generation"
+
+# --- Game constants ---
+TIMER_SECONDS = 90
+INITIAL_IP = 8
+TOOL_COSTS = {"signature": 1, "metadata": 1, "financial": 2}
+LEADERBOARD_TOP_N = 50
+
+# --- Misc config ---
+GAME_SALT = os.environ.get("GAME_SALT", "dev-salt")  # for deterministic seeds / HMAC
+ADMIN_KEY = os.environ.get("ADMIN_KEY")  # optional for admin endpoints
+IA_USER_AGENT = os.environ.get("IA_USER_AGENT", "HiddenStrokeBot/1.0 (+https://reddit.com)")  # polite UA
+
+# -----------------------------------------------------------------------------
+# 2) UTILS
+# -----------------------------------------------------------------------------
+def utc_today_str() -> str:
+    return datetime.now(timezone.utc).strftime("%Y%m%d")
+
+def case_ref(case_id: str):
+    return db_root.child(f"cases/{case_id}")
+
+def plays_ref(case_id: str):
+    return db_root.child(f"plays/{case_id}")
+
+def leaderboard_ref(case_id: str):
+    return db_root.child(f"leaderboards/{case_id}/top")
+
+def sessions_ref():
+    return db_root.child("sessions")
+
+def ia_pool_ref():
+    return db_root.child("ia_pool")
+
+def hmac_hex(s: str) -> str:
+    return hmac.new(GAME_SALT.encode(), s.encode(), hashlib.sha256).hexdigest()
+
+def upload_bytes_to_storage(data: bytes, path: str, content_type: str) -> str:
+    blob = bucket.blob(path)
+    blob.upload_from_string(data, content_type=content_type)
+    blob.make_public()
+    return blob.public_url
+
+def pil_from_inline_image_part(part) -> Image.Image:
+    image_bytes = part.inline_data.data
+    return Image.open(io.BytesIO(image_bytes)).convert("RGB")
+
+def save_image_return_url(img: Image.Image, path: str, quality=92) -> str:
+    b = io.BytesIO()
+    img.save(b, format="JPEG", quality=quality, optimize=True)
+    return upload_bytes_to_storage(b.getvalue(), path, "image/jpeg")
+
+def extract_user_from_headers(req) -> Tuple[str, str]:
+    uname = (req.headers.get("X-Reddit-User") or "").strip()
+    uid = (req.headers.get("X-Reddit-Id") or "").strip()
+    if not uname:
+        uname = "anon"
+    if not uid:
+        uid = uname
+    return uid, uname
+
+def seed_for_date(case_id: str) -> int:
+    return int(hmac_hex(f"seed::{case_id}")[:12], 16)
+
+def fifty_fifty_mode(case_seed: int) -> str:
+    return "knowledge" if (case_seed % 2 == 0) else "observation"
+
+def http_get_json(url: str, params: dict = None) -> dict:
+    headers = {"User-Agent": IA_USER_AGENT}
+    r = requests.get(url, params=params, headers=headers, timeout=30)
+    r.raise_for_status()
+    return r.json()
+
+def http_get_bytes(url: str) -> bytes:
+    headers = {"User-Agent": IA_USER_AGENT}
+    r = requests.get(url, headers=headers, timeout=60)
+    r.raise_for_status()
+    return r.content
+
+def ia_advanced_search(query: str, rows: int, page: int) -> List[dict]:
+    # Internet Archive Advanced Search (no key required)
+    # docs: /advancedsearch.php?q=...&rows=...&page=...&output=json
+    url = "https://archive.org/advancedsearch.php"
+    params = {"q": query, "rows": rows, "page": page, "output": "json"}
+    data = http_get_json(url, params=params)
+    return data.get("response", {}).get("docs", [])
+
+def ia_metadata(identifier: str) -> dict:
+    url = f"https://archive.org/metadata/{identifier}"
+    return http_get_json(url)
+
+def ia_best_image_from_metadata(meta: dict) -> Optional[dict]:
+    # Pick the largest suitable image file from /metadata result
+    files = meta.get("files", []) or []
+    best = None
+    best_pixels = -1
+    for f in files:
+        name = f.get("name", "")
+        fmt = (f.get("format") or "").lower()
+        if any(x in fmt for x in ["jpeg", "jpg", "png", "tiff", "image"]):
+            # width/height sometimes present
+            w = int(f.get("width") or 0)
+            h = int(f.get("height") or 0)
+            if w and h:
+                px = w * h
+            else:
+                px = int(f.get("size") or 0)  # fallback by bytes
+            if px > best_pixels:
+                best_pixels = px
+                best = f
+    return best
+
+def ingest_ia_doc(doc: dict) -> Optional[dict]:
+    """
+    Given a doc from advancedsearch, fetch /metadata and store best image into ia_pool.
+    """
+    identifier = doc.get("identifier")
+    if not identifier:
+        return None
+    meta = ia_metadata(identifier)
+    best = ia_best_image_from_metadata(meta)
+    if not best:
+        return None
+
+    title = (meta.get("metadata", {}) or {}).get("title", "") or doc.get("title", "")
+    date = (meta.get("metadata", {}) or {}).get("date", "") or doc.get("date", "")
+    creator = (meta.get("metadata", {}) or {}).get("creator", "") or doc.get("creator", "")
+    rights = (meta.get("metadata", {}) or {}).get("rights", "") or doc.get("rights", "")
+    licenseurl = (meta.get("metadata", {}) or {}).get("licenseurl", "") or doc.get("licenseurl", "")
+
+    download_url = f"https://archive.org/download/{identifier}/{best['name']}"
+    record = {
+        "identifier": identifier,
+        "title": title,
+        "date": str(date),
+        "creator": creator,
+        "rights": rights,
+        "licenseurl": licenseurl,
+        "download_url": download_url,
+        "file_name": best["name"],
+        "format": best.get("format"),
+        "width": best.get("width"),
+        "height": best.get("height"),
+        "size": best.get("size"),
+        "source": "internet_archive"
+    }
+    ia_pool_ref().child(identifier).set(record)
+    return record
+
+def choose_ia_item_for_case(case_id: str) -> Optional[dict]:
+    pool = ia_pool_ref().get() or {}
+    if not pool:
+        return None
+    identifiers = sorted(pool.keys())
+    case_seed = seed_for_date(case_id)
+    idx = case_seed % len(identifiers)
+    ident = identifiers[idx]
+    return pool[ident]
+
+def download_image_to_pil(url: str) -> Image.Image:
+    data = http_get_bytes(url)
+    img = Image.open(io.BytesIO(data)).convert("RGB")
+    return img
+
+def crop_signature_macro(img: Image.Image, size: int = 512) -> Image.Image:
+    # simple lower-right macro crop (if smaller, clamp)
+    w, h = img.size
+    cw = min(size, w)
+    ch = min(size, h)
+    left = max(0, w - cw)
+    top = max(0, h - ch)
+    return img.crop((left, top, left + cw, top + ch))
+
+# -----------------------------------------------------------------------------
+# 3) CASE GENERATION (now uses IA for the authentic image)
+# -----------------------------------------------------------------------------
+def ensure_case_generated(case_id: str) -> Dict[str, Any]:
+    existing_public = case_ref(case_id).child("public").get()
+    if existing_public:
+        return existing_public
+
+    # Ensure we have at least some IA records; if not, auto-ingest a default set (one page)
+    pool = ia_pool_ref().get() or {}
+    if not pool:
+        try:
+            # Default query targets well-known museum collections with images
+            default_query = '(collection:(metropolitanmuseum OR smithsonian OR getty OR artic) AND mediatype:image)'
+            docs = ia_advanced_search(default_query, rows=100, page=1)
+            for d in docs:
+                try:
+                    ingest_ia_doc(d)
+                except Exception:
+                    continue
+        except Exception as e:
+            print("WARNING: IA default ingest failed:", e)
+
+    # Pick authentic from ia_pool deterministically
+    ia_item = choose_ia_item_for_case(case_id)
+    if not ia_item:
+        # absolute fallback (rare)
+        raise RuntimeError("No IA items available. Ingest needed.")
+
+    # Deterministic mode
+    case_seed = seed_for_date(case_id)
+    rng = random.Random(case_seed)
+    mode = "knowledge" if (case_seed % 2 == 0) else "observation"
+
+    # Style label (flavor text only)
+    style_period = "sourced from Internet Archive; museum catalog reproduction"
+
+    # Download authentic image
+    auth_img = download_image_to_pil(ia_item["download_url"])
+
+    images_urls: List[str] = []
+    signature_crops: List[str] = []
+
+    # Save authentic as image #1
+    images_urls.append(
+        save_image_return_url(auth_img, f"hidden_stroke/{case_id}/images/img_1.jpg")
+    )
+    # Macro crop for signature area
+    crop1 = crop_signature_macro(auth_img, 512)
+    signature_crops.append(
+        save_image_return_url(crop1, f"hidden_stroke/{case_id}/signature_crops/crop_1.jpg", quality=88)
+    )
+
+    if mode == "knowledge":
+        # Use the same authentic visual for all three; differences come from metadata only
+        for idx in [2, 3]:
+            images_urls.append(images_urls[0])  # same URL OK (client treats as separate cards)
+            signature_crops.append(signature_crops[0])
+    else:
+        # observation: generate 2 subtle variants (near-identical; tweak signature micro-geometry)
+        for i in range(2):
+            forg_prompt = """
+Create a near-identical variant of the provided painting. 
+Keep composition, palette, and lighting the same.
+Only introduce a subtle change in signature micro-geometry (baseline alignment, stroke overlap order, or curve spacing).
+No annotations. Differences must be visible only at macro zoom.
+"""
+            resp = client.models.generate_content(
+                model=GENERATION_MODEL,
+                contents=[forg_prompt, auth_img],
+                config=types.GenerateContentConfig(response_modalities=["IMAGE"])
+            )
+            f_img = None
+            for p in resp.candidates[0].content.parts:
+                if getattr(p, "inline_data", None):
+                    f_img = pil_from_inline_image_part(p)
+                    break
+            if f_img is None:
+                f_img = auth_img.copy()
+
+            url = save_image_return_url(f_img, f"hidden_stroke/{case_id}/images/img_{i+2}.jpg")
+            images_urls.append(url)
+            crop = crop_signature_macro(f_img, 512)
+            c_url = save_image_return_url(crop, f"hidden_stroke/{case_id}/signature_crops/crop_{i+2}.jpg", quality=88)
+            signature_crops.append(c_url)
+
+    # === Gemini: Case brief + 3 metadata bundles + ledger + solution ===
+    # Feed IA title/creator/year so the authentic bundle aligns with reality.
+    title = ia_item.get("title") or "Untitled"
+    creator = ia_item.get("creator") or ""
+    date = ia_item.get("date") or ""
+    rights = ia_item.get("rights") or ""
+    licenseurl = ia_item.get("licenseurl") or ""
+
+    meta_prompt = f"""
+You are generating a daily case for a noir art investigation game.
+
+MODE: {"KNOWLEDGE" if mode=="knowledge" else "OBSERVATION"}
+
+AUTHENTIC CONTEXT (from Internet Archive):
+- title: {title}
+- creator: {creator}
+- date: {date}
+- rights: {rights}
+- licenseurl: {licenseurl}
+
+TASK:
+1) Create a short, punchy "case_brief" (2–4 sentences) explaining why the artifact matters and why fraud is suspected — NO SPOILERS.
+2) Prepare THREE metadata bundles for images A,B,C with NEARLY IDENTICAL fields.
+   Ensure exactly ONE bundle is AUTHENTIC and that it corresponds to the above authentic context.
+   The other two are FORGERIES that are almost correct but contain subtle, reality-checkable anomalies.
+3) Provide a concise "ledger_summary" describing a believable ownership/payment trail.
+4) Provide the solution with: "answer_index" (0 for A, 1 for B, 2 for C) and detailed flags for signature/metadata/financial, plus an "explanation".
+
+OUTPUT STRICT JSON with this schema:
+{{
+  "case_brief": "...",
+  "metadata": [
+    {{"title":"...", "year": "...", "medium": "...", "ink_or_pigment": "...", "catalog_ref": "...", "ownership_chain": ["...","..."], "notes":"..."}},
+    {{"title":"...", "year": "...", "medium": "...", "ink_or_pigment": "...", "catalog_ref": "...", "ownership_chain": ["...","..."], "notes":"..."}},
+    {{"title":"...", "year": "...", "medium": "...", "ink_or_pigment": "...", "catalog_ref": "...", "ownership_chain": ["...","..."], "notes":"..."}}
+  ],
+  "ledger_summary": "short paragraph",
+  "solution": {{
+     "answer_index": 0,
+     "flags_signature": [ "..." ],
+     "flags_metadata": [ "..." ],
+     "flags_financial": [ "..." ],
+     "explanation": "A few sentences that justify the authentic pick without listing spoilers."
+  }}
+}}
+
+CONSTRAINTS:
+- Keep all three bundles plausible and near-identical at a glance.
+- Anomalies must be subtle and testable (chemistry/ink era, currency introductions, institution timelines, accession formats, etc.).
+- If MODE=KNOWLEDGE, the tells should be discoverable via metadata/ledger alone.
+- If MODE=OBSERVATION, include at least one signature micro-geometry flag in "flags_signature".
+- The authentic bundle should be consistent with the AUTHENTIC CONTEXT.
+"""
+    meta_resp = client.models.generate_content(
+        model=CATEGORY_MODEL,
+        contents=[meta_prompt]
+    )
+    raw_text = meta_resp.text.strip()
+    try:
+        meta_json = json.loads(raw_text)
+    except Exception:
+        cleaned = raw_text
+        if "```" in raw_text:
+            cleaned = raw_text.split("```")[1]
+            if cleaned.lower().startswith("json"):
+                cleaned = cleaned.split("\n", 1)[1]
+        meta_json = json.loads(cleaned)
+
+    case_brief = meta_json.get("case_brief", "A resurfaced portrait raises questions—its paper trail glitters a little too perfectly.")
+    metadata = meta_json.get("metadata", [])
+    ledger_summary = meta_json.get("ledger_summary", "")
+    solution = meta_json.get("solution", {})
+    answer_index = int(solution.get("answer_index", 0))
+    flags_signature = solution.get("flags_signature", [])
+    flags_metadata = solution.get("flags_metadata", [])
+    flags_financial = solution.get("flags_financial", [])
+    explanation = solution.get("explanation", "The authentic work aligns with period-accurate details; the others contain subtle contradictions.")
+
+    if len(metadata) != 3:
+        raise RuntimeError("Expected exactly 3 metadata bundles.")
+
+    public = {
+        "case_id": case_id,
+        "mode": mode,
+        "brief": case_brief,
+        "style_period": style_period,
+        "images": images_urls,
+        "signature_crops": signature_crops,
+        "metadata": metadata,          # sanitized (no answer)
+        "ledger_summary": ledger_summary,
+        "timer_seconds": TIMER_SECONDS,
+        "initial_ip": INITIAL_IP,
+        "tool_costs": TOOL_COSTS,
+        "credits": {
+            "source": "Internet Archive",
+            "identifier": ia_item.get("identifier"),
+            "title": title,
+            "creator": creator,
+            "rights": rights,
+            "licenseurl": licenseurl
+        }
+    }
+    solution_doc = {
+        "answer_index": answer_index,
+        "flags_signature": flags_signature,
+        "flags_metadata": flags_metadata,
+        "flags_financial": flags_financial,
+        "explanation": explanation
+    }
+
+    cref = case_ref(case_id)
+    cref.child("public").set(public)
+    cref.child("solution").set(solution_doc)
+    return public
+
+# -----------------------------------------------------------------------------
+# 4) SESSIONS, TOOLS, GUESS, LEADERBOARD (same behavior as before)
+# -----------------------------------------------------------------------------
+def create_session(user_id: str, username: str, case_id: str) -> Dict[str, Any]:
+    session_id = str(uuid.uuid4())
+    expires_at = (datetime.now(timezone.utc) + timedelta(seconds=TIMER_SECONDS)).isoformat()
+    session_doc = {
+        "session_id": session_id,
+        "user_id": user_id,
+        "username": username,
+        "case_id": case_id,
+        "ip_remaining": INITIAL_IP,
+        "started_at": datetime.now(timezone.utc).isoformat(),
+        "expires_at": expires_at,
+        "actions": [],
+        "status": "active"
+    }
+    sessions_ref().child(session_id).set(session_doc)
+    return session_doc
+
+def get_session(session_id: str) -> Dict[str, Any]:
+    return sessions_ref().child(session_id).get() or {}
+
+def require_active_session(req) -> Tuple[Dict[str, Any], Dict[str, Any]]:
+    session_id = req.headers.get("X-Session-Id", "")
+    if not session_id:
+        return {}, {"error": "Missing X-Session-Id header."}
+    sess = get_session(session_id)
+    if not sess or sess.get("status") != "active":
+        return {}, {"error": "Invalid or inactive session."}
+    now = datetime.now(timezone.utc)
+    exp = datetime.fromisoformat(sess["expires_at"].replace("Z", "+00:00"))
+    if now > exp:
+        sess["status"] = "expired"
+        sessions_ref().child(session_id).child("status").set("expired")
+        return {}, {"error": "Session expired."}
+    return sess, {}
+
+def spend_ip(session: Dict[str, Any], cost: int, action: Dict[str, Any]) -> Tuple[Dict[str, Any], Dict[str, Any]]:
+    if session["ip_remaining"] < cost:
+        return session, {"error": "Not enough Investigation Points."}
+    new_ip = session["ip_remaining"] - cost
+    session["ip_remaining"] = new_ip
+    action["ts"] = datetime.now(timezone.utc).isoformat()
+    sessions_ref().child(session["session_id"]).child("ip_remaining").set(new_ip)
+    sessions_ref().child(session["session_id"]).child("actions").push(action)
+    return session, {}
+
+def score_result(correct: bool, session: Dict[str, Any]) -> Dict[str, Any]:
+    exp = datetime.fromisoformat(session["expires_at"].replace("Z", "+00:00"))
+    now = datetime.now(timezone.utc)
+    seconds_left = max(0, int((exp - now).total_seconds()))
+    time_bonus = (seconds_left + 9) // 10
+    ip_bonus = session["ip_remaining"] * 2
+    base = 100 if correct else 0
+    penalty = 40 if not correct else 0
+    score = max(0, base + time_bonus + ip_bonus - penalty)
+    return {"score": score, "seconds_left": seconds_left, "ip_left": session["ip_remaining"]}
+
+def upsert_leaderboard(case_id: str, user_id: str, username: str, score: int):
+    plays_ref(case_id).child(user_id).set({
+        "user_id": user_id,
+        "username": username,
+        "score": score,
+        "ts": datetime.now(timezone.utc).isoformat()
+    })
+    plays = plays_ref(case_id).get() or {}
+    top = sorted(plays.values(), key=lambda x: x.get("score", 0), reverse=True)[:LEADERBOARD_TOP_N]
+    leaderboard_ref(case_id).set(top)
+
+# -----------------------------------------------------------------------------
+# 5) ROUTES
+# -----------------------------------------------------------------------------
+@app.route("/health", methods=["GET"])
+def health():
+    return jsonify({"ok": True, "time": datetime.now(timezone.utc).isoformat()})
+
+# --- Admin: Internet Archive ingestion ---
+@app.route("/admin/ingest-ia", methods=["POST"])
+def admin_ingest_ia():
+    if not ADMIN_KEY or request.headers.get("X-Admin-Key") != ADMIN_KEY:
+        return jsonify({"error": "Forbidden"}), 403
+
+    body = request.get_json() or {}
+    # Example default: a few reputable museum collections with images
+    query = body.get("query") or '(collection:(metropolitanmuseum OR smithsonian OR getty OR artic) AND mediatype:image)'
+    pages = int(body.get("pages") or 2)
+    rows = int(body.get("rows") or 100)
+    ingested = 0
+    errors = 0
+
+    for page in range(1, pages + 1):
+        try:
+            docs = ia_advanced_search(query, rows=rows, page=page)
+        except Exception as e:
+            errors += 1
+            continue
+        for d in docs:
+            ident = d.get("identifier")
+            if not ident:
+                continue
+            # skip if already ingested
+            if ia_pool_ref().child(ident).get():
+                continue
+            try:
+                rec = ingest_ia_doc(d)
+                if rec:
+                    ingested += 1
+            except Exception:
+                errors += 1
+                continue
+
+    pool_size = len(ia_pool_ref().get() or {})
+    return jsonify({"ok": True, "ingested": ingested, "errors": errors, "pool_size": pool_size})
+
+@app.route("/admin/ia-pool/stats", methods=["GET"])
+def ia_pool_stats():
+    if not ADMIN_KEY or request.headers.get("X-Admin-Key") != ADMIN_KEY:
+        return jsonify({"error": "Forbidden"}), 403
+    pool = ia_pool_ref().get() or {}
+    return jsonify({"pool_size": len(pool)})
+
+# --- Admin: pre-generate today's case (optional) ---
+@app.route("/admin/generate-today", methods=["POST"])
+def admin_generate_today():
+    if not ADMIN_KEY or request.headers.get("X-Admin-Key") != ADMIN_KEY:
+        return jsonify({"error": "Forbidden"}), 403
+    case_id = utc_today_str()
+    public = ensure_case_generated(case_id)
+    return jsonify({"generated": True, "case_id": case_id, "mode": public.get("mode")})
+
+# --- Player flow ---
+@app.route("/cases/today/start", methods=["POST"])
+def start_case():
+    user_id, username = extract_user_from_headers(request)
+    case_id = utc_today_str()
+    public = ensure_case_generated(case_id)
+
+    # Create/reuse an active session for this user+case
+    existing = sessions_ref().order_by_child("user_id").equal_to(user_id).get()
+    sess = None
+    if existing:
+        for sid, sdoc in existing.items():
+            if sdoc.get("case_id") == case_id and sdoc.get("status") == "active":
+                sess = sdoc
+                break
+    if not sess:
+        sess = create_session(user_id, username, case_id)
+
+    payload = {
+        "session_id": sess["session_id"],
+        "case": public
+    }
+    return jsonify(payload)
+
+@app.route("/cases/<case_id>/tool/signature", methods=["POST"])
+def tool_signature(case_id):
+    session, err = require_active_session(request)
+    if err: return jsonify(err), 400
+    if session["case_id"] != case_id:
+        return jsonify({"error": "Session/case mismatch."}), 400
+
+    body = request.get_json() or {}
+    img_index = int(body.get("image_index", 0))
+    if img_index not in [0,1,2]:
+        return jsonify({"error": "image_index must be 0,1,2"}), 400
+
+    session, err = spend_ip(session, TOOL_COSTS["signature"], {"type": "tool_signature", "image_index": img_index})
+    if err: return jsonify(err), 400
+
+    public = case_ref(case_id).child("public").get() or {}
+    crops = public.get("signature_crops", [])
+    crop_url = crops[img_index] if img_index < len(crops) else ""
+    hint = "Examine baseline alignment and stroke overlap." if public.get("mode") == "observation" else ""
+    return jsonify({"crop_url": crop_url, "hint": hint, "ip_remaining": session["ip_remaining"]})
+
+@app.route("/cases/<case_id>/tool/metadata", methods=["POST"])
+def tool_metadata(case_id):
+    session, err = require_active_session(request)
+    if err: return jsonify(err), 400
+    if session["case_id"] != case_id:
+        return jsonify({"error": "Session/case mismatch."}), 400
+
+    body = request.get_json() or {}
+    img_index = int(body.get("image_index", 0))
+    if img_index not in [0,1,2]:
+        return jsonify({"error": "image_index must be 0,1,2"}), 400
+
+    session, err = spend_ip(session, TOOL_COSTS["metadata"], {"type": "tool_metadata", "image_index": img_index})
+    if err: return jsonify(err), 400
+
+    solution = case_ref(case_id).child("solution").get() or {}
+    flags_metadata: List[str] = solution.get("flags_metadata", [])
+    hint = flags_metadata[0] if flags_metadata else "Check chronology, chemistry, and institutional formats."
+    return jsonify({"flags": [hint], "ip_remaining": session["ip_remaining"]})
+
+@app.route("/cases/<case_id>/tool/financial", methods=["POST"])
+def tool_financial(case_id):
+    session, err = require_active_session(request)
+    if err: return jsonify(err), 400
+    if session["case_id"] != case_id:
+        return jsonify({"error": "Session/case mismatch."}), 400
+
+    session, err = spend_ip(session, TOOL_COSTS["financial"], {"type": "tool_financial"})
+    if err: return jsonify(err), 400
+
+    solution = case_ref(case_id).child("solution").get() or {}
+    flags_financial: List[str] = solution.get("flags_financial", [])
+    hint = flags_financial[0] if flags_financial else "Follow currency, jurisdiction, and payment method timelines."
+    return jsonify({"flags": [hint], "ip_remaining": session["ip_remaining"]})
+
+@app.route("/cases/<case_id>/guess", methods=["POST"])
+def submit_guess(case_id):
+    session, err = require_active_session(request)
+    if err: return jsonify(err), 400
+    if session["case_id"] != case_id:
+        return jsonify({"error": "Session/case mismatch."}), 400
+
+    body = request.get_json() or {}
+    guess_index = int(body.get("image_index", -1))
+    rationale = (body.get("rationale") or "").strip()
+    if guess_index not in [0,1,2]:
+        return jsonify({"error": "image_index must be 0,1,2"}), 400
+
+    sessions_ref().child(session["session_id"]).child("status").set("finished")
+    session["status"] = "finished"
+
+    solution = case_ref(case_id).child("solution").get() or {}
+    answer_index = int(solution.get("answer_index", 0))
+    correct = (guess_index == answer_index)
+
+    summary = score_result(correct, session)
+    upsert_leaderboard(case_id, session["user_id"], session["username"], summary["score"])
+
+    reveal = {
+        "authentic_index": answer_index,
+        "explanation": solution.get("explanation", ""),
+        "flags_signature": solution.get("flags_signature", []),
+        "flags_metadata": solution.get("flags_metadata", []),
+        "flags_financial": solution.get("flags_financial", [])
+    }
+
+    plays_ref(case_id).child(session["user_id"]).update({
+        "rationale": rationale,
+        "correct": correct,
+        "score": summary["score"],
+        "seconds_left": summary["seconds_left"],
+        "ip_left": summary["ip_left"],
+        "finished_at": datetime.now(timezone.utc).isoformat()
+    })
+
+    return jsonify({
+        "correct": correct,
+        "score": summary["score"],
+        "timeLeft": summary["seconds_left"],
+        "ipLeft": summary["ip_left"],
+        "reveal": reveal
+    })
+
+@app.route("/leaderboard/daily", methods=["GET"])
+def leaderboard_daily():
+    case_id = utc_today_str()
+    top = leaderboard_ref(case_id).get() or []
+    user_id, username = extract_user_from_headers(request)
+    me = plays_ref(case_id).child(user_id).get() or {}
+    rank = None
+    if top:
+        for i, row in enumerate(top):
+            if row.get("user_id") == user_id:
+                rank = i + 1
+                break
+    return jsonify({"case_id": case_id, "top": top, "me": {"score": me.get("score"), "rank": rank}})
+
+# -----------------------------------------------------------------------------
+# 6) MAIN
+# -----------------------------------------------------------------------------
+if __name__ == "__main__":
+    app.run(host="0.0.0.0", port=int(os.environ.get("PORT", "7860")), debug=True)