Live delivery progress: background removal, embeddings, labels

app.py

@@ -5,7 +5,9 @@
 import json
 import logging
 import os
+import re
 import secrets
+import threading
 import time
 from collections import defaultdict, deque
 
@@ -199,12 +201,45 @@ def create_delivery():
     days = request.form.get("delivered_days_ago", "0").strip() or "0"
     if not days.isdigit() or int(days) > 365:
         raise service.InputError("'Delivered days ago' must be a whole number between 0 and 365.")
-    order = service.register_delivery(uploaded_images(), customer["customer_id"],
-                                      request.form.get("product_name", "").strip()[:120],
-                                      request.form.get("category", "other"), int(days))
+    job = _progress_key(customer["customer_id"], request.form.get("job_id", ""))
+
+    def on_stage(key, detail=""):
+        if job:
+            with _progress_lock:
+                _progress[job] = {"stage": key, "detail": detail, "at": time.time()}
+
+    try:
+        order = service.register_delivery(uploaded_images(), customer["customer_id"],
+                                          request.form.get("product_name", "").strip()[:120],
+                                          request.form.get("category", "other"), int(days), on_stage=on_stage)
+    finally:
+        if job:
+            with _progress_lock:
+                _progress.pop(job, None)
     return jsonify(success=True, order=order, images=media_urls("orders", order["order_id"]))
 
 
+# Live delivery progress: the browser sends a random job_id with the upload and polls this while it waits.
+_progress: dict[tuple[str, str], dict] = {}
+_progress_lock = threading.Lock()
+
+
+def _progress_key(customer_id: str, job_id: str):
+    return (customer_id, job_id) if re.fullmatch(r"[A-Za-z0-9-]{8,64}", job_id or "") else None
+
+
+@app.get("/api/deliveries/progress/<job_id>")
+def delivery_progress(job_id):
+    customer = require_customer()
+    key = _progress_key(customer["customer_id"], job_id)
+    with _progress_lock:
+        stale = [k for k, v in _progress.items() if time.time() - v["at"] > 600]
+        for k in stale:
+            _progress.pop(k, None)
+        state = _progress.get(key) if key else None
+    return jsonify(success=True, stage=state["stage"] if state else None, detail=state["detail"] if state else "")
+
+
 @app.post("/api/returns")
 def create_return():
     customer = require_customer()

returnguard/service.py

@@ -97,21 +97,32 @@ def _save(images: dict, cutouts: dict, folder):
 
 # ── delivery ───────────────────────────────────────────────────────────────
 def register_delivery(files: dict, customer_id: str, product_name: str, category: str,
-                      delivered_days_ago: int = 0) -> dict:
+                      delivered_days_ago: int = 0, on_stage=None) -> dict:
+    """on_stage(key, detail) is called as each step starts, so the UI can show live progress."""
+    stage = on_stage or (lambda key, detail="": None)
     if category not in config.RETURN_WINDOW_DAYS:
         raise InputError(f"Unknown category '{category}'.")
     images = _load_all(files)
-    cutouts = {a: imaging.remove_background(images[a]) for a in config.ANGLES}
+    cutouts = {}
+    for i, a in enumerate(config.ANGLES, 1):
+        stage("background", f"{a} view ({i}/{len(config.ANGLES)})")
+        cutouts[a] = imaging.remove_background(images[a])
+    stage("quality", "blur and framing")
     quality = {a: imaging.assess_quality(images[a], cutouts[a]) for a in config.ANGLES}
     bad = [f"{a.capitalize()}: {q.problem}" for a, q in quality.items() if not q.ok]
     if bad:
         raise InputError(" ".join(bad))
 
-    features = {a: view_features(cutouts[a]).to_dict() for a in config.ANGLES}
+    features = {}
+    for i, a in enumerate(config.ANGLES, 1):
+        stage("embeddings", f"{a} view ({i}/{len(config.ANGLES)})")
+        features[a] = view_features(cutouts[a]).to_dict()
+    stage("save", "")
     delivered_at = (datetime.now(timezone.utc) - timedelta(days=max(0, delivered_days_ago))).isoformat(timespec="seconds")
     order_id = storage.create_order(customer_id, product_name, category, delivered_at, features)
     _save(images, cutouts, order_dir(order_id))
 
+    stage("labels", f"order #{order_id}")
     try:
         fp, rec = identity.fingerprint(cutouts)
         fingerprint = fp.model_dump()

static/app.css

@@ -595,3 +595,14 @@ footer a:hover { color: var(--text); }
 @media (prefers-reduced-motion: reduce) {
   *, *::before, *::after { animation-duration: .001ms !important; transition-duration: .001ms !important; }
 }
