Real OCR on image upload via cloud ZeroGPU Lab (text/seed stay deterministic)

- LMC_IMAGE_OCR decouples photo OCR from the text extractor: /ingest/image
routes to the ZeroGPU NuExtract3 Lab (real image->markdown + KVT4 facts),
while seeded card + text paste + safety stay on deterministic stub
(instant load, zero cloud unless a photo is explicitly uploaded)
- pipeline.ingest gains a per-doc extractor override (no change to card default)
- normalize fact timestamps to tz-aware UTC in observation_to_kvt (fixes
naive-vs-aware crash when cloud-OCR facts merge into stub-seeded series)
- Dockerfile: add gradio_client, set LMC_IMAGE_OCR=ocrlab

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

Dockerfile

@@ -1,16 +1,20 @@
-# LiveMedCard demo — Hugging Face Docker Space (CPU, детермінований stub-режим).
-# Публічний прототип для Digital Future Hackathon. Дані не покидають процес; без LLM/GPU.
+# LiveMedCard demo — Hugging Face Docker Space (CPU).
+# Публічний прототип для Digital Future Hackathon. Текст/сід/безпека — детермінований
+# `stub` (миттєвий старт, дані не покидають процес). Завантаження ФОТО (`/ingest/image`)
+# — реальний OCR через хмарний ZeroGPU Lab (NuExtract3), лише синтетичні документи.
 FROM python:3.12-slim
 
 ENV PYTHONUNBUFFERED=1 \
     PIP_NO_CACHE_DIR=1 \
     LMC_EXTRACTOR=stub \
+    LMC_IMAGE_OCR=ocrlab \
     LMC_SEED_SAMPLES=1
 
 WORKDIR /app
 
-# Лише stub-залежності (без torch/transformers) — легкий образ, швидкий cold-start.
-RUN pip install "pydantic>=2" "networkx>=3" "fastapi>=0.110" "uvicorn>=0.29"
+# stub-залежності (без torch/transformers) + gradio_client для виклику хмарного
+# OCR Lab із фото. Легкий образ, швидкий cold-start; GPU лишається на боці Lab.
+RUN pip install "pydantic>=2" "networkx>=3" "fastapi>=0.110" "uvicorn>=0.29" "gradio_client>=1.3"
 
 # Пакет разом зі static/ (SPA) і data/ (демо-документи, довідники).
 COPY livemedcard ./livemedcard

livemedcard/api.py

@@ -37,6 +37,7 @@ from pydantic import BaseModel
 from .bundle import from_bundle, to_bundle
 from .config import (
     EXTRACTOR,
+    IMAGE_OCR,
     MAX_DOC_CHARS,
     PERSIST_PATH,
     SEED_SAMPLES,
@@ -147,14 +148,20 @@ def ingest_image(req: ImageIngestRequest):
             detail="Зображення порожнє або некоректне",
         )
 
-    # У режимах nuextract/ocrlab зображення читає сам NuExtract (image→markdown),
-    # тож окремий OCR не потрібен — уникаємо накопичення помилок OCR→summary→extract.
-    # ocrlab робить image→markdown на хмарному ZeroGPU Space (opt-in).
+    # Бекенд OCR для фото відокремлений від текстового EXTRACTOR (config.IMAGE_OCR):
+    # публічне демо тримає `stub` для сіду/тексту (миттєво, детерміновано, 0 хмари),
+    # а фото — реальний OCR через хмарний Lab. `nuextract`/`ocrlab` самі роблять
+    # image→markdown, тож окремий OCR не потрібен. Витяг фактів для цього документа
+    # робить відповідний екстрактор (override), не змінюючи дефолт картки.
+    img_backend = IMAGE_OCR or EXTRACTOR
+    img_extractor: Extractor | None = None
     try:
-        if EXTRACTOR == "ocrlab":
+        if img_backend == "ocrlab":
             text = l2b_ocrlab.image_to_markdown(req.image_base64)
-        elif EXTRACTOR == "nuextract":
+            img_extractor = OcrLabExtractor()
+        elif img_backend == "nuextract":
             text = l2b_nuextract.image_to_markdown(req.image_base64)
+            img_extractor = NuExtractExtractor()
         else:
             text = OcrService.perform_ocr(req.image_base64)
     except (OcrError, LLMError, OcrLabError) as exc:
@@ -183,9 +190,12 @@ def ingest_image(req: ImageIngestRequest):
     doc_id = f"doc-ocr-{hashlib.sha1(text.encode('utf-8')).hexdigest()[:12]}"
     doc = Document(id=doc_id, text=text, kind=req.kind)
 
