fix: warm EasyOCR at startup — cold-init on first currency request exceeded HF proxy timeout and 500'd after every container restart

app/currency_detector.py

@@ -52,20 +52,25 @@ import numpy as np
 import torch
 import torch.nn as nn
 
+import threading
+
 _easyocr_reader = None
+_easyocr_lock = threading.Lock()
 
 
 def _get_ocr_reader():
     """Lazy-loaded, process-wide EasyOCR reader (pure Python, no Tesseract
-    binary dependency — heavy to init, so load once)."""
+    binary dependency — heavy to init, so load once). Lock-guarded because
+    startup warms it from a background thread while requests may arrive."""
     global _easyocr_reader
-    if _easyocr_reader is None:
-        try:
-            import easyocr
-            _easyocr_reader = easyocr.Reader(["en"], gpu=torch.cuda.is_available(), verbose=False)
-        except Exception as e:
-            print(f"[CURRENCY] EasyOCR unavailable ({e}) — OCR-based checks will report not_applicable.")
-            _easyocr_reader = False  # sentinel: tried and failed, don't retry every call
+    with _easyocr_lock:
+        if _easyocr_reader is None:
+            try:
+                import easyocr
+                _easyocr_reader = easyocr.Reader(["en"], gpu=torch.cuda.is_available(), verbose=False)
+            except Exception as e:
+                print(f"[CURRENCY] EasyOCR unavailable ({e}) — OCR-based checks will report not_applicable.")
+                _easyocr_reader = False  # sentinel: tried and failed, don't retry every call
     return _easyocr_reader or None
 
 

app/main.py

@@ -85,6 +85,22 @@ async def lifespan(app: FastAPI):
     currency_detector = CurrencyDetector(weights_dir=weights_dir, device=device)
     print(f"  [OK] Currency detector ready (mode: {currency_detector.mode})")
 
+    # Warm EasyOCR in the background: its lazy first-call init takes long
+    # enough on the free-tier 2vCPU host that the first currency request
+    # after every container (re)start blew past the HF proxy timeout and
+    # 500'd (observed 2026-07-19 — failures rotated across images, warm
+    # container always fine). Boot stays fast; only OCR-dependent checks
+    # degrade gracefully until the thread finishes.
+    import threading
+    from app.currency_detector import _get_ocr_reader
+
+    def _warm_ocr():
+        print("  [P7] Warming EasyOCR reader (background)...")
+        _get_ocr_reader()
+        print("  [P7] EasyOCR reader warm")
+
+    threading.Thread(target=_warm_ocr, daemon=True).start()
+
     print(f"\n{'='*60}")
     print("  KAWACH startup complete — 6 endpoints live")
     print(f"{'='*60}\n")