+
+/* ── live progress steps (busy overlay) ─────────────────────────────── */
+.live-steps { list-style: none; margin: 18px auto 0; padding: 0; text-align: left; display: grid; gap: 10px; min-width: 300px; }
+.live-steps li { display: flex; align-items: flex-start; gap: 10px; font-size: 14px; color: var(--text-3); transition: color .2s; }
+.live-steps .ls-icon { width: 18px; height: 18px; flex-shrink: 0; margin-top: 1px; border-radius: 50%; border: 1.5px solid var(--border-strong, var(--border)); }
+.live-steps .ls-detail { color: var(--text-3); font-size: 12.5px; font-weight: 400; }
+.live-steps li.active { color: var(--text); font-weight: 500; }
+.live-steps li.active .ls-icon { border: 2px solid var(--surface-3); border-top-color: var(--accent); animation: spin .8s linear infinite; }
+.live-steps li.done { color: var(--text-2); }
+.live-steps li.done .ls-icon { border-color: var(--ok); background: var(--ok); position: relative; }
+.live-steps li.done .ls-icon::after { content: ""; position: absolute; left: 5px; top: 2px; width: 4px; height: 8px; border: solid #fff; border-width: 0 2px 2px 0; transform: rotate(45deg); }

static/app.js

@@ -49,11 +49,37 @@ function toast(msg, type = '') {
   clearTimeout(toastTimer);
   toastTimer = setTimeout(() => t.classList.remove('show'), 4500);
 }
-function busy(on, title = '', sub = '') {
+function busy(on, title = '', sub = '', steps = null) {
   $('#busy').classList.toggle('show', on);
+  $('#busy-spinner').classList.toggle('hidden', on && !!steps);
+  $('#busy-steps').classList.toggle('hidden', !(on && steps));
   if (on) { $('#busy-title').textContent = title; $('#busy-sub').textContent = sub; }
+  if (on && steps) {
+    $('#busy-steps').innerHTML = steps.map(s => `<li data-step="${s.key}"><span class="ls-icon"></span><span class="ls-text">${esc(s.label)}<small class="ls-detail"></small></span></li>`).join('');
+    busyStep(steps[0].key);
+  }
+}
+// Mark every step before `key` done and `key` itself active (with an optional detail like "front view (1/3)").
+function busyStep(key, detail = '') {
+  const items = $$('#busy-steps li');
+  const at = items.findIndex(li => li.dataset.step === key);
+  if (at < 0) return;
+  items.forEach((li, i) => {
+    li.className = i < at ? 'done' : i === at ? 'active' : '';
+    $('.ls-detail', li).textContent = i === at && detail ? ` · ${detail}` : '';
+  });
 }
 
+const DELIVERY_STEPS = [
+  { key: 'upload', label: 'Uploading photos' },
+  { key: 'background', label: 'Removing backgrounds' },
+  { key: 'quality', label: 'Checking photo quality' },
+  { key: 'embeddings', label: 'Computing DINOv2 embeddings and colour' },
+  { key: 'save', label: 'Saving the order' },
+  { key: 'labels', label: 'Gemini reading labels and serials' },
+];
+const newJobId = () => (crypto.randomUUID ? crypto.randomUUID() : `job-${Date.now()}-${Math.random().toString(36).slice(2, 10)}`);
+
 /* ── theme ───────────────────────────────────────────────────────────── */
 function initTheme() {
   const apply = t => {
@@ -163,9 +189,24 @@ function initDelivery() {
   form.addEventListener('submit', async e => {
     e.preventDefault();
     if (ANGLES.some(a => !$(`input[name="${a}_image"]`, form).files.length)) return toast('Add all three photos (front, back, side).', 'error');
-    busy(true, 'Registering delivery', 'Removing backgrounds, computing embeddings, and reading labels with the identity agent…');
+    busy(true, 'Registering delivery', 'Live progress from the server:', DELIVERY_STEPS);
+    const jobId = newJobId();
+    const body = new FormData(form);
+    body.append('job_id', jobId);
+    let polling = true;
+    (async function poll() {
+      while (polling) {
+        try {
+          const p = await api(`/api/deliveries/progress/${jobId}`);
+          if (polling && p.stage) busyStep(p.stage, p.detail);
+        } catch (e) { /* progress is best effort */ }
+        await new Promise(r => setTimeout(r, 450));
+      }
+    })();
     try {
-      const data = await api('/api/deliveries', { method: 'POST', body: new FormData(form) });
+      const data = await api('/api/deliveries', { method: 'POST', body });
+      polling = false;
+      $$('#busy-steps li').forEach(li => { li.className = 'done'; });
       store.set('rg-last-order', data.order.order_id);
       renderDelivery(data.order, data.images);
       clearPreviews(form);
@@ -175,6 +216,7 @@ function initDelivery() {
     } catch (err) {
       toast(err.message, 'error');
     } finally {
+      polling = false;
       busy(false);
     }
   });

templates/index.html

@@ -56,7 +56,7 @@
 </div>
 
 <div class="toast" id="toast" role="status" aria-live="polite"></div>
-<div class="busy" id="busy"><div class="busy-card"><div class="spinner"></div><div class="h3" id="busy-title">Working…</div><p class="muted" id="busy-sub"></p></div></div>
+<div class="busy" id="busy"><div class="busy-card"><div class="spinner" id="busy-spinner"></div><div class="h3" id="busy-title">Working…</div><p class="muted" id="busy-sub"></p><ol class="live-steps hidden" id="busy-steps"></ol></div></div>
 
 <main>
 <!-- ══════════════════════════ HOME ══════════════════════════ -->