feat(ai): migrate annotator tool and training scripts into infra repo

- tools/annotator/ — Gradio annotation UI (app.py, detection.py,
requirements.txt, packages.txt) previously hosted as a standalone
HF Space repo. Deploy to Infin8-AI/Annotation via git subtree push.
- scripts/build_dataset_from_events.py — build YOLO dataset from events.jsonl
- scripts/generate_training_data.py — auto-label PDFs via vector grid detection
- scripts/train_facade_detector.py — train YOLO11n with CAD-optimised params
- pyproject.toml — add per-file-ignores for tools/ and training scripts

The from-annotation backend endpoint is already present in
apps/tenant-core-api-lambda/src/features/frame_instances/router.py.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

CLAUDE.md

@@ -0,0 +1,34 @@
+# Annotator Tool
+
+Gradio annotation tool for facade frame detection. Deployed to HF Spaces as `Infin8-AI/Annotation`.
+
+## Files
+
+- `app.py` — Gradio UI (3 tabs: Detect, Review & Edit, Send to Backend)
+- `detection.py` — YOLO inference wrapper with OpenCV fallback
+- `requirements.txt` — Python deps for local dev and HF Spaces
+- `packages.txt` — System deps (poppler-utils) for HF Spaces
+- `best.pt` — YOLO11n weights (not in git — download from HF Hub or train locally)
+
+## Deploying to HF Spaces
+
+HF Spaces builds from `hf/main`. The Space expects files at the repo root, so use git subtree:
+
+```bash
+# Add remote once
+git remote add hf https://YOUR_HF_TOKEN@huggingface.co/spaces/Infin8-AI/Annotation
+
+# Push this subdirectory as the Space root
+git subtree push --prefix=tools/annotator hf main
+```
+
+## Training loop
+
+See `scripts/build_dataset_from_events.py` and `scripts/train_facade_detector.py` at the repo root.
+
+```bash
+# From repo root — after exporting events.jsonl from the Gradio tool
+python scripts/build_dataset_from_events.py --events events.jsonl --pdf source.pdf
+python scripts/train_facade_detector.py --version v2
+cp models/yolo_facade_v2/best.pt tools/annotator/best.pt
+```

README.md

@@ -0,0 +1,78 @@
+# Takeoff AI Annotator
+
+A self-improving annotation tool for detecting facade frame (curtain wall panel) units on architectural construction drawings. Every human correction becomes a training signal that feeds back into the YOLO model over time.
+
+Deployed as a Hugging Face Space: `Infin8-AI/Annotation`
+
+## Tabs
+
+### Detect
+Upload a construction plan image (PNG/JPG) or a PDF page and click **Detect Panels**. The detected bounding boxes are drawn on the image and a JSON payload is shown for review.
+
+### Review & Edit
+Upload a PDF and use the HTML5 canvas to inspect detections page by page:
+
+| Action | Effect | Training signal logged |
+|--------|--------|----------------------|
+| **Detect This Page** | Run YOLO/OpenCV on the current page | — |
+| **Approve All** | Mark all boxes green | N × `accepted` events |
+| **Reject All** | Mark all boxes red | N × `rejected` events |
+| **Approve Selected** | Click a table row, then approve | 1 × `accepted` |
+| **Delete Selected** | Remove a single box | 1 × `rejected` |
+| **Add Box Manually** | Draw a new ground-truth box | 1 × `created` |
+| **Export Events (JSON)** | Download `events.jsonl` with full before/after coords | — |
+| **Export Dataset (YOLO)** | Download a zip of 640×640 tiles + YOLO labels | — |
+
+Box colours: orange = pending, green = approved, red = rejected.
+
+### Send to Backend
+POST approved detections to a running tenant-core-api instance using the `from-annotation` endpoint.
+
+Endpoint: `POST /api/v1/tenants/documents/{document_id}/frame-instances/from-annotation`
+
+## Continuous learning loop
+
+```
+Gradio Review UI
+   ↓  every approve / reject / add / delete
+events.jsonl  (exported from the Review tab)
+   ↓
+python scripts/build_dataset_from_events.py --events events.jsonl --pdf source.pdf
+   ↓
+python scripts/train_facade_detector.py --version v2
+   ↓
+cp models/yolo_facade_v2/best.pt tools/annotator/best.pt
+   ↓
+Restart Gradio — model version shown in header
+```
+
+## Detection engine
+
+The app loads `best.pt` (YOLO11n weights) from the same directory at startup. If not found, it falls back to OpenCV contour detection automatically. The status bar shows which engine is active.
+
+To point to a custom model path:
+```bash
+FACADE_MODEL_PATH=/path/to/best.pt python app.py
+```
+
+## Local development
+
+```bash
+cd tools/annotator
+pip install -r requirements.txt
+python app.py
+```
+
+PDF rendering uses PyMuPDF — no Poppler required locally (packages.txt installs it on HF Spaces / Linux).
+
+## Deploying to HF Spaces
+
+The Space (`Infin8-AI/Annotation`) expects the root of the repo to contain `app.py`. Use git subtree to push just this subdirectory:
+
+```bash
+# First time — add the remote
+git remote add hf https://YOUR_HF_TOKEN@huggingface.co/spaces/Infin8-AI/Annotation
+
+# Push (maps this subdirectory to the Space root)
+git subtree push --prefix=tools/annotator hf main
+```

app.py

