Unit guard before L2a, LOINC aliases, cloud consent, honest confidence

livemedcard/api.py

@@ -88,6 +88,20 @@ def _make_extractor() -> Extractor:
     return StubExtractor()
 
 
+def _photo_ocr_mode() -> str:
+    """Куди піде завантажене фото: 'cloud' | 'local' | 'none'.
+
+    Публічне демо тримає детермінований `stub` для тексту, але фото віддає в хмарний
+    ZeroGPU Lab — і UI мусить показувати саме це, а не загальне «без хмари».
+    """
+    backend = IMAGE_OCR or EXTRACTOR
+    if backend == "ocrlab":
+        return "cloud"
+    if backend in ("nuextract", "local", "two_stage", "two_stage_lora"):
+        return "local"
+    return "none"
+
+
 class _State:
     """Тримач картки одного пацієнта: доступ лише під `lock`."""
 
@@ -375,6 +389,9 @@ def get_state_endpoint(lang: str = "uk", state: _State = Depends(_get_state)):
             "medications": medications,
             "signals": [s.model_dump() for s in sigs],
             "decision": decision.model_dump(),
+            # Куди піде ФОТО. Інтерфейс мусить казати про це правду: у публічному
+            # демо текст/сід/безпека лишаються на сервері, а фото їде в хмарний Lab.
+            "photo_ocr": _photo_ocr_mode(),
         }
 
 

livemedcard/config.py

@@ -18,6 +18,13 @@ LOW_CONFIDENCE = float(os.getenv("LMC_LOW_CONFIDENCE", "0.6"))
 # Реальний екстрактор (MedGemma) має ставити модельну впевненість замість цієї.
 STUB_CONFIDENCE = float(os.getenv("LMC_STUB_CONFIDENCE", "0.95"))
 
+# Впевненість витягу, зробленого LLM (NuExtract/LoRA/хмарний Lab). Тримаємо НИЖЧЕ
+# LOW_CONFIDENCE навмисно: калібрування в нас поки немає, а обірваний OCR виглядає
+# рівно так само, як повний. Поки не вміємо міряти — чесне значення це «не
+# перевірено», і L3 веде такий документ до людини. Детермінований `stub` (regex +
+# vocab на сирому тексті) лишається при 0.95: там впевненість справді щось означає.
+UNVERIFIED_CONFIDENCE = float(os.getenv("LMC_UNVERIFIED_CONFIDENCE", "0.5"))
+
 # Максимальний розмір тексту документа (символів) — валідація API.
 MAX_DOC_CHARS = int(os.getenv("LMC_MAX_DOC_CHARS", "20000"))
 

livemedcard/layers/l2a_trends.py

@@ -10,6 +10,7 @@ from typing import Optional
 from ..dto import Signal
 from ..reference import range_for
 from ..stores import FactStore
+from ..units import canonical, same_unit
 
 
 def _fmt(v: float) -> str:
@@ -33,6 +34,10 @@ def detect_trends(store: FactStore, lang: str = "uk") -> list[Signal]:
         series = store.series(loinc)
         if len(series) < 3:
             continue
+        # Ряд у різних одиницях — не ряд: 100 mg/dL і 5.5 mmol/L «зростають» лише
+        # на папері. Тренд рахуємо тільки на однорідних одиницях.
+        if len({canonical(f.unit) for f in series}) > 1:
+            continue
         values = [f.value for f in series]
         # Нестрога монотонність із чистою зміною: рівний крок (повторне значення)
         # НЕ скасовує очевидний тренд, але суто рівний ряд трендом не вважається.
