fix: scan

Author: Leoglme

api/services/card_image_gate.py

@@ -0,0 +1,104 @@
+"""
+Cheap pre-check run *before* any (paid) Groq vision call: does this frame
+actually contain a sharp, framed trading card?
+
+A phone camera in "cash register" mode streams many frames; without this gate
+an empty desk, a blurry pan or a finger would each cost a Groq request and
+trip 429s. Pure Pillow + stdlib — no numpy / OpenCV dependency.
+
+Heuristics (all must pass):
+
+* **detail**   — luminance stddev. An empty/uniform surface is flat.
+* **focus**    — edge-energy spread (variance-of-Laplacian proxy). A blurry
+  or motion-smeared frame has little high-frequency content.
+* **framing**  — the "busy" region (thresholded edges) must fill a large,
+  roughly centered, card-proportioned part of the frame, i.e. an actual card
+  presented to the lens rather than clutter in a corner.
+"""
+
+from __future__ import annotations
+
+import io
+import logging
+from dataclasses import dataclass
+
+from PIL import Image, ImageFilter, ImageOps, ImageStat
+
+logger = logging.getLogger(__name__)
+
+#: Long edge the frame is downscaled to before analysis (speed).
+_ANALYZE_EDGE = 256
+#: Edge-map binarisation threshold (0–255) for the "busy region" mask.
+_EDGE_BIN_THRESHOLD = 38
+
+# --- Acceptance thresholds (strict: better to skip a frame than to spam Groq;
+#     a real card held in frame produces several qualifying frames anyway).
+_MIN_DETAIL_STDDEV = 17.0
+_MIN_FOCUS = 9.0
+_MIN_FILL = 0.42
+_CENTER_LO = 0.22
+_CENTER_HI = 0.78
+_CARD_AR_MIN = 0.45
+_CARD_AR_MAX = 2.20
+
+
+@dataclass(frozen=True)
+class CardGateResult:
+    """Outcome of :func:`assess_card_image`."""
+
+    is_card: bool
+    #: ``ok`` | ``unreadable`` | ``too_small`` | ``empty`` | ``blurry`` | ``no_card``
+    reason: str
+    detail: float
+    focus: float
+    fill: float
+
+
+def _bbox_metrics(edges: Image.Image, w: int, h: int) -> tuple[float, bool, bool]:
+    """Return ``(fill_ratio, centered, aspect_ok)`` for the thresholded edge map."""
+    lut = [0 if i <= _EDGE_BIN_THRESHOLD else 255 for i in range(256)]
+    box = edges.point(lut).getbbox()
+    if not box:
+        return 0.0, False, False
+    bx0, by0, bx1, by1 = box
+    bw = max(1, bx1 - bx0)
+    bh = max(1, by1 - by0)
+    fill = (bw * bh) / float(w * h)
+    cx = (bx0 + bx1) / 2.0 / w
+    cy = (by0 + by1) / 2.0 / h
+    centered = _CENTER_LO <= cx <= _CENTER_HI and _CENTER_LO <= cy <= _CENTER_HI
+    aspect = bw / bh
+    aspect_ok = _CARD_AR_MIN <= aspect <= _CARD_AR_MAX
+    return fill, centered, aspect_ok
+
+
+def assess_card_image(image_bytes: bytes) -> CardGateResult:
+    """
+    Decide whether ``image_bytes`` looks like a card worth sending to OCR.
+
+    Never raises — any decode/processing error is reported as a non-card so the
+    caller simply skips the frame (no Groq call).
+    """
+    try:
+        img = Image.open(io.BytesIO(image_bytes))
+        img = ImageOps.exif_transpose(img).convert("L")
+    except Exception:  # noqa: BLE001 - any malformed upload is just "not a card"
+        return CardGateResult(False, "unreadable", 0.0, 0.0, 0.0)
+
+    img.thumbnail((_ANALYZE_EDGE, _ANALYZE_EDGE))
+    w, h = img.size
+    if w < 48 or h < 48:
+        return CardGateResult(False, "too_small", 0.0, 0.0, 0.0)
+
+    detail = float(ImageStat.Stat(img).stddev[0])
+    edges = img.filter(ImageFilter.FIND_EDGES)
+    focus = float(ImageStat.Stat(edges).stddev[0])
+    fill, centered, aspect_ok = _bbox_metrics(edges, w, h)
+
+    if detail < _MIN_DETAIL_STDDEV:
+        return CardGateResult(False, "empty", detail, focus, fill)
+    if focus < _MIN_FOCUS:
+        return CardGateResult(False, "blurry", detail, focus, fill)
+    if fill < _MIN_FILL or not centered or not aspect_ok:
+        return CardGateResult(False, "no_card", detail, focus, fill)
+    return CardGateResult(True, "ok", detail, focus, fill)

