Stages 7+8: LLM normalisation and review workbench

smoke_signal/scripts/05_llm_normalise.py

@@ -0,0 +1,507 @@
+#!/usr/bin/env python3
+"""
+Smoke Signal — Stage 7: LLM Normalisation Layer
+=================================================
+Takes low-confidence or visually complex regions from Stage 5
+and sends them to an LLM (via HF Inference API) for cleanup.
+
+Rules (non-negotiable):
+  - LLM receives: page image crop + raw OCR candidates
+  - LLM must return strict JSON only — no free text, no preamble
+  - Uncertain words must be marked uncertain, NEVER silently guessed
+  - LLM may NOT invent text that isn't visually present
+  - Only low-confidence / flagged pages are sent (cost + drift control)
+  - Every call logs: prompt version, model, input hash, output hash, cost
+
+Output per region:
+  {
+    "text_raw":         "original OCR text",
+    "text_clean":       "LLM corrected text",
+    "uncertain_words":  ["word1", "word2"],
+    "confidence_notes": "why confidence is low",
+    "changed_from_ocr": true/false,
+    "visible_context":  "brief note on what the LLM can see"
+  }
+
+Usage:
+    python scripts/05_llm_normalise.py
+    python scripts/05_llm_normalise.py --book-id SS-BOOK-0001
+    python scripts/05_llm_normalise.py --dry-run
+    python scripts/05_llm_normalise.py --confidence-below 0.80
+"""
+
+import argparse
+import base64
+import hashlib
+import json
+import sys
+import time
+from datetime import datetime
+from pathlib import Path
+from typing import Optional
+
+# ── Paths ──────────────────────────────────────────────────────────────────────
+ROOT          = Path(__file__).resolve().parents[1]
+MANIFEST_CSV  = ROOT / "manifest" / "source_manifest.csv"
+REGIONS_DIR   = ROOT / "regions"
+OCR_RAW_DIR   = ROOT / "ocr_raw"
+RENDERS_DIR   = ROOT / "renders"
+LOGS_DIR      = ROOT / "logs"
+REVIEW_DIR    = ROOT / "review"
+CLEANED_DIR   = ROOT / "regions" / "cleaned"
+
+CLEANED_DIR.mkdir(parents=True, exist_ok=True)
+LOGS_DIR.mkdir(parents=True, exist_ok=True)
+
+# ── Config (freeze before running — do not change mid-batch) ──────────────────
+CONFIG = {
+    "config_version":       "ss_llm_v0.1",
+    "prompt_version":       "ss_prompt_v0.1",
+    "model":                "meta-llama/Llama-3.2-11B-Vision-Instruct",  # HF Inference API
+    "confidence_threshold": 0.75,   # only send pages below this
+    "max_pages_per_run":    50,     # cost control — cap per batch
+    "temperature":          0.1,    # low = deterministic, no hallucination
+    "max_new_tokens":       512,
+    "eligible_statuses":    ["ocred"],
+    "story_classes":        ["narration", "dialogue-speech-bubble", "caption"],
+}
+
+# ── Prompt (versioned — never change without bumping prompt_version) ───────────
+SYSTEM_PROMPT = """You are a precise OCR correction assistant for children's picture books.
+
+RULES — follow exactly:
+1. Return ONLY valid JSON. No preamble, no explanation, no markdown fences.
+2. Correct OCR errors you can see in the image. Do NOT invent text.
+3. If a word is unclear or unreadable, add it to uncertain_words — do NOT guess.
+4. Keep the author's exact words, punctuation, and line breaks.
+5. Do not add, remove, or reorder words unless fixing a clear OCR error.
+6. changed_from_ocr must be true only if you changed something.
+
+Return this exact JSON structure:
+{
+  "text_clean": "corrected text here",
+  "uncertain_words": ["list", "of", "unclear", "words"],
+  "confidence_notes": "brief note on what made this hard to read",
+  "changed_from_ocr": false,
+  "visible_context_notes": "brief note on what you can see in the image"
+}"""
+
+USER_PROMPT_TEMPLATE = """Here is the raw OCR output for a picture book page region:
+
+RAW OCR: {raw_text}
+REGION CLASS: {region_class}
+OCR CONFIDENCE: {confidence}
+
+Please examine the image crop and return the corrected JSON."""
+
+
+# ── HF Inference API ───────────────────────────────────────────────────────────
+def _get_hf_token() -> Optional[str]:
+    """Get HF token from environment or huggingface_hub cache."""
+    import os
+    token = os.environ.get("HF_TOKEN") or os.environ.get("HUGGINGFACE_HUB_TOKEN")
+    if token:
+        return token
+    try:
+        from huggingface_hub import get_token
+        return get_token()
+    except Exception:
+        return None
+
+
+def call_llm_with_image(
+    image_path: Path,
+    raw_text: str,
+    region_class: str,
+    confidence: float,
+) -> dict:
+    """
+    Call HF Inference API with image + OCR text.
+    Returns parsed JSON result or error dict.
+    """
+    import urllib.request
+    import urllib.error
+
+    token = _get_hf_token()
+    if not token:
+        return {
+            "error": "no_hf_token",
+            "text_clean": raw_text,
+            "uncertain_words": [],
+            "confidence_notes": "HF token not found — set HF_TOKEN env var or run huggingface-cli login",
+            "changed_from_ocr": False,
+        }
+
+    # Encode image as base64
+    try:
+        with open(image_path, "rb") as f:
+            image_b64 = base64.b64encode(f.read()).decode("utf-8")
+        image_ext = image_path.suffix.lower().replace(".", "")
+        media_type = f"image/{image_ext if image_ext in ('png','jpg','jpeg','webp') else 'png'}"
+    except Exception as e:
+        return {"error": f"image_load_failed: {e}", "text_clean": raw_text,
+                "uncertain_words": [], "changed_from_ocr": False}
+
+    user_message = USER_PROMPT_TEMPLATE.format(
+        raw_text=raw_text[:800],  # truncate for token budget
+        region_class=region_class,
+        confidence=round(confidence, 3),
+    )
+
+    payload = json.dumps({
+        "model": CONFIG["model"],
+        "messages": [
+            {"role": "system", "content": SYSTEM_PROMPT},
+            {
+                "role": "user",
+                "content": [
+                    {
+                        "type": "image_url",
+                        "image_url": {"url": f"data:{media_type};base64,{image_b64}"}
+                    },
+                    {"type": "text", "text": user_message}
+                ]
+            }
+        ],
+        "max_tokens": CONFIG["max_new_tokens"],
+        "temperature": CONFIG["temperature"],
+    }).encode("utf-8")
+
+    api_url = f"https://api-inference.huggingface.co/models/{CONFIG['model']}/v1/chat/completions"
+
+    req = urllib.request.Request(
+        api_url,
+        data=payload,
+        headers={
+            "Authorization": f"Bearer {token}",
+            "Content-Type": "application/json",
+        },
+        method="POST",
+    )
+
+    try:
+        with urllib.request.urlopen(req, timeout=30) as resp:
+            response_data = json.loads(resp.read().decode("utf-8"))
+        raw_response = response_data["choices"][0]["message"]["content"].strip()
+    except urllib.error.HTTPError as e:
+        return {"error": f"http_{e.code}: {e.reason}", "text_clean": raw_text,
+                "uncertain_words": [], "changed_from_ocr": False}
+    except Exception as e:
+        return {"error": str(e), "text_clean": raw_text,
+                "uncertain_words": [], "changed_from_ocr": False}
+
+    # Parse JSON response — strip markdown fences if model added them
+    try:
+        clean = raw_response.strip()
+        if clean.startswith("```"):
+            clean = clean.split("```")[1]
+            if clean.startswith("json"):
+                clean = clean[4:]
+        result = json.loads(clean.strip())
+    except json.JSONDecodeError:
+        return {
+            "error": "invalid_json_response",
+            "raw_response": raw_response[:500],
+            "text_clean": raw_text,
+            "uncertain_words": [],
+            "changed_from_ocr": False,
+        }
+
+    return result
+
+
+# ── Input hash (for audit trail) ──────────────────────────────────────────────
+def _input_hash(text: str, image_path: Path) -> str:
+    h = hashlib.sha256()
+    h.update(text.encode("utf-8"))
+    if image_path.exists():
+        with open(image_path, "rb") as f:
+            h.update(f.read(4096))  # first 4kb sufficient for fingerprint
+    return h.hexdigest()[:16]
+
+
+def _output_hash(result: dict) -> str:
+    return hashlib.sha256(
+        json.dumps(result, sort_keys=True).encode("utf-8")
+    ).hexdigest()[:16]
+
+
+# ── Load region data ───────────────────────────────────────────────────────────
+def load_ordered_regions(book_id: str) -> Optional[dict]:
+    path = REGIONS_DIR / f"{book_id}_ordered_regions.json"
+    return json.load(open(path)) if path.exists() else None
+
+
+# ── Per-region normalisation ───────────────────────────────────────────────────
+def normalise_region(
+    book_id: str,
+    page_num: int,
+    region: dict,
+    render_path: Optional[str],
+    dry_run: bool,
+) -> dict:
+    """Normalise a single region via LLM. Returns enriched region dict."""
+
+    raw_text     = region.get("text", "").strip()
+    region_class = region.get("region_class", "narration")
+    confidence   = region.get("confidence", 1.0)
+    region_id    = region.get("region_id", f"{book_id}_p{page_num:04d}")
+
+    if dry_run:
+        return {
+            **region,
+            "text_clean":           raw_text,
+            "uncertain_words":      [],
+            "confidence_notes":     "dry-run",
+            "changed_from_ocr":     False,
+            "visible_context_notes": "dry-run",
+            "llm_model":            CONFIG["model"],
+            "prompt_version":       CONFIG["prompt_version"],
+            "normalised_at":        datetime.utcnow().isoformat() + "Z",
+            "dry_run":              True,
+        }
+
+    # Find render image
+    img_path = None
+    if render_path:
+        candidate = ROOT / render_path if not Path(render_path).is_absolute() else Path(render_path)
+        if candidate.exists():
+            img_path = candidate
+
+    if img_path is None:
+        # Try to find any render for this book/page
+        book_renders = RENDERS_DIR / book_id
+        if book_renders.exists():
+            candidates = sorted(book_renders.glob(f"{book_id}_page_{page_num:04d}_*.png"))
+            if candidates:
+                img_path = candidates[0]
+
+    if img_path is None:
+        return {
+            **region,
+            "text_clean":       raw_text,
+            "uncertain_words":  [],
+            "confidence_notes": "no_render_available",
+            "changed_from_ocr": False,
+            "error":            "no_render_found",
+        }
+
+    in_hash  = _input_hash(raw_text, img_path)
+
+    llm_result = call_llm_with_image(img_path, raw_text, region_class, confidence)
+
+    out_hash = _output_hash(llm_result)
+
+    return {
+        **region,
+        "text_clean":            llm_result.get("text_clean", raw_text),
+        "uncertain_words":       llm_result.get("uncertain_words", []),
+        "confidence_notes":      llm_result.get("confidence_notes", ""),
+        "changed_from_ocr":      llm_result.get("changed_from_ocr", False),
+        "visible_context_notes": llm_result.get("visible_context_notes", ""),
+        "llm_model":             CONFIG["model"],
+        "prompt_version":        CONFIG["prompt_version"],
+        "input_hash":            in_hash,
+        "output_hash":           out_hash,
+        "llm_error":             llm_result.get("error"),
+        "normalised_at":         datetime.utcnow().isoformat() + "Z",
+    }
+
+
+# ── Per-book normalisation ────────────────────────────────────────────────────
+def normalise_book(
+    book_id: str,
+    filename: str,
+    confidence_threshold: float,
+    max_pages: int,
+    dry_run: bool,
+) -> tuple:
+    print(f"\n  [{book_id}] {filename}")
+
+    regions_data = load_ordered_regions(book_id)
+    if regions_data is None:
+        print(f"    ✗ No region data. Run 04_region_detector.py first.")
+        return None, {"error": "no_region_data"}
+
+    pages_to_process = []
+    for page in regions_data.get("pages", []):
+        page_conf = page.get("page_confidence", 1.0)
+        route     = page.get("route", "embedded_text")
+        if route == "embedded_text":
+            continue
+        if page_conf < confidence_threshold:
+            pages_to_process.append(page)
+
+    if not pages_to_process:
+        print(f"    ✓ No pages below confidence threshold {confidence_threshold} — skipping.")
+        return regions_data, {}
+
+    # Apply page cap
+    if len(pages_to_process) > max_pages:
+        print(f"    ⚠️  {len(pages_to_process)} pages need normalisation — capping at {max_pages}")
+        pages_to_process = pages_to_process[:max_pages]
+
+    print(f"    Pages to normalise: {len(pages_to_process)}")
+
+    total_changed  = 0
+    total_uncertain = 0
+    total_errors   = 0
+    call_log       = []
+
+    # Process each page
+    page_index = {p["page_number"]: i for i, p in enumerate(regions_data["pages"])}
+
+    for page in pages_to_process:
+        page_num    = page["page_number"]
+        page_conf   = page.get("page_confidence", 0)
+        render_path = None
+
+        # Find render path from OCR raw data
+        ocr_path = OCR_RAW_DIR / book_id / f"{book_id}_ocr_raw.json"
+        if ocr_path.exists():
+            ocr_data = json.load(open(ocr_path))
+            for ocr_page in ocr_data.get("pages", []):
+                if ocr_page.get("page_number") == page_num:
+                    render_path = ocr_page.get("render_path")
+                    break
+
+        print(f"    Page {page_num:3d} (conf={page_conf:.2f}): ", end="", flush=True)
+
+        normalised_regions = []
+        for region in page.get("regions", []):
+            region_class = region.get("region_class", "narration")
+
+            # Only normalise story-relevant regions
+            if region_class not in CONFIG["story_classes"]:
+                normalised_regions.append(region)
+                continue
+
+            region_conf = region.get("confidence", 1.0)
+            if region_conf >= confidence_threshold:
+                normalised_regions.append(region)
+                continue
+
+            result = normalise_region(book_id, page_num, region, render_path, dry_run)
+
+            if result.get("changed_from_ocr"):
+                total_changed += 1
+            if result.get("uncertain_words"):
+                total_uncertain += len(result["uncertain_words"])
+            if result.get("llm_error"):
+                total_errors += 1
+
+            call_log.append({
+                "book_id":        book_id,
+                "page_number":    page_num,
+                "region_id":      region.get("region_id"),
+                "input_hash":     result.get("input_hash"),
+                "output_hash":    result.get("output_hash"),
+                "changed":        result.get("changed_from_ocr", False),
+                "uncertain_count": len(result.get("uncertain_words", [])),
+                "error":          result.get("llm_error"),
+                "model":          CONFIG["model"],
+                "prompt_version": CONFIG["prompt_version"],
+            })
+
+            normalised_regions.append(result)
+
+        # Update page in regions data
+        idx = page_index.get(page_num)
+        if idx is not None:
+            regions_data["pages"][idx]["regions"] = normalised_regions
+            regions_data["pages"][idx]["normalised"] = True
+
+        changed_count   = sum(1 for r in normalised_regions if r.get("changed_from_ocr"))
+        uncertain_count = sum(len(r.get("uncertain_words", [])) for r in normalised_regions)
+        print(f"changed={changed_count} uncertain_words={uncertain_count}")
+
+    # ── Save cleaned regions ──────────────────────────────────────────────────
+    if not dry_run:
+        regions_data["normalised_at"]    = datetime.utcnow().isoformat() + "Z"
+        regions_data["prompt_version"]   = CONFIG["prompt_version"]
+        regions_data["llm_model"]        = CONFIG["model"]
+        regions_data["normalisation_log"] = call_log
+
+        cleaned_path = CLEANED_DIR / f"{book_id}_cleaned_regions.json"
+        with open(cleaned_path, "w", encoding="utf-8") as f:
+            json.dump(regions_data, f, indent=2)
+        print(f"    Cleaned regions → {cleaned_path.relative_to(ROOT)}")
+
+        # Log file
+        log_path = LOGS_DIR / f"llm_calls_{book_id}_{datetime.utcnow().strftime('%Y%m%d')}.json"
+        with open(log_path, "w") as f:
+            json.dump(call_log, f, indent=2)
+
+    print(f"    Total changed={total_changed} | uncertain_words={total_uncertain} | errors={total_errors}")
+    return regions_data, {}
+
+
+# ── Main ───────────────────────────────────────────────────────────────────────
+def main():
+    parser = argparse.ArgumentParser(description="Smoke Signal — Stage 7: LLM Normalisation")
+    parser.add_argument("--book-id",           help="Process a single book by ID")
+    parser.add_argument("--batch-id",          help="Tag this run with a batch ID")
+    parser.add_argument("--confidence-below",  type=float, default=CONFIG["confidence_threshold"],
+                        help=f"Only process pages below this confidence (default {CONFIG['confidence_threshold']})")
+    parser.add_argument("--max-pages",         type=int, default=CONFIG["max_pages_per_run"],
+                        help=f"Max pages per book per run (default {CONFIG['max_pages_per_run']})")
+    parser.add_argument("--dry-run",           action="store_true")
+    args = parser.parse_args()
+
+    run_id   = args.batch_id or f"SS-RUN-{datetime.utcnow().strftime('%Y%m%d-%H%M%S')}"
+    dry_run  = args.dry_run
+
+    print(f"\n{'='*60}")
+    print(f"  Smoke Signal — Stage 7: LLM Normalisation")
+    print(f"  Run ID    : {run_id}")
+    print(f"  Model     : {CONFIG['model']}")
+    print(f"  Prompt    : {CONFIG['prompt_version']}")
+    print(f"  Threshold : conf < {args.confidence_below}")
+    print(f"  Max pages : {args.max_pages}")
+    if dry_run:
+        print(f"  Mode      : DRY RUN")
+    print(f"{'='*60}")
+
+    # Find books with region data
+    if args.book_id:
+        region_files = [REGIONS_DIR / f"{args.book_id}_ordered_regions.json"]
+    else:
+        region_files = sorted(REGIONS_DIR.glob("*_ordered_regions.json"))
+
+    if not region_files:
+        print("\n  No region files found. Run 04_region_detector.py first.")
+        sys.exit(0)
+
+    print(f"\n  Books to process: {len(region_files)}")
+
+    results  = []
+    t_start  = time.time()
+
+    for region_file in region_files:
+        book_id  = region_file.stem.replace("_ordered_regions", "")
+        filename = book_id  # fallback
+
+        _, error = normalise_book(
+            book_id,
+            filename,
+            args.confidence_below,
+            args.max_pages,
+            dry_run,
+        )
+
+        results.append({"book_id": book_id, "error": error})
+
+    elapsed   = round(time.time() - t_start, 1)
+    succeeded = sum(1 for r in results if not r.get("error"))
+
+    print(f"\n{'─'*60}")
+    print(f"  Books processed : {len(results)}")
+    print(f"  Succeeded       : {succeeded}")
+    print(f"  Time            : {elapsed}s")
+    print(f"{'─'*60}")
+    print(f"\n  Cleaned regions → {CLEANED_DIR.relative_to(ROOT)}")
+    print(f"  Next: Run 06_review_workbench.py (Stage 8)\n")
+
+
+if __name__ == "__main__":
+    main()