@@ -84,6 +89,29 @@ def detect_range_breaches(
         # series відсортований за часом; беремо ОСТАННІЙ (при рівних мітках —
         # останній доданий), щоб L2a і Q&A узгоджено бачили те саме значення.
         latest = series[-1]
+        # Порівнювати з межею можна лише в тих самих одиницях. Інакше — не мовчимо,
+        # а кажемо прямо: перевірку не виконано (мовчазний пропуск гірший за незгоду).
+        if not same_unit(latest.unit, ref.unit):
+            keyword = (ref.keyword_en if lang == "en" and ref.keyword_en else ref.keyword)
+            got = latest.unit or ("not stated" if lang == "en" else "не вказано")
+            detail = (
+                f"{keyword} {_fmt(latest.value)} {got}: units do not match the reference "
+                f"({ref.unit}) — range check not performed"
+                if lang == "en" else
+                f"{keyword} {_fmt(latest.value)} {got}: одиниці не збігаються з довідником "
+                f"({ref.unit}) — перевірку меж не виконано"
+            )
+            signals.append(
+                Signal(
+                    layer="L2a",
+                    kind="unit_mismatch",
+                    severity="moderate",
+                    detail=detail,
+                    subjects=[loinc],
+                    confidence=1.0,
+                )
+            )
+            continue
         if latest.value < ref.low:
             direction = "below range" if lang == "en" else "нижче норми"
         elif latest.value > ref.high:

livemedcard/layers/l2b_extractor.py

@@ -17,6 +17,7 @@ from ..config import (
     STAGE2_MODEL,
     STAGE2_URL,
     STUB_CONFIDENCE,
+    UNVERIFIED_CONFIDENCE,
 )
 from ..dto import Document, ExtractionResult
 from ..fhir import (
@@ -330,6 +331,9 @@ class TwoStageExtractor:
         ext = deterministic_extract(
             summary_text, doc, patient_id, extracted_by="MedGemma-4B+Stage2"
         )
+        # Stage 2 тут детермінований, але читає він LLM-summary: чого модель не
+        # внесла у стиснення, того регекс уже не поверне. Отже — «не перевірено».
+        ext.mean_confidence = UNVERIFIED_CONFIDENCE if ext.observations else 0.0
         ext.document_reference = _build_docref(doc, summary_text, patient_id)
         return ext
 
@@ -367,7 +371,7 @@ class LoraStage2Extractor:
         )
         return ExtractionResult(
             observations=observations,
-            mean_confidence=STUB_CONFIDENCE if observations else 0.0,
+            mean_confidence=UNVERIFIED_CONFIDENCE if observations else 0.0,
             document_reference=_build_docref(doc, summary_text, patient_id),
         )
 
@@ -392,7 +396,7 @@ class NuExtractExtractor:
         )
         return ExtractionResult(
             observations=observations,
-            mean_confidence=STUB_CONFIDENCE if observations else 0.0,
+            mean_confidence=UNVERIFIED_CONFIDENCE if observations else 0.0,
             document_reference=_build_docref(doc, doc.text, patient_id),
         )
 
@@ -427,7 +431,7 @@ class OcrLabExtractor:
         )
         return ExtractionResult(
             observations=observations,
-            mean_confidence=STUB_CONFIDENCE if observations else 0.0,
+            mean_confidence=UNVERIFIED_CONFIDENCE if observations else 0.0,
             document_reference=_build_docref(doc, doc.text, patient_id),
         )
 

livemedcard/layers/l2b_stage2_lora.py