-    with _state.lock:
-        report = _state.card.ingest(doc)
-        _state.autosave()
+    try:
+        with _state.lock:
+            report = _state.card.ingest(doc, extractor=img_extractor)
+            _state.autosave()
+    except OcrLabError as exc:  # витяг фактів Stage 2 у хмарному Lab
+        raise HTTPException(status_code=503, detail=str(exc))
     return report
 
 

livemedcard/config.py

@@ -41,8 +41,15 @@ OCR_MODEL = os.getenv("LMC_OCR_MODEL", "medgemma-1.5-4b-it")
 #                      (opt-in cloud; лише синтетичні/деідентифіковані документи).
 EXTRACTOR = os.getenv("LMC_EXTRACTOR", "stub")
 
-# Хмарний OCR Lab (ZeroGPU) — окремий Gradio Space (Spec.md). Вмикається лише коли
-# EXTRACTOR == "ocrlab"; за замовчуванням не використовується (pitch-демо на stub).
+# Бекенд OCR саме для завантаження ФОТО (`/ingest/image`), відокремлений від
+# текстового екстрактора. Дозволяє публічному демо тримати детермінований `stub`
+# для сіду/тексту/безпеки (миттєвий старт, 0 хмари), але для явного завантаження
+# фото — робити РЕАЛЬНИЙ OCR через хмарний Lab. Порожньо → успадковує EXTRACTOR.
+#   "ocrlab" — хмарний ZeroGPU NuExtract3; "nuextract" — локальний; "local" — vision-LLM (OcrService).
+IMAGE_OCR = os.getenv("LMC_IMAGE_OCR", "")
+
+# Хмарний OCR Lab (ZeroGPU) — окремий Gradio Space (Spec.md). Вмикається, коли
+# EXTRACTOR == "ocrlab" АБО IMAGE_OCR == "ocrlab" (лише синтетичні/деідентифіковані документи).
 OCRLAB_SPACE = os.getenv("LMC_OCRLAB_SPACE", "DocUA/livemedcard-ocr-lab")
 OCRLAB_TOKEN = os.getenv("LMC_OCRLAB_TOKEN") or os.getenv("HF_TOKEN") or None
 

livemedcard/pipeline.py

@@ -104,14 +104,19 @@ class LiveMedCard:
             self.factstore, self.patient.gender, lang
         )
 
-    def ingest(self, doc: Document) -> TraceReport:
-        """Прогнати один документ і повернути повний TRACE-звіт поточного стану."""
+    def ingest(self, doc: Document, *, extractor: "Extractor | None" = None) -> TraceReport:
+        """Прогнати один документ і повернути повний TRACE-звіт поточного стану.
+
+        `extractor` — разовий override L2b для цього документа (не змінює дефолт
+        картки). Використовується для завантаження фото через хмарний OCR Lab,
+        коли текстовий шлях лишається детермінованим `stub`.
+        """
         # Без мітки часу обзервації не потрапляють у факт-стор і зникають з
         # таймлайну (і з перевірок безпеки). Проставляємо час прийому документа.
         if doc.received_at is None:
             doc = doc.model_copy(update={"received_at": datetime.now(timezone.utc)})
         self._document_ids.add(doc.id)
-        ext = self.extractor.extract(doc, self.patient.id)
+        ext = (extractor or self.extractor).extract(doc, self.patient.id)
         _assert_provenance(ext)
         self._absorb(ext)
         signals = self.current_signals()

livemedcard/stores.py

@@ -9,7 +9,7 @@
 """
 from __future__ import annotations
 
-from datetime import datetime
+from datetime import datetime, timezone
 from typing import Optional
 
 import networkx as nx
@@ -61,13 +61,19 @@ def observation_to_kvt(o: Observation) -> Optional[KVTFact]:
     if o.valueQuantity is None or o.effectiveDateTime is None:
         return None
     kw = o.code.text or (o.code.coding[0].display if o.code.coding else "obs")
+    ts = o.effectiveDateTime
+    # Нормалізуємо до tz-aware UTC: різні джерела дають naive (демо-семпли) чи
+    # aware (екстрактори) мітки; без цього series() падає на порівнянні при їх
+    # змішуванні (напр. stub-сід + хмарний OCR фото в одному LOINC-ряді).
+    if ts.tzinfo is None:
+        ts = ts.replace(tzinfo=timezone.utc)
     return KVTFact(
         obs_id=o.id,
         keyword=kw,
         loinc=loinc_of(o),
         value=o.valueQuantity.value,
         unit=o.valueQuantity.unit,
-        ts=o.effectiveDateTime,
+        ts=ts,
         source_doc_id=o.provenance.source_doc_id if o.provenance else None,
         source_span=o.provenance.source_span if o.provenance else None,
     )