api/services/scan_stream_service.py

@@ -27,6 +27,7 @@
 from core.database import SessionLocal
 from models.collection_card import CollectionCard
 from services import collection_card_service
+from services.card_image_gate import assess_card_image
 from services.collection_card_lookup_service import fetch_card_for_collection
 from services.ocr_service import extract_card_from_bytes
 from services.scan_service import detect_physical_language_from_ocr
@@ -40,6 +41,14 @@
 _GROQ_PARALLELISM = 4
 _groq_sem = asyncio.Semaphore(_GROQ_PARALLELISM)
 
+#: Per-user guards so a "cash register" frame stream becomes *one* Groq call
+#: per physical card instead of a burst (the source of the 429s).
+#: - ``_inflight``: a scan is already being processed for this user.
+#: - ``_last_accept``: epoch of the last frame that passed the gate.
+_MIN_OCR_INTERVAL_SEC = 2.5
+_inflight: set[int] = set()
+_last_accept: dict[int, float] = {}
+
 
 def _now_iso() -> float:
     return time.time()
@@ -139,7 +148,7 @@ def _add_or_increment(
         db.close()
 
 
-async def _run_scan_pipeline(
+async def _process_scan(
     *,
     event_id: str,
     user_id: int,
@@ -149,7 +158,7 @@ async def _run_scan_pipeline(
     physical_language: str,
     user_hint: str | None,
 ) -> None:
-    """End-to-end processing for a single scan event."""
+    """End-to-end processing for a single scan event (gate already passed)."""
     hub = get_scan_stream_hub()
 
     preview = _short_preview_data_url(image_bytes, mime)
@@ -330,6 +339,65 @@ async def _run_scan_pipeline(
     )
 
 
+async def _run_scan_pipeline(
+    *,
+    event_id: str,
+    user_id: int,
+    image_bytes: bytes,
+    filename: str,
+    mime: str,
+    physical_language: str,
+    user_hint: str | None,
+) -> None:
+    """
+    Pre-Groq gate. A streaming camera sends many frames; we only let one
+    through per real card:
+
+    * **in-flight guard** — a scan is already running for this user → drop.
+    * **debounce** — last accepted frame < ``_MIN_OCR_INTERVAL_SEC`` ago → drop.
+    * **card pre-detection** — empty / blurry / not-a-card → drop.
+
+    Rejections are silent (no websocket event), so the live feed only shows
+    real cards — like the existing phone card-scanner apps. No Groq call is
+    made unless a frame clears every check, which is what stops the 429s.
+    """
+    now = time.time()
+    if user_id in _inflight:
+        logger.debug("scan-stream: drop (in-flight) user=%s", user_id)
+        return
+    if now - _last_accept.get(user_id, 0.0) < _MIN_OCR_INTERVAL_SEC:
+        logger.debug("scan-stream: drop (debounce) user=%s", user_id)
+        return
+
+    loop = asyncio.get_running_loop()
+    gate = await loop.run_in_executor(None, lambda: assess_card_image(image_bytes))
+    if not gate.is_card:
+        logger.debug(
+            "scan-stream: drop (%s) user=%s detail=%.1f focus=%.1f fill=%.2f",
+            gate.reason,
+            user_id,
+            gate.detail,
+            gate.focus,
+            gate.fill,
+        )
+        return
+
+    _inflight.add(user_id)
+    _last_accept[user_id] = now
+    try:
+        await _process_scan(
+            event_id=event_id,
+            user_id=user_id,
+            image_bytes=image_bytes,
+            filename=filename,
+            mime=mime,
+            physical_language=physical_language,
+            user_hint=user_hint,
+        )
+    finally:
+        _inflight.discard(user_id)
+
+
 def submit_scan(
     *,
     user_id: int,