@@ -0,0 +1,1360 @@
+import base64
+import hashlib
+import json
+import tempfile
+import uuid
+import zipfile
+from datetime import UTC, datetime
+from io import BytesIO
+from pathlib import Path
+
+import cv2
+import gradio as gr
+import numpy as np
+import requests
+from detection import detect_rectangles, draw_detections, get_model_version
+from PIL import Image
+
+# Fix gradio_client 5.9.1 crash when schema is a bool
+try:
+    import gradio_client.utils as _gcu
+
+    _orig_get_type = _gcu.get_type
+
+    def _safe_get_type(schema):
+        if not isinstance(schema, dict):
+            return "Any"
+        return _orig_get_type(schema)
+
+    _gcu.get_type = _safe_get_type
+    _orig_j2p = _gcu._json_schema_to_python_type
+
+    def _safe_j2p(schema, defs=None):
+        if not isinstance(schema, dict):
+            return "Any"
+        try:
+            return _orig_j2p(schema, defs)
+        except (TypeError, AttributeError):
+            return "Any"
+
+    _gcu._json_schema_to_python_type = _safe_j2p
+    _orig_j2p_pub = _gcu.json_schema_to_python_type
+
+    def _safe_j2p_pub(schema):
+        try:
+            return _orig_j2p_pub(schema)
+        except (TypeError, AttributeError):
+            return "Any"
+
+    _gcu.json_schema_to_python_type = _safe_j2p_pub
+except Exception:
+    pass
+
+try:
+    import fitz
+
+    PDF_SUPPORT = True
+except ImportError:
+    PDF_SUPPORT = False
+
+try:
+    import pandas as pd
+
+    PANDAS_SUPPORT = True
+except ImportError:
+    PANDAS_SUPPORT = False
+
+
+def _pil_to_bgr(pil_img):
+    return cv2.cvtColor(np.array(pil_img.convert("RGB")), cv2.COLOR_RGB2BGR)
+
+
+def _render_pdf_page(pdf_path, page_number, dpi=100):
+    if not PDF_SUPPORT:
+        return None
+    try:
+        doc = fitz.open(pdf_path)
+        idx = max(0, min(page_number - 1, len(doc) - 1))
+        page = doc[idx]
+        mat = fitz.Matrix(dpi / 72, dpi / 72)
+        pix = page.get_pixmap(matrix=mat, colorspace=fitz.csRGB)
+        return np.frombuffer(pix.samples, dtype=np.uint8).reshape(pix.height, pix.width, 3)
+    except Exception as exc:
+        print(f"[app] PDF render error: {exc}")
+        return None
+
+
+def _count_pdf_pages(pdf_path):
+    if not PDF_SUPPORT:
+        return 1
+    try:
+        return len(fitz.open(pdf_path))
+    except Exception:
+        return 1
+
+
+def _load_image_for_detect(image_path, pdf_path, pdf_page):
+    if image_path:
+        img = cv2.imread(image_path)
+        if img is None:
+            img = _pil_to_bgr(Image.open(image_path))
+        return img
+    if pdf_path and PDF_SUPPORT:
+        rgb = _render_pdf_page(pdf_path, pdf_page, dpi=150)
+        return cv2.cvtColor(rgb, cv2.COLOR_RGB2BGR) if rgb is not None else None
+    return None
+
+
+# ---------------------------------------------------------------------------
+# Canvas helpers — HTML5 canvas replaces Plotly for the Review & Edit tab
+# ---------------------------------------------------------------------------
+_CANVAS_MAX_PX = 1400  # max dimension sent to canvas (keeps base64 small)
+
+
+def _build_canvas_json(img_rgb, annotations, selected=-1):
+    """
+    Return JSON string sent to the HTML canvas via rv_canvas_render_txt.
+    Pass img_rgb=None for annotations-only updates (JS keeps its cached image).
+    Annotation coords are always in ORIGINAL image pixels; JS scales for display.
+    """
+    anns_data = [
+        {
+            "x1": float(a["x1"]),
+            "y1": float(a["y1"]),
+            "x2": float(a["x2"]),
+            "y2": float(a["y2"]),
+            "conf": float(a.get("conf", 1.0)),
+            "status": a.get("status", "pending"),
+            "source": a.get("source", "unknown"),
+        }
+        for a in annotations
+    ]
+    if img_rgb is None:
+        return json.dumps(
+            {
+                "image": None,
+                "imageW": 0,
+                "imageH": 0,
+                "annotations": anns_data,
+                "selected": selected,
+            }
+        )
+    H, W = img_rgb.shape[:2]
+    # Scale down for transfer — keep annotation coords in original pixels
+    scale = min(1.0, _CANVAS_MAX_PX / max(W, H))
+    if scale < 1.0:
+        nw, nh = int(W * scale), int(H * scale)
+        pil = Image.fromarray(img_rgb).resize((nw, nh), Image.LANCZOS)
+    else:
+        pil = Image.fromarray(img_rgb)
+    buf = BytesIO()
+    pil.save(buf, format="JPEG", quality=80)
+    b64 = base64.b64encode(buf.getvalue()).decode()
+    return json.dumps(
+        {
+            "image": f"data:image/jpeg;base64,{b64}",
+            "imageW": W,
+            "imageH": H,  # original dimensions so JS scales coords correctly
+            "annotations": anns_data,
+            "selected": selected,
+        }
+    )
+
+
+def _build_review_df(annotations):
+    if not PANDAS_SUPPORT or not annotations:
+        return []
+    return pd.DataFrame(
+        [
+            {
+                "#": i + 1,
+                "x1": round(ann["x1"]),
+                "y1": round(ann["y1"]),
+                "x2": round(ann["x2"]),
+                "y2": round(ann["y2"]),
+                "conf": f"{ann.get('conf', 1.0):.2f}",
+                "status": ann.get("status", "pending"),
+            }
+            for i, ann in enumerate(annotations)
+        ]
+    )
+
+
+# ---------------------------------------------------------------------------
+# Ground Truth Ledger helpers
+# ---------------------------------------------------------------------------
+def _now():
+    return datetime.now(UTC).isoformat()
+
+
+def _make_box(ann):
+    return {"x1": ann["x1"], "y1": ann["y1"], "x2": ann["x2"], "y2": ann["y2"], "conf": ann.get("conf", 1.0)}
+
+
+def _ledger_summary(ledger):
+    counts = {"accepted": 0, "rejected": 0, "modified": 0, "created": 0}
+    for e in ledger:
+        t = e.get("event_type", "")
+        if t in counts:
+            counts[t] += 1
+    return (
+        f"{len(ledger)} events — "
+        f"{counts['accepted']} accepted, {counts['rejected']} rejected, "
+        f"{counts['modified']} modified, {counts['created']} created"
+    )
+
+
+def _append_events(ledger, events):
+    return list(ledger) + events
+
+
+def _make_event(page, ann, event_type, before=None, after=None):
+    return {
+        "event_id": str(uuid.uuid4()),
+        "timestamp": _now(),
+        "page_number": page,
+        "annotation_id": ann.get("id", -1),
+        "source": ann.get("source", "unknown"),
+        "model_version": get_model_version(),
+        "event_type": event_type,
+        "before": before,
+        "after": after,
+    }
+
+
+# ---------------------------------------------------------------------------
+# Export helpers
+# ---------------------------------------------------------------------------
+def _image_hash(img_rgb):
+    return hashlib.sha256(img_rgb.tobytes()).hexdigest()[:16]
+
+
+def export_events_jsonl(ledger):
+    if not ledger:
+        return None
+    tmp = tempfile.NamedTemporaryFile(mode="w", suffix=".jsonl", delete=False, encoding="utf-8")
+    for event in ledger:
+        tmp.write(json.dumps(event) + "\n")
+    tmp.close()
+    return tmp.name
+
+
+def export_yolo_dataset_zip(ledger, rv_pdf):
+    if not ledger or not rv_pdf or not PDF_SUPPORT:
+        return None
+    by_page = {}
+    for ev in ledger:
+        pg = ev.get("page_number", 1)
+        by_page.setdefault(pg, []).append(ev)
+    tile_size = 640
+    tmp_dir = Path(tempfile.mkdtemp())
+    img_dir = tmp_dir / "images"
+    lbl_dir = tmp_dir / "labels"
+    img_dir.mkdir()
+    lbl_dir.mkdir()
+    written = 0
+    for page_num, events in by_page.items():
+        img_rgb = _render_pdf_page(rv_pdf, page_num, dpi=100)
+        if img_rgb is None:
+            continue
+        H, W = img_rgb.shape[:2]
+        img_hash = _image_hash(img_rgb)
+        for ev in events:
+            ev_type = ev.get("event_type", "")
+            box = ev.get("after") or ev.get("before")
+            if box is None:
+                continue
+            cx = (box["x1"] + box["x2"]) / 2
+            cy = (box["y1"] + box["y2"]) / 2
+            tx = max(0, min(int(cx - tile_size / 2), W - tile_size))
+            ty = max(0, min(int(cy - tile_size / 2), H - tile_size))
+            tx2 = min(tx + tile_size, W)
+            ty2 = min(ty + tile_size, H)
+            crop = img_rgb[ty:ty2, tx:tx2]
+            pad_h = tile_size - crop.shape[0]
+            pad_w = tile_size - crop.shape[1]
+            if pad_h > 0 or pad_w > 0:
+                crop = np.pad(crop, ((0, pad_h), (0, pad_w), (0, 0)), mode="constant", constant_values=255)
+            stem = f"p{page_num}_{img_hash}_{ev['event_id'][:8]}"
+            Image.fromarray(crop).save(img_dir / f"{stem}.jpg", quality=90)
+            lbl_path = lbl_dir / f"{stem}.txt"
+            if ev_type in ("accepted", "created", "modified"):
+                bx1 = max(box["x1"] - tx, 0)
+                by1 = max(box["y1"] - ty, 0)
+                bx2 = min(box["x2"] - tx, tile_size)
+                by2 = min(box["y2"] - ty, tile_size)
+                bw = bx2 - bx1
+                bh = by2 - by1
+                if bw > 0 and bh > 0:
+                    bcx = (bx1 + bx2) / 2 / tile_size
+                    bcy = (by1 + by2) / 2 / tile_size
+                    lbl_path.write_text(f"0 {bcx:.6f} {bcy:.6f} {bw / tile_size:.6f} {bh / tile_size:.6f}\n")
+                else:
+                    lbl_path.write_text("")
+            else:
+                lbl_path.write_text("")
+            written += 1
+    if written == 0:
+        return None
+    (tmp_dir / "data.yaml").write_text("path: .\ntrain: images\nval: images\nnc: 1\nnames: ['facade_frame']\n")
+    zip_path = tmp_dir.parent / "facade_annotations.zip"
+    with zipfile.ZipFile(zip_path, "w", zipfile.ZIP_DEFLATED) as zf:
+        for f in tmp_dir.rglob("*"):
+            if f.is_file():
+                zf.write(f, f.relative_to(tmp_dir))
+    return str(zip_path)
+
+
+# ---------------------------------------------------------------------------
+# Detect tab handlers
+# ---------------------------------------------------------------------------
+def run_detection(
+    image_path, pdf_file, pdf_page, page_number, conf_threshold, min_area, max_area, epsilon_factor, threshold
+):
+    pdf_path = (pdf_file if isinstance(pdf_file, str) else pdf_file.name) if pdf_file is not None else None
+    img = _load_image_for_detect(image_path, pdf_path, int(pdf_page))
+    if img is None:
+        return None, {}, [], "No image provided."
+    from detection import _get_model
+
+    using_yolo = _get_model() is not None
+    boxes = detect_rectangles(
+        img,
+        conf=float(conf_threshold),
+        min_area=int(min_area),
+        max_area=int(max_area),
+        epsilon_factor=float(epsilon_factor),
+        threshold=int(threshold),
+    )
+    annotated_rgb = cv2.cvtColor(draw_detections(img, boxes), cv2.COLOR_BGR2RGB)
+    shapes = [
+        {"page_number": int(page_number), "x1": b["x1"], "y1": b["y1"], "x2": b["x2"], "y2": b["y2"], "conf": b["conf"]}
+        for b in boxes
+    ]
+    payload = {"frame_template_id": 1, "shapes": shapes, "color": None, "quantity_multiplier": 1}
+    engine = "YOLO" if using_yolo else "OpenCV (YOLO model not found)"
+    return annotated_rgb, payload, shapes, f"[{engine}] Detected {len(boxes)} panel(s)."
+
+
+# ---------------------------------------------------------------------------
+# Send to Backend handler
+# ---------------------------------------------------------------------------
+def send_to_backend(
+    rv_annotations, backend_url, document_id, frame_template_id, x_tenant_id, x_user_id, color, quantity_multiplier
+):
+    shapes = []
+    for page_num, anns in sorted((rv_annotations or {}).items()):
+        for ann in anns:
+            if ann.get("status") == "approved":
+                shapes.append(
+                    {
+                        "page_number": page_num,
+                        "x1": ann["x1"],
+                        "y1": ann["y1"],
+                        "x2": ann["x2"],
+                        "y2": ann["y2"],
+                    }
+                )
+    if not shapes:
+        return {"error": "No approved annotations. Go to Review & Edit, detect + approve boxes first."}
+    if not backend_url:
+        return {"error": "Backend URL is required."}
+    url = f"{backend_url.rstrip('/')}/api/v1/tenants/documents/{int(document_id)}/frame-instances/from-annotation"
+    payload = {
+        "frame_template_id": int(frame_template_id),
+        "shapes": shapes,
+        "quantity_multiplier": int(quantity_multiplier),
+    }
+    if color and color.strip():
+        payload["color"] = color.strip()
+    headers = {
+        "Content-Type": "application/json",
+        "x-tenant-id": str(int(x_tenant_id)),
+        "x-user-id": str(int(x_user_id)),
+    }
+    try:
+        resp = requests.post(url, json=payload, headers=headers, timeout=15)
+        try:
+            body = resp.json()
+        except Exception:
+            body = resp.text
+        return {"status_code": resp.status_code, "response": body}
+    except requests.exceptions.RequestException as exc:
+        return {"error": str(exc)}
+
+
+# ---------------------------------------------------------------------------
+# Review & Edit tab handlers
+# ---------------------------------------------------------------------------
+def on_rv_pdf_upload(pdf_file):
+    if pdf_file is None or not PDF_SUPPORT:
+        return (_build_canvas_json(None, []), _build_review_df([]), "No PDF loaded", None, 1, 1, {}, [])
+    pdf_path = pdf_file if isinstance(pdf_file, str) else pdf_file.name
+    total = _count_pdf_pages(pdf_path)
+    img_rgb = _render_pdf_page(pdf_path, 1, dpi=100)
+    return (_build_canvas_json(img_rgb, []), _build_review_df([]), f"Page 1 / {total}", pdf_path, 1, total, {}, [])
+
+
+def _navigate(rv_pdf, rv_page, rv_total, rv_annotations, delta):
+    if rv_pdf is None:
+        return _build_canvas_json(None, []), _build_review_df([]), "No PDF loaded", rv_page
+    new_page = max(1, min(rv_total, rv_page + delta))
+    anns = rv_annotations.get(new_page, [])
+    img_rgb = _render_pdf_page(rv_pdf, new_page, dpi=100)
+    return (
+        _build_canvas_json(img_rgb, anns),
+        _build_review_df(anns),
+        f"Page {new_page} / {rv_total} — {len(anns)} box(es)",
+        new_page,
+    )
+
+
+def on_rv_prev(rv_pdf, rv_page, rv_total, rv_annotations):
+    return _navigate(rv_pdf, rv_page, rv_total, rv_annotations, -1)
+
+
+def on_rv_next(rv_pdf, rv_page, rv_total, rv_annotations):
+    return _navigate(rv_pdf, rv_page, rv_total, rv_annotations, +1)
+
+
+def on_rv_goto_page(page_str, rv_pdf, rv_total, rv_annotations):
+    try:
+        page_num = max(1, min(int(rv_total), int(str(page_str).strip())))
+    except (ValueError, TypeError):
+        return gr.update(), gr.update(), gr.update(), gr.update()
+    if rv_pdf is None:
+        return _build_canvas_json(None, []), _build_review_df([]), "No PDF loaded", 1
+    anns = rv_annotations.get(page_num, [])
+    img_rgb = _render_pdf_page(rv_pdf, page_num, dpi=100)
+    return (
+        _build_canvas_json(img_rgb, anns),
+        _build_review_df(anns),
+        f"Page {page_num} / {rv_total} — {len(anns)} box(es)",
+        page_num,
+    )
+
+
+def on_canvas_events(events_json, rv_pdf, rv_page, rv_annotations, rv_ledger):
+    """Process annotation changes sent from the JS canvas."""
+    if not events_json or not events_json.strip():
+        return gr.update(), rv_annotations, rv_ledger, gr.update(), -1
+    try:
+        data = json.loads(events_json)
+    except Exception:
+        return gr.update(), rv_annotations, rv_ledger, gr.update(), -1
+
+    raw_anns = data.get("annotations", [])
+    selected = int(data.get("selected", -1))
+    action = data.get("action", "sync")
+
+    old_anns = list(rv_annotations.get(rv_page, []))
+
+    new_anns = []
+    for i, a in enumerate(raw_anns):
+        new_anns.append(
+            {
+                "id": i,
+                "x1": float(a["x1"]),
+                "y1": float(a["y1"]),
+                "x2": float(a["x2"]),
+                "y2": float(a["y2"]),
+                "conf": float(a.get("conf", 1.0)),
+                "status": a.get("status", "pending"),
+                "source": a.get("source", "human_added"),
+            }
+        )
+
+    rv_annotations = dict(rv_annotations)
+    rv_annotations[rv_page] = new_anns
+
+    events = []
+    if action == "created" and new_anns:
+        ann = new_anns[-1]
+        events.append(_make_event(rv_page, ann, "created", before=None, after=_make_box(ann)))
+    elif action in ("moved", "resized") and 0 <= selected < len(new_anns):
+        if selected < len(old_anns):
+            events.append(
+                _make_event(
+                    rv_page,
+                    new_anns[selected],
+                    "modified",
+                    before=_make_box(old_anns[selected]),
+                    after=_make_box(new_anns[selected]),
+                )
+            )
+    rv_ledger = _append_events(rv_ledger, events)
+
+    canvas_json = _build_canvas_json(None, new_anns, selected=selected)
+    return canvas_json, rv_annotations, rv_ledger, _build_review_df(new_anns), selected
+
+
+def on_rv_detect(rv_pdf, rv_page, rv_annotations, rv_conf):
+    if rv_pdf is None:
+        return _build_canvas_json(None, []), _build_review_df([]), rv_annotations, "No PDF loaded."
+    img_rgb = _render_pdf_page(rv_pdf, rv_page, dpi=100)
+    if img_rgb is None:
+        return _build_canvas_json(None, []), _build_review_df([]), rv_annotations, "Failed to render page."
+    img_bgr = cv2.cvtColor(img_rgb, cv2.COLOR_RGB2BGR)
+    from detection import _get_model
+
+    using_yolo = _get_model() is not None
+    boxes = detect_rectangles(img_bgr, conf=float(rv_conf))
+    annotations = [
+        {
+            "id": i,
+            "x1": b["x1"],
+            "y1": b["y1"],
+            "x2": b["x2"],
+            "y2": b["y2"],
+            "conf": b["conf"],
+            "status": "pending",
+            "source": "yolo" if using_yolo else "opencv",
+        }
+        for i, b in enumerate(boxes)
+    ]
+    rv_annotations = dict(rv_annotations)
+    rv_annotations[rv_page] = annotations
+    engine = "YOLO" if using_yolo else "OpenCV"
+    return (
+        _build_canvas_json(img_rgb, annotations),
+        _build_review_df(annotations),
+        rv_annotations,
+        f"[{engine}] Found {len(boxes)} panel(s) on page {rv_page}.",
+    )
+
+
+def on_rv_detect_all(rv_pdf, rv_page, rv_total, rv_annotations, rv_conf):
+    if rv_pdf is None:
+        return _build_canvas_json(None, []), _build_review_df([]), rv_annotations, "No PDF loaded."
+    if not PDF_SUPPORT:
+        return _build_canvas_json(None, []), _build_review_df([]), rv_annotations, "PDF support unavailable."
+    from detection import _get_model
+
+    using_yolo = _get_model() is not None
+    all_anns = dict(rv_annotations)
+    total_found = 0
+    detect_dpi = 72  # lower DPI = smaller images = much faster inference per page
+    try:
+        doc = fitz.open(rv_pdf)
+        mat = fitz.Matrix(detect_dpi / 72, detect_dpi / 72)
+        for page_num in range(1, rv_total + 1):
+            try:
+                page = doc[page_num - 1]
+                pix = page.get_pixmap(matrix=mat, colorspace=fitz.csRGB)
+                img_rgb = np.frombuffer(pix.samples, dtype=np.uint8).reshape(pix.height, pix.width, 3)
+            except Exception:
+                continue
+            img_bgr = cv2.cvtColor(img_rgb, cv2.COLOR_RGB2BGR)
+            boxes = detect_rectangles(img_bgr, conf=float(rv_conf))
+            # Scale coords back to 100-DPI space so they match the display image
+            scale = 100.0 / detect_dpi
+            all_anns[page_num] = [
+                {
+                    "id": i,
+                    "x1": b["x1"] * scale,
+                    "y1": b["y1"] * scale,
+                    "x2": b["x2"] * scale,
+                    "y2": b["y2"] * scale,
+                    "conf": b["conf"],
+                    "status": "pending",
+                    "source": "yolo" if using_yolo else "opencv",
+                }
+                for i, b in enumerate(boxes)
+            ]
+            total_found += len(boxes)
+        doc.close()
+    except Exception as exc:
+        return _build_canvas_json(None, []), _build_review_df([]), rv_annotations, f"Error: {exc}"
+    img_rgb = _render_pdf_page(rv_pdf, rv_page, dpi=100)
+    anns = all_anns.get(rv_page, [])
+    engine = "YOLO" if using_yolo else "OpenCV"
+    return (
+        _build_canvas_json(img_rgb, anns),
+        _build_review_df(anns),
+        all_anns,
+        f"[{engine}] Detected {total_found} panel(s) across {rv_total} page(s).",
+    )
+
+
+def on_fill_edit_form(selected_idx, rv_page, rv_annotations):
+    anns = rv_annotations.get(rv_page, [])
+    idx = int(selected_idx) if selected_idx is not None else -1
+    if idx < 0 or idx >= len(anns):
+        return None, None, None, None
+    a = anns[idx]
+    return a["x1"], a["y1"], a["x2"], a["y2"]
+
+
+def on_rv_update_box(rv_pdf, rv_page, rv_annotations, ledger, selected_idx, x1, y1, x2, y2):
+    anns = rv_annotations.get(rv_page, [])
+    if rv_pdf is None or not anns or selected_idx is None or int(selected_idx) < 0:
+        return gr.update(), _build_review_df(anns), rv_annotations, ledger, "Select a box first."
+    idx = int(selected_idx)
+    if idx >= len(anns):
+        return gr.update(), _build_review_df(anns), rv_annotations, ledger, "Invalid selection."
+    try:
+        x1, y1, x2, y2 = float(x1), float(y1), float(x2), float(y2)
+    except (TypeError, ValueError):
+        return gr.update(), _build_review_df(anns), rv_annotations, ledger, "Invalid coordinates."
+    if x2 <= x1 or y2 <= y1:
+        return gr.update(), _build_review_df(anns), rv_annotations, ledger, "x2>x1 and y2>y1 required."
+    rv_annotations = dict(rv_annotations)
+    new_anns = list(anns)
+    old = new_anns[idx]
+    before = _make_box(old)
+    new_anns[idx] = dict(old, x1=x1, y1=y1, x2=x2, y2=y2)
+    rv_annotations[rv_page] = new_anns
+    event = _make_event(rv_page, old, "modified", before=before, after=_make_box(new_anns[idx]))
+    ledger = _append_events(ledger, [event])
+    img_rgb = _render_pdf_page(rv_pdf, rv_page, dpi=100)
+    return (
+        _build_canvas_json(img_rgb, new_anns, selected=idx),
+        _build_review_df(new_anns),
+        rv_annotations,
+        ledger,
+        f"Updated box #{idx + 1}. {_ledger_summary(ledger)}",
+    )
+
+
+def on_rv_approve_all(rv_pdf, rv_page, rv_annotations, ledger):
+    if rv_pdf is None or not rv_annotations.get(rv_page):
+        return gr.update(), _build_review_df([]), rv_annotations, ledger, "No boxes on this page."
+    rv_annotations = dict(rv_annotations)
+    old_anns = rv_annotations[rv_page]
+    new_anns = [dict(a, status="approved") for a in old_anns]
+    rv_annotations[rv_page] = new_anns
+    events = [
+        _make_event(rv_page, a, "accepted", before=_make_box(a), after=_make_box(a))
+        for a in old_anns
+        if a.get("status") != "approved"
+    ]
+    ledger = _append_events(ledger, events)
+    return (
+        _build_canvas_json(None, new_anns),
+        _build_review_df(new_anns),
+        rv_annotations,
+        ledger,
+        f"Approved {len(new_anns)} box(es). {_ledger_summary(ledger)}",
+    )
+
+
+def on_rv_reject_all(rv_pdf, rv_page, rv_annotations, ledger):
+    if rv_pdf is None or not rv_annotations.get(rv_page):
+        return gr.update(), _build_review_df([]), rv_annotations, ledger, "No boxes on this page."
+    rv_annotations = dict(rv_annotations)
+    old_anns = rv_annotations[rv_page]
+    new_anns = [dict(a, status="rejected") for a in old_anns]
+    rv_annotations[rv_page] = new_anns
+    events = [
+        _make_event(rv_page, a, "rejected", before=_make_box(a), after=None)
+        for a in old_anns
+        if a.get("status") != "rejected"
+    ]
+    ledger = _append_events(ledger, events)
+    return (
+        _build_canvas_json(None, new_anns),
+        _build_review_df(new_anns),
+        rv_annotations,
+        ledger,
+        f"Rejected {len(new_anns)} box(es). {_ledger_summary(ledger)}",
+    )
+
+
+def on_rv_approve_selected(rv_pdf, rv_page, rv_annotations, ledger, selected_idx):
+    anns = rv_annotations.get(rv_page, [])
+    if rv_pdf is None or not anns or selected_idx is None or selected_idx < 0:
+        return gr.update(), _build_review_df(anns), rv_annotations, ledger, "Select a box first."
+    idx = int(selected_idx)
+    if idx >= len(anns):
+        return gr.update(), _build_review_df(anns), rv_annotations, ledger, "Invalid selection."
+    rv_annotations = dict(rv_annotations)
+    new_anns = list(anns)
+    old = new_anns[idx]
+    new_anns[idx] = dict(old, status="approved")
+    rv_annotations[rv_page] = new_anns
+    event = _make_event(rv_page, old, "accepted", before=_make_box(old), after=_make_box(new_anns[idx]))
+    ledger = _append_events(ledger, [event])
+    return (
+        _build_canvas_json(None, new_anns, selected=idx),
+        _build_review_df(new_anns),
+        rv_annotations,
+        ledger,
+        f"Approved box #{idx + 1}. {_ledger_summary(ledger)}",
+    )
+
+
+def on_rv_delete_selected(rv_pdf, rv_page, rv_annotations, ledger, selected_idx):
+    anns = rv_annotations.get(rv_page, [])
+    if rv_pdf is None or not anns or selected_idx is None or selected_idx < 0:
+        return gr.update(), _build_review_df(anns), rv_annotations, ledger, "Select a box first.", selected_idx
+    idx = int(selected_idx)
+    if idx >= len(anns):
+        return gr.update(), _build_review_df(anns), rv_annotations, ledger, "Invalid selection.", selected_idx
+    rv_annotations = dict(rv_annotations)
+    removed = anns[idx]
+    new_anns = [a for i, a in enumerate(anns) if i != idx]
+    for j, a in enumerate(new_anns):
+        a["id"] = j
+    rv_annotations[rv_page] = new_anns
+    event = _make_event(rv_page, removed, "rejected", before=_make_box(removed), after=None)
+    ledger = _append_events(ledger, [event])
+    new_sel = min(idx, len(new_anns) - 1) if new_anns else -1
+    return (
+        _build_canvas_json(None, new_anns, selected=new_sel),
+        _build_review_df(new_anns),
+        rv_annotations,
+        ledger,
+        f"Deleted box #{idx + 1}. {_ledger_summary(ledger)}",
+        new_sel,
+    )
+
+
+def on_rv_copy_selected(rv_pdf, rv_page, rv_annotations, ledger, selected_idx):
+    anns = rv_annotations.get(rv_page, [])
+    if not anns or selected_idx is None or selected_idx < 0:
+        return gr.update(), _build_review_df(anns), rv_annotations, ledger, "Select a box first."
+    idx = int(selected_idx)
+    if idx >= len(anns):
+        return gr.update(), _build_review_df(anns), rv_annotations, ledger, "Invalid selection."
+    rv_annotations = dict(rv_annotations)
+    src = anns[idx]
+    new_ann = dict(
+        src, id=len(anns), x1=src["x1"] + 15, y1=src["y1"] + 15, x2=src["x2"] + 15, y2=src["y2"] + 15, status="pending"
+    )
+    new_anns = [*list(anns), new_ann]
+    rv_annotations[rv_page] = new_anns
+    new_sel = len(new_anns) - 1
+    event = _make_event(rv_page, new_ann, "created", before=None, after=_make_box(new_ann))
+    ledger = _append_events(ledger, [event])
+    return (
+        _build_canvas_json(None, new_anns, selected=new_sel),
+        _build_review_df(new_anns),
+        rv_annotations,
+        ledger,
+        f"Copied to box #{new_sel + 1}. {_ledger_summary(ledger)}",
+    )
+
+
+def on_row_select(evt: gr.SelectData):
+    return evt.index[0] if evt and evt.index else -1
+
+
+def on_export_events(ledger):
+    if not ledger:
+        return None
+    return export_events_jsonl(ledger)
+
+
+def on_export_dataset(ledger, rv_pdf):
+    if not ledger:
+        return None
+    return export_yolo_dataset_zip(ledger, rv_pdf)
+
+
+# ---------------------------------------------------------------------------
+# Gradio UI
+# ---------------------------------------------------------------------------
+_model_version = get_model_version()
+
+_CANVAS_HTML = """
+<div id="rv-canvas-outer" style="width:100%;min-height:600px;background:#0f0f0f;border-radius:8px;overflow:hidden;position:relative;user-select:none;-webkit-user-select:none;">
+  <canvas id="rv-ann-canvas" style="display:block;width:100%;cursor:crosshair;touch-action:none;"></canvas>
+  <div id="rv-canvas-msg" style="position:absolute;top:50%;left:50%;transform:translate(-50%,-50%);color:#555;font-family:monospace;font-size:13px;pointer-events:none;text-align:center;line-height:1.8;">
+    Upload a PDF to begin<br><span style="color:#333;font-size:11px;">Drag on canvas to draw &bull; click box to select &bull; drag to move &bull; drag corner to resize</span>
+  </div>
+</div>
+<div id="rv-ann-tooltip" style="position:fixed;display:none;background:rgba(20,20,20,0.93);color:#fff;border-radius:6px;padding:8px 12px;font-family:monospace;font-size:12px;pointer-events:none;z-index:9999;box-shadow:0 2px 10px rgba(0,0,0,0.5);line-height:1.7;max-width:280px;"></div>
+"""
+
+_CANVAS_JS = """
+<script>
+(function() {
+  'use strict';
+
+  var COLORS = {pending:'#F97316', approved:'#22C55E', rejected:'#EF4444'};
+  var HANDLE = 9;
+
+  var canvas = null, ctx = null;
+  var cachedImg = null, cachedImgSrc = '';
+  var imgW = 0, imgH = 0;
+  var anns = [], selected = -1;
+  var drag = null;
+  var lastRender = '';
+
+  // ── Boot ────────────────────────────────────────────────────────────────
+  var _iv = setInterval(function() {
+    if (document.getElementById('rv-ann-canvas')) {
+      clearInterval(_iv);
+      canvas = document.getElementById('rv-ann-canvas');
+      ctx = canvas.getContext('2d');
+      canvas.addEventListener('mousedown', onDown);
+      canvas.addEventListener('mousemove', onMove);
+      canvas.addEventListener('mouseup', onUp);
+      canvas.addEventListener('mouseleave', function(e) { hideTooltip(); if (drag) { onUp(e); } });
+      new ResizeObserver(refit).observe(canvas.parentElement);
+      setInterval(checkRender, 150);
+    }
+  }, 200);
+
+  // ── Python → JS sync ────────────────────────────────────────────────────
+  function checkRender() {
+    var el = document.querySelector('#rv-canvas-render textarea');
+    if (!el || !el.value || el.value === lastRender) return;
+    lastRender = el.value;
+    try { applyRender(JSON.parse(el.value)); } catch(e) {}
+  }
+
+  function applyRender(d) {
+    anns = (d.annotations || []).map(function(a) { return Object.assign({}, a); });
+    selected = (d.selected !== undefined && d.selected !== null) ? parseInt(d.selected, 10) : -1;
+    if (isNaN(selected)) selected = -1;
+    var msg = document.getElementById('rv-canvas-msg');
+    if (d.image && d.image !== cachedImgSrc) {
+      imgW = d.imageW; imgH = d.imageH;
+      var im = new Image();
+      im.onload = function() { cachedImg = im; cachedImgSrc = d.image; refit(); };
+      im.onerror = function() { console.warn('Canvas: failed to load image'); };
+      im.src = d.image;
+      if (msg) msg.style.display = 'none';
+    } else {
+      draw();
+      if (msg && cachedImg) msg.style.display = 'none';
+    }
+  }
+
+  function refit() {
+    if (!canvas || !imgW || !imgH) return;
+    var w = canvas.parentElement.clientWidth || 800;
+    canvas.width  = Math.round(w);
+    canvas.height = Math.round(imgH * (w / imgW));
+    draw();
+  }
+
+  function s() { return canvas && imgW ? canvas.width / imgW : 1; }
+
+  // ── Draw ─────────────────────────────────────────────────────────────────
+  function draw() {
+    if (!canvas) return;
+    var sc = s();
+    ctx.clearRect(0, 0, canvas.width, canvas.height);
+    if (cachedImg) ctx.drawImage(cachedImg, 0, 0, canvas.width, canvas.height);
+
+    anns.forEach(function(ann, i) {
+      var x1 = ann.x1*sc, y1 = ann.y1*sc, x2 = ann.x2*sc, y2 = ann.y2*sc;
+      var c = COLORS[ann.status] || COLORS.pending;
+      var sel = (i === selected);
+
+      // Fill
+      ctx.fillStyle = c + (sel ? '55' : '22');
+      ctx.fillRect(x1, y1, x2-x1, y2-y1);
+
+      // Border
+      ctx.strokeStyle = c;
+      ctx.lineWidth = sel ? 3 : 2;
+      ctx.strokeRect(x1, y1, x2-x1, y2-y1);
+
+      // Resize handles on selected box
+      if (sel) {
+        [[x1,y1],[x2,y1],[x2,y2],[x1,y2]].forEach(function(pt) {
+          ctx.fillStyle = '#fff';
+          ctx.fillRect(pt[0]-HANDLE/2, pt[1]-HANDLE/2, HANDLE, HANDLE);
+          ctx.strokeStyle = c; ctx.lineWidth = 2;
+          ctx.strokeRect(pt[0]-HANDLE/2, pt[1]-HANDLE/2, HANDLE, HANDLE);
+        });
+      }
+    });
+
+    // Draw-in-progress preview
+    if (drag && drag.mode === 'draw') {
+      ctx.strokeStyle = '#2563EB'; ctx.lineWidth = 2;
+      ctx.setLineDash([5, 4]);
+      ctx.strokeRect(drag.ox, drag.oy, drag.cx - drag.ox, drag.cy - drag.oy);
+      ctx.setLineDash([]);
+      ctx.fillStyle = 'rgba(37,99,235,0.1)';
+      ctx.fillRect(drag.ox, drag.oy, drag.cx - drag.ox, drag.cy - drag.oy);
+    }
+  }
+
+  // ── Tooltip ──────────────────────────────────────────────────────────────
+  var hoveredIdx = -1;
+
+  function showTooltip(ann, i, clientX, clientY) {
+    var tip = document.getElementById('rv-ann-tooltip');
+    if (!tip) return;
+    tip.innerHTML =
+      '<b>Box #' + (i + 1) + '</b><br>' +
+      'conf: '   + ((ann.conf || 1) * 1).toFixed(2) + '<br>' +
+      'status: ' + ann.status + '<br>' +
+      '(' + Math.round(ann.x1) + ', ' + Math.round(ann.y1) + ') &rarr; ' +
+      '(' + Math.round(ann.x2) + ', ' + Math.round(ann.y2) + ')';
+    tip.style.display = 'block';
+    tip.style.left = (clientX + 14) + 'px';
+    tip.style.top  = (clientY + 14) + 'px';
+  }
+
+  function hideTooltip() {
+    var tip = document.getElementById('rv-ann-tooltip');
+    if (tip) tip.style.display = 'none';
+    hoveredIdx = -1;
+  }
+
+  // ── Hit testing ──────────────────────────────────────────────────────────
+  function hitHandle(ann, cx, cy) {
+    var sc = s(), h = HANDLE;
+    var pts = [
+      [ann.x1*sc, ann.y1*sc, 'nw'], [ann.x2*sc, ann.y1*sc, 'ne'],
+      [ann.x2*sc, ann.y2*sc, 'se'], [ann.x1*sc, ann.y2*sc, 'sw'],
+    ];
+    for (var i = 0; i < pts.length; i++) {
+      if (Math.abs(cx - pts[i][0]) <= h && Math.abs(cy - pts[i][1]) <= h)
+        return pts[i][2];
+    }
+    return null;
+  }
+
+  function hitBox(ann, cx, cy) {
+    var sc = s();
+    return cx >= ann.x1*sc && cx <= ann.x2*sc && cy >= ann.y1*sc && cy <= ann.y2*sc;
+  }
+
+  function pos(e) {
+    var r = canvas.getBoundingClientRect();
+    var sx = canvas.width  / r.width;
+    var sy = canvas.height / r.height;
+    return { x: (e.clientX - r.left) * sx, y: (e.clientY - r.top) * sy };
+  }
+
+  function fi(v) { return v / s(); }
+
+  // ── Mouse ───────────────────────────────────────────────────��────────────
+  function onDown(e) {
+    hideTooltip();
+    var p = pos(e);
+    // Resize handles on selected box take priority
+    if (selected >= 0 && selected < anns.length) {
+      var dir = hitHandle(anns[selected], p.x, p.y);
+      if (dir) {
+        drag = { mode:'resize', dir:dir, idx:selected,
+                 orig:Object.assign({}, anns[selected]), ox:p.x, oy:p.y };
+        return;
+      }
+    }
+    // Click inside any box to select + move
+    for (var i = anns.length - 1; i >= 0; i--) {
+      if (hitBox(anns[i], p.x, p.y)) {
+        selected = i;
+        drag = { mode:'move', idx:i,
+                 orig:Object.assign({}, anns[i]), ox:p.x, oy:p.y };
+        draw();
+        sync('select');
+        return;
+      }
+    }
+    // Empty area — start drawing new box
+    selected = -1;
+    drag = { mode:'draw', ox:p.x, oy:p.y, cx:p.x, cy:p.y };
+    draw();
+  }
+
+  function onMove(e) {
+    var p = pos(e);
+    // Tooltip on hover (only when not dragging)
+    if (!drag) {
+      var hovered = -1;
+      for (var j = anns.length - 1; j >= 0; j--) {
+        if (hitBox(anns[j], p.x, p.y)) { hovered = j; break; }
+      }
+      if (hovered >= 0) {
+        showTooltip(anns[hovered], hovered, e.clientX, e.clientY);
+      } else {
+        hideTooltip();
+      }
+      return;
+    }
+    var dx = fi(p.x - drag.ox), dy = fi(p.y - drag.oy);
+    if (drag.mode === 'move') {
+      var o = drag.orig;
+      anns[drag.idx] = Object.assign({}, o,
+        { x1:o.x1+dx, y1:o.y1+dy, x2:o.x2+dx, y2:o.y2+dy });
+    } else if (drag.mode === 'resize') {
+      var o = drag.orig, a = Object.assign({}, o), d = drag.dir;
+      if (d.indexOf('e') >= 0) a.x2 = o.x2 + dx;
+      if (d.indexOf('w') >= 0) a.x1 = o.x1 + dx;
+      if (d.indexOf('s') >= 0) a.y2 = o.y2 + dy;
+      if (d.indexOf('n') >= 0) a.y1 = o.y1 + dy;
+      anns[drag.idx] = a;
+    } else if (drag.mode === 'draw') {
+      drag.cx = p.x; drag.cy = p.y;
+    }
+    draw();
+  }
+
+  function onUp(e) {
+    if (!drag) return;
+    var action = drag.mode;
+    if (drag.mode === 'draw') {
+      var p = pos(e);
+      var x1c = Math.min(drag.ox, p.x), y1c = Math.min(drag.oy, p.y);
+      var x2c = Math.max(drag.ox, p.x), y2c = Math.max(drag.oy, p.y);
+      if (x2c - x1c > 5 && y2c - y1c > 5) {
+        anns.push({ x1:fi(x1c), y1:fi(y1c), x2:fi(x2c), y2:fi(y2c),
+                    conf:1.0, status:'pending', source:'human_added' });
+        selected = anns.length - 1;
+        action = 'created';
+      } else {
+        drag = null; draw(); return;
+      }
+    } else {
+      action = drag.mode === 'resize' ? 'resized' : 'moved';
+    }
+    drag = null;
+    draw();
+    sync(action);
+  }
+
+  // ── JS-side copy (C key / canvas copy shortcut) ──────────────────────────
+  function copySelected() {
+    if (selected < 0 || selected >= anns.length) return;
+    var src = anns[selected];
+    anns.push(Object.assign({}, src, {
+      x1: src.x1+15, y1: src.y1+15, x2: src.x2+15, y2: src.y2+15, status:'pending'
+    }));
+    selected = anns.length - 1;
+    draw();
+    sync('created');
+  }
+
+  function deleteSelected() {
+    if (selected < 0 || selected >= anns.length) return;
+    anns.splice(selected, 1);
+    selected = anns.length > 0 ? Math.min(selected, anns.length - 1) : -1;
+    draw();
+    sync('deleted');
+  }
+
+  // ── JS → Python sync ────────────────────────────────────────────────────
+  function sync(action) {
+    var tb = document.querySelector('#rv-canvas-events textarea');
+    if (!tb) return;
+    var payload = JSON.stringify({ annotations:anns, selected:selected, action:action || 'sync' });
+    tb.value = payload;
+    tb.dispatchEvent(new Event('input',  { bubbles:true }));
+    tb.dispatchEvent(new Event('change', { bubbles:true }));
+  }
+
+  // ── Keyboard ─────────────────────────────────────────────────────────────
+  function triggerBtn(id) {
+    var el = document.getElementById(id);
+    if (!el) return;
+    var btn = el.tagName === 'BUTTON' ? el : el.querySelector('button');
+    if (btn) btn.click();
+  }
+
+  document.addEventListener('keydown', function(e) {
+    var tag = e.target.tagName;
+    if (tag === 'INPUT' || tag === 'TEXTAREA' || tag === 'SELECT') return;
+    switch (e.key) {
+      case 'c': case 'C':      copySelected(); break;
+      case 'Delete': case 'Backspace': deleteSelected(); break;
+      case 'a': case 'A':     triggerBtn('rv-approve-sel'); break;
+      case 'ArrowLeft':        e.preventDefault(); triggerBtn('rv-prev'); break;
+      case 'ArrowRight':       e.preventDefault(); triggerBtn('rv-next'); break;
+    }
+  });
+})();
+</script>
+"""
+
+with gr.Blocks(title="Takeoff AI Annotator") as demo:
+    gr.Markdown(f"# Takeoff AI Annotator  \n_Model: `{_model_version}`_")
+
+    shapes_state = gr.State([])
+
+    rv_pdf_state = gr.State(None)
+    rv_page_state = gr.State(1)
+    rv_total_state = gr.State(1)
+    rv_annotations_state = gr.State({})
+    rv_ledger_state = gr.State([])
+    rv_selected_state = gr.State(-1)
+
+    with gr.Tabs():
+        # ------------------------------------------------------------------ #
+        #  Tab 1: Detect                                                       #
+        # ------------------------------------------------------------------ #
+        with gr.Tab("Detect"):
+            with gr.Row():
+                with gr.Column():
+                    image_input = gr.Image(label="Upload Image (PNG/JPG)", type="filepath")
+                    if PDF_SUPPORT:
+                        pdf_input = gr.File(label="Or Upload PDF", file_types=[".pdf"])
+                        pdf_page_input = gr.Number(label="PDF Page Number", value=1, minimum=1, precision=0)
+                    else:
+                        pdf_input = gr.State(None)
+                        pdf_page_input = gr.State(1)
+                        gr.Markdown("_PDF support unavailable._")
+                    page_number_input = gr.Number(
+                        label="Page Number (sent to backend)",
+                        value=1,
+                        minimum=1,
+                        precision=0,
+                    )
+                    with gr.Accordion("Detection Parameters", open=True):
+                        conf_slider = gr.Slider(0.05, 0.95, value=0.25, step=0.05, label="Confidence Threshold (YOLO)")
+                        gr.Markdown("_Sliders below are OpenCV fallback only._")
+                        min_area_slider = gr.Slider(100, 10_000, value=500, step=100, label="Min Area (px²)")
+                        max_area_slider = gr.Slider(1_000, 2_000_000, value=500_000, step=1_000, label="Max Area (px²)")
+                        epsilon_slider = gr.Slider(0.005, 0.1, value=0.02, step=0.005, label="Epsilon Factor")
+                        threshold_slider = gr.Slider(0, 255, value=127, step=1, label="Binarization Threshold")
+                    detect_btn = gr.Button("Detect Panels", variant="primary")
+                    status_output = gr.Textbox(label="Status", interactive=False)
+                with gr.Column():
+                    annotated_output = gr.Image(label="Detected Rectangles")
+                    json_output = gr.JSON(label="Payload Preview")
+            detect_btn.click(
+                fn=run_detection,
+                inputs=[
+                    image_input,
+                    pdf_input,
+                    pdf_page_input,
+                    page_number_input,
+                    conf_slider,
+                    min_area_slider,
+                    max_area_slider,
+                    epsilon_slider,
+                    threshold_slider,
+                ],
+                outputs=[annotated_output, json_output, shapes_state, status_output],
+            )
+
+        # ------------------------------------------------------------------ #
+        #  Tab 2: Review & Edit                                                #
+        # ------------------------------------------------------------------ #
+        with gr.Tab("Review & Edit"):
+            rv_pdf_input = gr.File(label="Upload PDF", file_types=[".pdf"])
+
+            with gr.Row():
+                rv_prev_btn = gr.Button("◀", scale=1, min_width=48, elem_id="rv-prev")
+                rv_page_lbl = gr.Textbox(value="Upload a PDF to begin", show_label=False, interactive=False, scale=4)
+                rv_next_btn = gr.Button("▶", scale=1, min_width=48, elem_id="rv-next")
+                rv_page_jump = gr.Textbox(value="", show_label=False, scale=1, min_width=80, placeholder="Go to page…")
+                rv_conf_slider = gr.Slider(0.05, 0.95, value=0.25, step=0.05, label="Conf", scale=3)
+                rv_detect_btn = gr.Button("Detect Page", variant="primary", scale=2)
+                rv_detect_all_btn = gr.Button("Detect All", scale=2)
+
+            with gr.Row():
+                with gr.Column(scale=7):
+                    gr.HTML(_CANVAS_HTML)
+                    rv_canvas_render_txt = gr.Textbox(visible=False, elem_id="rv-canvas-render")
+                    rv_canvas_events_txt = gr.Textbox(visible=False, elem_id="rv-canvas-events")
+
+                with gr.Column(scale=3):
+                    rv_status = gr.Textbox(show_label=False, interactive=False, placeholder="Status", lines=1)
+
+                    gr.Markdown("**Selected box**")
+                    rv_selected_lbl = gr.Textbox(value="— none —", show_label=False, interactive=False)
+                    with gr.Row():
+                        rv_approve_sel_btn = gr.Button(
+                            "✓ Approve", variant="secondary", elem_id="rv-approve-sel", scale=2
+                        )
+                        rv_copy_sel_btn = gr.Button("⧉ Copy", scale=1)
+                        rv_delete_sel_btn = gr.Button("🗑 Delete", variant="stop", elem_id="rv-delete-sel", scale=2)
+
+                    gr.Markdown("**Edit coords** _(type values → Update)_")
+                    with gr.Row():
+                        edit_x1 = gr.Number(label="x1", precision=0, min_width=80)
+                        edit_y1 = gr.Number(label="y1", precision=0, min_width=80)
+                    with gr.Row():
+                        edit_x2 = gr.Number(label="x2", precision=0, min_width=80)
+                        edit_y2 = gr.Number(label="y2", precision=0, min_width=80)
+                    update_box_btn = gr.Button("↩ Update Box", variant="primary")
+
+                    gr.Markdown("**Page actions**")
+                    with gr.Row():
+                        rv_approve_all_btn = gr.Button("✓ Approve All", variant="secondary")
+                        rv_reject_all_btn = gr.Button("✗ Reject All", variant="stop")
+
+                    rv_df = gr.Dataframe(
+                        headers=["#", "x1", "y1", "x2", "y2", "conf", "status"],
+                        label="Detections — click row to select",
+                        interactive=False,
+                        wrap=False,
+                        max_height=220,
+                    )
+
+                    with gr.Row():
+                        export_events_btn = gr.Button("↓ Events", scale=1)
+                        export_dataset_btn = gr.Button("↓ Dataset", scale=1)
+                    export_file_out = gr.File(label="Download", visible=True)
+
+            gr.Markdown(
+                "`A` approve &nbsp; `C` copy &nbsp; `Del` delete &nbsp; "
+                "`← →` pages &nbsp; — draw box by dragging on empty canvas"
+            )
+
+            # ── Wire events ─────────────────────────────────────────────────
+            rv_pdf_input.upload(
+                fn=on_rv_pdf_upload,
+                inputs=[rv_pdf_input],
+                outputs=[
+                    rv_canvas_render_txt,
+                    rv_df,
+                    rv_page_lbl,
+                    rv_pdf_state,
+                    rv_page_state,
+                    rv_total_state,
+                    rv_annotations_state,
+                    rv_ledger_state,
+                ],
+            )
+            rv_prev_btn.click(
+                fn=on_rv_prev,
+                inputs=[rv_pdf_state, rv_page_state, rv_total_state, rv_annotations_state],
+                outputs=[rv_canvas_render_txt, rv_df, rv_page_lbl, rv_page_state],
+            )
+            rv_next_btn.click(
+                fn=on_rv_next,
+                inputs=[rv_pdf_state, rv_page_state, rv_total_state, rv_annotations_state],
+                outputs=[rv_canvas_render_txt, rv_df, rv_page_lbl, rv_page_state],
+            )
+            rv_page_jump.submit(
+                fn=on_rv_goto_page,
+                inputs=[rv_page_jump, rv_pdf_state, rv_total_state, rv_annotations_state],
+                outputs=[rv_canvas_render_txt, rv_df, rv_page_lbl, rv_page_state],
+            )
+            rv_canvas_events_txt.change(
+                fn=on_canvas_events,
+                inputs=[rv_canvas_events_txt, rv_pdf_state, rv_page_state, rv_annotations_state, rv_ledger_state],
+                outputs=[rv_canvas_render_txt, rv_annotations_state, rv_ledger_state, rv_df, rv_selected_state],
+            ).then(
+                fn=lambda idx: f"Box #{idx + 1}" if idx >= 0 else "— none —",
+                inputs=[rv_selected_state],
+                outputs=[rv_selected_lbl],
+            ).then(
+                fn=on_fill_edit_form,
+                inputs=[rv_selected_state, rv_page_state, rv_annotations_state],
+                outputs=[edit_x1, edit_y1, edit_x2, edit_y2],
+            )
+            rv_detect_btn.click(
+                fn=on_rv_detect,
+                inputs=[rv_pdf_state, rv_page_state, rv_annotations_state, rv_conf_slider],
+                outputs=[rv_canvas_render_txt, rv_df, rv_annotations_state, rv_status],
+            )
+            rv_detect_all_btn.click(
+                fn=on_rv_detect_all,
+                inputs=[rv_pdf_state, rv_page_state, rv_total_state, rv_annotations_state, rv_conf_slider],
+                outputs=[rv_canvas_render_txt, rv_df, rv_annotations_state, rv_status],
+            )
+            rv_approve_all_btn.click(
+                fn=on_rv_approve_all,
+                inputs=[rv_pdf_state, rv_page_state, rv_annotations_state, rv_ledger_state],
+                outputs=[rv_canvas_render_txt, rv_df, rv_annotations_state, rv_ledger_state, rv_status],
+            )
+            rv_reject_all_btn.click(
+                fn=on_rv_reject_all,
+                inputs=[rv_pdf_state, rv_page_state, rv_annotations_state, rv_ledger_state],
+                outputs=[rv_canvas_render_txt, rv_df, rv_annotations_state, rv_ledger_state, rv_status],
+            )
+            rv_df.select(
+                fn=on_row_select,
+                inputs=None,
+                outputs=[rv_selected_state],
+            ).then(
+                fn=lambda idx: f"Box #{idx + 1}" if idx >= 0 else "— none —",
+                inputs=[rv_selected_state],
+                outputs=[rv_selected_lbl],
+            ).then(
+                fn=on_fill_edit_form,
+                inputs=[rv_selected_state, rv_page_state, rv_annotations_state],
+                outputs=[edit_x1, edit_y1, edit_x2, edit_y2],
+            )
+            rv_approve_sel_btn.click(
+                fn=on_rv_approve_selected,
+                inputs=[rv_pdf_state, rv_page_state, rv_annotations_state, rv_ledger_state, rv_selected_state],
+                outputs=[rv_canvas_render_txt, rv_df, rv_annotations_state, rv_ledger_state, rv_status],
+            )
+            rv_copy_sel_btn.click(
+                fn=on_rv_copy_selected,
+                inputs=[rv_pdf_state, rv_page_state, rv_annotations_state, rv_ledger_state, rv_selected_state],
+                outputs=[rv_canvas_render_txt, rv_df, rv_annotations_state, rv_ledger_state, rv_status],
+            )
+            rv_delete_sel_btn.click(
+                fn=on_rv_delete_selected,
+                inputs=[rv_pdf_state, rv_page_state, rv_annotations_state, rv_ledger_state, rv_selected_state],
+                outputs=[
+                    rv_canvas_render_txt,
+                    rv_df,
+                    rv_annotations_state,
+                    rv_ledger_state,
+                    rv_status,
+                    rv_selected_state,
+                ],
+            ).then(
+                fn=lambda idx: f"Box #{idx + 1}" if idx >= 0 else "— none —",
+                inputs=[rv_selected_state],
+                outputs=[rv_selected_lbl],
+            )
+            update_box_btn.click(
+                fn=on_rv_update_box,
+                inputs=[
+                    rv_pdf_state,
+                    rv_page_state,
+                    rv_annotations_state,
+                    rv_ledger_state,
+                    rv_selected_state,
+                    edit_x1,
+                    edit_y1,
+                    edit_x2,
+                    edit_y2,
+                ],
+                outputs=[rv_canvas_render_txt, rv_df, rv_annotations_state, rv_ledger_state, rv_status],
+            )
+            export_events_btn.click(
+                fn=on_export_events,
+                inputs=[rv_ledger_state],
+                outputs=[export_file_out],
+            )
+            export_dataset_btn.click(
+                fn=on_export_dataset,
+                inputs=[rv_ledger_state, rv_pdf_state],
+                outputs=[export_file_out],
+            )
+
+        # ------------------------------------------------------------------ #
+        #  Tab 3: Send to Backend                                              #
+        # ------------------------------------------------------------------ #
+        with gr.Tab("Send to Backend"):
+            gr.Markdown(
+                "Sends **approved** annotations from the **Review & Edit** tab to your backend. "
+                "Detect pages, approve the boxes you want, then click **Send to Backend**."
+            )
+            with gr.Row():
+                with gr.Column():
+                    backend_url_input = gr.Textbox(label="Backend Base URL", value="http://localhost:8000")
+                    document_id_input = gr.Number(label="Document ID", value=1, precision=0)
+                    frame_template_id_input = gr.Number(label="Frame Template ID", value=1, precision=0)
+                    tenant_id_input = gr.Number(label="x-tenant-id", value=1, precision=0)
+                    user_id_input = gr.Number(label="x-user-id", value=1, precision=0)
+                    color_input = gr.Textbox(label="Color (optional)", placeholder="#FF5500")
+                    quantity_input = gr.Number(label="Quantity Multiplier", value=1, minimum=1, precision=0)
+                    send_btn = gr.Button("Send to Backend", variant="primary")
+                with gr.Column():
+                    response_output = gr.JSON(label="Backend Response")
+            send_btn.click(
+                fn=send_to_backend,
+                inputs=[
+                    rv_annotations_state,
+                    backend_url_input,
+                    document_id_input,
+                    frame_template_id_input,
+                    tenant_id_input,
+                    user_id_input,
+                    color_input,
+                    quantity_input,
+                ],
+                outputs=[response_output],
+            )
+
+    gr.HTML(_CANVAS_JS)
+
+if __name__ == "__main__":
+    demo.launch()