@@ -35,9 +35,13 @@ from ..llm_client import chat_completions
 _KEYWORD_LOINC: dict[str, tuple[str, str]] = {
     # EN (readmission-домен FT) + UA — білінгвальний міст
     "creatinine": ("2160-0", "Creatinine"),
+    "serum creatinine": ("2160-0", "Creatinine"),
     "креатинін": ("2160-0", "Creatinine"),
     "glucose": ("2345-7", "Glucose"),
+    "fasting glucose": ("2345-7", "Glucose"),
+    "blood glucose": ("2345-7", "Glucose"),
     "глюкоза": ("2345-7", "Glucose"),
+    "глюкоза натще": ("2345-7", "Glucose"),
     "potassium": ("2823-3", "Potassium"),
     "калій": ("2823-3", "Potassium"),
     "sodium": ("2951-2", "Sodium"),
@@ -45,6 +49,8 @@ _KEYWORD_LOINC: dict[str, tuple[str, str]] = {
     "hemoglobin": ("718-7", "Hemoglobin"),
     "гемоглобін": ("718-7", "Hemoglobin"),
     "hba1c": ("4548-4", "Hemoglobin A1c"),
+    "hemoglobin a1c": ("4548-4", "Hemoglobin A1c"),
+    "glycated hemoglobin": ("4548-4", "Hemoglobin A1c"),
     "глікований гемоглобін": ("4548-4", "Hemoglobin A1c"),
     "hematocrit": ("4544-3", "Hematocrit"),
     "гематокрит": ("4544-3", "Hematocrit"),
@@ -191,6 +197,12 @@ def to_observations(
         num, unit = _split_value(item.get("value"))
         if num is None:  # нечислові (Yes/No, назви) лишаються лише в summary
             continue
+        # KVT4 з хмарного Lab несе одиницю ОКРЕМИМ полем ({"value":"135","unit":"µmol/L"}),
+        # тоді як локальний шлях вкладає її в рядок значення ("135 мкмоль/л"). Без цього
+        # рядка кожен факт із фото приходив без одиниці — і псував FHIR-експорт.
+        if unit is None:
+            raw_unit = str(item.get("unit") or "").strip()
+            unit = raw_unit or None
         eff = _parse_timestamp(item.get("timestamp"), doc.received_at)
         bridge = _resolve_loinc(keyword)
         coding = (

livemedcard/static/index.html

@@ -268,6 +268,17 @@
   .drawer .cap{padding:10px 18px 0;color:var(--faint);font-size:11.5px}
   .drawer .body{padding:14px 18px 20px;overflow:auto;white-space:pre-wrap;
     font-size:13.5px;line-height:1.75;color:var(--muted)}
+  /* ── cloud consent (photo leaves the device — say so before it does) ── */
+  .consent{position:fixed;left:50%;top:50%;transform:translate(-50%,-46%) scale(.98);
+    width:min(470px,92vw);background:var(--panel);border:1px solid var(--line);border-radius:14px;
+    padding:22px 24px 18px;z-index:60;opacity:0;pointer-events:none;
+    box-shadow:0 24px 60px rgba(4,9,13,.28);transition:opacity .16s,transform .16s}
+  .consent.show{opacity:1;pointer-events:auto;transform:translate(-50%,-50%) scale(1)}
+  .consent h3{margin:0 0 10px;font-size:15.5px;color:var(--critical)}
+  .consent p{margin:0 0 16px;font-size:13px;line-height:1.6;color:var(--muted);white-space:pre-line}
+  .consent .row{display:flex;gap:9px;justify-content:flex-end}
+  .consent .ghost{background:none;border:1px solid var(--line);color:var(--muted)}
+  .consent .ghost:hover{color:var(--ink);border-color:var(--accent)}
   .drawer .body mark{background:color-mix(in srgb,var(--accent) 26%,transparent);color:var(--ink);
     border-radius:4px;padding:1px 3px;font-weight:650;
     box-shadow:0 0 0 1px color-mix(in srgb,var(--accent) 45%,transparent)}
@@ -390,6 +401,15 @@
   <div class="cap" id="drawer-cap"></div>
   <div class="body" id="drawer-body"></div>
 </aside>
+<div class="drawer-back" id="consent-back"></div>
+<div class="consent" id="consent" role="dialog" aria-modal="true" aria-labelledby="consent-title">
+  <h3 id="consent-title"></h3>
+  <p id="consent-body"></p>
+  <div class="row">
+    <button class="ghost" id="consent-cancel"></button>
+    <button id="consent-ok"></button>
+  </div>
+</div>
 <div class="toast" id="toast"></div>
 
 <script>
@@ -456,10 +476,16 @@ const I18N = {
       'What medications and any interactions?','What about HbA1c?'],
     story:(docs,pair)=>`One timeline from ${docs} documents in two languages. The card flagged a dangerous combination — <b>${pair}</b> — deterministically, by safety rules, not by AI guess. See the red alert in the Safety panel.`,
     groupL1:'L1 · deterministic rules', groupL2a:'L2a · trends & reference ranges',
-    trust:['No cloud LLM','Deterministic safety rules (L1)','FHIR export','Local-first by design'],
+    trust:['No LLM in safety decisions','Deterministic safety rules (L1)','FHIR export','Local-first by design'],
+    trustPhotoCloud:'Photo OCR → cloud lab',
+    trustPhotoLocal:'Photo OCR → on-device',
     drawerTitle:id=>`Source · ${id}`,
     drawerCap:'The extracted fact is highlighted in the source document.',
     srcTitle:'Show source document',
+    consentTitle:'This photo will leave your device',
+    consentBody:'To read the photo, this public demo sends it to a cloud OCR lab (Hugging Face ZeroGPU). Text you type, the demo card and every safety decision stay on the server and never go to an LLM.\n\nUpload synthetic or fully de-identified documents only — never real personal medical data.',
+    consentOk:'Send the photo',
+    consentCancel:'Cancel',
   },
   ua: {
     htmlLang:'uk', title:'LiveMedCard — жива медична картка',
@@ -500,10 +526,16 @@ const I18N = {
       'Які ліки приймає і чи є взаємодії?','Що з HbA1c?'],
     story:(docs,pair)=>`Один таймлайн із ${docs} документів двома мовами. Картка помітила небезпечну комбінацію — <b>${pair}</b> — детерміновано, правилами безпеки, а не «на думку» ШІ. Дивіться червоний сигнал у панелі безпеки.`,
     groupL1:'L1 · детерміновані правила', groupL2a:'L2a · тренди й референсні межі',
-    trust:['Без хмарної LLM','Детерміновані правила безпеки (L1)','Експорт FHIR','Local-first за дизайном'],
+    trust:['Жодної LLM у рішеннях безпеки','Детерміновані правила безпеки (L1)','Експорт FHIR','Local-first за дизайном'],
+    trustPhotoCloud:'OCR фото → хмарний лаб',
+    trustPhotoLocal:'OCR фото → на пристрої',
     drawerTitle:id=>`Джерело · ${id}`,
     drawerCap:'Витягнутий факт підсвічено в документі-джерелі.',
     srcTitle:'Показати документ-джерело',
+    consentTitle:'Це фото покине ваш пристрій',
+    consentBody:'Щоб прочитати фото, це публічне демо надсилає його в хмарний OCR-лаб (Hugging Face ZeroGPU). Введений текст, демо-картка й усі рішення безпеки лишаються на сервері й до жодної LLM не потрапляють.\n\nЗавантажуйте лише синтетичні або повністю деідентифіковані документи — ніколи не справжні персональні медичні дані.',
+    consentOk:'Надіслати фото',
+    consentCancel:'Скасувати',
   },
 };
 
@@ -542,7 +574,7 @@ function applyLang(lang){
   $('#qa-tag').textContent = t.qaTag;
   $('#q').placeholder = t.qPlaceholder;
   $('#ask').textContent = t.ask;
-  $('#trust').innerHTML = t.trust.map(x=>`<span>${x}</span>`).join('');
+  renderTrust();
   $('#site-footer').innerHTML = `${t.footer1}<br>${t.footer2}
     <div class="flinks"><a href="https://github.com/SZabolotnii/Digital_Future_Hackathon" target="_blank" rel="noopener">GitHub</a> ·
     <a href="https://traces.solutions" target="_blank" rel="noopener">traces.solutions</a> ·
@@ -628,8 +660,20 @@ function trendOf(s){
   return ['→ 0%','flat'];
 }
 
+/* Чипи довіри мають відповідати тому, що система РОБИТЬ: якщо фото їде в хмару,
+   мовчати про це не можна — інакше «local-first» на екрані стає неправдою. */
+function renderTrust(){
+  const t=I18N[LANG];
+  const mode = lastState && lastState.photo_ocr;
+  const chips = t.trust.slice();
+  if(mode==='cloud') chips.push(t.trustPhotoCloud);
+  else if(mode==='local') chips.push(t.trustPhotoLocal);
+  $('#trust').innerHTML = chips.map(x=>`<span>${x}</span>`).join('');
+}
+
 function render(st){
   lastState = st;
+  renderTrust();
   const t=I18N[LANG];
   const docs=st.document_count||0;
   $('#patient').innerHTML = docs ? t.patient(st.patient.id, docs) : t.patientNone;
@@ -778,6 +822,32 @@ $('#btn-export').onclick=async()=>{
 };
 $('#btn-add').onclick=()=>$('#add-form').classList.toggle('show');
 
+/* Згода на відправку фото в хмару. Питаємо ПЕРЕД тим, як файл покине пристрій —
+   згода постфактум згодою не є. Локальний бекенд нічого не питає. */
+function askCloudConsent(){
+  if(!lastState || lastState.photo_ocr !== 'cloud') return Promise.resolve(true);
+  const t=I18N[LANG];
+  $('#consent-title').textContent=t.consentTitle;
+  $('#consent-body').textContent=t.consentBody;
+  $('#consent-ok').textContent=t.consentOk;
+  $('#consent-cancel').textContent=t.consentCancel;
+  $('#consent').classList.add('show'); $('#consent-back').classList.add('show');
+  $('#consent-ok').focus();
+  return new Promise(res=>{
+    const done=v=>{
+      $('#consent').classList.remove('show'); $('#consent-back').classList.remove('show');
+      $('#consent-ok').onclick=null; $('#consent-cancel').onclick=null;
+      $('#consent-back').onclick=null; document.removeEventListener('keydown',onKey);
+      res(v);
+    };
+    const onKey=e=>{ if(e.key==='Escape') done(false); };
+    $('#consent-ok').onclick=()=>done(true);
+    $('#consent-cancel').onclick=()=>done(false);
+    $('#consent-back').onclick=()=>done(false);
+    document.addEventListener('keydown',onKey);
+  });
+}
+
 const fileInput=$('#add-image'), dz=$('#dropzone');
 fileInput.onchange=e=>{const f=e.target.files[0];if(f){$('#dropzone-text').textContent=I18N[LANG].selected(f.name);$('#add-text').value='';}};
 dz.addEventListener('dragover',e=>{e.preventDefault();dz.classList.add('dragover');});
@@ -794,6 +864,7 @@ $('#add-submit').onclick=async()=>{
   try{
     let rep;
     if(file){
+      if(!await askCloudConsent()){ btn.disabled=false; btn.textContent=orig; return; }
       btn.textContent=t.ocrReading;
       // Хмарний OCR — це ~70–90 с. Без попередження мовчазне очікування читається
       // як зависання (і саме так виглядає для журі, що клікне демо самостійно).

livemedcard/units.py

@@ -0,0 +1,48 @@
+"""Нормалізація одиниць виміру — запобіжник перед детермінованими сигналами L2a.
+
+Значення без узгодженої одиниці порівнювати з референсною межею НЕ можна: глюкоза
+100 mg/dL проти меж 3.9–6.1 mmol/L дасть хибне «вище норми». Тому L2a спершу питає
+`same_unit`, і якщо одиниці не збігаються (або одиниці факту немає) — сигнал не
+формується, а натомість піднімається `unit_mismatch` (мовчазний пропуск гірший за
+явну незгоду).
+
+Свідомо БЕЗ конверсій: перерахунок mg/dL → mmol/L потребує коефіцієнта на кожен
+аналіт, і помилка в ньому — це хибний клінічний сигнал. Канонічний UCUM-шар із
+таблицею конверсій — у роадмапі; тут лише чесне «одиниці не збігаються».
+"""
+from __future__ import annotations
+
+from typing import Optional
+
+# Написання однієї й тієї ж одиниці різняться за джерелом (UA-бланк, EN-бланк,
+# OCR-модель): зводимо до спільного ключа.
+_ALIASES: dict[str, str] = {
+    "umol/l": "umol/l", "мкмоль/л": "umol/l",
+    "mmol/l": "mmol/l", "ммоль/л": "mmol/l",
+    "mg/dl": "mg/dl", "мг/дл": "mg/dl",
+    "g/l": "g/l", "г/л": "g/l",
+    "mmhg": "mmhg", "мм рт.ст.": "mmhg", "мм рт. ст.": "mmhg",
+    "%": "%",
+}
+
+
+def canonical(unit: Optional[str]) -> Optional[str]:
+    """Одиниця у канонічному вигляді; None — коли одиниці немає."""
+    if not unit:
+        return None
+    u = unit.strip().lower()
+    # µ (micro sign) і μ (грецька мю) — різні кодпойнти, обидва означають «мікро».
+    u = u.replace("µ", "u").replace("μ", "u")
+    u = " ".join(u.split())
+    return _ALIASES.get(u, u)
+
+
+def same_unit(a: Optional[str], b: Optional[str]) -> bool:
+    """Чи можна порівнювати два значення напряму.
+
+    Відсутня одиниця — НЕ привід вважати збіг: невідоме не дорівнює очікуваному.
+    """
+    ca, cb = canonical(a), canonical(b)
+    if ca is None or cb is None:
+        return False
+    return ca == cb