smoke_signal/scripts/06_review_workbench.py

@@ -0,0 +1,628 @@
+#!/usr/bin/env python3
+"""
+Smoke Signal — Stage 8: Human Review Workbench
+================================================
+Gradio app for reviewing low-confidence OCR pages.
+
+Reviewer actions per page:
+  - ACCEPT   : text is correct, pass to Codex export
+  - EDIT     : correct the text, then accept
+  - REJECT   : unusable, exclude from export
+  - QUARANTINE: flag for specialist review
+  - ILLUSTRATION ONLY: no text on this page
+
+Captures: reviewer ID, timestamp, edits, reason codes, final status.
+
+To run locally:
+    pip install gradio
+    python scripts/06_review_workbench.py
+
+To deploy on HF Spaces:
+    This file should be copied to the root as smoke_signal_review.py
+    or integrated into the main app.py as a new tab.
+"""
+
+import csv
+import json
+import os
+from datetime import datetime
+from pathlib import Path
+from typing import Optional
+
+import gradio as gr
+
+# ── Paths ──────────────────────────────────────────────────────────────────────
+ROOT        = Path(__file__).resolve().parents[1]
+REVIEW_DIR  = ROOT / "review"
+REGIONS_DIR = ROOT / "regions"
+CLEANED_DIR = ROOT / "regions" / "cleaned"
+RENDERS_DIR = ROOT / "renders"
+EXPORTS_DIR = ROOT / "exports"
+
+REVIEW_DIR.mkdir(parents=True, exist_ok=True)
+EXPORTS_DIR.mkdir(parents=True, exist_ok=True)
+
+QUEUE_CSV    = REVIEW_DIR / "review_queue.csv"
+DECISIONS_CSV = REVIEW_DIR / "review_decisions.csv"
+
+# ── Reason codes ───────────────────────────────────────────────────────────────
+REASON_CODES = [
+    "OCR_MISS",
+    "OCR_WRONG_WORD",
+    "REGION_MISSING",
+    "REGION_FALSE_POSITIVE",
+    "READING_ORDER_ERROR",
+    "DECORATIVE_FONT",
+    "SPEECH_BUBBLE_ERROR",
+    "LOW_CONTRAST",
+    "SCAN_SKEW_BLUR",
+    "NON_STORY_TEXT",
+    "RIGHTS_UNCLEAR",
+    "DUPLICATE_SOURCE",
+    "LLM_OVER_CORRECTION",
+    "MANUAL_TRANSCRIPTION_REQUIRED",
+    "OTHER",
+]
+
+REVIEW_STATUSES = ["pending", "accepted", "edited", "rejected", "quarantined", "illustration-only"]
+
+# ── CSS ────────────────────────────────────────────────────────────────────────
+CSS = """
+@import url('https://fonts.googleapis.com/css2?family=Playfair+Display:wght@700;900&family=Source+Code+Pro:wght@400;600&family=Lato:wght@300;400;700&display=swap');
+
+:root {
+    --ink:      #1a1a2e;
+    --paper:    #f5f0e8;
+    --smoke:    #2d3561;
+    --signal:   #e94560;
+    --ash:      #8892b0;
+    --accepted: #00b894;
+    --rejected: #e17055;
+    --quarantine: #fdcb6e;
+    --pending:  #74b9ff;
+}
+
+.gradio-container {
+    background: var(--paper) !important;
+    font-family: 'Lato', sans-serif !important;
+    max-width: none !important;
+}
+
+footer { display: none !important; }
+
+#ss-header {
+    background: var(--ink);
+    padding: 20px 32px;
+    border-bottom: 3px solid var(--signal);
+    display: flex;
+    align-items: center;
+    gap: 20px;
+}
+
+#ss-title {
+    font-family: 'Playfair Display', serif;
+    font-size: 28px;
+    font-weight: 900;
+    color: var(--paper);
+    letter-spacing: -0.5px;
+    margin: 0;
+}
+
+#ss-subtitle {
+    font-family: 'Source Code Pro', monospace;
+    font-size: 11px;
+    color: var(--ash);
+    letter-spacing: 3px;
+    text-transform: uppercase;
+    margin: 0;
+}
+
+#ss-signal {
+    color: var(--signal);
+    font-size: 36px;
+    font-weight: 900;
+}
+
+.queue-panel {
+    background: white;
+    border: 1px solid #e0d9cc;
+    border-radius: 8px;
+    padding: 16px;
+    height: 600px;
+    overflow-y: auto;
+}
+
+.queue-item {
+    padding: 12px 14px;
+    border-radius: 6px;
+    margin-bottom: 8px;
+    cursor: pointer;
+    border: 2px solid transparent;
+    transition: all 0.15s;
+    font-size: 13px;
+}
+
+.queue-item:hover { border-color: var(--smoke); }
+.queue-item.active { border-color: var(--signal); background: #fff5f7; }
+.queue-item.pending   { border-left: 4px solid var(--pending); }
+.queue-item.accepted  { border-left: 4px solid var(--accepted); opacity: 0.6; }
+.queue-item.rejected  { border-left: 4px solid var(--rejected); opacity: 0.6; }
+.queue-item.quarantined { border-left: 4px solid var(--quarantine); }
+
+.page-image-panel {
+    background: #2a2a2a;
+    border-radius: 8px;
+    min-height: 400px;
+    display: flex;
+    align-items: center;
+    justify-content: center;
+}
+
+.confidence-badge {
+    display: inline-block;
+    padding: 3px 10px;
+    border-radius: 999px;
+    font-size: 12px;
+    font-weight: 700;
+    font-family: 'Source Code Pro', monospace;
+}
+
+.conf-high    { background: #d4f5e9; color: #00695c; }
+.conf-medium  { background: #fff3cd; color: #856404; }
+.conf-low     { background: #fde8e8; color: #c62828; }
+.conf-quarantine { background: #2a2a2a; color: #fdcb6e; }
+
+.action-btn {
+    font-weight: 700 !important;
+    font-size: 14px !important;
+    border-radius: 6px !important;
+    min-height: 44px !important;
+    transition: transform 0.1s !important;
+}
+
+.action-btn:active { transform: scale(0.97) !important; }
+
+.accept-btn  { background: var(--accepted) !important; color: white !important; }
+.reject-btn  { background: var(--rejected) !important; color: white !important; }
+.quar-btn    { background: var(--quarantine) !important; color: var(--ink) !important; }
+.illus-btn   { background: var(--smoke) !important; color: white !important; }
+
+.stats-bar {
+    background: var(--ink);
+    color: var(--paper);
+    padding: 10px 20px;
+    border-radius: 6px;
+    font-family: 'Source Code Pro', monospace;
+    font-size: 12px;
+    display: flex;
+    gap: 24px;
+    margin-bottom: 12px;
+}
+
+.stat-item { display: flex; flex-direction: column; gap: 2px; }
+.stat-value { font-size: 20px; font-weight: 600; }
+.stat-label { color: var(--ash); font-size: 10px; letter-spacing: 1px; }
+
+.ocr-text-box textarea {
+    font-family: 'Source Code Pro', monospace !important;
+    font-size: 14px !important;
+    background: #fafaf8 !important;
+    border: 2px solid #e0d9cc !important;
+    border-radius: 6px !important;
+}
+
+.ocr-text-box textarea:focus {
+    border-color: var(--signal) !important;
+}
+"""
+
+# ── Data loading ───────────────────────────────────────────────────────────────
+def load_queue() -> list:
+    """Load the review queue CSV."""
+    if not QUEUE_CSV.exists():
+        return []
+    with open(QUEUE_CSV, newline="", encoding="utf-8") as f:
+        return list(csv.DictReader(f))
+
+
+def load_decisions() -> dict:
+    """Load existing decisions keyed by region_id."""
+    decisions = {}
+    if not DECISIONS_CSV.exists():
+        return decisions
+    with open(DECISIONS_CSV, newline="", encoding="utf-8") as f:
+        for row in csv.DictReader(f):
+            decisions[row.get("region_id", "")] = row
+    return decisions
+
+
+def save_decision(
+    region_id: str,
+    book_id: str,
+    page: int,
+    status: str,
+    final_text: str,
+    reason_code: str,
+    reviewer: str,
+    notes: str,
+) -> None:
+    """Append or update a decision record."""
+    fields = [
+        "region_id", "book_id", "page", "status",
+        "final_text", "reason_code", "reviewer", "notes", "decided_at"
+    ]
+    existing = load_decisions()
+    existing[region_id] = {
+        "region_id":  region_id,
+        "book_id":    book_id,
+        "page":       page,
+        "status":     status,
+        "final_text": final_text,
+        "reason_code": reason_code,
+        "reviewer":   reviewer,
+        "notes":      notes,
+        "decided_at": datetime.utcnow().isoformat() + "Z",
+    }
+    write_header = not DECISIONS_CSV.exists()
+    with open(DECISIONS_CSV, "w", newline="", encoding="utf-8") as f:
+        writer = csv.DictWriter(f, fieldnames=fields)
+        writer.writeheader()
+        writer.writerows(existing.values())
+
+
+def get_queue_stats(queue: list, decisions: dict) -> dict:
+    total     = len(queue)
+    decided   = len(decisions)
+    pending   = total - decided
+    accepted  = sum(1 for d in decisions.values() if d["status"] == "accepted")
+    edited    = sum(1 for d in decisions.values() if d["status"] == "edited")
+    rejected  = sum(1 for d in decisions.values() if d["status"] == "rejected")
+    quarantined = sum(1 for d in decisions.values() if d["status"] == "quarantined")
+    return {
+        "total": total, "pending": pending, "accepted": accepted,
+        "edited": edited, "rejected": rejected, "quarantined": quarantined,
+    }
+
+
+# ── Image loader ───────────────────────────────────────────────────────────────
+def get_page_image(book_id: str, page: str) -> Optional[str]:
+    """Find the rendered page image."""
+    try:
+        page_num = int(page)
+    except (ValueError, TypeError):
+        return None
+
+    book_dir = RENDERS_DIR / str(book_id)
+    if book_dir.exists():
+        candidates = sorted(book_dir.glob(f"{book_id}_page_{page_num:04d}_*.png"))
+        if candidates:
+            return str(candidates[0])
+    return None
+
+
+# ── Queue HTML builder ─────────────────────────────────────────────────────────
+def build_queue_html(queue: list, decisions: dict, active_idx: int = 0) -> str:
+    if not queue:
+        return "<div style='padding:20px;color:#888;font-family:monospace'>No items in review queue.<br>Run the pipeline first.</div>"
+
+    items = []
+    for i, item in enumerate(queue):
+        region_id = item.get("region_id", "")
+        decision  = decisions.get(region_id, {})
+        status    = decision.get("status", item.get("status", "pending"))
+        conf      = float(item.get("confidence", 0))
+        page      = item.get("page", "?")
+        book_id   = item.get("book_id", "?")
+        conf_str  = f"{conf:.0%}"
+        active    = "active" if i == active_idx else ""
+        items.append(f"""
+        <div class="queue-item {status} {active}" onclick="selectItem({i})" id="qi-{i}">
+            <div style="display:flex;justify-content:space-between;align-items:center">
+                <span style="font-weight:700;color:#1a1a2e">{book_id} · p{page}</span>
+                <span style="font-size:11px;color:#888">{status.upper()}</span>
+            </div>
+            <div style="margin-top:4px;font-size:12px;color:#555">
+                conf: <b style="color:{'#c62828' if conf < 0.6 else '#856404' if conf < 0.85 else '#00695c'}">{conf_str}</b>
+                &nbsp;·&nbsp; {item.get('region_class','?')}
+            </div>
+        </div>""")
+
+    return f"<div class='queue-panel'>{''.join(items)}</div>"
+
+
+def build_stats_html(stats: dict) -> str:
+    progress = (stats['accepted'] + stats['edited']) / max(stats['total'], 1) * 100
+    return f"""
+    <div class="stats-bar">
+        <div class="stat-item"><span class="stat-value">{stats['total']}</span><span class="stat-label">TOTAL</span></div>
+        <div class="stat-item"><span class="stat-value" style="color:var(--pending)">{stats['pending']}</span><span class="stat-label">PENDING</span></div>
+        <div class="stat-item"><span class="stat-value" style="color:var(--accepted)">{stats['accepted'] + stats['edited']}</span><span class="stat-label">APPROVED</span></div>
+        <div class="stat-item"><span class="stat-value" style="color:var(--rejected)">{stats['rejected']}</span><span class="stat-label">REJECTED</span></div>
+        <div class="stat-item"><span class="stat-value" style="color:var(--quarantine)">{stats['quarantined']}</span><span class="stat-label">QUARANTINED</span></div>
+        <div class="stat-item" style="flex:1">
+            <span class="stat-label">PROGRESS</span>
+            <div style="background:#333;border-radius:4px;height:8px;margin-top:6px">
+                <div style="background:var(--accepted);width:{progress:.0f}%;height:8px;border-radius:4px;transition:width 0.3s"></div>
+            </div>
+        </div>
+    </div>"""
+
+
+# ── Gradio app ────────────────────────────────────────────────────────────────
+def build_app():
+
+    queue     = load_queue()
+    decisions = load_decisions()
+    state     = {"idx": 0, "queue": queue, "decisions": decisions}
+
+    def get_current_item():
+        q = state["queue"]
+        if not q:
+            return None
+        idx = min(state["idx"], len(q) - 1)
+        return q[idx]
+
+    def refresh_view():
+        queue     = state["queue"]
+        decisions = state["decisions"]
+        item      = get_current_item()
+        stats     = get_queue_stats(queue, decisions)
+        stats_html = build_stats_html(stats)
+        queue_html = build_queue_html(queue, decisions, state["idx"])
+
+        if not item:
+            return (
+                stats_html, queue_html,
+                None, "", "", "", "pending", "", "",
+                "No items in queue"
+            )
+
+        region_id = item.get("region_id", "")
+        decision  = decisions.get(region_id, {})
+        book_id   = item.get("book_id", "")
+        page      = item.get("page", "")
+        conf      = float(item.get("confidence", 0))
+        conf_class = "conf-low" if conf < 0.6 else "conf-medium" if conf < 0.85 else "conf-high"
+
+        raw_text   = item.get("raw_ocr", "")
+        final_text = decision.get("final_text", raw_text)
+        status     = decision.get("status", "pending")
+        reason     = decision.get("reason_code", "")
+        reviewer   = decision.get("reviewer", "")
+        notes      = decision.get("notes", "")
+
+        img_path = get_page_image(book_id, page)
+
+        info = f"<span class='confidence-badge {conf_class}'>conf: {conf:.0%}</span> &nbsp; {book_id} · page {page} · {item.get('region_class','?')}"
+
+        return (
+            stats_html, queue_html,
+            img_path, raw_text, final_text,
+            info, status, reason, reviewer, notes
+        )
+
+    def navigate(direction: int):
+        q = state["queue"]
+        if not q:
+            return refresh_view()
+        state["idx"] = max(0, min(state["idx"] + direction, len(q) - 1))
+        return refresh_view()
+
+    def submit_decision(final_text, status, reason_code, reviewer, notes):
+        item = get_current_item()
+        if not item:
+            return refresh_view()
+
+        region_id = item.get("region_id", "")
+        book_id   = item.get("book_id", "")
+        page      = item.get("page", "")
+
+        # Determine actual status
+        raw_text   = item.get("raw_ocr", "")
+        act_status = status
+        if status == "accepted" and final_text.strip() != raw_text.strip():
+            act_status = "edited"
+
+        save_decision(
+            region_id=region_id,
+            book_id=book_id,
+            page=page,
+            status=act_status,
+            final_text=final_text,
+            reason_code=reason_code,
+            reviewer=reviewer or "reviewer",
+            notes=notes,
+        )
+
+        state["decisions"] = load_decisions()
+
+        # Auto-advance to next pending item
+        q = state["queue"]
+        for i in range(state["idx"] + 1, len(q)):
+            rid = q[i].get("region_id", "")
+            if rid not in state["decisions"]:
+                state["idx"] = i
+                break
+
+        return refresh_view()
+
+    def quick_action(action: str, reviewer_name: str):
+        item = get_current_item()
+        if not item:
+            return refresh_view()
+        region_id = item.get("region_id", "")
+        book_id   = item.get("book_id", "")
+        page      = item.get("page", "")
+        raw_text  = item.get("raw_ocr", "")
+
+        status_map = {
+            "accept":    "accepted",
+            "reject":    "rejected",
+            "quarantine": "quarantined",
+            "illus":     "illustration-only",
+        }
+        save_decision(
+            region_id=region_id, book_id=book_id, page=page,
+            status=status_map.get(action, "accepted"),
+            final_text=raw_text, reason_code="", reviewer=reviewer_name or "reviewer", notes="",
+        )
+        state["decisions"] = load_decisions()
+
+        # Auto-advance
+        q = state["queue"]
+        for i in range(state["idx"] + 1, len(q)):
+            rid = q[i].get("region_id", "")
+            if rid not in state["decisions"]:
+                state["idx"] = i
+                break
+
+        return refresh_view()
+
+    def export_approved():
+        """Export all accepted/edited decisions to JSONL for Codex."""
+        decisions = load_decisions()
+        approved  = [d for d in decisions.values() if d["status"] in ("accepted", "edited")]
+
+        if not approved:
+            return "No approved items to export yet."
+
+        ts = datetime.utcnow().strftime("%Y%m%d_%H%M%S")
+        out_path = EXPORTS_DIR / f"review_export_{ts}.jsonl"
+        with open(out_path, "w", encoding="utf-8") as f:
+            for d in approved:
+                f.write(json.dumps(d) + "\n")
+
+        return f"Exported {len(approved)} approved records → {out_path.relative_to(ROOT)}"
+
+    # ── Layout ────────────────────────────────────────────────────────────────
+    with gr.Blocks(title="Smoke Signal — Review Workbench", css=CSS) as app:
+
+        gr.HTML("""
+        <div id="ss-header">
+            <span id="ss-signal">◈</span>
+            <div>
+                <p id="ss-title">Smoke Signal</p>
+                <p id="ss-subtitle">OCR Review Workbench · Human-in-the-Loop</p>
+            </div>
+        </div>
+        """)
+
+        # Stats bar
+        stats_html = gr.HTML()
+
+        with gr.Row():
+            # ── Left: queue ───────────────────────────────────────────────────
+            with gr.Column(scale=1):
+                gr.Markdown("### Review Queue")
+                queue_html = gr.HTML()
+
+                with gr.Row():
+                    prev_btn = gr.Button("← Prev", size="sm")
+                    next_btn = gr.Button("Next →", size="sm")
+
+                reviewer_name = gr.Textbox(
+                    label="Your name / ID",
+                    placeholder="e.g. jamal",
+                    scale=1,
+                )
+
+            # ── Centre: page image ────────────────────────────────────────────
+            with gr.Column(scale=2):
+                gr.Markdown("### Page Image")
+                page_image = gr.Image(
+                    label="",
+                    type="filepath",
+                    height=480,
+                    show_download_button=False,
+                )
+                item_info = gr.HTML()
+
+            # ── Right: text + actions ─────────────────────────────────────────
+            with gr.Column(scale=2):
+                gr.Markdown("### OCR Text")
+                raw_text_box = gr.Textbox(
+                    label="Raw OCR (read-only)",
+                    lines=5,
+                    interactive=False,
+                    elem_classes=["ocr-text-box"],
+                )
+                final_text_box = gr.Textbox(
+                    label="Final Text (edit if needed)",
+                    lines=8,
+                    interactive=True,
+                    elem_classes=["ocr-text-box"],
+                )
+
+                with gr.Row():
+                    accept_btn = gr.Button("✓ Accept", elem_classes=["action-btn", "accept-btn"])
+                    reject_btn = gr.Button("✗ Reject", elem_classes=["action-btn", "reject-btn"])
+
+                with gr.Row():
+                    quar_btn  = gr.Button("⚑ Quarantine", elem_classes=["action-btn", "quar-btn"])
+                    illus_btn = gr.Button("◉ Illus Only", elem_classes=["action-btn", "illus-btn"])
+
+                gr.Markdown("### Decision Details")
+                status_dd = gr.Dropdown(
+                    label="Status",
+                    choices=REVIEW_STATUSES,
+                    value="pending",
+                )
+                reason_dd = gr.Dropdown(
+                    label="Reason Code",
+                    choices=[""] + REASON_CODES,
+                    value="",
+                )
+                notes_box = gr.Textbox(label="Notes", lines=2)
+
+                submit_btn = gr.Button(
+                    "Save Decision",
+                    variant="primary",
+                    size="lg",
+                )
+
+                export_btn = gr.Button("⬇ Export Approved to Codex", variant="secondary")
+                export_status = gr.Textbox(label="Export status", interactive=False)
+
+        # ── Wire events ───────────────────────────────────────────────────────
+        outputs = [
+            stats_html, queue_html,
+            page_image, raw_text_box, final_text_box,
+            item_info, status_dd, reason_dd, reviewer_name, notes_box,
+        ]
+
+        app.load(refresh_view, outputs=outputs)
+
+        prev_btn.click(lambda: navigate(-1), outputs=outputs)
+        next_btn.click(lambda: navigate(1), outputs=outputs)
+
+        accept_btn.click(
+            lambda rev: quick_action("accept", rev),
+            inputs=[reviewer_name], outputs=outputs
+        )
+        reject_btn.click(
+            lambda rev: quick_action("reject", rev),
+            inputs=[reviewer_name], outputs=outputs
+        )
+        quar_btn.click(
+            lambda rev: quick_action("quarantine", rev),
+            inputs=[reviewer_name], outputs=outputs
+        )
+        illus_btn.click(
+            lambda rev: quick_action("illus", rev),
+            inputs=[reviewer_name], outputs=outputs
+        )
+
+        submit_btn.click(
+            submit_decision,
+            inputs=[final_text_box, status_dd, reason_dd, reviewer_name, notes_box],
+            outputs=outputs,
+        )
+
+        export_btn.click(export_approved, outputs=[export_status])
+
+    return app
+
+
+if __name__ == "__main__":
+    app = build_app()
+    app.launch(share=False)