detection.py

@@ -0,0 +1,187 @@
+"""
+YOLO-based facade frame detector for Takeoff AI Annotator.
+
+The model is loaded once at startup from the path set by the FACADE_MODEL_PATH
+environment variable (defaults to 'best.pt' in the same directory as this
+file). Pass a different path at launch time:
+
+    FACADE_MODEL_PATH=/path/to/best.pt python app.py
+"""
+
+from __future__ import annotations
+
+import os
+from pathlib import Path
+
+import cv2
+import numpy as np
+
+# ---------------------------------------------------------------------------
+# Model loading
+# ---------------------------------------------------------------------------
+_MODEL = None
+_MODEL_PATH: str | None = None
+
+
+def _get_model():
+    global _MODEL, _MODEL_PATH
+
+    path = os.environ.get(
+        "FACADE_MODEL_PATH",
+        str(Path(__file__).parent / "best.pt"),
+    )
+
+    if _MODEL is None or path != _MODEL_PATH:
+        try:
+            from ultralytics import YOLO
+
+            _MODEL = YOLO(path)
+            _MODEL_PATH = path
+            print(f"[detection] Loaded YOLO model from: {path}")
+        except Exception as exc:
+            print(f"[detection] WARNING: Could not load YOLO model ({exc}). Falling back to OpenCV contour detection.")
+            _MODEL = None
+
+    return _MODEL
+
+
+def get_model_version() -> str:
+    """Return the version tag from versions.json if present, else 'unversioned'."""
+    versions_path = Path(__file__).parent / "versions.json"
+    if versions_path.exists():
+        try:
+            import json
+
+            data = json.loads(versions_path.read_text())
+            if isinstance(data, list) and data:
+                return data[-1].get("version", "unversioned")
+            if isinstance(data, dict):
+                return data.get("version", "unversioned")
+        except Exception:
+            pass
+    return "unversioned"
+
+
+# ---------------------------------------------------------------------------
+# Detection — returns list[dict] with keys x1, y1, x2, y2, conf
+# ---------------------------------------------------------------------------
+
+
+def detect_rectangles(
+    image: np.ndarray,
+    conf: float = 0.25,
+    iou: float = 0.45,
+    # Legacy parameters — only used when YOLO is not available (OpenCV fallback)
+    min_area: int = 500,
+    max_area: int = 500_000,
+    epsilon_factor: float = 0.02,
+    threshold: int = 127,
+) -> list[dict]:
+    """
+    Detect facade frame panels in a construction plan image.
+
+    Tries YOLO first; falls back to OpenCV contour detection if the model
+    is unavailable.
+
+    Returns a list of dicts: {x1, y1, x2, y2, conf} in image pixel coordinates.
+    conf is the model confidence (0-1). OpenCV fallback sets conf=1.0.
+    """
+    model = _get_model()
+
+    if model is not None:
+        return _yolo_detect(model, image, conf=conf, iou=iou)
+
+    return _cv_detect(image, min_area=min_area, max_area=max_area, epsilon_factor=epsilon_factor, threshold=threshold)
+
+
+def _yolo_detect(
+    model,
+    image: np.ndarray,
+    conf: float,
+    iou: float,
+) -> list[dict]:
+    results = model.predict(
+        source=image,
+        conf=conf,
+        iou=iou,
+        imgsz=640,
+        device="cpu",
+        verbose=False,
+    )
+    boxes: list[dict] = []
+    for result in results:
+        if result.boxes is None:
+            continue
+        for box in result.boxes:
+            x1, y1, x2, y2 = box.xyxy[0].tolist()
+            c = float(box.conf[0])
+            boxes.append({"x1": float(x1), "y1": float(y1), "x2": float(x2), "y2": float(y2), "conf": round(c, 4)})
+    return boxes
+
+
+def _cv_detect(
+    image: np.ndarray,
+    min_area: int,
+    max_area: int,
+    epsilon_factor: float,
+    threshold: int,
+) -> list[dict]:
+    """OpenCV fallback — original contour-based detection, conf fixed at 1.0."""
+    gray = cv2.cvtColor(image, cv2.COLOR_BGR2GRAY) if len(image.shape) == 3 else image.copy()
+    blurred = cv2.GaussianBlur(gray, (5, 5), 0)
+
+    _, binary = cv2.threshold(blurred, threshold, 255, cv2.THRESH_BINARY_INV)
+    edges = cv2.Canny(blurred, 50, 150)
+    combined = cv2.bitwise_or(binary, edges)
+
+    contours, _ = cv2.findContours(combined, cv2.RETR_TREE, cv2.CHAIN_APPROX_SIMPLE)
+
+    results: list[dict] = []
+    seen: set[tuple[int, int, int, int]] = set()
+
+    for contour in contours:
+        area = cv2.contourArea(contour)
+        if area < min_area or area > max_area:
+            continue
+
+        peri = cv2.arcLength(contour, True)
+        approx = cv2.approxPolyDP(contour, epsilon_factor * peri, True)
+
+        if len(approx) != 4:
+            continue
+
+        x, y, w, h = cv2.boundingRect(approx)
+        key = (x, y, x + w, y + h)
+        if key in seen:
+            continue
+        seen.add(key)
+
+        results.append({"x1": float(x), "y1": float(y), "x2": float(x + w), "y2": float(y + h), "conf": 1.0})
+
+    return results
+
+
+# ---------------------------------------------------------------------------
+# Visualisation helper
+# ---------------------------------------------------------------------------
+
+
+def draw_detections(image: np.ndarray, boxes: list[dict]) -> np.ndarray:
+    """Draw detection boxes on image. boxes is list[dict] with x1,y1,x2,y2,conf."""
+    annotated = image.copy()
+    for i, box in enumerate(boxes):
+        x1, y1, x2, y2 = int(box["x1"]), int(box["y1"]), int(box["x2"]), int(box["y2"])
+        conf = box.get("conf", 1.0)
+        cv2.rectangle(annotated, (x1, y1), (x2, y2), (0, 200, 0), 2)
+        label = f"{i + 1} {conf:.2f}"
+        cv2.putText(
+            annotated,
+            label,
+            (x1 + 4, y1 + 16),
+            cv2.FONT_HERSHEY_SIMPLEX,
+            0.5,
+            (0, 200, 0),
+            1,
+            cv2.LINE_AA,
+        )
+    return annotated

packages.txt

@@ -0,0 +1 @@
+poppler-utils

requirements.txt

@@ -0,0 +1,9 @@
+gradio>=5.9.1,<5.10.0
+opencv-python-headless>=4.8.0
+numpy>=1.24.0
+Pillow>=10.0.0
+requests>=2.31.0
+pymupdf>=1.23.0
+ultralytics>=8.3.0
+plotly>=5.18.0
+pandas>=2.0.0