Deploy LiveMedCard demo (Docker, stub, seeded bilingual card)

Dockerfile

@@ -0,0 +1,19 @@
+# LiveMedCard demo — Hugging Face Docker Space (CPU, детермінований stub-режим).
+# Публічний прототип для Digital Future Hackathon. Дані не покидають процес; без LLM/GPU.
+FROM python:3.12-slim
+
+ENV PYTHONUNBUFFERED=1 \
+    PIP_NO_CACHE_DIR=1 \
+    LMC_EXTRACTOR=stub \
+    LMC_SEED_SAMPLES=1
+
+WORKDIR /app
+
+# Лише stub-залежності (без torch/transformers) — легкий образ, швидкий cold-start.
+RUN pip install "pydantic>=2" "networkx>=3" "fastapi>=0.110" "uvicorn>=0.29"
+
+# Пакет разом зі static/ (SPA) і data/ (демо-документи, довідники).
+COPY livemedcard ./livemedcard
+
+EXPOSE 7860
+CMD ["uvicorn", "livemedcard.api:app", "--host", "0.0.0.0", "--port", "7860"]

README.md

@@ -1,10 +1,24 @@
 ---
 title: LiveMedCard
-emoji: 👁
-colorFrom: pink
-colorTo: pink
+emoji: 🫀
+colorFrom: green
+colorTo: blue
 sdk: docker
+app_port: 7860
 pinned: false
+short_description: Жива медична картка · таймлайн · сигнали безпеки · Q&A
 ---
 
-Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference
+# LiveMedCard
+
+**Жива медична картка** для літньої людини — прототип для Digital Future Hackathon
+(ніша Aging & Longevity). Структурує медичні документи (українські й англомовні) у
+**лонгітюдний таймлайн**, детерміновано помічає **небезпечні взаємодії ліків і тренди
+показників**, відповідає на питання природною мовою з посиланням на джерело.
+
+Демо стартує із заповненою білінгвальною карткою (UA-виписки + англомовний
+lab-report). Архітектура — **TRACE** (вимірювана межа довіри): сигнали безпеки
+рахуються детерміновано, а не генеративною моделлю. Система **не ставить діагнозів**.
+
+> Цей публічний демо — детермінований `stub`-режим (без хмарних LLM). У продукті
+> обробка локальна, на пристрої (privacy by design).

livemedcard/__init__.py

@@ -0,0 +1,5 @@
+"""LiveMedCard — жива медична картка на архітектурі TRACE.
+
+Публічний API конвеєра — див. :mod:`livemedcard.pipeline`.
+"""
+__version__ = "0.1.0"

livemedcard/api.py

@@ -0,0 +1,318 @@
+"""FastAPI-фасад над конвеєром LiveMedCard (демо-сервер, стан у пам'яті).
+
+Ендпойнти:
+  GET  /                  — веб-інтерфейс користувача (SPA)
+  POST /ingest            — прогнати один документ
+  POST /ingest/samples    — прогнати демо-таймлайн
+  POST /reset             — очистити картку (новий пацієнт)
+  GET  /timeline/{loinc}  — часовий ряд показника
+  GET  /signals           — поточні детерміновані сигнали
+  GET  /state             — агрегований стан картки (для UI)
+  POST /ask               — grounded Q&A
+  GET  /export            — експорт у FHIR Bundle
+  POST /import            — імпорт з FHIR Bundle
+  GET  /audit             — журнал рішень L3
+  GET  /metrics           — агреговані метрики
+
+Стан одного пацієнта інкапсульовано в `_State` і серіалізовано `threading.Lock`:
+sync-ендпойнти FastAPI виконуються в пулі потоків, тож без лока конкурентні
+запити (кілька вкладок) гонялися б за спільною карткою. Жодного `global`.
+
+Опційна персистентність: env `LMC_PERSIST_PATH` → автозбереження/автозавантаження
+знімка картки у локальний JSON-файл (local-first). Пошкоджений файл знімка валить
+старт сервера явно (див. `repository.load_card`) — це захист від мовчазного
+перезапису даних порожнім станом.
+"""
+from __future__ import annotations
+
+import threading
+from datetime import date
+
+import hashlib
+
+from fastapi import Body, FastAPI, HTTPException
+from fastapi.responses import FileResponse
+from pydantic import BaseModel
+
+from .bundle import from_bundle, to_bundle
+from .config import (
+    EXTRACTOR,
+    MAX_DOC_CHARS,
+    PERSIST_PATH,
+    SEED_SAMPLES,
+    STATIC_DIR,
+)
+from .dto import Document, DocKind
+from .fhir import Patient
+from .layers import l3_router
+from .layers import l2b_nuextract
+from .layers.l2b_extractor import (
+    Extractor,
+    LoraStage2Extractor,
+    NuExtractExtractor,
+    StubExtractor,
+    TwoStageExtractor,
+)
+from .llm_client import LLMError
+from .pipeline import LiveMedCard
+from .qa import Answer, QA
+from .reference import load_sample_docs, range_for
+from .repository import load_card, save_card
+from .ocr import OcrService, OcrError
+
+
+app = FastAPI(title="LiveMedCard", version="0.1.0")
+
+_STATIC = STATIC_DIR
+
+
+def _new_patient() -> Patient:
+    return Patient(id="mom-001", gender="female", birthDate=date(1954, 6, 1))
+
+
+def _make_extractor() -> Extractor:
+    """Екстрактор L2b: 'nuextract' | 'two_stage_lora' | 'two_stage' | 'stub'."""
+    if EXTRACTOR == "nuextract":
+        return NuExtractExtractor()
+    if EXTRACTOR == "two_stage_lora":
+        return LoraStage2Extractor()
+    if EXTRACTOR == "two_stage":
+        return TwoStageExtractor()
+    return StubExtractor()
+
+
+class _State:
+    """Тримач картки одного пацієнта: доступ лише під `lock`."""
+
+    def __init__(self, card: LiveMedCard) -> None:
+        self.card = card
+        self.lock = threading.Lock()
+
+    def autosave(self) -> None:
+        """Зберегти знімок, якщо ввімкнено персистентність. Кличеться під lock."""
+        if PERSIST_PATH:
+            save_card(self.card, PERSIST_PATH)
+
+
+def _initial_card() -> LiveMedCard:
+    if PERSIST_PATH:
+        loaded = load_card(PERSIST_PATH, _make_extractor())
+        if loaded is not None:
+            return loaded
+    card = LiveMedCard(_new_patient(), _make_extractor())
+    if SEED_SAMPLES:  # публічне демо (HF Space) стартує з заповненою карткою
+        card.ingest_all([Document(**d) for d in load_sample_docs()])
+    return card
+
+
+_state = _State(_initial_card())
+
+
+class AskRequest(BaseModel):
+    question: str
+
+
+@app.get("/")
+def index() -> FileResponse:
+    return FileResponse(_STATIC / "index.html")
+
+
+@app.post("/ingest")
+def ingest(doc: Document):
+    if len(doc.text) > MAX_DOC_CHARS:
+        raise HTTPException(
+            status_code=413,
+            detail=f"Документ завеликий (> {MAX_DOC_CHARS} символів)",
+        )
+    with _state.lock:
+        report = _state.card.ingest(doc)
+        _state.autosave()
+    return report
+
+
+class ImageIngestRequest(BaseModel):
+    image_base64: str
+    kind: DocKind = "note"
+
+
+@app.post("/ingest/image")
+def ingest_image(req: ImageIngestRequest):
+    if not req.image_base64.strip():
+        raise HTTPException(
+            status_code=422,
+            detail="Зображення порожнє або некоректне",
+        )
+
+    # У режимі nuextract зображення читає сам NuExtract (image→markdown), тож
+    # окремий OCR не потрібен — уникаємо накопичення помилок OCR→summary→extract.
+    try:
+        if EXTRACTOR == "nuextract":
+            text = l2b_nuextract.image_to_markdown(req.image_base64)
+        else:
+            text = OcrService.perform_ocr(req.image_base64)
+    except (OcrError, LLMError) as exc:
+        raise HTTPException(
+            status_code=503,
+            detail=str(exc),
+        )
+    except Exception as exc:
+        raise HTTPException(
+            status_code=500,
+            detail=f"Помилка під час OCR: {exc}",
+        )
+
+    if not text:
+        raise HTTPException(
+            status_code=422,
+            detail="Не вдалося розпізнати текст із зображення",
+        )
+
+    if len(text) > MAX_DOC_CHARS:
+        raise HTTPException(
+            status_code=413,
+            detail=f"Розпізнаний текст документа завеликий (> {MAX_DOC_CHARS} символів)",
+        )
+
+    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()
+    return report
+
+
+
+@app.post("/ingest/samples")
+def ingest_samples():
+    docs = [Document(**d) for d in load_sample_docs()]
+    with _state.lock:
+        reports = _state.card.ingest_all(docs)
+        _state.autosave()
+    return reports
+
+
+@app.post("/reset")
+def reset():
+    with _state.lock:
+        _state.card = LiveMedCard(_new_patient(), _make_extractor())
+        _state.autosave()
+        return {"status": "reset", "patient": _state.card.patient.id}
+
+
+@app.get("/export")
+def export_bundle():
+    """Експорт картки як FHIR Bundle (для передачі лікарю / еЗдоров'ю)."""
+    with _state.lock:
+        return to_bundle(_state.card)
+
+
+@app.post("/import")
+def import_bundle(bundle: dict = Body(...)):
+    """Імпорт картки з FHIR Bundle (замінює поточний стан)."""
+    try:
+        card = from_bundle(bundle, _make_extractor())
+    except (ValueError, KeyError, TypeError) as exc:
+        raise HTTPException(status_code=422, detail=f"Некоректний Bundle: {exc}")
+    with _state.lock:
+        _state.card = card
+        _state.autosave()
+        return {"status": "imported", "documents": _state.card.document_count}
+
+
+@app.get("/audit")
+def audit():
+    """Журнал рішень L3 (спостережуваність)."""
+    with _state.lock:
+        return _state.card.audit_log()
+
+
+@app.get("/metrics")
+def metrics():
+    """Агреговані метрики роботи конвеєра."""
+    with _state.lock:
+        card = _state.card
+        log = card.audit_log()
+        n = len(log)
+        escalated = sum(1 for a in log if a["escalate"])
+        return {
+            "documents": card.document_count,
+            "observations": len(card.observations),
+            "medications": len(card.medications),
+            "decisions": n,
+            "escalated": escalated,
+            "auto": n - escalated,
+            "escalation_rate": round(escalated / n, 3) if n else 0.0,
+            "active_signals": len(card.current_signals()),
+        }
+
+
+@app.get("/timeline/{loinc}")
+def timeline(loinc: str):
+    with _state.lock:
+        return _state.card.factstore.series(loinc)
+
+
+@app.get("/signals")
+def signals():
+    with _state.lock:
+        return _state.card.current_signals()
+
+
+@app.get("/state")
+def state():
+    """Агрегований знімок картки для інтерфейсу."""
+    with _state.lock:
+        card = _state.card
+        sigs = card.current_signals()
+        # Рішення L3 над поточним станом (сигнали детерміновані → впевненість 1.0).
+        decision = l3_router.route(sigs, 1.0, "стан картки")
+        sex = card.patient.gender
+
+        series = []
+        for loinc in card.factstore.loincs():
+            pts = card.factstore.series(loinc)
+            ref = range_for(loinc, sex)
+            series.append({
+                "loinc": loinc,
+                "keyword": pts[0].keyword,
+                "unit": pts[-1].unit,
+                "low": ref.low if ref else None,
+                "high": ref.high if ref else None,
+                "points": [
+                    {"ts": p.ts.date().isoformat(), "value": p.value, "source": p.source_doc_id}
+                    for p in pts
+                ],
+            })
+
+        seen: dict[str, None] = {}
+        for n in card.graph.nodes_of_type("MedicationRequest"):
+            seen.setdefault(card.graph.g.nodes[n].get("label", n), None)
+        medications = list(seen)
+
+        return {
+            "patient": {"id": card.patient.id, "gender": card.patient.gender},
+            "document_count": card.document_count,
+            "series": series,
+            "medications": medications,
+            "signals": [s.model_dump() for s in sigs],
+            "decision": decision.model_dump(),
+        }
+
+
+@app.post("/ask", response_model=Answer)
+def ask(req: AskRequest) -> Answer:
+    with _state.lock:
+        card = _state.card
+        qa = QA(card.factstore, card.graph, card.current_signals(), sex=card.patient.gender)
+        return qa.ask(req.question)
+
+
+@app.get("/health")
+def health():
+    with _state.lock:
+        return {
+            "status": "ok",
+            "patient": _state.card.patient.id,
+            "documents": _state.card.document_count,
+        }

livemedcard/bundle.py

@@ -0,0 +1,61 @@
+"""Експорт/імпорт картки як стандартного FHIR Bundle (type=collection).
+
+Наслідок продуктовий: картку можна передати лікарняній системі чи еЗдоров'ю у
+стандартному форматі, а не як скрін. Метадані (документи, аудит) — у полі `_meta`,
+щоб не порушувати FHIR-структуру ресурсів.
+"""
+from __future__ import annotations
+
+from typing import Optional
+
+from .layers.l2b_extractor import Extractor
+from .pipeline import LiveMedCard
+
+_RT_TO_KEY = {
+    "Observation": "observations",
+    "Condition": "conditions",
+    "MedicationRequest": "medications",
+    "DocumentReference": "document_references",
+}
+
+
+def to_bundle(card: LiveMedCard) -> dict:
+    """Серіалізувати картку у FHIR Bundle."""
+    snap = card.snapshot()
+    entries = [{"resource": snap["patient"]}]
+    for key in ("observations", "conditions", "medications", "document_references"):
+        entries.extend({"resource": r} for r in snap[key])
+    return {
+        "resourceType": "Bundle",
+        "type": "collection",
+        "entry": entries,
+        "_meta": {"documents": snap["documents"], "audit": snap["audit"]},
+    }
+
+
+def from_bundle(data: dict, extractor: Optional[Extractor] = None) -> LiveMedCard:
+    """Відновити картку з FHIR Bundle."""
+    patient: Optional[dict] = None
+    buckets: dict[str, list] = {
+        "observations": [],
+        "conditions": [],
+        "medications": [],
+        "document_references": [],
+    }
+    for entry in data.get("entry", []):
+        resource = entry.get("resource", {})
+        rt = resource.get("resourceType")
+        if rt == "Patient":
+            patient = resource
+        elif rt in _RT_TO_KEY:
+            buckets[_RT_TO_KEY[rt]].append(resource)
+    if patient is None:
+        raise ValueError("Bundle не містить ресурсу Patient")
+    meta = data.get("_meta", {})
+    snapshot = {
+        "patient": patient,
+        **buckets,
+        "documents": meta.get("documents", []),
+        "audit": meta.get("audit", []),
+    }
+    return LiveMedCard.from_snapshot(snapshot, extractor)

livemedcard/config.py

@@ -0,0 +1,55 @@
+"""Централізовані налаштування застосунку (з можливістю override через env).
+
+Виносить «магічні» пороги й шляхи з коду в одне місце — легше конфігурувати й
+тестувати. Значення читаються один раз при імпорті.
+"""
+from __future__ import annotations
+
+import os
+from pathlib import Path
+
+DATA_DIR = Path(__file__).parent / "data"
+STATIC_DIR = Path(__file__).parent / "static"
+
+# Поріг впевненості витягу L2b, нижче якого документ іде на перегляд людиною (L3).
+LOW_CONFIDENCE = float(os.getenv("LMC_LOW_CONFIDENCE", "0.6"))
+
+# Впевненість, яку StubExtractor приписує кожному словниковому збігу.
+# Реальний екстрактор (MedGemma) має ставити модельну впевненість замість цієї.
+STUB_CONFIDENCE = float(os.getenv("LMC_STUB_CONFIDENCE", "0.95"))
+
+# Максимальний розмір тексту документа (символів) — валідація API.
+MAX_DOC_CHARS = int(os.getenv("LMC_MAX_DOC_CHARS", "20000"))
+
+# Шлях до файлу персистентності (JSON). Порожньо → стан лише в пам'яті.
+PERSIST_PATH = os.getenv("LMC_PERSIST_PATH", "")
+
+# Засіяти демо-картку на старті (для публічного демо на HF Space — щоб картка була
+# заповнена одразу). Порожньо → старт з порожньої картки (дефолт, тести/CI).
+SEED_SAMPLES = os.getenv("LMC_SEED_SAMPLES", "")
+
+# Налаштування локальної LLM/Vision моделі для OCR
+LMSTUDIO_URL = os.getenv("LMC_LMSTUDIO_URL", "http://127.0.0.1:1234/v1")
+OCR_MODEL = os.getenv("LMC_OCR_MODEL", "medgemma-1.5-4b-it")
+
+# Екстрактор L2b:
+#   "stub"           — детермінований offline (дефолт, тести/CI/демо);
+#   "two_stage"      — Stage 1 (LLM SGR) → Stage 2 (детермінована vocab KV-T);
+#   "two_stage_lora" — Stage 1 (база) → Stage 2 (база+LoRA генерує KVT4);
+#   "nuextract"      — NuExtract3 VLM: image→markdown + markdown→JSON за шаблоном.
+EXTRACTOR = os.getenv("LMC_EXTRACTOR", "stub")
+
+# Модель Stage 1 (SGR-стиснення). None → автовизначення завантаженої моделі.
+STAGE1_MODEL = os.getenv("LMC_STAGE1_MODEL") or None
+
+# Двосерверний LoRA-сетап (llama.cpp): Stage 1 — база, Stage 2 — база+LoRA-адаптер.
+# Аліаси/порти за README FT-моделі DocUA/...-two-stage.
+STAGE1_URL = os.getenv("LMC_STAGE1_URL", LMSTUDIO_URL)
+STAGE2_URL = os.getenv("LMC_STAGE2_URL", "http://127.0.0.1:1246/v1")
+STAGE2_MODEL = os.getenv("LMC_STAGE2_MODEL", "medgemma-ft-lora-adapters-q5_k_m")
+
+# NuExtract (VLM structured extraction) — OpenAI-сумісний ендпойнт (llama-server
+# --jinja з mmproj, або vLLM). Один рушій робить image→markdown і markdown→JSON.
+NUEXTRACT_URL = os.getenv("LMC_NUEXTRACT_URL", "http://127.0.0.1:1299/v1")
+NUEXTRACT_MODEL = os.getenv("LMC_NUEXTRACT_MODEL", "NuExtract3")
+

livemedcard/data/dose_limits.json

@@ -0,0 +1,9 @@
+{
+  "_note": "Максимальна добова доза (спрощення MVP). Коди RxNorm, одиниця mg/добу.",
+  "limits": [
+    {"rxnorm": "6809", "name": "Метформін", "max_daily": 2550, "unit": "mg"},
+    {"rxnorm": "1191", "name": "Аспірин", "max_daily": 4000, "unit": "mg"},
+    {"rxnorm": "29046", "name": "Лізиноприл", "max_daily": 80, "unit": "mg"},
+    {"rxnorm": "11289", "name": "Варфарин", "max_daily": 10, "unit": "mg"}
+  ]
+}

livemedcard/data/interactions.json

@@ -0,0 +1,13 @@
+{
+  "_note": "Демо-підмножина взаємодій. У проді — відкрита БД RxNorm/NLM. Коди RxNorm. Поле detail — лише механізм; назви препаратів додає L1 з фактичних ресурсів.",
+  "pairs": [
+    {"a": "11289", "b": "1191", "severity": "major",
+     "detail": "сумація антитромботичного ефекту, підвищений ризик кровотечі"},
+    {"a": "11289", "b": "703", "severity": "major",
+     "detail": "аміодарон інгібує метаболізм варфарину, ризик кровотечі"},
+    {"a": "11289", "b": "5640", "severity": "major",
+     "detail": "підвищений ризик шлунково-кишкової кровотечі"},
+    {"a": "5640", "b": "29046", "severity": "moderate",
+     "detail": "зниження антигіпертензивного ефекту та ризик для нирок"}
+  ]
+}

livemedcard/data/reference_ranges.json

@@ -0,0 +1,21 @@
+{
+  "_note": "Референсні межі показників. Коди LOINC. default — загальні межі; by_sex — уточнення за статтю.",
+  "ranges": {
+    "2160-0": {
+      "keyword": "Креатинін", "unit": "µmol/L",
+      "default": {"low": 44, "high": 106},
+      "by_sex": {"female": {"low": 44, "high": 90}, "male": {"low": 62, "high": 106}}
+    },
+    "4548-4": {"keyword": "HbA1c", "unit": "%", "default": {"low": 4.0, "high": 6.0}},
+    "2823-3": {"keyword": "Калій", "unit": "mmol/L", "default": {"low": 3.5, "high": 5.1}},
+    "8480-6": {"keyword": "Систолічний тиск", "unit": "mmHg", "default": {"low": 90, "high": 140}},
+    "2345-7": {"keyword": "Глюкоза", "unit": "mmol/L", "default": {"low": 3.9, "high": 6.1}},
+    "718-7": {
+      "keyword": "Гемоглобін", "unit": "g/L",
+      "default": {"low": 120, "high": 160},
+      "by_sex": {"female": {"low": 120, "high": 150}, "male": {"low": 130, "high": 170}}
+    },
+    "1742-6": {"keyword": "АЛТ", "unit": "U/L", "default": {"low": 0, "high": 41}},
+    "2093-3": {"keyword": "Холестерин загальний", "unit": "mmol/L", "default": {"low": 0, "high": 5.2}}
+  }
+}

livemedcard/data/sample_docs.json

@@ -0,0 +1,29 @@
+{
+  "_note": "Білінгвальний демо-таймлайн однієї пацієнтки (mom-001): українські виписки + англомовний lab-report приватної лабораторії на ОДНОМУ таймлайні. Формат тексту імітує витяг фото документа.",
+  "documents": [
+    {
+      "id": "doc-2023-05",
+      "kind": "discharge_summary",
+      "received_at": "2023-05-01T10:00:00",
+      "text": "Виписний епікриз. Пацієнтка 69 років. Діагноз: фібриляція передсердь. Лабораторно: креатинін 88 µmol/L, калій 4.6 mmol/L. Призначено: варфарин 5 мг на добу під контролем МНВ."
+    },
+    {
+      "id": "doc-2023-11",
+      "kind": "lab_report",
+      "received_at": "2023-11-03T09:30:00",
+      "text": "Біохімія крові. Креатинін 104 µmol/L. Калій 4.9 mmol/L. Глікований гемоглобін 6.4 %."
+    },
+    {
+      "id": "doc-2024-04",
+      "kind": "discharge_summary",
+      "received_at": "2024-04-09T14:15:00",
+      "text": "Виписний епікриз. Скарги на набряки. Артеріальна гіпертензія. Креатинін 121 µmol/L, глікований гемоглобін 7.2 %. Призначено: аспірин 100 мг на добу, метформін 3000 мг на добу."
+    },
+    {
+      "id": "doc-2024-10-en",
+      "kind": "lab_report",
+      "received_at": "2024-10-15T11:00:00",
+      "text": "Private Laboratory. Biochemistry panel. Creatinine 135 µmol/L. Potassium 5.1 mmol/L. Glucose 6.8 mmol/L. Glycated hemoglobin 7.6 %."
+    }
+  ]
+}

livemedcard/data/vocab.json

@@ -0,0 +1,55 @@
+{
+  "_note": "Словник StubExtractor (білінгвальний UA/EN): термін → стандартний код. Ключі — у нижньому регістрі.",
+  "labs": {
+    "креатинін": {"loinc": "2160-0", "unit": "µmol/L", "display": "Creatinine"},
+    "creatinine": {"loinc": "2160-0", "unit": "µmol/L", "display": "Creatinine"},
+    "калій": {"loinc": "2823-3", "unit": "mmol/L", "display": "Potassium"},
+    "potassium": {"loinc": "2823-3", "unit": "mmol/L", "display": "Potassium"},
+    "натрій": {"loinc": "2951-2", "unit": "mmol/L", "display": "Sodium"},
+    "sodium": {"loinc": "2951-2", "unit": "mmol/L", "display": "Sodium"},
+    "глюкоза": {"loinc": "2345-7", "unit": "mmol/L", "display": "Glucose"},
+    "глюкоза крові": {"loinc": "2345-7", "unit": "mmol/L", "display": "Glucose"},
+    "glucose": {"loinc": "2345-7", "unit": "mmol/L", "display": "Glucose"},
+    "blood glucose": {"loinc": "2345-7", "unit": "mmol/L", "display": "Glucose"},
+    "гемоглобін": {"loinc": "718-7", "unit": "g/L", "display": "Hemoglobin"},
+    "hemoglobin": {"loinc": "718-7", "unit": "g/L", "display": "Hemoglobin"},
+    "глікований гемоглобін": {"loinc": "4548-4", "unit": "%", "display": "HbA1c"},
+    "glycated hemoglobin": {"loinc": "4548-4", "unit": "%", "display": "HbA1c"},
+    "hba1c": {"loinc": "4548-4", "unit": "%", "display": "HbA1c"},
+    "систолічний тиск": {"loinc": "8480-6", "unit": "mmHg", "display": "Systolic BP"},
+    "systolic bp": {"loinc": "8480-6", "unit": "mmHg", "display": "Systolic BP"},
+    "systolic blood pressure": {"loinc": "8480-6", "unit": "mmHg", "display": "Systolic BP"}
+  },
+  "medications": {
+    "варфарин": {"rxnorm": "11289", "display": "Warfarin"},
+    "warfarin": {"rxnorm": "11289", "display": "Warfarin"},
+    "аспірин": {"rxnorm": "1191", "display": "Aspirin"},
+    "aspirin": {"rxnorm": "1191", "display": "Aspirin"},
+    "ацетилсаліцилова кислота": {"rxnorm": "1191", "display": "Aspirin"},
+    "ібупрофен": {"rxnorm": "5640", "display": "Ibuprofen"},
+    "ibuprofen": {"rxnorm": "5640", "display": "Ibuprofen"},
+    "метформін": {"rxnorm": "6809", "display": "Metformin"},
+    "metformin": {"rxnorm": "6809", "display": "Metformin"},
+    "лізиноприл": {"rxnorm": "29046", "display": "Lisinopril"},
+    "lisinopril": {"rxnorm": "29046", "display": "Lisinopril"},
+    "аміодарон": {"rxnorm": "703", "display": "Amiodarone"},
+    "amiodarone": {"rxnorm": "703", "display": "Amiodarone"},
+    "кордарон": {"rxnorm": "703", "display": "Amiodarone"}
+  },
+  "conditions": {
+    "фібриляція передсердь": {"snomed": "49436004", "display": "Atrial fibrillation"},
+    "atrial fibrillation": {"snomed": "49436004", "display": "Atrial fibrillation"},
+    "цукровий діабет": {"snomed": "44054006", "display": "Diabetes mellitus type 2"},
+    "diabetes": {"snomed": "44054006", "display": "Diabetes mellitus type 2"},
+    "diabetes mellitus": {"snomed": "44054006", "display": "Diabetes mellitus type 2"},
+    "артеріальна гіпертензія": {"snomed": "38341003", "display": "Hypertension"},
+    "hypertension": {"snomed": "38341003", "display": "Hypertension"},
+    "гіпертонічна хвороба": {"snomed": "38341003", "display": "Hypertension"},
+    "belching": {"snomed": "77526002", "display": "Belching"},
+    "indigestion": {"snomed": "50289006", "display": "Indigestion"},
+    "gastroesophageal reflux disease without esophagitis": {"snomed": "366258000", "display": "Gastroesophageal reflux disease without esophagitis"},
+    "history of hiatal hernia": {"snomed": "395041006", "display": "History of hiatal hernia"},
+    "hiatal hernia": {"snomed": "58293003", "display": "Hiatal hernia"},
+    "ruq pain": {"snomed": "249511003", "display": "Right upper quadrant pain"}
+  }
+}

livemedcard/demo.py

@@ -0,0 +1,67 @@
+"""E2E демонстратор LiveMedCard у терміналі.
+
+Прогін: демо-документи → витяг → таймлайн → детерміновані сигнали → рішення L3 →
+grounded Q&A з посиланням на джерела.
+
+Запуск: ``uv run python -m livemedcard.demo``
+"""
+from __future__ import annotations
+
+from datetime import date
+
+from .dto import Document, TraceReport
+from .fhir import Patient
+from .pipeline import LiveMedCard
+from .qa import QA
+from .reference import load_sample_docs
+
+
+def _print_report(r: TraceReport) -> None:
+    e = r.extraction
+    print(f"\n=== Документ {r.document_id} ===")
+    print(
+        f"  Витяг (L2b): observations={len(e.observations)} "
+        f"conditions={len(e.conditions)} medications={len(e.medications)} "
+        f"впевненість={e.mean_confidence:.2f}"
+    )
+    if r.signals:
+        print("  Сигнали (L1/L2a, детерміновано):")
+        for s in r.signals:
+            print(f"    [{s.layer}/{s.kind}/{s.severity}] {s.detail}")
+    else:
+        print("  Сигналів немає.")
+    d = r.decision
+    mark = "⛳ ЕСКАЛАЦІЯ ДО ЛЮДИНИ (L4)" if d.escalate else "auto"
+    print(f"  Рішення (L3): {d.route_to} — {mark}")
+    for reason in d.reasons:
+        print(f"    · {reason}")
+
+
+def main() -> None:
+    patient = Patient(id="mom-001", gender="female", birthDate=date(1954, 6, 1))
+    card = LiveMedCard(patient)
+
+    docs = [Document(**d) for d in load_sample_docs()]
+    print("LiveMedCard — E2E демо (TRACE)")
+    print(f"Пацієнт: {patient.id}, документів: {len(docs)}")
+
+    reports = card.ingest_all(docs)
+    for r in reports:
+        _print_report(r)
+
+    print("\n=== Grounded Q&A (з посиланням на документи-джерела) ===")
+    qa = QA(card.factstore, card.graph, card.current_signals(), sex=patient.gender)
+    for question in (
+        "Що в мами з нирками за останній рік?",
+        "Який був калій?",
+        "Які ліки приймає і чи є взаємодії?",
+    ):
+        ans = qa.ask(question)
+        print(f"\nQ: {question}")
+        print(f"A: {ans.text}")
+        if ans.sources:
+            print(f"   Джерела: {', '.join(ans.sources)}")
+
+
+if __name__ == "__main__":
+    main()

livemedcard/dto.py

@@ -0,0 +1,94 @@
+"""DTO конвеєра TRACE — спільні типи між шарами.
+
+`Signal` — єдиний тип сигналу для L1 і L2a; це роз'єднує L3-роутер від реалізацій
+шарів безпеки. Детерміновані сигнали мають ``confidence == 1.0``.
+"""
+from __future__ import annotations
+
+from datetime import datetime
+from typing import Literal, Optional
+
+from pydantic import BaseModel, Field
+
+from .fhir import Condition, DocumentReference, MedicationRequest, Observation
+
+Severity = Literal["info", "moderate", "major", "critical"]
+DocKind = Literal["discharge_summary", "lab_report", "prescription", "note"]
+
+_SEVERITY_ORDER: dict[str, int] = {"info": 0, "moderate": 1, "major": 2, "critical": 3}
+
+
+def severity_rank(s: Severity) -> int:
+    """Порядковий ранг тяжкості (більше = гірше)."""
+    return _SEVERITY_ORDER[s]
+
+
+class Document(BaseModel):
+    """Вхідний документ (у MVP — текст; у проді — фото → OCR/vision)."""
+
+    id: str
+    text: str
+    kind: DocKind = "note"
+    received_at: Optional[datetime] = None
+
+
+class ExtractionResult(BaseModel):
+    """Результат L2b: FHIR-ресурси + середня впевненість витягу.
+
+    ``document_reference`` (free-text іпостась) заповнює лише двоетапний
+    екстрактор; детермінований stub лишає None.
+    """
+
+    observations: list[Observation] = Field(default_factory=list)
+    conditions: list[Condition] = Field(default_factory=list)
+    medications: list[MedicationRequest] = Field(default_factory=list)
+    mean_confidence: float = 1.0
+    document_reference: Optional[DocumentReference] = None
+
+    def is_empty(self) -> bool:
+        return not (self.observations or self.conditions or self.medications)
+
+
+class Signal(BaseModel):
+    """Детермінований сигнал безпеки/тренду (L1 або L2a)."""
+
+    layer: Literal["L1", "L2a"]
+    kind: str  # напр. "interaction", "dose_limit", "trend", "range_breach"
+    severity: Severity
+    detail: str
+    subjects: list[str] = Field(default_factory=list)  # посилання на FHIR-ресурси
+    confidence: float = 1.0
+
+
+class Decision(BaseModel):
+    """Рішення L3: авто чи ескалація до людини (L4)."""
+
+    route_to: Literal["auto", "L4_human"]
+    escalate: bool
+    reasons: list[str] = Field(default_factory=list)
+    signals: list[Signal] = Field(default_factory=list)
+
+
+class TraceReport(BaseModel):
+    """Повний результат прогону одного документа крізь конвеєр."""
+
+    document_id: str
+    extraction: ExtractionResult
+    signals: list[Signal]
+    decision: Decision
+
+
+class AuditEntry(BaseModel):
+    """Запис аудиту одного рішення L3 (типізована схема журналу).
+
+    Гарантує стабільну структуру журналу між версіями: знімки зі сторонніми чи
+    неповними записами відхиляються валідацією при відновленні.
+    """
+
+    ts: datetime
+    document_id: str
+    kind: str
+    extraction_confidence: float
+    n_signals: int
+    route_to: Literal["auto", "L4_human"]
+    escalate: bool

livemedcard/fhir.py

@@ -0,0 +1,165 @@
+"""FHIR-вирівняні моделі даних (HL7 FHIR R4, мінімальний профіль для MVP).
+
+Беремо СТРУКТУРИ РЕСУРСІВ як схему даних; серверний шар (REST/OAuth/Bundle) не беремо.
+Cardinality й value sets — за fhir-developer-skill. `Provenance` — не-FHIR розширення,
+основа метрики довіри (звідки взято факт).
+"""
+from __future__ import annotations
+
+from datetime import date, datetime, timezone
+from typing import Literal, Optional
+
+from pydantic import BaseModel, Field
+
+
+def _utcnow() -> datetime:
+    return datetime.now(timezone.utc)
+
+
+class Sys:
+    """URL кодувальних систем."""
+
+    LOINC = "http://loinc.org"
+    SNOMED = "http://snomed.info/sct"
+    RXNORM = "http://www.nlm.nih.gov/research/umls/rxnorm"
+    ICD10 = "http://hl7.org/fhir/sid/icd-10"
+
+
+# ── datatypes ────────────────────────────────────────────────────────────────
+class Coding(BaseModel):
+    system: str
+    code: str
+    display: Optional[str] = None
+
+
+class CodeableConcept(BaseModel):
+    coding: list[Coding] = Field(default_factory=list)
+    text: Optional[str] = None
+
+
+class Reference(BaseModel):
+    reference: str  # напр. "Patient/mom-001"
+    display: Optional[str] = None
+
+
+class Quantity(BaseModel):
+    value: float
+    unit: Optional[str] = None
+    system: Optional[str] = None
+    code: Optional[str] = None
+
+
+class Provenance(BaseModel):
+    """Не-FHIR розширення: звідки взято факт. Живить провенанс-ребра графа."""
+
+    source_doc_id: str
+    extracted_by: str = "MedGemma-4B"
+    extracted_at: datetime = Field(default_factory=_utcnow)
+    confidence: Optional[float] = None
+
+
+class Attachment(BaseModel):
+    """Вміст документа (FHIR Attachment, мінімальний профіль).
+
+    Free-text іпостась зберігається у ``data`` (напр. Stage 1 SGR-summary).
+    """
+
+    contentType: str = "text/plain"
+    data: Optional[str] = None
+    title: Optional[str] = None
+
+
+# ── resources ─────────────────────────────────────────────────────────────────
+class Patient(BaseModel):
+    resourceType: Literal["Patient"] = "Patient"
+    id: str
+    gender: Optional[Literal["male", "female", "other", "unknown"]] = None
+    birthDate: Optional[date] = None
+
+
+class Encounter(BaseModel):
+    resourceType: Literal["Encounter"] = "Encounter"
+    id: str
+    status: Literal[
+        "planned", "arrived", "triaged", "in-progress", "onleave",
+        "finished", "cancelled", "entered-in-error", "unknown",
+    ]
+    class_: Coding = Field(alias="class")  # 1..1 Coding (не CodeableConcept)
+    subject: Optional[Reference] = None
+    period_start: Optional[date] = None
+    model_config = {"populate_by_name": True}
+
+
+class Observation(BaseModel):
+    resourceType: Literal["Observation"] = "Observation"
+    id: str
+    status: Literal[
+        "registered", "preliminary", "final", "amended", "corrected",
+        "cancelled", "entered-in-error", "unknown",
+    ]
+    code: CodeableConcept  # 1..1
+    subject: Optional[Reference] = None
+    effectiveDateTime: Optional[datetime] = None
+    valueQuantity: Optional[Quantity] = None
+    provenance: Optional[Provenance] = None
+
+
+class Condition(BaseModel):
+    resourceType: Literal["Condition"] = "Condition"
+    id: str
+    subject: Reference  # 1..1 — єдине обов'язкове
+    code: Optional[CodeableConcept] = None
+    clinicalStatus: Optional[
+        Literal["active", "recurrence", "relapse", "inactive", "remission", "resolved"]
+    ] = None
+    onsetDateTime: Optional[datetime] = None
+    provenance: Optional[Provenance] = None
+
+
+class MedicationRequest(BaseModel):
+    resourceType: Literal["MedicationRequest"] = "MedicationRequest"
+    id: str
+    status: Literal[
+        "active", "on-hold", "cancelled", "completed",
+        "entered-in-error", "stopped", "draft", "unknown",
+    ]
+    intent: Literal[
+        "proposal", "plan", "order", "original-order", "reflex-order",
+        "filler-order", "instance-order", "option",
+    ]
+    medicationCodeableConcept: CodeableConcept  # medication[x] 1..1
+    subject: Reference  # 1..1
+    reason: Optional[Reference] = None  # → Condition (ребро indicated_for)
+    dose_mg_per_day: Optional[float] = None  # спрощення для дозового чеку L1
+    provenance: Optional[Provenance] = None
+
+
+class DocumentReference(BaseModel):
+    """FHIR DocumentReference (мінімальний R4-профіль) — free-text іпостась.
+
+    Тримає згорнутий Stage 1 SGR-summary документа поряд зі структурованими
+    фактами. ``id`` детермінований від ``source_doc_id`` (docref-<doc_id>), тож
+    повторний прогін того самого документа не дублює запис.
+    """
+
+    resourceType: Literal["DocumentReference"] = "DocumentReference"
+    id: str
+    status: Literal["current", "superseded", "entered-in-error"] = "current"
+    subject: Optional[Reference] = None
+    date: Optional[datetime] = None
+    type: Optional[CodeableConcept] = None  # несе DocKind документа
+    content: Attachment
+    provenance: Optional[Provenance] = None
+
+
+def rxnorm_of(m: MedicationRequest) -> Optional[str]:
+    """RxNorm-код препарату або None."""
+    return next(
+        (c.code for c in m.medicationCodeableConcept.coding if c.system == Sys.RXNORM),
+        None,
+    )
+
+
+def loinc_of(o: Observation) -> Optional[str]:
+    """LOINC-код показника або None."""
+    return next((c.code for c in o.code.coding if c.system == Sys.LOINC), None)

livemedcard/lang.py

@@ -0,0 +1,23 @@
+"""Легкий детектор мови (UA/EN) для білінгвального режиму.
+
+Евристика за абеткою: частка кириличних літер серед усіх літер. Достатньо для
+вибору мови відповіді Q&A та адаптації промптів — без важких залежностей.
+"""
+from __future__ import annotations
+
+import re
+from typing import Literal
+
+Lang = Literal["uk", "en"]
+
+_CYRILLIC_RE = re.compile(r"[Ѐ-ӿ]")
+_LATIN_RE = re.compile(r"[A-Za-z]")
+
+
+def detect_lang(text: str, *, default: Lang = "uk") -> Lang:
+    """Повертає 'uk' чи 'en' за переважанням абетки; `default` — коли літер немає."""
+    cyr = len(_CYRILLIC_RE.findall(text))
+    lat = len(_LATIN_RE.findall(text))
+    if cyr == 0 and lat == 0:
+        return default
+    return "uk" if cyr >= lat else "en"

livemedcard/layers/__init__.py

@@ -0,0 +1 @@
+"""Шари архітектури TRACE: L1 (безпека), L2a (тренди), L2b (екстракція), L3 (роутинг)."""

livemedcard/layers/l1_safety.py

@@ -0,0 +1,91 @@
+"""Шар TRACE L1: детермінований шар безпеки (взаємодії ліків, межі доз).
+
+Це якір конвеєра: рішення про клінічну небезпеку приймається за перевіреними
+правилами відкритих довідкових БД (RxNorm), а не мовною моделлю. Усі сигнали
+L1 детерміновані — ``confidence == 1.0``.
+"""
+from __future__ import annotations
+
+from functools import lru_cache
+from itertools import combinations
+
+from ..dto import Signal
+from ..fhir import MedicationRequest, rxnorm_of
+from ..refmodels import Interaction
+from ..reference import load_dose_limits, load_interactions
+
+
+@lru_cache(maxsize=None)
+def _pair_map() -> dict[frozenset[str], Interaction]:
+    """Індекс взаємодій за неупорядкованою парою RxNorm (будується один раз)."""
+    return {entry.pair(): entry for entry in load_interactions()}
+
+
+def _display_name(m: MedicationRequest) -> str:
+    """Назва препарату для тексту сигналу: text CodeableConcept → display coding → RxNorm-код."""
+    cc = m.medicationCodeableConcept
+    if cc.text:
+        return cc.text
+    for c in cc.coding:
+        if c.display:
+            return c.display
+    return rxnorm_of(m) or m.id
+
+
+def check_interactions(meds: list[MedicationRequest]) -> list[Signal]:
+    """Перевірка кожної неупорядкованої пари ліків на відому взаємодію (RxNorm)."""
+    pair_map = _pair_map()
+    signals: list[Signal] = []
+    for m1, m2 in combinations(meds, 2):
+        rx1, rx2 = rxnorm_of(m1), rxnorm_of(m2)
+        if rx1 is None or rx2 is None:
+            continue
+        entry = pair_map.get(frozenset((rx1, rx2)))
+        if entry is None:
+            continue
+        name1, name2 = _display_name(m1), _display_name(m2)
+        signals.append(
+            Signal(
+                layer="L1",
+                kind="interaction",
+                severity=entry.severity,
+                detail=f"{name1} + {name2}: {entry.detail}",
+                subjects=[f"MedicationRequest/{m1.id}", f"MedicationRequest/{m2.id}"],
+                confidence=1.0,
+            )
+        )
+    return signals
+
+
+def check_dose_limits(meds: list[MedicationRequest]) -> list[Signal]:
+    """Перевірка кожних ліків на перевищення максимальної добової дози (RxNorm)."""
+    limits = load_dose_limits()
+    signals: list[Signal] = []
+    for m in meds:
+        rx = rxnorm_of(m)
+        if rx is None or rx not in limits:
+            continue
+        if m.dose_mg_per_day is None:
+            continue
+        limit = limits[rx]
+        if m.dose_mg_per_day > limit.max_daily:
+            signals.append(
+                Signal(
+                    layer="L1",
+                    kind="dose_limit",
+                    severity="major",
+                    detail=(
+                        f"{limit.name}: добова доза {m.dose_mg_per_day:g} "
+                        f"{limit.unit} — перевищено добову межу "
+                        f"{limit.max_daily:g} {limit.unit}"
+                    ),
+                    subjects=[f"MedicationRequest/{m.id}"],
+                    confidence=1.0,
+                )
+            )
+    return signals
+
+
+def run(meds: list[MedicationRequest]) -> list[Signal]:
+    """Повний прогін L1: взаємодії + межі доз, у стабільному порядку."""
+    return check_interactions(meds) + check_dose_limits(meds)

livemedcard/layers/l2a_trends.py

@@ -0,0 +1,93 @@
+"""L2a — класичний детермінований аналіз на факт-сторі, не LLM.
+
+Дві перевірки над `FactStore`: виявлення стійких трендів показника (монотонне
+зростання/спадання) та порушення референсних меж за останнім виміром.
+"""
+from __future__ import annotations
+
+from typing import Optional
+
+from ..dto import Signal
+from ..reference import range_for
+from ..stores import FactStore
+
+
+def _fmt(v: float) -> str:
+    """Компактне форматування числа (без зайвих `.0`)."""
+    return f"{v:g}"
+
+
+def detect_trends(store: FactStore) -> list[Signal]:
+    """Стійкий монотонний тренд (>=3 вимірювань, всі зростають або всі спадають)."""
+    signals: list[Signal] = []
+    for loinc in store.loincs():
+        series = store.series(loinc)
+        if len(series) < 3:
+            continue
+        values = [f.value for f in series]
+        # Нестрога монотонність із чистою зміною: рівний крок (повторне значення)
+        # НЕ скасовує очевидний тренд, але суто рівний ряд трендом не вважається.
+        rising = all(a <= b for a, b in zip(values, values[1:])) and values[-1] > values[0]
+        falling = all(a >= b for a, b in zip(values, values[1:])) and values[-1] < values[0]
+        if not (rising or falling):
+            continue
+        direction = "зростає" if rising else "знижується"
+        first, last = series[0], series[-1]
+        detail = (
+            f"{first.keyword} {direction} {len(series)} вимірювань поспіль: "
+            f"{_fmt(first.value)}→{_fmt(last.value)} "
+            f"({first.ts.date().isoformat()}..{last.ts.date().isoformat()})"
+        )
+        signals.append(
+            Signal(
+                layer="L2a",
+                kind="trend",
+                severity="moderate",
+                detail=detail,
+                subjects=[loinc],
+                confidence=1.0,
+            )
+        )
+    return signals
+
+
+def detect_range_breaches(store: FactStore, sex: Optional[str] = None) -> list[Signal]:
+    """Останнє значення показника поза референсною межею (з урахуванням статі)."""
+    signals: list[Signal] = []
+    for loinc in store.loincs():
+        ref = range_for(loinc, sex)
+        if ref is None:
+            continue
+        series = store.series(loinc)
+        if not series:
+            continue
+        # series відсортований за часом; беремо ОСТАННІЙ (при рівних мітках —
+        # останній доданий), щоб L2a і Q&A узгоджено бачили те саме значення.
+        latest = series[-1]
+        if latest.value < ref.low:
+            direction = "нижче норми"
+        elif latest.value > ref.high:
+            direction = "вище норми"
+        else:
+            continue
+        unit = latest.unit or ref.unit or ""
+        detail = (
+            f"{ref.keyword} {_fmt(latest.value)} {unit} {direction} "
+            f"({_fmt(ref.low)}–{_fmt(ref.high)})"
+        )
+        signals.append(
+            Signal(
+                layer="L2a",
+                kind="range_breach",
+                severity="major",
+                detail=detail,
+                subjects=[loinc],
+                confidence=1.0,
+            )
+        )
+    return signals
+
+
+def run(store: FactStore, sex: Optional[str] = None) -> list[Signal]:
+    """Усі сигнали L2a: тренди + порушення референсних меж."""
+    return detect_trends(store) + detect_range_breaches(store, sex)

livemedcard/layers/l2b_extractor.py

@@ -0,0 +1,406 @@
+"""L2b — розуміння вільного тексту.
+
+У MVP детермінований stub замість MedGemma; екстрактор НЕ робить висновків
+про безпеку, лише витягує факти (лабораторні показники, ліки, діагнози)
+з українського вільного тексту у FHIR-ресурси.
+"""
+from __future__ import annotations
+
+import hashlib
+import re
+from datetime import datetime, timezone
+from typing import Optional, Protocol, TypeVar
+
+from ..config import (
+    STAGE1_MODEL,
+    STAGE1_URL,
+    STAGE2_MODEL,
+    STAGE2_URL,
+    STUB_CONFIDENCE,
+)
+from ..dto import Document, ExtractionResult
+from ..fhir import (
+    Attachment,
+    CodeableConcept,
+    Coding,
+    Condition,
+    DocumentReference,
+    MedicationRequest,
+    Observation,
+    Provenance,
+    Quantity,
+    Reference,
+    Sys,
+)
+from ..config import NUEXTRACT_MODEL, NUEXTRACT_URL
+from ..reference import load_vocab
+from . import l2b_nuextract, l2b_stage1, l2b_stage2_lora
+
+_T = TypeVar("_T")
+
+# Значення показника і дозу шукаємо ТІЛЬКИ впритул після терміна (між ними —
+# лише роздільники), а не пошуком уперед по всьому тексту. Інакше показник чи
+# ліки без власного числа «крадуть» число наступного терміна (напр. систолічний
+# тиск забирав би значення калію, а варфарин — дозу аспірину).
+_SEP = r"[\s:=–—-]*"
+_LAB_VALUE_RE = re.compile(_SEP + r"(\d+(?:\.\d+)?)")
+_DOSE_MG_RE = re.compile(_SEP + r"(\d+(?:\.\d+)?)\s*мг")
+# Кратність прийому: «×2», «x2», «2 рази», «двічі», «тричі» → множник за добу.
+_FREQ_RE = re.compile(r"[×xх]\s*(\d+)|(\d+)\s*раз|(двіч)|(тріч)", re.IGNORECASE)
+# Дата вимірювання на факт: ISO «2024-03-15» або «15.03.2024» у тому самому рядку.
+_DATE_RE = re.compile(r"\b(\d{4})-(\d{2})-(\d{2})\b|\b(\d{2})\.(\d{2})\.(\d{4})\b")
+
+
+def _stable_id(prefix: str, *parts: object) -> str:
+    """Детермінований id ресурсу від його змісту, а не порядку знахідки.
+
+    Стабільний між запусками і версіями словника: зміна порядку матчингу не
+    змінює id, тож ідемпотентність FactStore переживає повторний витяг і
+    відновлення зі старих знімків. Ідентичний зміст (той самий документ, код,
+    значення, час) навмисно дає той самий id — це один факт.
+    """
+    key = "|".join(str(p) for p in parts)
+    return f"{prefix}-{hashlib.sha1(key.encode('utf-8')).hexdigest()[:12]}"
+
+
+def _parse_effective_date(
+    text: str, pos: int, fallback: Optional[datetime]
+) -> Optional[datetime]:
+    """Дата факту з решти поточного рядка (після значення); інакше `fallback`.
+
+    Шукаємо ISO/dotted-дату лише до кінця рядка, щоб дата з наступного факту не
+    «перетікала» на попередній. Повертаємо tz-aware UTC-опівніч.
+    """
+    eol = text.find("\n", pos)
+    segment = text[pos:] if eol == -1 else text[pos:eol]
+    m = _DATE_RE.search(segment)
+    if m is None:
+        return fallback
+    if m.group(1):  # ISO YYYY-MM-DD
+        y, mo, d = int(m.group(1)), int(m.group(2)), int(m.group(3))
+    else:  # DD.MM.YYYY
+        d, mo, y = int(m.group(4)), int(m.group(5)), int(m.group(6))
+    try:
+        return datetime(y, mo, d, tzinfo=timezone.utc)
+    except ValueError:  # напр. 2024-13-40 — ігноруємо, лишаємо fallback
+        return fallback
+
+
+def _parse_daily_dose_mg(text: str, pos: int) -> Optional[float]:
+    """Добова доза в мг: разова доза «N мг» × кратність прийому (за замовч. 1)."""
+    m = _DOSE_MG_RE.match(text, pos)
+    if m is None:
+        return None
+    single = float(m.group(1))
+    freq = 1
+    fm = _FREQ_RE.search(text, m.end(), m.end() + 25)  # вікно тієї самої фрази
+    if fm:
+        if fm.group(1):
+            freq = int(fm.group(1))
+        elif fm.group(2):
+            freq = int(fm.group(2))
+        elif fm.group(3):
+            freq = 2  # двічі
+        elif fm.group(4):
+            freq = 3  # тричі
+    return single * freq
+
+
+class Extractor(Protocol):
+    """Контракт L2b-екстрактора."""
+
+    def extract(self, doc: Document, patient_id: str) -> ExtractionResult: ...
+
+
+def _find_vocab_terms(
+    text: str, vocab_terms: dict[str, _T]
+) -> list[tuple[str, _T, re.Match[str]]]:
+    """Знаходить УСІ входження кожного терміна в тексті.
+
+    Довші (багатослівні) терміни перевіряються першими, щоб виграти при
+    перекритті зі коротшими. Результат впорядкований за позицією входження
+    в тексті.
+    """
+    terms_by_length_desc = sorted(vocab_terms.items(), key=lambda kv: -len(kv[0]))
+    claimed_spans: list[tuple[int, int]] = []
+    found: list[tuple[int, str, _T, re.Match[str]]] = []
+    for term, info in terms_by_length_desc:
+        pattern = re.compile(rf"\b{re.escape(term)}\b", re.IGNORECASE)
+        # Усі входження терміна, а не лише перше — щоб не губити повторні
+        # вимірювання одного показника в межах документа.
+        for match in pattern.finditer(text):
+            start, end = match.span()
+            if any(start < claimed_end and end > claimed_start for claimed_start, claimed_end in claimed_spans):
+                continue
+            claimed_spans.append((start, end))
+            found.append((start, term, info, match))
+    found.sort(key=lambda item: item[0])
+    return [(term, info, match) for _, term, info, match in found]
+
+
+def deterministic_extract(
+    text: str, doc: Document, patient_id: str, *, extracted_by: str = "StubExtractor"
+) -> ExtractionResult:
+    """Детермінований Stage 2: текст → FHIR-ресурси (LOINC/RxNorm/SNOMED).
+
+    Спільне ядро для `StubExtractor` (вхід — сирий `doc.text`) і `TwoStageExtractor`
+    (вхід — Stage 1 SGR-summary). Дата обзервації береться з рядка факту, інакше
+    fallback на `doc.received_at` — тож на тексті без дат id/час не змінюються.
+    """
+    vocab = load_vocab()
+    subject = Reference(reference=f"Patient/{patient_id}")
+
+    observations: list[Observation] = []
+    seen_obs: set[str] = set()
+    for term, info, match in _find_vocab_terms(text, vocab.labs):
+        number_match = _LAB_VALUE_RE.match(text, match.end())
+        if number_match is None:
+            continue
+        eff_date = _parse_effective_date(text, number_match.end(), doc.received_at)
+        obs_id = _stable_id(
+            "obs", doc.id, info.loinc, number_match.group(1), eff_date
+        )
+        if obs_id in seen_obs:  # ідентична повторна згадка — той самий факт
+            continue
+        seen_obs.add(obs_id)
+        observations.append(
+            Observation(
+                id=obs_id,
+                status="final",
+                code=CodeableConcept(
+                    coding=[
+                        Coding(
+                            system=Sys.LOINC,
+                            code=info.loinc,
+                            display=info.display,
+                        )
+                    ],
+                    text=term.capitalize(),
+                ),
+                subject=subject,
+                effectiveDateTime=eff_date,
+                valueQuantity=Quantity(
+                    value=float(number_match.group(1)), unit=info.unit
+                ),
+                provenance=Provenance(
+                    source_doc_id=doc.id,
+                    extracted_by=extracted_by,
+                    confidence=STUB_CONFIDENCE,
+                ),
+            )
+        )
+
+    medications: list[MedicationRequest] = []
+    seen_med: set[str] = set()
+    for term, info, match in _find_vocab_terms(text, vocab.medications):
+        dose_mg_per_day: Optional[float] = _parse_daily_dose_mg(text, match.end())
+        med_id = _stable_id("med", doc.id, info.rxnorm, dose_mg_per_day)
+        if med_id in seen_med:
+            continue
+        seen_med.add(med_id)
+        medications.append(
+            MedicationRequest(
+                id=med_id,
+                status="active",
+                intent="order",
+                medicationCodeableConcept=CodeableConcept(
+                    coding=[
+                        Coding(
+                            system=Sys.RXNORM,
+                            code=info.rxnorm,
+                            display=info.display,
+                        )
+                    ],
+                    text=term.capitalize(),
+                ),
+                subject=subject,
+                dose_mg_per_day=dose_mg_per_day,
+                provenance=Provenance(
+                    source_doc_id=doc.id,
+                    extracted_by=extracted_by,
+                    confidence=STUB_CONFIDENCE,
+                ),
+            )
+        )
+
+    conditions: list[Condition] = []
+    seen_cond: set[str] = set()
+    for term, info, _match in _find_vocab_terms(text, vocab.conditions):
+        cond_id = _stable_id("cond", doc.id, info.snomed)
+        if cond_id in seen_cond:
+            continue
+        seen_cond.add(cond_id)
+        conditions.append(
+            Condition(
+                id=cond_id,
+                subject=subject,
+                code=CodeableConcept(
+                    coding=[
+                        Coding(
+                            system=Sys.SNOMED,
+                            code=info.snomed,
+                            display=info.display,
+                        )
+                    ],
+                    text=term,
+                ),
+                clinicalStatus="active",
+                onsetDateTime=doc.received_at,
+                provenance=Provenance(
+                    source_doc_id=doc.id,
+                    extracted_by=extracted_by,
+                    confidence=STUB_CONFIDENCE,
+                ),
+            )
+        )
+
+    # Порожній витяг означає «нічого не розпізнали», а не «впевнені на 100%».
+    # Низька впевненість веде документ на перегляд людиною (L3), а не в auto.
+    mean_confidence = (
+        STUB_CONFIDENCE if (observations or medications or conditions) else 0.0
+    )
+    return ExtractionResult(
+        observations=observations,
+        conditions=conditions,
+        medications=medications,
+        mean_confidence=mean_confidence,
+    )
+
+
+class StubExtractor:
+    """Детермінований stub-екстрактор: Stage 2 напряму по сирому `doc.text`."""
+
+    def extract(self, doc: Document, patient_id: str) -> ExtractionResult:
+        return deterministic_extract(doc.text, doc, patient_id)
+
+
+def _build_docref(
+    doc: Document, summary_text: str, patient_id: str
+) -> DocumentReference:
+    """FHIR DocumentReference з Stage 1 SGR-summary (free-text іпостась)."""
+    return DocumentReference(
+        id=f"docref-{doc.id}",
+        status="current",
+        subject=Reference(reference=f"Patient/{patient_id}"),
+        date=doc.received_at,
+        type=CodeableConcept(text=doc.kind),
+        content=Attachment(
+            contentType="text/plain",
+            data=summary_text,
+            title=f"SGR summary: {doc.id}",
+        ),
+        provenance=Provenance(
+            source_doc_id=doc.id,
+            extracted_by="MedGemma-Stage1",
+            confidence=STUB_CONFIDENCE,
+        ),
+    )
+
+
+class TwoStageExtractor:
+    """Двоетапний L2b: Stage 1 (LLM SGR-стиснення) → Stage 2 (детермінована KV-T).
+
+    Дає дві іпостасі одного документа: `DocumentReference` (free-text summary) і
+    структуровані FHIR-факти. Потребує живого локального LLM-сервера (LM Studio).
+    """
+
+    def __init__(self, *, model: str | None = None) -> None:
+        self._model = model
+
+    def extract(self, doc: Document, patient_id: str) -> ExtractionResult:
+        summary_text = l2b_stage1.summarize(doc.text, model=self._model)
+        ext = deterministic_extract(
+            summary_text, doc, patient_id, extracted_by="MedGemma-4B+Stage2"
+        )
+        ext.document_reference = _build_docref(doc, summary_text, patient_id)
+        return ext
+
+
+class LoraStage2Extractor:
+    """Двоетапний L2b з FT LoRA-Stage 2 (двосерверний llama.cpp-сетап).
+
+    Stage 1 — база (SGR-summary → `DocumentReference`); Stage 2 — база+LoRA
+    генерує KVT4, які парсяться у FHIR Observations (часті лаби мостяться у LOINC).
+    Потребує двох llama.cpp-серверів (`STAGE1_URL`, `STAGE2_URL`).
+    """
+
+    def __init__(
+        self,
+        *,
+        stage1_model: str | None = STAGE1_MODEL,
+        stage1_url: str | None = STAGE1_URL,
+        stage2_model: str | None = STAGE2_MODEL,
+        stage2_url: str | None = STAGE2_URL,
+    ) -> None:
+        self._s1_model = stage1_model
+        self._s1_url = stage1_url
+        self._s2_model = stage2_model
+        self._s2_url = stage2_url
+
+    def extract(self, doc: Document, patient_id: str) -> ExtractionResult:
+        summary_text = l2b_stage1.summarize(
+            doc.text, model=self._s1_model, base_url=self._s1_url
+        )
+        kvt = l2b_stage2_lora.extract_facts(
+            summary_text, url=self._s2_url, model=self._s2_model
+        )
+        observations = l2b_stage2_lora.to_observations(
+            kvt, doc, patient_id, extracted_by="MedGemma-LoRA-Stage2"
+        )
+        return ExtractionResult(
+            observations=observations,
+            mean_confidence=STUB_CONFIDENCE if observations else 0.0,
+            document_reference=_build_docref(doc, summary_text, patient_id),
+        )
+
+
+class NuExtractExtractor:
+    """L2b через NuExtract3 (VLM). Stage 2 (текст/markdown → KVT-факти за шаблоном)
+    → Observations (міст keyword→LOINC). `doc.text` (markdown або звичайний текст)
+    зберігається як `DocumentReference` — розширена іпостась.
+
+    Для зображень Stage 1 (image→markdown) робить `/ingest/image` через
+    `l2b_nuextract.image_to_markdown`, тож сюди вже приходить markdown у `doc.text`.
+    """
+
+    def __init__(self, *, url: str | None = NUEXTRACT_URL, model: str | None = NUEXTRACT_MODEL) -> None:
+        self._url = url
+        self._model = model
+
+    def extract(self, doc: Document, patient_id: str) -> ExtractionResult:
+        kvt = l2b_nuextract.extract_facts(doc.text, url=self._url, model=self._model)
+        observations = l2b_stage2_lora.to_observations(
+            kvt, doc, patient_id, extracted_by="NuExtract3"
+        )
+        return ExtractionResult(
+            observations=observations,
+            mean_confidence=STUB_CONFIDENCE if observations else 0.0,
+            document_reference=_build_docref(doc, doc.text, patient_id),
+        )
+
+
+def extract_documents(
+    docs: list[Document], patient_id: str, extractor: Extractor | None = None
+) -> ExtractionResult:
+    """Об'єднує результати L2b-екстракції з кількох документів."""
+    extractor = extractor if extractor is not None else StubExtractor()
+
+    observations: list[Observation] = []
+    conditions: list[Condition] = []
+    medications: list[MedicationRequest] = []
+    confidences: list[float] = []
+
+    for doc in docs:
+        result = extractor.extract(doc, patient_id)
+        observations.extend(result.observations)
+        conditions.extend(result.conditions)
+        medications.extend(result.medications)
+        confidences.append(result.mean_confidence)
+
+    mean_confidence = sum(confidences) / len(confidences) if confidences else 1.0
+    return ExtractionResult(
+        observations=observations,
+        conditions=conditions,
+        medications=medications,
+        mean_confidence=mean_confidence,
+    )

livemedcard/layers/l2b_nuextract.py

@@ -0,0 +1,65 @@
+"""L2b через NuExtract3 (VLM structured extraction) — один рушій, дві іпостасі.
+
+NuExtract читає документ (текст/зображення) + JSON-шаблон і повертає структурований
+JSON; окремо вміє image→markdown. Використовуємо двоетапно (за результатами бенчмарку
+найточніше): Stage 1 image→markdown (розширена іпостась), Stage 2 markdown→facts
+(стисла). Шаблон передається через `chat_template_kwargs` (llama-server --jinja / vLLM).
+
+Не медична модель → кодування в LOINC робимо мостом (`l2b_stage2_lora`).
+"""
+from __future__ import annotations
+
+import json
+
+from ..config import NUEXTRACT_MODEL, NUEXTRACT_URL
+from ..llm_client import chat_completions
+
+# Шаблон KVT-фактів (leaf-значення = типи NuExtract).
+_FACTS_TEMPLATE = {
+    "facts": [
+        {"keyword": "verbatim-string", "value": "verbatim-string", "timestamp": "verbatim-string"}
+    ]
+}
+_TEMPLATE_JSON = json.dumps(_FACTS_TEMPLATE, indent=2)
+
+
+def _ctk(**kw) -> dict:
+    return {"chat_template_kwargs": {"enable_thinking": False, **kw}}
+
+
+def image_to_markdown(base64_image: str, *, url: str | None = None, model: str | None = None) -> str:
+    """Stage 1: зображення → markdown (розширена іпостась). mode=markdown."""
+    if "," in base64_image:
+        base64_image = base64_image.split(",", 1)[1]
+    messages = [{
+        "role": "user",
+        "content": [{"type": "image_url",
+                     "image_url": {"url": f"data:image/jpeg;base64,{base64_image}"}}],
+    }]
+    return chat_completions(
+        messages, model=model or NUEXTRACT_MODEL, base_url=url or NUEXTRACT_URL,
+        temperature=0.0, max_tokens=4096, timeout=180.0,
+        service_name="NuExtract", extra_body=_ctk(mode="markdown"),
+    )
+
+
+def extract_facts(text: str, *, url: str | None = None, model: str | None = None) -> list[dict]:
+    """Stage 2: текст/markdown → KVT-факти за шаблоном. Повертає [{keyword,value,timestamp}]."""
+    messages = [{"role": "user", "content": [{"type": "text", "text": text}]}]
+    raw = chat_completions(
+        messages, model=model or NUEXTRACT_MODEL, base_url=url or NUEXTRACT_URL,
+        temperature=0.0, max_tokens=3072, timeout=120.0,
+        service_name="NuExtract", extra_body=_ctk(template=_TEMPLATE_JSON),
+    )
+    try:
+        data = json.loads(raw)
+    except json.JSONDecodeError:
+        start, end = raw.find("{"), raw.rfind("}")
+        if start == -1 or end <= start:
+            return []
+        try:
+            data = json.loads(raw[start:end + 1])
+        except json.JSONDecodeError:
+            return []
+    facts = data.get("facts", []) if isinstance(data, dict) else data
+    return [f for f in facts if isinstance(f, dict) and f.get("keyword")]

livemedcard/layers/l2b_stage1.py

@@ -0,0 +1,211 @@
+"""L2b Stage 1 — SGR-стиснення вільного тексту в стабільний summary.
+
+Локальна MedGemma читає сирий текст (OCR або введений) і повертає стислий,
+формат-стабільний SGR-summary з 9 доменними ключами. Це **free-text іпостась**:
+згорнута, клінічно структурована, але ще не канонізована. Детермінований Stage 2
+(`l2b_extractor.deterministic_extract`) далі витягує з неї KV-T факти.
+
+Метод і промпт-контракт — за статтею автора «LLM StructCore» (Schema-Guided
+Reasoning Condensation): LLM лише стискає (стохастика впливає на recall), а
+формат/словник гарантує детермінований Stage 2. Адаптовано під лонгітюдну
+українську медкартку: без фіксованого CRF, зі збереженням сирих значень і
+**дат на факт**.
+"""
+from __future__ import annotations
+
+import json
+import re
+from typing import Iterable
+
+from ..config import STAGE1_MODEL
+from ..llm_client import chat_completions
+
+STAGE1_KEYS_9: list[str] = [
+    "DEMOGRAPHICS",
+    "VITALS",
+    "LABS",
+    "PROBLEMS",
+    "SYMPTOMS",
+    "MEDICATIONS",
+    "PROCEDURES",
+    "UTILIZATION",
+    "DISPOSITION",
+]
+
+
+def build_stage1_system_prompt() -> str:
+    keys_str = ", ".join(f'"{k}"' for k in STAGE1_KEYS_9)
+    return f"""You are an expert clinical information compression engine for a
+longitudinal medical card. Convert ONE clinical document (in any language,
+often Ukrainian) into a compact, reliable intermediate summary.
+This is Stage 1 only — a downstream deterministic parser will extract structured facts.
+
+OUTPUT CONTRACT (STRICT):
+1) Output MUST be a single valid JSON object. The FIRST character MUST be "{{".
+2) Output JSON only: no markdown, no code fences, no extra text.
+3) Do NOT output analysis, chain-of-thought, or "thinking".
+4) Use EXACTLY these keys (no extra, no missing):
+   {keys_str}
+
+VALUE FORMAT (STRICT):
+- Each value MUST be a string (never a nested object or array).
+- If a cluster has no supported facts: use exactly "not stated".
+- For multiple facts use "\\n" (two characters) between short "Key: Value" lines.
+
+CONTENT RULES:
+- Keep the document's original language and the EXACT raw values (numbers, units,
+  test names). Do NOT translate values, do NOT round, do NOT infer from absence.
+- Include a fact ONLY if it is explicitly stated. If unsure, omit the line.
+- MEASURED VALUES, NOT SCAFFOLDING: capture the patient's own measured/reported
+  values. Do NOT record reference ranges, target thresholds, or chart axis ticks
+  (e.g. "Target Range 70-180 mg/dL", "Above 250 mg/dL", axis labels like
+  "250 / 180 / 70") as facts — they are scale, not measurements.
+- DATES PER FACT: if a measurement/prescription date is stated in the text, append
+  it in parentheses at the END of that line in ISO form: "(YYYY-MM-DD)".
+  Example: "креатинін: 120 (2024-03-15)". If no date is stated, omit the parentheses.
+
+ANTI-DRIFT (MUST FOLLOW):
+- NEVER repeat the same line. Deduplicate. Max ~12 lines and ~700 chars per field.
+- If you start repeating, STOP and output the JSON object immediately.
+
+CLUSTER GUIDANCE (9 clusters):
+- DEMOGRAPHICS: patient context, past medical history, social/baseline.
+- VITALS: BP/HR/RR/Temp/SpO2 and severity cues (raw values).
+- LABS: lab/biomarker values (raw numbers + units).
+- PROBLEMS: diagnoses and clinical problems (acute/chronic).
+- SYMPTOMS: presenting symptoms and course.
+- MEDICATIONS: medications with dose/frequency exactly as written.
+- PROCEDURES: imaging/tests/procedures performed and findings.
+- UTILIZATION: ED events, consults, monitoring, escalation.
+- DISPOSITION: discharge outcome/follow-up if stated (else "not stated").
+
+FORMAT SKELETON (structure only; do NOT copy these placeholder values):
+{{
+  "DEMOGRAPHICS": "not stated",
+  "VITALS": "not stated",
+  "LABS": "not stated",
+  "PROBLEMS": "not stated",
+  "SYMPTOMS": "not stated",
+  "MEDICATIONS": "not stated",
+  "PROCEDURES": "not stated",
+  "UTILIZATION": "not stated",
+  "DISPOSITION": "not stated"
+}}
+"""
+
+
+def build_stage1_user_prompt(note_text: str) -> str:
+    return f"Clinical document:\n{note_text}\n\nReturn the Stage 1 JSON now:"
+
+
+# ── парсинг відповіді моделі ──────────────────────────────────────────────────
+def _strip_thinking_wrappers(text: str) -> str:
+    # Gemma-family інколи емітить <unusedNN>thought…-обгортки навколо міркувань.
+    s = text.strip()
+    s = re.sub(r"<unused\d+>thought.*?(?:<unused\d+>|$)", "", s, flags=re.DOTALL | re.IGNORECASE)
+    s = re.sub(r"<unused\d+>", "", s, flags=re.IGNORECASE)
+    return s.strip()
+
+
+def extract_json_object(text: str) -> dict:
+    """Витягти JSON-обʼєкт із відповіді моделі, з ремонтом обрізаного хвоста.
+
+    Якщо модель урвала вивід перед фінальною "}" (типово через повтори),
+    відкочуємось до найдовшого префікса, що парситься як валідний JSON.
+    """
+    s = _strip_thinking_wrappers(text)
+    if "```json" in s:
+        s = s.split("```json", 1)[1].split("```", 1)[0].strip()
+    elif "```" in s:
+        s = s.split("```", 1)[1].split("```", 1)[0].strip()
+
+    if "{" not in s:
+        raise ValueError("No JSON object start '{' found.")
+    start = s.find("{")
+    end = s.rfind("}")
+    if end > start:
+        return json.loads(s[start : end + 1])
+
+    cand = s[start:]
+    max_backtrack = max(0, len(cand) - 20000)  # обмежити роботу на дуже довгих
+    for cut in range(len(cand), max_backtrack, -1):
+        chunk = cand[:cut].strip()
+        if not chunk:
+            continue
+        chunk2 = chunk if chunk.endswith("}") else chunk + "}"
+        try:
+            obj = json.loads(chunk2)
+            if isinstance(obj, dict):
+                return obj
+        except Exception:
+            continue
+    raise ValueError("No JSON object end '}' found.")
+
+
+def coerce_stage1_summary(obj: dict) -> dict[str, str]:
+    """Зробити Stage 1 вивід безпечним і стабільним: усі 9 ключів, лише рядки.
+
+    Відсутні ключі → "not stated"; зайві відкидаються; вкладені dict/list
+    сплощуються у "Key: Value" рядки (контракт «лише рядки»).
+    """
+    def _flatten(v: object) -> str:
+        if v is None:
+            return "not stated"
+        if isinstance(v, str):
+            s = v.strip()
+            return s or "not stated"
+        if isinstance(v, dict):
+            lines: list[str] = []
+            for kk, vv in v.items():
+                kks = str(kk).strip()
+                if not kks or vv is None:
+                    continue
+                if isinstance(vv, (dict, list)):
+                    inner = ", ".join(
+                        str(x).strip()
+                        for x in (vv.values() if isinstance(vv, dict) else vv)
+                        if str(x).strip()
+                    )
+                    if inner:
+                        lines.append(f"{kks}: {inner}")
+                    continue
+                vvs = str(vv).strip()
+                if vvs:
+                    lines.append(f"{kks}: {vvs}")
+            return "\n".join(lines) if lines else "not stated"
+        if isinstance(v, list):
+            lines = [str(x).strip() for x in v if str(x).strip()]
+            return "\n".join(lines) if lines else "not stated"
+        s = str(v).strip()
+        return s or "not stated"
+
+    return {k: _flatten(obj.get(k, "not stated")) for k in STAGE1_KEYS_9}
+
+
+def stage1_summary_to_text(summary: dict[str, str], keys: Iterable[str] | None = None) -> str:
+    """Компактний стабільний текстовий вигляд summary для Stage 2 та зберігання."""
+    parts: list[str] = []
+    for k in keys or STAGE1_KEYS_9:
+        parts.append(f"## {k}")
+        parts.append(summary.get(k, "not stated"))
+    return "\n".join(parts) + "\n"
+
+
+def summarize(
+    note_text: str, *, model: str | None = None, base_url: str | None = None
+) -> str:
+    """Stage 1: сирий текст → SGR-summary (плаский текст із заголовками ## KEY).
+
+    Викликає локальну MedGemma; ремонтує/нормалізує JSON; повертає текст, готовий
+    і для зберігання (DocumentReference), і для Stage 2. `base_url` — окремий
+    Stage 1-сервер (двосерверний LoRA-сетап).
+    """
+    messages = [
+        {"role": "system", "content": build_stage1_system_prompt()},
+        {"role": "user", "content": build_stage1_user_prompt(note_text)},
+    ]
+    raw = chat_completions(
+        messages, model=model or STAGE1_MODEL, timeout=120.0, base_url=base_url
+    )
+    summary = coerce_stage1_summary(extract_json_object(raw))
+    return stage1_summary_to_text(summary)

livemedcard/layers/l2b_stage2_lora.py

@@ -0,0 +1,203 @@
+"""L2b Stage 2 (LoRA) — fine-tuned MedGemma генерує KVT4 факти.
+
+Альтернатива детермінованому `deterministic_extract`: замість regex+vocab.json
+тут працює FT-модель DocUA/medgemma-1.5-4b-it-...-two-stage (база+LoRA-адаптер),
+натренована видавати KVT4 — `{cluster, keyword, value, timestamp}`. Знімає
+обмеження словника, узагальнює на будь-який документ.
+
+Межа безпеки збережена: LoRA лише **витягує факти**; сигнали L1/L2a рахуються
+детерміновано на FactStore. Часті лабораторні keywords мостяться у LOINC (щоб
+потрапляли в таймлайн і перевірки), решта лишаються free-form у summary.
+"""
+from __future__ import annotations
+
+import hashlib
+import json
+import re
+from datetime import datetime, timezone
+from typing import Optional
+
+from ..config import STAGE2_MODEL, STAGE2_URL
+from ..dto import Document
+from ..fhir import (
+    CodeableConcept,
+    Coding,
+    Observation,
+    Provenance,
+    Quantity,
+    Reference,
+    Sys,
+)
+from ..llm_client import chat_completions
+
+# ── keyword → LOINC міст (часті лаби readmission-домену) ──────────────────────
+# Значення: (LOINC, людська назва). Одиниця береться з value LoRA (fallback — тут).
+_KEYWORD_LOINC: dict[str, tuple[str, str]] = {
+    # EN (readmission-домен FT) + UA — білінгвальний міст
+    "creatinine": ("2160-0", "Creatinine"),
+    "креатинін": ("2160-0", "Creatinine"),
+    "glucose": ("2345-7", "Glucose"),
+    "глюкоза": ("2345-7", "Glucose"),
+    "potassium": ("2823-3", "Potassium"),
+    "калій": ("2823-3", "Potassium"),
+    "sodium": ("2951-2", "Sodium"),
+    "натрій": ("2951-2", "Sodium"),
+    "hemoglobin": ("718-7", "Hemoglobin"),
+    "гемоглобін": ("718-7", "Hemoglobin"),
+    "hematocrit": ("4544-3", "Hematocrit"),
+    "гематокрит": ("4544-3", "Hematocrit"),
+    "wbc": ("6690-2", "Leukocytes"),
+    "leukocytes": ("6690-2", "Leukocytes"),
+    "лейкоцити": ("6690-2", "Leukocytes"),
+    "platelet": ("777-3", "Platelets"),
+    "тромбоцити": ("777-3", "Platelets"),
+    "bun": ("3094-0", "Urea nitrogen"),
+    "сечовина": ("3094-0", "Urea nitrogen"),
+    "bicarbonate": ("1963-8", "Bicarbonate"),
+    "бікарбонат": ("1963-8", "Bicarbonate"),
+}
+
+# CGM/AGP-метрики → стандартні LOINC CGM-панелі. Substring-матчинг, бо NuExtract
+# дає варіативні формулювання («Glucose Management Indicator (GMI)», «CGM Average
+# Glucose»). Даємо ЛИШЕ headline-коди, в яких упевнені; TIR-біни / variability /
+# active-time свідомо НЕ мапимо (коди треба звірити з авторитетним LOINC —
+# фабрикувати клінічні коди небезпечно). Порядок — специфічніше раніше.
+# ⚠ Перед клінічним використанням підтвердити ці коди за офіційним LOINC.
+_CGM_LOINC: list[tuple[tuple[str, ...], str, str]] = [
+    (("glucose management indicator", "gmi"), "97506-0", "Glucose Management Indicator"),
+    (("average glucose", "mean glucose"), "97507-8", "Mean glucose (CGM)"),
+]
+
+
+def _resolve_loinc(keyword: str) -> tuple[str, str] | None:
+    """LOINC для keyword: точний збіг (лаби) → substring (CGM) → None (free-form)."""
+    low = keyword.lower()
+    exact = _KEYWORD_LOINC.get(low)
+    if exact is not None:
+        return exact
+    for toks, code, display in _CGM_LOINC:
+        if any(t in low for t in toks):
+            return code, display
+    return None
+
+_THOUGHT_TOKEN_RE = re.compile(r"<unused\d+>", re.IGNORECASE)
+_VALUE_NUM_RE = re.compile(r"^\s*(-?\d+(?:[.,]\d+)?)\s*(.*)$")
+_TS_DATE_FORMATS = ("%Y-%m-%d", "%d.%m.%Y", "%m/%d/%Y", "%B %d, %Y", "%b %d, %Y")
+
+
+def _stable_id(*parts: object) -> str:
+    key = "|".join(str(p) for p in parts)
+    return f"obs-{hashlib.sha1(key.encode('utf-8')).hexdigest()[:12]}"
+
+
+def build_stage2_system_prompt() -> str:
+    return (
+        "You extract clinical facts from a structured Stage-1 summary. "
+        "Output ONLY a JSON array of facts, each an object with keys "
+        '"cluster", "keyword", "value", "timestamp". '
+        "Use the patient's own measured values (numbers with units where present). "
+        "If a date/period is stated for a fact, put it in \"timestamp\", else use "
+        '"not stated". Do NOT invent facts. Output JSON only, no prose.'
+    )
+
+
+def _extract_json_array(text: str) -> list[dict]:
+    """Витягти JSON-масив фактів із відповіді моделі (стрип thought-токенів)."""
+    s = _THOUGHT_TOKEN_RE.sub("", text).strip()
+    if "```json" in s:
+        s = s.split("```json", 1)[1].split("```", 1)[0].strip()
+    elif "```" in s:
+        s = s.split("```", 1)[1].split("```", 1)[0].strip()
+    start, end = s.find("["), s.rfind("]")
+    if start == -1 or end <= start:
+        return []
+    try:
+        data = json.loads(s[start : end + 1])
+    except json.JSONDecodeError:
+        return []
+    return [d for d in data if isinstance(d, dict)]
+
+
+def _split_value(value: object) -> tuple[Optional[float], Optional[str]]:
+    """'204 mg/dL' → (204.0, 'mg/dL'); '34%' → (34.0, '%'); 'Yes' → (None, None)."""
+    m = _VALUE_NUM_RE.match(str(value))
+    if m is None:
+        return None, None
+    num = float(m.group(1).replace(",", "."))
+    unit = m.group(2).strip() or None
+    return num, unit
+
+
+def _parse_timestamp(ts: object, fallback: Optional[datetime]) -> Optional[datetime]:
+    """Дата факту з різних форматів; для періоду «A - B» береться КІНЕЦЬ (B)."""
+    s = str(ts).strip()
+    if not s or s.lower() == "not stated":
+        return fallback
+    for sep in (" - ", " – ", " — ", " to "):
+        if sep in s:
+            s = s.split(sep)[-1].strip()
+            break
+    for fmt in _TS_DATE_FORMATS:
+        try:
+            return datetime.strptime(s, fmt).replace(tzinfo=timezone.utc)
+        except ValueError:
+            continue
+    return fallback
+
+
+def extract_facts(summary_text: str, *, url: str | None = None, model: str | None = None) -> list[dict]:
+    """Викликати LoRA-Stage 2 сервер і повернути сирі KVT4-обʼєкти."""
+    messages = [
+        {"role": "system", "content": build_stage2_system_prompt()},
+        {"role": "user", "content": summary_text},
+    ]
+    raw = chat_completions(
+        messages,
+        model=model or STAGE2_MODEL,
+        base_url=url or STAGE2_URL,
+        temperature=0.0,
+        max_tokens=768,
+        frequency_penalty=0.1,  # ≈ repetition-penalty 1.1 з README
+        service_name="LoRA Stage 2",
+    )
+    return _extract_json_array(raw)
+
+
+def to_observations(
+    kvt: list[dict], doc: Document, patient_id: str, *, extracted_by: str
+) -> list[Observation]:
+    """KVT4 → FHIR Observations (лише числові; часті лаби мостяться у LOINC)."""
+    subject = Reference(reference=f"Patient/{patient_id}")
+    observations: list[Observation] = []
+    seen: set[str] = set()
+    for item in kvt:
+        keyword = str(item.get("keyword", "")).strip()
+        if not keyword:
+            continue
+        num, unit = _split_value(item.get("value"))
+        if num is None:  # нечислові (Yes/No, назви) лишаються лише в summary
+            continue
+        eff = _parse_timestamp(item.get("timestamp"), doc.received_at)
+        bridge = _resolve_loinc(keyword)
+        coding = (
+            [Coding(system=Sys.LOINC, code=bridge[0], display=bridge[1])]
+            if bridge else []
+        )
+        obs_id = _stable_id(doc.id, keyword.lower(), num, eff)
+        if obs_id in seen:
+            continue
+        seen.add(obs_id)
+        observations.append(
+            Observation(
+                id=obs_id,
+                status="final",
+                code=CodeableConcept(coding=coding, text=keyword),
+                subject=subject,
+                effectiveDateTime=eff,
+                valueQuantity=Quantity(value=num, unit=unit),
+                provenance=Provenance(
+                    source_doc_id=doc.id, extracted_by=extracted_by, confidence=None
+                ),
+            )
+        )
+    return observations

livemedcard/layers/l3_router.py

@@ -0,0 +1,58 @@
+"""Шар TRACE L3: stateful політика роутингу/ескалації.
+
+Два незалежні приводи ескалації до людини (L4):
+
+1. **Детермінований сигнал високого ризику** (major/critical з L1/L2a). Такі
+   сигнали самі по собі достовірні (confidence = 1.0), тому їхня передача людині
+   НЕ залежить від впевненості текстового витягу L2b — реальна небезпека завжди
+   потребує рішення людини.
+2. **Низька впевненість витягу L2b** — документ погано розпізнано, факти
+   ненадійні, тому потрібна перевірка людиною навіть без сигналів.
+"""
+from __future__ import annotations
+
+from typing import Optional
+
+from ..config import LOW_CONFIDENCE
+from ..dto import Decision, Severity, Signal, severity_rank
+
+__all__ = ["route", "LOW_CONFIDENCE"]
+
+
+def route(signals: list[Signal], extraction_confidence: float, doc_kind: str) -> Decision:
+    """Приймає рішення про маршрут документа: "auto" чи "L4_human"."""
+    top: Optional[Signal] = max(
+        signals, key=lambda s: severity_rank(s.severity), default=None
+    )
+    high_risk = top is not None and severity_rank(top.severity) >= severity_rank(
+        _MAJOR
+    )
+    low_confidence = extraction_confidence < LOW_CONFIDENCE
+    escalate = high_risk or low_confidence
+
+    reasons: list[str] = []
+    if high_risk and top is not None:
+        reasons.append(
+            f"Детермінований сигнал рівня «{top.severity}» ({top.kind}) — "
+            f"рішення за людиною незалежно від впевненості витягу"
+        )
+    if low_confidence:
+        reasons.append(
+            f"Низька впевненість витягу ({extraction_confidence:.2f}) — "
+            f"потрібна перевірка людиною"
+        )
+    if not escalate:
+        reasons.append(
+            "Немає сигналів високого ризику, витяг впевнений — автоматична обробка"
+        )
+    reasons.append(f"Тип документа: {doc_kind}")
+
+    return Decision(
+        route_to="L4_human" if escalate else "auto",
+        escalate=escalate,
+        reasons=reasons,
+        signals=signals,
+    )
+
+
+_MAJOR: Severity = "major"

livemedcard/llm_client.py

@@ -0,0 +1,98 @@
+"""Спільний клієнт до локального OpenAI-сумісного сервера (LM Studio, llama.cpp).
+
+Один канал доступу до on-device MedGemma для обох споживачів: OCR (`ocr.py`) і
+Stage 1 SGR-стиснення (`layers/l2b_stage1.py`). Використовує лише stdlib
+(`urllib`), щоб тести могли мокати `urllib.request.urlopen` так само, як для OCR.
+"""
+from __future__ import annotations
+
+import json
+import urllib.error
+import urllib.request
+
+from .config import LMSTUDIO_URL, OCR_MODEL
+
+
+class LLMError(Exception):
+    """Помилка виклику локальної LLM (недоступний сервер, порожня відповідь тощо)."""
+
+
+def detect_model(base_url: str | None = None) -> str:
+    """Назва завантаженої моделі з `/models`; fallback на `OCR_MODEL`."""
+    url = f"{(base_url or LMSTUDIO_URL).rstrip('/')}/models"
+    try:
+        req = urllib.request.Request(url, method="GET")
+        with urllib.request.urlopen(req, timeout=5.0) as response:
+            data = json.loads(response.read().decode("utf-8"))
+            if data.get("data"):
+                model_id = data["data"][0].get("id")
+                if model_id:
+                    return model_id
+    except Exception:
+        pass
+    return OCR_MODEL
+
+
+def chat_completions(
+    messages: list[dict],
+    *,
+    model: str | None = None,
+    temperature: float = 0.0,
+    max_tokens: int = 2048,
+    timeout: float = 120.0,
+    service_name: str = "локальною LLM",
+    frequency_penalty: float | None = None,
+    presence_penalty: float | None = None,
+    base_url: str | None = None,
+    extra_body: dict | None = None,
+) -> str:
+    """Викликати `/chat/completions` і повернути текст першого choice.
+
+    `messages` — у форматі OpenAI (роль + content; content може бути рядком або
+    списком частин для vision). `model=None` → автовизначення через `detect_model()`.
+    `service_name` — назва сервісу у повідомленні про помилку з'єднання (напр.
+    «LM Studio» для OCR). `frequency_penalty`/`presence_penalty` (коли задані) —
+    придушення повторів (напр. зациклення на підписах осей при OCR інфографіки).
+    `base_url` — override ендпойнта (напр. окремий llama.cpp-сервер LoRA-Stage 2).
+    """
+    endpoint = base_url or LMSTUDIO_URL
+    model_name = model or detect_model(endpoint)
+    url = f"{endpoint.rstrip('/')}/chat/completions"
+    payload = {
+        "model": model_name,
+        "messages": messages,
+        "temperature": temperature,
+        "max_tokens": max_tokens,
+        "stream": False,
+    }
+    if frequency_penalty is not None:
+        payload["frequency_penalty"] = frequency_penalty
+    if presence_penalty is not None:
+        payload["presence_penalty"] = presence_penalty
+    if extra_body:  # напр. NuExtract chat_template_kwargs (template / mode)
+        payload.update(extra_body)
+    req = urllib.request.Request(
+        url,
+        data=json.dumps(payload).encode("utf-8"),
+        headers={"Content-Type": "application/json"},
+        method="POST",
+    )
+    try:
+        with urllib.request.urlopen(req, timeout=timeout) as response:
+            res_data = json.loads(response.read().decode("utf-8"))
+    except urllib.error.URLError as exc:
+        raise LLMError(
+            f"Не вдалося з'єднатися з {service_name} за адресою {endpoint}. "
+            f"Переконайтеся, що сервер запущено та завантажено модель. "
+            f"Помилка: {exc.reason if hasattr(exc, 'reason') else exc}"
+        ) from exc
+    except Exception as exc:
+        raise LLMError(f"Помилка виклику локальної LLM: {exc}") from exc
+
+    choices = res_data.get("choices", [])
+    if not choices:
+        raise LLMError("LLM повернула порожню відповідь (choices порожній).")
+    content = choices[0].get("message", {}).get("content", "")
+    if not content:
+        raise LLMError("У відповіді моделі відсутній вміст (content).")
+    return content.strip()

livemedcard/ocr.py

@@ -0,0 +1,80 @@
+"""OCR Service Layer.
+
+Uses local LM Studio API (with medgemma-1.5-4b-it or other loaded vision model)
+to perform OCR on medical documents using base64 image data. HTTP-виклик
+делеговано спільному `llm_client`; тут лишається лише vision-специфіка (формат
+повідомлення із зображенням і промпт транскрипції).
+"""
+from __future__ import annotations
+
+from .config import OCR_MODEL
+from .llm_client import LLMError, chat_completions, detect_model
+
+
+class OcrError(Exception):
+    """Custom exception for OCR failures."""
+    pass
+
+
+_OCR_PROMPT = (
+    "You transcribe a medical document image into plain text. Follow these rules:\n"
+    "1. LANGUAGE: keep the original language. Do NOT translate. No comments, "
+    "headings, or explanations — output only the transcription.\n"
+    "2. VALUES ARE CRITICAL: transcribe every number, unit and date exactly "
+    "(e.g. '204 mg/dL', '8.2%', '06/13/2025'). Never omit a value.\n"
+    "3. PAIR LABELS WITH THEIR VALUES: this may be a multi-column report where a "
+    "metric name and its value are separated horizontally or placed in different "
+    "columns. Read the layout and write each on one line as 'Label: value unit' "
+    "(e.g. 'Average Glucose: 204 mg/dL', 'Time CGM Active: 34%').\n"
+    "4. CHARTS: for plots/graphs, transcribe axis titles and the legend ONCE. Do "
+    "NOT repeat tick labels or time-axis labels (e.g. '12am 3am 6am'); write such a "
+    "sequence at most once. Never loop or repeat a line.\n"
+    "5. If a value is unreadable, write the label with '[unreadable]' — do NOT "
+    "invent a number.\n"
+    "Output the transcription now."
+)
+
+
+class OcrService:
+    """Service to handle OCR operations with local LLM server."""
+
+    @staticmethod
+    def detect_model() -> str:
+        """Query LM Studio to detect loaded model name, fallback to config."""
+        return detect_model()
+
+    @classmethod
+    def perform_ocr(cls, base64_image: str) -> str:
+        """Send base64 image to local vision LLM for transcription."""
+        # Strip potential data URL prefix, e.g. "data:image/png;base64,"
+        if "," in base64_image:
+            base64_image = base64_image.split(",", 1)[1]
+
+        messages = [
+            {
+                "role": "user",
+                "content": [
+                    {"type": "text", "text": _OCR_PROMPT},
+                    {
+                        "type": "image_url",
+                        "image_url": {
+                            "url": f"data:image/jpeg;base64,{base64_image}"
+                        },
+                    },
+                ],
+            }
+        ]
+        try:
+            return chat_completions(
+                messages,
+                # OCR мусить цілитись у КОНКРЕТНУ vision-модель (OCR_MODEL), а не в
+                # «першу завантажену»: інакше text-only модель (напр. 27B) перехопить
+                # запит і поверне 500 на зображення. Auto-detect тут недоречний.
+                model=OCR_MODEL,
+                max_tokens=4096,  # щільні звіти не влазять у 2048
+                timeout=180.0,  # vision inference is slow
+                service_name="LM Studio",
+                frequency_penalty=0.8,  # проти зациклення на підписах осей
+            )
+        except LLMError as exc:
+            raise OcrError(str(exc)) from exc

livemedcard/pipeline.py

@@ -0,0 +1,174 @@
+"""Оркестрація конвеєра TRACE: документ → витяг → сховища → сигнали → рішення.
+
+Головний інваріант: сигнали безпеки (L1/L2a) рахуються детерміновано на факт-сторі,
+а L2b (екстрактор) лише витягує факти й не робить висновків про безпеку.
+
+`LiveMedCard` — джерело істини для FHIR-ресурсів пацієнта; `FactStore` і
+`KnowledgeGraph` — похідні проєкції над ними. Це дає знімок стану (snapshot),
+експорт у FHIR Bundle і аудит рішень.
+"""
+from __future__ import annotations
+
+from datetime import datetime, timezone
+from typing import Optional
+
+from .dto import AuditEntry, Document, ExtractionResult, Signal, TraceReport
+from .fhir import (
+    Condition,
+    DocumentReference,
+    MedicationRequest,
+    Observation,
+    Patient,
+)
+from .layers import l1_safety, l2a_trends, l3_router
+from .layers.l2b_extractor import Extractor, StubExtractor
+from .stores import FactStore, KnowledgeGraph
+
+
+class LiveMedCard:
+    """Стан однієї медичної картки пацієнта + прогін документів крізь TRACE."""
+
+    def __init__(self, patient: Patient, extractor: Optional[Extractor] = None) -> None:
+        self.patient = patient
+        self.extractor: Extractor = extractor or StubExtractor()
+        self.factstore = FactStore()
+        self.graph = KnowledgeGraph()
+        self.graph.add_patient(patient)
+        # Джерело істини — утримувані FHIR-ресурси (дедуплікація за id).
+        self._observations: list[Observation] = []
+        self._conditions: list[Condition] = []
+        self._medications: list[MedicationRequest] = []
+        self._doc_refs: list[DocumentReference] = []
+        self._obs_ids: set[str] = set()
+        self._cond_ids: set[str] = set()
+        self._med_ids: set[str] = set()
+        self._docref_ids: set[str] = set()
+        self._document_ids: set[str] = set()
+        self._audit: list[AuditEntry] = []
+
+    # ── L2b → сховища ───────────────────────────────────────────────────────
+    def _absorb(self, ext: ExtractionResult) -> None:
+        for o in ext.observations:
+            self.factstore.add_observation(o)
+            self.graph.add_observation(o, self.patient.id)
+            if o.id not in self._obs_ids:
+                self._observations.append(o)
+                self._obs_ids.add(o.id)
+        for c in ext.conditions:
+            self.graph.add_condition(c, self.patient.id)
+            if c.id not in self._cond_ids:
+                self._conditions.append(c)
+                self._cond_ids.add(c.id)
+        for m in ext.medications:
+            self.graph.add_medication(m, self.patient.id)
+            if m.id not in self._med_ids:
+                self._medications.append(m)
+                self._med_ids.add(m.id)
+        if ext.document_reference is not None:
+            self._absorb_docref(ext.document_reference)
+
+    def _absorb_docref(self, dref: DocumentReference) -> None:
+        """Зберегти free-text іпостась + додати текст у вузол-документ графа."""
+        if dref.provenance is not None:
+            self.graph.add_document(
+                dref.provenance.source_doc_id, dref.content.data or ""
+            )
+        if dref.id not in self._docref_ids:
+            self._doc_refs.append(dref)
+            self._docref_ids.add(dref.id)
+
+    # ── L1 + L2a на поточному стані сховищ ────────────────────────────────────
+    def current_signals(self) -> list[Signal]:
+        """Детерміновані сигнали над усім накопиченим станом."""
+        return l1_safety.run(self._medications) + l2a_trends.run(
+            self.factstore, self.patient.gender
+        )
+
+    def ingest(self, doc: Document) -> TraceReport:
+        """Прогнати один документ і повернути повний TRACE-звіт поточного стану."""
+        # Без мітки часу обзервації не потрапляють у факт-стор і зникають з
+        # таймлайну (і з перевірок безпеки). Проставляємо час прийому документа.
+        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)
+        self._absorb(ext)
+        signals = self.current_signals()
+        decision = l3_router.route(signals, ext.mean_confidence, doc.kind)
+        self._record_audit(doc, ext, signals, decision)
+        return TraceReport(
+            document_id=doc.id, extraction=ext, signals=signals, decision=decision
+        )
+
+    def ingest_all(self, docs: list[Document]) -> list[TraceReport]:
+        return [self.ingest(d) for d in docs]
+
+    # ── аудит рішень L3 ───────────────────────────────────────────────────────
+    def _record_audit(self, doc, ext, signals, decision) -> None:
+        self._audit.append(AuditEntry(
+            ts=datetime.now(timezone.utc),
+            document_id=doc.id,
+            kind=doc.kind,
+            extraction_confidence=ext.mean_confidence,
+            n_signals=len(signals),
+            route_to=decision.route_to,
+            escalate=decision.escalate,
+        ))
+
+    def audit_log(self) -> list[dict]:
+        """Журнал рішень L3 як JSON-сумісні dict (для API/метрик)."""
+        return [a.model_dump(mode="json") for a in self._audit]
+
+    # ── знімок / відновлення (персистентність, FHIR Bundle) ───────────────────
+    def snapshot(self) -> dict:
+        """Серіалізований стан картки (FHIR-ресурси + метадані)."""
+        return {
+            "patient": self.patient.model_dump(mode="json", by_alias=True),
+            "observations": [o.model_dump(mode="json") for o in self._observations],
+            "conditions": [c.model_dump(mode="json") for c in self._conditions],
+            "medications": [m.model_dump(mode="json") for m in self._medications],
+            "document_references": [
+                d.model_dump(mode="json") for d in self._doc_refs
+            ],
+            "documents": sorted(self._document_ids),
+            "audit": [a.model_dump(mode="json") for a in self._audit],
+        }
+
+    @classmethod
+    def from_snapshot(
+        cls, data: dict, extractor: Optional[Extractor] = None
+    ) -> "LiveMedCard":
+        """Відновити картку зі знімка (`snapshot`)."""
+        card = cls(Patient(**data["patient"]), extractor)
+        card._absorb(ExtractionResult(
+            observations=[Observation(**o) for o in data.get("observations", [])],
+            conditions=[Condition(**c) for c in data.get("conditions", [])],
+            medications=[MedicationRequest(**m) for m in data.get("medications", [])],
+        ))
+        for d in data.get("document_references", []):
+            card._absorb_docref(DocumentReference(**d))
+        card._document_ids.update(data.get("documents", []))
+        # Валідація журналу при відновленні: биті записи → явна помилка, не сміття.
+        card._audit.extend(AuditEntry(**a) for a in data.get("audit", []))
+        return card
+
+    # ── зручні акселератори для API/Q&A ───────────────────────────────────────
+    @property
+    def observations(self) -> list[Observation]:
+        return list(self._observations)
+
+    @property
+    def conditions(self) -> list[Condition]:
+        return list(self._conditions)
+
+    @property
+    def medications(self) -> list[MedicationRequest]:
+        return list(self._medications)
+
+    @property
+    def document_references(self) -> list[DocumentReference]:
+        return list(self._doc_refs)
+
+    @property
+    def document_count(self) -> int:
+        return len(self._document_ids)

livemedcard/qa.py

@@ -0,0 +1,245 @@
+"""Grounded Q&A: детермінований ретрив по FactStore + графу з посиланням на джерела.
+
+LLM тут НЕ робить висновків про безпеку — відповіді будуються з фактів і провенансу.
+Інтерфейс лишає місце під майбутню генеративну модель (L2b) для формулювання,
+але фактаж і посилання завжди детерміновані.
+"""
+from __future__ import annotations
+
+import re
+from typing import Optional
+
+from pydantic import BaseModel, Field
+
+from .dto import Signal
+from .lang import Lang, detect_lang
+from .reference import range_for
+from .stores import FactStore, KnowledgeGraph
+
+# Ключові слова питання → LOINC показника. Кожен термін мапиться на СВІЙ аналіт:
+# «глікований»/«hba1c» → HbA1c; «гемоглобін» → звичайний Hb; «цукор»/«глюкоза» →
+# глюкоза. Порядок важливий: специфічні терміни («глікован») перед загальними
+# («гемоглобін»), бо перший збіг виграє.
+_KEYWORD_TO_LOINC: dict[str, str] = {
+    "нирк": "2160-0",
+    "креатинін": "2160-0",
+    "hba1c": "4548-4",
+    "глікован": "4548-4",
+    "діабет": "4548-4",
+    "гемоглобін": "718-7",
+    "цукор": "2345-7",
+    "глюкоз": "2345-7",
+    "калій": "2823-3",
+    "тиск": "8480-6",
+    "холестерин": "2093-3",
+    "алт": "1742-6",
+    # EN-аліаси (специфічні — раніше за загальні, щоб «glycated hemoglobin»
+    # не перехопився «hemoglobin»)
+    "glycated hemoglobin": "4548-4",
+    "a1c": "4548-4",
+    "diabetes": "4548-4",
+    "kidney": "2160-0",
+    "creatinine": "2160-0",
+    "hemoglobin": "718-7",
+    "glucose": "2345-7",
+    "sugar": "2345-7",
+    "potassium": "2823-3",
+    "blood pressure": "8480-6",
+    "pressure": "8480-6",
+    "cholesterol": "2093-3",
+    "alt": "1742-6",
+}
+
+_MED_KEYWORDS = (
+    "ліки", "препарат", "таблет", "взаємод", "приймає", "приймати",
+    "medication", "medicine", "drug", "pill", "interaction", "taking",
+)
+
+# Каталог фраз відповіді за мовою питання (автовибір через detect_lang).
+_MSG: dict[Lang, dict[str, str]] = {
+    "uk": {
+        "lab_none": "У картці немає вимірювань показника «{name}».",
+        "lab_latest": "{name}: останнє значення {v} {u} ({d}).",
+        "lab_trend": "Динаміка за {n} вимірювань: {a}→{b} ({d1}..{d2}), {dir}.",
+        "dir_up": "стабільно зростає",
+        "dir_down": "стабільно знижується",
+        "dir_flat": "змінюється нерівномірно",
+        "above": "Останнє значення ВИЩЕ норми ({lo}–{hi} {u}).",
+        "within": "Останнє значення в межах норми ({lo}–{hi} {u}).",
+        "below": "Останнє значення НИЖЧЕ норми ({lo}–{hi} {u}).",
+        "meds_list": "Призначені препарати: {list}.",
+        "meds_none": "У картці немає призначених препаратів.",
+        "interactions": "⚠ Виявлені взаємодії:",
+        "no_interactions": "Небезпечних взаємодій між препаратами не виявлено.",
+        "freetext_header": "За текстом виписок:",
+        "fallback": (
+            "Не вдалося зіставити питання з наявними даними. Спробуйте спитати "
+            "про показник (нирки/креатинін, HbA1c, калій, тиск) або про ліки та взаємодії."
+        ),
+    },
+    "en": {
+        "lab_none": "No measurements of «{name}» in the record.",
+        "lab_latest": "{name}: latest value {v} {u} ({d}).",
+        "lab_trend": "Trend over {n} measurements: {a}→{b} ({d1}..{d2}), {dir}.",
+        "dir_up": "steadily increasing",
+        "dir_down": "steadily decreasing",
+        "dir_flat": "changing unevenly",
+        "above": "Latest value is ABOVE the reference range ({lo}–{hi} {u}).",
+        "within": "Latest value is within the reference range ({lo}–{hi} {u}).",
+        "below": "Latest value is BELOW the reference range ({lo}–{hi} {u}).",
+        "meds_list": "Prescribed medications: {list}.",
+        "meds_none": "No prescribed medications in the record.",
+        "interactions": "⚠ Detected interactions:",
+        "no_interactions": "No dangerous drug interactions detected.",
+        "freetext_header": "Per document text:",
+        "fallback": (
+            "Could not match the question to available data. Try asking about a lab "
+            "value (kidney/creatinine, HbA1c, potassium, blood pressure) or about "
+            "medications and interactions."
+        ),
+    },
+}
+
+
+class Answer(BaseModel):
+    text: str
+    sources: list[str] = Field(default_factory=list)  # id документів-джерел
+
+
+class QA:
+    def __init__(
+        self,
+        factstore: FactStore,
+        graph: KnowledgeGraph,
+        signals: Optional[list[Signal]] = None,
+        sex: Optional[str] = None,
+    ) -> None:
+        self.factstore = factstore
+        self.graph = graph
+        self.signals = signals or []
+        self.sex = sex
+
+    def ask(self, question: str) -> Answer:
+        q = question.lower()
+        lang = detect_lang(question)  # мова відповіді = мова питання
+
+        # Наміри про ліки/взаємодії перевіряємо ПЕРШИМИ: інакше питання про ліки,
+        # що містить лабораторну підстроку (напр. «...при тиску»), помилково
+        # перехоплювалося б лабораторною гілкою.
+        if any(k in q for k in _MED_KEYWORDS):
+            return self._answer_medications(lang)
+
+        loinc = self._match_loinc(q)
+        if loinc is not None:
+            return self._answer_lab(loinc, lang)
+
+        # Fallback на free-text іпостась (Stage 1 summary у вузлах-документах):
+        # структурного збігу немає, але відповідь може бути в тексті виписки.
+        freetext = self._answer_freetext(q, lang)
+        if freetext is not None:
+            return freetext
+
+        return Answer(text=_MSG[lang]["fallback"])
+
+    # ── маршрутизація ─────────────────────────────────────────────────────────
+    def _match_loinc(self, q: str) -> Optional[str]:
+        for kw, loinc in _KEYWORD_TO_LOINC.items():
+            if kw in q:
+                return loinc
+        return None
+
+    def _answer_lab(self, loinc: str, lang: Lang) -> Answer:
+        m = _MSG[lang]
+        series = self.factstore.series(loinc)
+        ref = range_for(loinc, self.sex)
+        name = ref.keyword if ref else (series[0].keyword if series else loinc)
+        if not series:
+            return Answer(text=m["lab_none"].format(name=name))
+
+        latest = series[-1]
+        first = series[0]
+        unit = latest.unit or (ref.unit if ref else "")
+        parts = [m["lab_latest"].format(name=name, v=latest.value, u=unit, d=latest.ts.date())]
+        if len(series) >= 2:
+            # Напрям — за монотонністю всього ряду (узгоджено з L2a), а не лише
+            # за крайніми точками, щоб не називати «трендом» немонотонну динаміку.
+            vals = [f.value for f in series]
+            if all(a <= b for a, b in zip(vals, vals[1:])) and vals[-1] > vals[0]:
+                direction = m["dir_up"]
+            elif all(a >= b for a, b in zip(vals, vals[1:])) and vals[-1] < vals[0]:
+                direction = m["dir_down"]
+            else:
+                direction = m["dir_flat"]
+            parts.append(m["lab_trend"].format(
+                n=len(series), a=first.value, b=latest.value,
+                d1=first.ts.date(), d2=latest.ts.date(), dir=direction,
+            ))
+        if ref is not None:
+            key = "above" if latest.value > ref.high else "below" if latest.value < ref.low else "within"
+            parts.append(m[key].format(lo=ref.low, hi=ref.high, u=unit))
+
+        sources = _unique(f.source_doc_id for f in series if f.source_doc_id)
+        return Answer(text=" ".join(parts), sources=sources)
+
+    def _answer_freetext(self, q: str, lang: Lang) -> Optional[Answer]:
+        """Пошук у Stage 1 summary (free-text іпостась) за токенами питання.
+
+        Повертає рядки summary, що містять значущі слова питання, з посиланням на
+        документ-джерело. None, якщо збігів немає (тоді — загальний fallback).
+        """
+        tokens = [w for w in re.findall(r"\w+", q.lower()) if len(w) >= 4]
+        if not tokens:
+            return None
+        hits: list[str] = []
+        sources: list[str] = []
+        for nid in self.graph.nodes_of_type("Document"):
+            text = self.graph.g.nodes[nid].get("text") or ""
+            doc_id = nid.split("/", 1)[-1]
+            for line in text.splitlines():
+                stripped = line.strip()
+                if not stripped or stripped.startswith("##") or stripped == "not stated":
+                    continue
+                low = stripped.lower()
+                if any(t in low for t in tokens):
+                    hits.append(stripped)
+                    sources.append(doc_id)
+                    if len(hits) >= 5:  # не заливати відповідь
+                        break
+            if len(hits) >= 5:
+                break
+        if not hits:
+            return None
+        text = _MSG[lang]["freetext_header"] + "\n" + "\n".join(f"— {h}" for h in hits)
+        return Answer(text=text, sources=_unique(sources))
+
+    def _answer_medications(self, lang: Lang) -> Answer:
+        m = _MSG[lang]
+        med_nodes = self.graph.nodes_of_type("MedicationRequest")
+        names = [self.graph.g.nodes[n].get("label", n) for n in med_nodes]
+        parts = []
+        if names:
+            parts.append(m["meds_list"].format(list=", ".join(sorted(set(names)))))
+        else:
+            parts.append(m["meds_none"])
+
+        interactions = [s for s in self.signals if s.kind == "interaction"]
+        if interactions:
+            parts.append(m["interactions"])
+            parts.extend(f"— {s.detail} ({s.severity})" for s in interactions)
+        else:
+            parts.append(m["no_interactions"])
+
+        sources = _unique(
+            self.graph.provenance_of(n)[0].split("/", 1)[-1]
+            for n in med_nodes
+            if self.graph.provenance_of(n)
+        )
+        return Answer(text="\n".join(parts), sources=sources)
+
+
+def _unique(items) -> list[str]:
+    seen: dict[str, None] = {}
+    for it in items:
+        if it:
+            seen.setdefault(it, None)
+    return list(seen)

livemedcard/reference.py

@@ -0,0 +1,78 @@
+"""Завантаження відкритих довідкових БД (детерміноване джерело для L1/L2a/L2b).
+
+Усі коди узгоджені між файлами: RxNorm (ліки), LOINC (аналізи), SNOMED (діагнози).
+
+Loader-и кешуються (`lru_cache`) і повертають **незмінні** структури: заморожені
+Pydantic-моделі (`refmodels.FrozenModel`) у tuple/MappingProxyType. Це водночас
+прибирає перебудову об'єктів на кожен виклик і унеможливлює псування спільного
+довідника випадковою мутацією (раніше від цього захищали свіжі копії).
+"""
+from __future__ import annotations
+
+import json
+from collections.abc import Mapping
+from functools import lru_cache
+from types import MappingProxyType
+from typing import Any, Optional
+
+from .config import DATA_DIR
+from .refmodels import (
+    CondTerm,
+    DoseLimit,
+    Interaction,
+    LabTerm,
+    MedTerm,
+    RangeSpec,
+    RefRange,
+    Vocab,
+)
+
+
+@lru_cache(maxsize=None)
+def _raw(name: str) -> Any:
+    return json.loads((DATA_DIR / name).read_text(encoding="utf-8"))
+
+
+@lru_cache(maxsize=None)
+def load_interactions() -> tuple[Interaction, ...]:
+    """Пари RxNorm-кодів із тяжкістю взаємодії."""
+    return tuple(Interaction(**p) for p in _raw("interactions.json")["pairs"])
+
+
+@lru_cache(maxsize=None)
+def load_dose_limits() -> Mapping[str, DoseLimit]:
+    """RxNorm → DoseLimit."""
+    return MappingProxyType(
+        {d["rxnorm"]: DoseLimit(**d) for d in _raw("dose_limits.json")["limits"]}
+    )
+
+
+@lru_cache(maxsize=None)
+def load_range_specs() -> Mapping[str, RangeSpec]:
+    """LOINC → RangeSpec (з опціональними варіантами за статтю)."""
+    return MappingProxyType({
+        loinc: RangeSpec(**spec)
+        for loinc, spec in _raw("reference_ranges.json")["ranges"].items()
+    })
+
+
+def range_for(loinc: str, sex: Optional[str] = None) -> Optional[RefRange]:
+    """Референсні межі показника, розвʼязані під стать пацієнта (або None)."""
+    spec = load_range_specs().get(loinc)
+    return spec.resolve(sex) if spec is not None else None
+
+
+@lru_cache(maxsize=None)
+def load_vocab() -> Vocab:
+    """Словник для StubExtractor: labs / medications / conditions."""
+    raw = _raw("vocab.json")
+    return Vocab(
+        labs={k: LabTerm(**v) for k, v in raw.get("labs", {}).items()},
+        medications={k: MedTerm(**v) for k, v in raw.get("medications", {}).items()},
+        conditions={k: CondTerm(**v) for k, v in raw.get("conditions", {}).items()},
+    )
+
+
+def load_sample_docs() -> list[dict]:
+    """Демо-документи (український текст) для E2E. Щоразу свіжа копія."""
+    return json.loads(json.dumps(_raw("sample_docs.json")["documents"]))

livemedcard/refmodels.py

@@ -0,0 +1,91 @@
+"""Типізовані моделі довідкових даних (замість «сирих» dict).
+
+Дає валідацію при завантаженні, автодоповнення й чіткий контракт для L1/L2a/L2b.
+
+Усі моделі **заморожені** (frozen): loader-и в `reference.py` кешують екземпляри,
+тож незмінність — гарантія, що жоден викликач не зіпсує спільний довідник.
+"""
+from __future__ import annotations
+
+from typing import Optional
+
+from pydantic import BaseModel, ConfigDict
+
+from .dto import Severity
+
+
+class FrozenModel(BaseModel):
+    """База довідкових моделей: незмінні після створення (безпечно кешувати)."""
+
+    model_config = ConfigDict(frozen=True)
+
+
+class Interaction(FrozenModel):
+    a: str  # RxNorm
+    b: str  # RxNorm
+    severity: Severity
+    detail: str
+
+    def pair(self) -> frozenset[str]:
+        return frozenset((self.a, self.b))
+
+
+class DoseLimit(FrozenModel):
+    rxnorm: str
+    name: str
+    max_daily: float
+    unit: str
+
+
+class Bounds(FrozenModel):
+    low: float
+    high: float
+
+
+class RangeSpec(FrozenModel):
+    """Референсні межі показника з опціональними варіантами за статтю."""
+
+    keyword: str
+    unit: str
+    default: Bounds
+    by_sex: dict[str, Bounds] = {}
+
+    def resolve(self, sex: Optional[str]) -> "RefRange":
+        bounds = self.by_sex.get(sex or "", self.default)
+        return RefRange(
+            keyword=self.keyword, unit=self.unit,
+            low=bounds.low, high=bounds.high,
+            sex=sex if (sex and sex in self.by_sex) else None,
+        )
+
+
+class RefRange(FrozenModel):
+    """Розвʼязані межі для конкретного пацієнта (стать враховано)."""
+
+    keyword: str
+    unit: str
+    low: float
+    high: float
+    sex: Optional[str] = None
+
+
+class LabTerm(FrozenModel):
+    loinc: str
+    unit: str
+    display: str
+
+
+class MedTerm(FrozenModel):
+    rxnorm: str
+    display: str
+
+
+class CondTerm(FrozenModel):
+    snomed: str
+    display: str
+
+
+class Vocab(FrozenModel):
+    labs: dict[str, LabTerm] = {}
+    medications: dict[str, MedTerm] = {}
+    conditions: dict[str, CondTerm] = {}

livemedcard/repository.py

@@ -0,0 +1,37 @@
+"""Персистентність картки у локальний JSON-файл (local-first).
+
+Дані не залишають пристрій — це умова довіри для медичних даних. Формат — знімок
+(`LiveMedCard.snapshot`), тож зберігання й відновлення симетричні.
+"""
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from typing import Optional
+
+from .layers.l2b_extractor import Extractor
+from .pipeline import LiveMedCard
+
+
+def save_card(card: LiveMedCard, path: str) -> None:
+    p = Path(path)
+    p.parent.mkdir(parents=True, exist_ok=True)
+    p.write_text(
+        json.dumps(card.snapshot(), ensure_ascii=False, indent=2), encoding="utf-8"
+    )
+
+
+def load_card(path: str, extractor: Optional[Extractor] = None) -> Optional[LiveMedCard]:
+    """Відновити картку зі знімка; None, якщо файлу ще немає.
+
+    Пошкоджений файл — ЯВНА помилка, а не «стартуємо порожнім»: інакше наступне
+    автозбереження перезаписало б знімок порожнім станом (втрата медичних даних).
+    """
+    p = Path(path)
+    if not p.exists():
+        return None
+    try:
+        data = json.loads(p.read_text(encoding="utf-8"))
+    except json.JSONDecodeError as exc:
+        raise ValueError(f"Пошкоджений файл знімка картки: {path} ({exc})") from exc
+    return LiveMedCard.from_snapshot(data, extractor)

livemedcard/static/index.html

@@ -0,0 +1,526 @@
+<!doctype html>
+<html lang="uk">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<title>LiveMedCard — жива медична картка</title>
+<style>
+  :root{
+    /* dark clinical (default) */
+    --bg:#080d12; --bg-grad:radial-gradient(1200px 600px at 78% -8%, rgba(45,212,191,.10), transparent 60%),
+                             radial-gradient(900px 500px at 10% 0%, rgba(56,140,255,.07), transparent 55%);
+    --panel:#101923; --panel-2:#0d151d; --panel-hi:#16232f;
+    --ink:#e9f1f5; --muted:#8ba1ae; --faint:#5f7583; --line:#1d2b37;
+    --accent:#2dd4bf; --accent-ink:#062b26; --accent-soft:#0f2622;
+    --critical:#ff6b6b; --major:#ff7d6b; --moderate:#f0b429; --ok:#34d399; --info:#8ba1ae;
+    --band:rgba(45,212,191,.10);
+    --shadow:0 1px 0 rgba(255,255,255,.02) inset, 0 10px 30px rgba(0,0,0,.45);
+    --glow:0 0 0 1px rgba(45,212,191,.25), 0 8px 30px rgba(45,212,191,.12);
+    --mono:ui-monospace,"SF Mono","JetBrains Mono",Menlo,monospace;
+    --sans:system-ui,-apple-system,"Segoe UI",Roboto,Ubuntu,sans-serif;
+  }
+  @media (prefers-color-scheme:light){
+    :root{
+      --bg:#eef3f6; --bg-grad:radial-gradient(1100px 560px at 80% -10%, rgba(13,148,136,.10), transparent 60%),
+                               radial-gradient(800px 460px at 8% 0%, rgba(37,99,235,.06), transparent 55%);
+      --panel:#ffffff; --panel-2:#f5f8fa; --panel-hi:#eef3f6;
+      --ink:#0d1b24; --muted:#4f6774; --faint:#7d94a1; --line:#dde6ec;
+      --accent:#0d9488; --accent-ink:#ffffff; --accent-soft:#e2f2ef;
+      --critical:#dc2626; --major:#e0483c; --moderate:#b45309; --ok:#0f9d58; --info:#4f6774;
+      --band:rgba(13,148,136,.12);
+      --shadow:0 1px 2px rgba(13,27,36,.05), 0 10px 26px rgba(13,27,36,.07);
+      --glow:0 0 0 1px rgba(13,148,136,.25), 0 8px 26px rgba(13,148,136,.12);
+    }
+  }
+  :root[data-theme="light"]{
+    --bg:#eef3f6; --bg-grad:radial-gradient(1100px 560px at 80% -10%, rgba(13,148,136,.10), transparent 60%),
+                             radial-gradient(800px 460px at 8% 0%, rgba(37,99,235,.06), transparent 55%);
+    --panel:#ffffff; --panel-2:#f5f8fa; --panel-hi:#eef3f6;
+    --ink:#0d1b24; --muted:#4f6774; --faint:#7d94a1; --line:#dde6ec;
+    --accent:#0d9488; --accent-ink:#ffffff; --accent-soft:#e2f2ef;
+    --critical:#dc2626; --major:#e0483c; --moderate:#b45309; --ok:#0f9d58; --info:#4f6774;
+    --band:rgba(13,148,136,.12);
+    --shadow:0 1px 2px rgba(13,27,36,.05), 0 10px 26px rgba(13,27,36,.07);
+    --glow:0 0 0 1px rgba(13,148,136,.25), 0 8px 26px rgba(13,148,136,.12);
+  }
+  :root[data-theme="dark"]{
+    --bg:#080d12; --panel:#101923; --panel-2:#0d151d; --panel-hi:#16232f;
+    --ink:#e9f1f5; --muted:#8ba1ae; --faint:#5f7583; --line:#1d2b37;
+    --accent:#2dd4bf; --accent-ink:#062b26; --accent-soft:#0f2622;
+    --critical:#ff6b6b; --major:#ff7d6b; --moderate:#f0b429; --ok:#34d399; --info:#8ba1ae;
+    --band:rgba(45,212,191,.10);
+    --shadow:0 1px 0 rgba(255,255,255,.02) inset, 0 10px 30px rgba(0,0,0,.45);
+    --glow:0 0 0 1px rgba(45,212,191,.25), 0 8px 30px rgba(45,212,191,.12);
+  }
+
+  *{box-sizing:border-box}
+  html{-webkit-text-size-adjust:100%}
+  body{margin:0;color:var(--ink);font:15px/1.55 var(--sans);
+    background:var(--bg-grad),var(--bg);background-attachment:fixed;min-height:100vh;
+    -webkit-font-smoothing:antialiased;}
+  a{color:var(--accent);text-underline-offset:2px}
+  .wrap{max-width:1160px;margin:0 auto;padding:26px 20px 72px}
+
+  /* ── header ─────────────────────────────────────────── */
+  header.top{display:flex;flex-wrap:wrap;align-items:center;gap:14px;margin-bottom:4px}
+  .brand{display:flex;align-items:center;gap:12px}
+  .logo{width:40px;height:40px;border-radius:11px;display:grid;place-items:center;flex:0 0 auto;
+    background:linear-gradient(150deg,var(--accent),color-mix(in srgb,var(--accent) 55%, #2563eb));
+    box-shadow:var(--glow)}
+  .logo svg{width:24px;height:24px;color:var(--accent-ink)}
+  .brand h1{font-size:23px;margin:0;letter-spacing:-.02em;font-weight:750}
+  .brand .sub{display:block;color:var(--muted);font-size:12.5px;margin-top:-1px;letter-spacing:.01em}
+  .top .spacer{flex:1}
+  .patient{font:12.5px/1.3 var(--mono);color:var(--muted);text-align:right;
+    background:var(--panel);border:1px solid var(--line);border-radius:10px;padding:7px 11px}
+  .patient b{color:var(--ink)}
+  .theme-btn{width:38px;height:38px;border-radius:10px;border:1px solid var(--line);background:var(--panel);
+    color:var(--muted);cursor:pointer;display:grid;place-items:center;transition:.15s}
+  .theme-btn:hover{color:var(--accent);border-color:var(--accent)}
+
+  /* pulse line */
+  .pulse{height:34px;margin:12px 0 2px;overflow:hidden;opacity:.9}
+  .pulse svg{width:100%;height:100%}
+  .pulse .lead{stroke:var(--accent);stroke-width:2;fill:none;
+    stroke-dasharray:1400;stroke-dashoffset:1400;animation:trace 4.5s linear infinite}
+  .pulse .ghost{stroke:var(--line);stroke-width:2;fill:none}
+  @keyframes trace{to{stroke-dashoffset:0}}
+
+  /* ── stat strip ─────────────────────────────────────── */
+  .stats{display:flex;flex-wrap:wrap;gap:10px;margin:14px 0 18px}
+  .stat{flex:1 1 130px;background:var(--panel);border:1px solid var(--line);border-radius:13px;
+    padding:13px 15px;box-shadow:var(--shadow);position:relative;overflow:hidden}
+  .stat .n{font:700 26px/1 var(--mono);letter-spacing:-.02em;font-variant-numeric:tabular-nums}
+  .stat .l{font-size:12px;color:var(--muted);margin-top:5px}
+  .stat.bi .n{color:var(--accent)}
+  .stat.alert .n{color:var(--major)}
+
+  /* ── toolbar ────────────────────────────────────────── */
+  .toolbar{display:flex;flex-wrap:wrap;gap:9px;margin:0 0 20px}
+  button{font:inherit;cursor:pointer;border:1px solid var(--line);background:var(--panel);
+    color:var(--ink);border-radius:10px;padding:9px 15px;transition:.14s;font-weight:550}
+  button:hover{border-color:var(--accent);transform:translateY(-1px)}
+  button:active{transform:translateY(0)}
+  button.primary{background:linear-gradient(150deg,var(--accent),color-mix(in srgb,var(--accent) 62%, #2563eb));
+    border-color:transparent;color:var(--accent-ink);font-weight:650;box-shadow:var(--glow)}
+  button.primary:hover{filter:brightness(1.05)}
+  button.ghost{background:transparent}
+  button:disabled{opacity:.55;cursor:default;transform:none}
+
+  /* ── layout ─────────────────────────────────────────── */
+  .grid{display:grid;grid-template-columns:1fr;gap:18px}
+  @media(min-width:900px){.grid{grid-template-columns:1.18fr .82fr}}
+  .panel{background:var(--panel);border:1px solid var(--line);border-radius:16px;padding:18px;
+    box-shadow:var(--shadow);animation:rise .5s cubic-bezier(.2,.7,.2,1) both}
+  .panel.d1{animation-delay:.05s} .panel.d2{animation-delay:.12s} .panel.d3{animation-delay:.19s}
+  @keyframes rise{from{opacity:0;transform:translateY(14px)}to{opacity:1;transform:none}}
+  .panel h2{font:600 11.5px/1 var(--sans);text-transform:uppercase;letter-spacing:.09em;color:var(--faint);
+    margin:0 0 15px;display:flex;align-items:center;gap:8px}
+  .panel h2 .tag{margin-left:auto;text-transform:none;letter-spacing:0;font-weight:600;font-size:11px;
+    color:var(--accent);background:var(--accent-soft);border-radius:999px;padding:3px 9px}
+  .right{display:grid;gap:18px}
+
+  /* ── metrics / timeline ─────────────────────────────── */
+  .series{display:grid;gap:13px}
+  .metric{border:1px solid var(--line);border-radius:13px;padding:14px 14px 10px;background:var(--panel-2);
+    transition:.16s;animation:rise .45s cubic-bezier(.2,.7,.2,1) both}
+  .metric:hover{border-color:color-mix(in srgb,var(--accent) 45%,var(--line));background:var(--panel-hi)}
+  .metric .row{display:flex;justify-content:space-between;align-items:flex-end;gap:10px}
+  .metric .name{font-weight:600;font-size:14.5px}
+  .metric .big{display:flex;align-items:baseline;gap:6px}
+  .metric .val{font:750 25px/1 var(--mono);letter-spacing:-.02em;font-variant-numeric:tabular-nums}
+  .metric .unit{font-size:12.5px;color:var(--muted);font-weight:600}
+  .metric .trend{font:700 12px/1 var(--mono);padding:2px 7px;border-radius:999px;white-space:nowrap}
+  .trend.up{color:var(--major);background:color-mix(in srgb,var(--major) 15%,transparent)}
+  .trend.down{color:var(--ok);background:color-mix(in srgb,var(--ok) 15%,transparent)}
+  .trend.flat{color:var(--muted);background:color-mix(in srgb,var(--muted) 14%,transparent)}
+  .metric .meta{display:flex;justify-content:space-between;align-items:baseline;gap:8px;margin-top:3px}
+  .metric .ref{color:var(--faint);font-size:11.5px;font-family:var(--mono)}
+  .status{font-size:11.5px;font-weight:700}
+  .status.ok{color:var(--ok)} .status.high{color:var(--major)} .status.low{color:var(--moderate)}
+  .metric .src{color:var(--faint);font-size:11px;margin-top:7px;display:flex;gap:6px;flex-wrap:wrap;align-items:center}
+  .lang{font:700 10px/1 var(--mono);padding:2px 5px;border-radius:5px;border:1px solid var(--line)}
+  .lang.ua{color:var(--accent)} .lang.en{color:#5e9dff}
+  .spark{margin-top:9px}
+  .spark path.line{stroke:var(--accent);stroke-width:2.2;fill:none;stroke-linejoin:round;stroke-linecap:round;
+    stroke-dasharray:var(--len);stroke-dashoffset:var(--len);animation:draw 1.1s .1s ease-out forwards}
+  @keyframes draw{to{stroke-dashoffset:0}}
+
+  /* ── safety ─────────────────────────────────────────── */
+  .decision{display:flex;align-items:center;gap:10px;margin-bottom:14px;padding:11px 13px;
+    border-radius:12px;border:1px solid var(--line);flex-wrap:wrap}
+  .decision.escalate{background:color-mix(in srgb,var(--major) 12%,transparent);
+    border-color:color-mix(in srgb,var(--major) 45%,var(--line))}
+  .decision.auto{background:color-mix(in srgb,var(--ok) 12%,transparent);
+    border-color:color-mix(in srgb,var(--ok) 40%,var(--line))}
+  .badge{display:inline-flex;align-items:center;gap:6px;padding:4px 11px;border-radius:999px;
+    font-size:12px;font-weight:700;color:#fff}
+  .decision .t{font:600 12.5px/1 var(--mono);color:var(--muted);margin-left:auto}
+  .reasons{margin:8px 0 0;padding-left:18px;color:var(--muted);font-size:12.5px;flex-basis:100%}
+  .sig{display:flex;gap:11px;padding:12px 0;border-top:1px solid var(--line)}
+  .sig:first-of-type{border-top:none;padding-top:2px}
+  .sig .dot{flex:0 0 auto;width:11px;height:11px;border-radius:50%;margin-top:4px;position:relative}
+  .sig.hot .dot::after{content:"";position:absolute;inset:-4px;border-radius:50%;
+    border:2px solid currentColor;opacity:.5;animation:ping 1.8s cubic-bezier(0,0,.2,1) infinite}
+  @keyframes ping{0%{transform:scale(.9);opacity:.6}70%,100%{transform:scale(2.1);opacity:0}}
+  .sig .k{font:600 10.5px/1.3 var(--mono);color:var(--faint);text-transform:uppercase;letter-spacing:.05em}
+  .sig .d{font-size:13.5px;margin-top:3px;display:block}
+
+  .meds{display:flex;flex-wrap:wrap;gap:8px}
+  .pill{background:var(--panel-2);border:1px solid var(--line);color:var(--ink);border-radius:999px;
+    padding:6px 13px;font-size:13px;font-weight:600;display:inline-flex;align-items:center;gap:7px}
+  .pill.flag{border-color:color-mix(in srgb,var(--major) 55%,var(--line));
+    color:var(--major);background:color-mix(in srgb,var(--major) 10%,transparent)}
+  .pill .warn{font-size:11px}
+  .empty{color:var(--muted);font-size:13px;padding:8px 0}
+
+  /* ── Q&A ────────────────────────────────────────────── */
+  .qa .log{display:grid;gap:10px;margin-bottom:14px;max-height:320px;overflow:auto;padding-right:4px}
+  .bubble{padding:11px 14px;border-radius:14px;max-width:90%;white-space:pre-wrap;
+    animation:pop .28s cubic-bezier(.2,.7,.2,1) both;font-size:14px}
+  @keyframes pop{from{opacity:0;transform:translateY(6px) scale(.98)}to{opacity:1;transform:none}}
+  .bubble.q{justify-self:end;background:linear-gradient(150deg,var(--accent),color-mix(in srgb,var(--accent) 62%, #2563eb));
+    color:var(--accent-ink);border-bottom-right-radius:5px;font-weight:550}
+  .bubble.a{justify-self:start;background:var(--panel-2);border:1px solid var(--line);border-bottom-left-radius:5px}
+  .bubble .src{display:block;margin-top:7px;font:11px/1.4 var(--mono);color:var(--faint)}
+  .askrow{display:flex;gap:9px}
+  .askrow input{flex:1;font:inherit;padding:11px 14px;border-radius:11px;border:1px solid var(--line);
+    background:var(--panel-2);color:var(--ink)}
+  .askrow input:focus{outline:none;border-color:var(--accent);box-shadow:var(--glow)}
+  .chips{display:flex;flex-wrap:wrap;gap:7px;margin-top:10px}
+  .chip{font-size:12.5px;color:var(--muted);background:var(--panel-2);border:1px solid var(--line);
+    border-radius:999px;padding:5px 12px;cursor:pointer;transition:.14s}
+  .chip:hover{color:var(--accent);border-color:var(--accent)}
+
+  /* add doc */
+  .add{margin:14px 0 0;display:none;gap:9px;grid-template-columns:1fr;background:var(--panel-2);
+    border:1px dashed var(--line);border-radius:13px;padding:14px}
+  .add.show{display:grid;animation:rise .3s ease both}
+  .add textarea{font:inherit;min-height:78px;border-radius:10px;border:1px solid var(--line);
+    padding:10px;background:var(--panel);color:var(--ink);resize:vertical}
+  .add textarea:focus,.add select:focus{outline:none;border-color:var(--accent)}
+  .add select{font:inherit;padding:9px;border-radius:10px;border:1px solid var(--line);
+    background:var(--panel);color:var(--ink)}
+  .or{margin:2px 0;font:600 11px/1 var(--mono);color:var(--faint);text-transform:uppercase;
+    letter-spacing:.06em;text-align:center}
+  .dropzone{display:flex;flex-direction:column;align-items:center;justify-content:center;padding:16px;
+    border:2px dashed var(--line);border-radius:11px;background:var(--panel);cursor:pointer;transition:.15s;
+    text-align:center;font-size:13px;color:var(--muted)}
+  .dropzone:hover,.dropzone.dragover{border-color:var(--accent);background:var(--accent-soft);color:var(--ink)}
+
+  footer{color:var(--faint);font-size:12px;margin-top:30px;text-align:center;line-height:1.6}
+  footer b{color:var(--muted)}
+  .toast{position:fixed;left:50%;bottom:26px;transform:translateX(-50%) translateY(8px);
+    background:var(--ink);color:var(--bg);padding:11px 18px;border-radius:11px;font-weight:600;font-size:13.5px;
+    box-shadow:0 10px 30px rgba(0,0,0,.35);opacity:0;transition:.28s;pointer-events:none;z-index:50}
+  .toast.show{opacity:1;transform:translateX(-50%) translateY(0)}
+
+  @media (prefers-reduced-motion:reduce){
+    *,*::before,*::after{animation-duration:.001s!important;animation-iteration-count:1!important;
+      transition-duration:.001s!important}
+    .spark path.line{stroke-dashoffset:0}
+  }
+</style>
+</head>
+<body>
+<div class="wrap">
+  <header class="top">
+    <div class="brand">
+      <div class="logo" aria-hidden="true">
+        <svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2.2" stroke-linecap="round" stroke-linejoin="round">
+          <path d="M3 12h3l2-5 4 10 2-5h5"/>
+        </svg>
+      </div>
+      <div>
+        <h1>LiveMedCard</h1>
+        <span class="sub">жива медична картка · архітектура TRACE</span>
+      </div>
+    </div>
+    <div class="spacer"></div>
+    <div class="patient" id="patient">картка не завантажена</div>
+    <button class="theme-btn" id="theme" title="Тема" aria-label="Перемкнути тему">
+      <svg width="18" height="18" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><circle cx="12" cy="12" r="4.5"/><path d="M12 2v2M12 20v2M4 12H2M22 12h-2M5 5l1.5 1.5M17.5 17.5L19 19M19 5l-1.5 1.5M6.5 17.5L5 19"/></svg>
+    </button>
+  </header>
+
+  <div class="pulse" aria-hidden="true">
+    <svg viewBox="0 0 1400 34" preserveAspectRatio="none">
+      <path class="ghost" d="M0,17 H520 l14,-13 l12,26 l16,-30 l14,17 H760 l16,-9 l10,9 H1400"/>
+      <path class="lead"  d="M0,17 H520 l14,-13 l12,26 l16,-30 l14,17 H760 l16,-9 l10,9 H1400"/>
+    </svg>
+  </div>
+
+  <div class="stats" id="stats"></div>
+
+  <div class="toolbar">
+    <button class="primary" id="btn-samples">Завантажити демо-картку</button>
+    <button class="ghost" id="btn-add">+ Додати документ</button>
+    <button class="ghost" id="btn-export">Експорт FHIR</button>
+    <button class="ghost" id="btn-reset">Скинути</button>
+  </div>
+
+  <div class="add" id="add-form">
+    <textarea id="add-text" placeholder="Вставте текст документа, напр.: «Креатинін 121 µmol/L. Призначено: аспірин 100 мг на добу.»"></textarea>
+    <div class="or">— або завантажте фото (OCR) —</div>
+    <label class="dropzone" id="dropzone">
+      <svg width="20" height="20" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" style="margin-bottom:5px;color:var(--accent)"><path d="M21 15v4a2 2 0 0 1-2 2H5a2 2 0 0 1-2-2v-4"/><polyline points="17 8 12 3 7 8"/><line x1="12" y1="3" x2="12" y2="15"/></svg>
+      <span id="dropzone-text">Перетягніть фото сюди або натисніть для вибору</span>
+      <input type="file" id="add-image" accept="image/*" style="display:none">
+    </label>
+    <div style="display:flex;gap:9px;flex-wrap:wrap">
+      <select id="add-kind">
+        <option value="discharge_summary">Виписний епікриз</option>
+        <option value="lab_report">Лабораторний звіт</option>
+        <option value="prescription">Рецепт</option>
+        <option value="note">Нотатка</option>
+      </select>
+      <button class="primary" id="add-submit">Обробити документ</button>
+    </div>
+  </div>
+
+  <div class="grid" style="margin-top:18px">
+    <section class="panel d1">
+      <h2>Таймлайн показників <span class="tag" id="bi-tag" style="display:none">білінгвально · UA + EN</span></h2>
+      <div class="series" id="series"><div class="empty">Даних ще немає. Натисніть «Завантажити демо-картку».</div></div>
+    </section>
+
+    <div class="right">
+      <section class="panel d2">
+        <h2>Безпека — шар TRACE</h2>
+        <div id="decision"></div>
+        <div id="signals"><div class="empty">Сигналів немає.</div></div>
+      </section>
+      <section class="panel d3">
+        <h2>Призначені ліки</h2>
+        <div class="meds" id="meds"><div class="empty">Ліків немає.</div></div>
+      </section>
+    </div>
+  </div>
+
+  <section class="panel qa" style="margin-top:18px">
+    <h2>Запитати картку <span class="tag">grounded · з посиланням на джерело</span></h2>
+    <div class="log" id="log"></div>
+    <div class="askrow">
+      <input id="q" placeholder="Напр.: Що з нирками за останній рік?" autocomplete="off">
+      <button class="primary" id="ask">Спитати</button>
+    </div>
+    <div class="chips" id="chips"></div>
+  </section>
+
+  <footer>Прототип для <b>Digital Future Hackathon</b> · ніша Aging &amp; Longevity.<br>
+    Система структурує факти й показує динаміку — <b>не ставить діагнозів і не призначає лікування</b>.</footer>
+</div>
+<div class="toast" id="toast"></div>
+
+<script>
+const $ = s => document.querySelector(s);
+const SEV = {critical:'var(--critical)',major:'var(--major)',moderate:'var(--moderate)',info:'var(--info)'};
+const SEV_UK = {critical:'критичний',major:'високий',moderate:'помірний',info:'інфо'};
+
+/* theme toggle (respects OS by default; stamps data-theme on click) */
+(function(){
+  const root=document.documentElement;
+  $('#theme').onclick=()=>{
+    const cur=root.getAttribute('data-theme')
+      || (matchMedia('(prefers-color-scheme:dark)').matches?'dark':'light');
+    root.setAttribute('data-theme', cur==='dark'?'light':'dark');
+  };
+})();
+
+function toast(msg){const t=$('#toast');t.textContent=msg;t.classList.add('show');
+  clearTimeout(t._t);t._t=setTimeout(()=>t.classList.remove('show'),2600);}
+
+async function api(path, opts){
+  const r=await fetch(path,opts);
+  if(!r.ok){
+    let msg=path+' '+r.status;
+    try{const err=await r.json(); if(err&&err.detail) msg=err.detail;}catch(e){}
+    throw new Error(msg);
+  }
+  return r.status===204?null:r.json();
+}
+
+function langOf(src){ return src && /(-|_)en\b|_en$|-en$/.test(src) ? 'en' : 'ua'; }
+
+function sparkline(points, low, high){
+  const w=300,h=64,pad=9;
+  const vals=points.map(p=>p.value);
+  let min=Math.min(...vals), max=Math.max(...vals);
+  if(low!=null)min=Math.min(min,low); if(high!=null)max=Math.max(max,high);
+  if(min===max){min-=1;max+=1;}
+  const X=i=>points.length===1?w/2:pad+i*(w-2*pad)/(points.length-1);
+  const Y=v=>h-pad-(v-min)/(max-min)*(h-2*pad);
+  let band='';
+  if(low!=null&&high!=null){const y1=Y(high),y2=Y(low);
+    band=`<rect x="0" y="${y1.toFixed(1)}" width="${w}" height="${Math.max(0,y2-y1).toFixed(1)}" fill="var(--band)"/>`;}
+  const dLine=points.map((p,i)=>`${i?'L':'M'}${X(i).toFixed(1)},${Y(p.value).toFixed(1)}`).join(' ');
+  const area=`${dLine} L${X(points.length-1).toFixed(1)},${h} L${X(0).toFixed(1)},${h} Z`;
+  const last=points[points.length-1];
+  const breach=(low!=null&&last.value<low)||(high!=null&&last.value>high);
+  const dots=points.map((p,i)=>{const isLast=i===points.length-1;
+    return `<circle cx="${X(i).toFixed(1)}" cy="${Y(p.value).toFixed(1)}" r="${isLast?4:2.3}"
+      fill="${isLast&&breach?'var(--major)':'var(--accent)'}"
+      ${isLast?'stroke="var(--panel-2)" stroke-width="2"':''}/>`;}).join('');
+  const gid='g'+Math.random().toString(36).slice(2,7);
+  // approx path length for draw animation
+  let len=0; for(let i=1;i<points.length;i++){const dx=X(i)-X(i-1),dy=Y(points[i].value)-Y(points[i-1].value);len+=Math.hypot(dx,dy);}
+  return `<svg class="spark" viewBox="0 0 ${w} ${h}" width="100%" height="${h}" preserveAspectRatio="none" style="display:block">
+    <defs><linearGradient id="${gid}" x1="0" y1="0" x2="0" y2="1">
+      <stop offset="0" stop-color="var(--accent)" stop-opacity=".22"/>
+      <stop offset="1" stop-color="var(--accent)" stop-opacity="0"/></linearGradient></defs>
+    ${band}<path d="${area}" fill="url(#${gid})"/>
+    <path class="line" style="--len:${len.toFixed(0)}" d="${dLine}"/>${dots}</svg>`;
+}
+
+function statusOf(s){
+  const v=s.points.at(-1).value;
+  if(s.high!=null && v>s.high) return ['вище норми','high'];
+  if(s.low!=null && v<s.low) return ['нижче норми','low'];
+  if(s.low!=null||s.high!=null) return ['у нормі','ok'];
+  return ['',''];
+}
+function trendOf(s){
+  if(s.points.length<2) return ['','flat'];
+  const a=s.points[0].value, b=s.points.at(-1).value;
+  const pct=a?Math.round((b-a)/Math.abs(a)*100):0;
+  if(b>a) return [`↑ ${pct>0?'+':''}${pct}%`,'up'];
+  if(b<a) return [`↓ ${pct}%`,'down'];
+  return ['→ 0%','flat'];
+}
+
+function render(st){
+  const docs=st.document_count||0;
+  $('#patient').innerHTML = docs
+    ? `пацієнт <b>${st.patient.id}</b> · документів <b>${docs}</b>`
+    : 'картка не завантажена';
+
+  // stat strip
+  const nMeas=st.series.reduce((a,s)=>a+s.points.length,0);
+  const langs=new Set();
+  st.series.forEach(s=>s.points.forEach(p=>p.source&&langs.add(langOf(p.source))));
+  const bilingual=langs.has('en')&&langs.has('ua');
+  $('#bi-tag').style.display = bilingual?'inline-block':'none';
+  const nAlerts=st.signals.length;
+  $('#stats').innerHTML = docs ? `
+    <div class="stat"><div class="n">${st.series.length}</div><div class="l">показників у динаміці</div></div>
+    <div class="stat"><div class="n">${nMeas}</div><div class="l">вимірювань на таймлайні</div></div>
+    <div class="stat alert"><div class="n">${nAlerts}</div><div class="l">сигналів безпеки</div></div>
+    <div class="stat bi"><div class="n">${bilingual?'UA+EN':(langs.has('en')?'EN':'UA')}</div><div class="l">мови документів</div></div>
+  ` : '';
+
+  // series
+  const sEl=$('#series');
+  if(!st.series.length){sEl.innerHTML='<div class="empty">Даних ще немає. Натисніть «Завантажити демо-картку».</div>';}
+  else{sEl.innerHTML=st.series.map((s,idx)=>{
+    const last=s.points.at(-1);const [txt,cls]=statusOf(s);const [ttxt,tcls]=trendOf(s);
+    const ref=(s.low!=null&&s.high!=null)?`норма ${s.low}–${s.high} ${s.unit||''}`:'';
+    const srcs=[...new Set(s.points.map(p=>p.source).filter(Boolean))];
+    const langBadges=[...new Set(srcs.map(langOf))].map(l=>`<span class="lang ${l}">${l.toUpperCase()}</span>`).join('');
+    return `<div class="metric" style="animation-delay:${(idx*.05).toFixed(2)}s">
+      <div class="row">
+        <span class="name">${s.keyword}</span>
+        <span class="big"><span class="val">${last.value}</span><span class="unit">${s.unit||''}</span>
+          ${ttxt?`<span class="trend ${tcls}">${ttxt}</span>`:''}</span>
+      </div>
+      <div class="meta"><span class="ref">${ref}</span><span class="status ${cls}">${txt}</span></div>
+      ${sparkline(s.points,s.low,s.high)}
+      <div class="src">${langBadges}<span>${s.points.length} вимір. · ${srcs.join(', ')||'—'}</span></div>
+    </div>`;}).join('');}
+
+  // decision
+  const d=st.decision;const dEl=$('#decision');
+  dEl.className='decision '+(d.escalate?'escalate':'auto');
+  dEl.innerHTML=`<span class="badge" style="background:${d.escalate?'var(--major)':'var(--ok)'}">
+      ${d.escalate?'ескалація до людини (L4)':'автоматична обробка'}</span>
+    <span class="t">${d.route_to}</span>
+    <ul class="reasons">${d.reasons.map(r=>`<li>${r}</li>`).join('')}</ul>`;
+
+  // signals — interaction/critical get a pulsing dot
+  const sig=$('#signals');
+  if(!st.signals.length){sig.innerHTML='<div class="empty">Показники в межах, небезпечних взаємодій не виявлено.</div>';}
+  else{sig.innerHTML=st.signals.map(x=>{
+    const hot=(x.kind==='interaction'||x.severity==='critical'||x.severity==='major');
+    const color=SEV[x.severity]||'var(--info)';
+    return `<div class="sig ${hot?'hot':''}">
+      <span class="dot" style="background:${color};color:${color}"></span>
+      <span><span class="k">${x.layer} · ${x.kind} · ${SEV_UK[x.severity]||x.severity}</span>
+      <span class="d">${x.detail}</span></span></div>`;}).join('');}
+
+  // meds — flag those named in an interaction
+  const interText=st.signals.filter(x=>x.kind==='interaction').map(x=>x.detail.toLowerCase()).join(' ');
+  const m=$('#meds');
+  m.innerHTML=st.medications.length?st.medications.map(n=>{
+    const flagged=interText.includes(n.toLowerCase());
+    return `<span class="pill ${flagged?'flag':''}">${n}${flagged?'<span class="warn">⚠</span>':''}</span>`;
+  }).join(''):'<div class="empty">Ліків немає.</div>';
+}
+
+async function refresh(){try{render(await api('/state'));}catch(e){toast('Помилка: '+e.message);}}
+
+async function ask(q){
+  q=(q||$('#q').value).trim(); if(!q)return;
+  const log=$('#log');
+  log.insertAdjacentHTML('beforeend',`<div class="bubble q">${q}</div>`);
+  $('#q').value='';log.scrollTop=log.scrollHeight;
+  try{const a=await api('/ask',{method:'POST',headers:{'Content-Type':'application/json'},body:JSON.stringify({question:q})});
+    const src=a.sources&&a.sources.length?`<span class="src">джерела: ${a.sources.join(', ')}</span>`:'';
+    log.insertAdjacentHTML('beforeend',`<div class="bubble a">${a.text}${src}</div>`);
+    log.scrollTop=log.scrollHeight;
+  }catch(e){toast('Помилка: '+e.message);}
+}
+
+$('#btn-samples').onclick=async()=>{await api('/ingest/samples',{method:'POST'});await refresh();toast('Демо-картку завантажено');};
+$('#btn-reset').onclick=async()=>{await api('/reset',{method:'POST'});$('#log').innerHTML='';await refresh();toast('Картку скинуто');};
+$('#btn-export').onclick=async()=>{
+  const b=await api('/export');
+  const blob=new Blob([JSON.stringify(b,null,2)],{type:'application/json'});
+  const url=URL.createObjectURL(blob);
+  const a=document.createElement('a');a.href=url;a.download='livemedcard_fhir_bundle.json';
+  document.body.appendChild(a);a.click();a.remove();URL.revokeObjectURL(url);
+  toast('FHIR Bundle завантажено');
+};
+$('#btn-add').onclick=()=>$('#add-form').classList.toggle('show');
+
+const fileInput=$('#add-image'), dz=$('#dropzone');
+fileInput.onchange=e=>{const f=e.target.files[0];if(f){$('#dropzone-text').textContent='Вибрано: '+f.name;$('#add-text').value='';}};
+dz.addEventListener('dragover',e=>{e.preventDefault();dz.classList.add('dragover');});
+dz.addEventListener('dragleave',()=>dz.classList.remove('dragover'));
+dz.addEventListener('drop',e=>{e.preventDefault();dz.classList.remove('dragover');
+  if(e.dataTransfer.files.length){fileInput.files=e.dataTransfer.files;
+    $('#dropzone-text').textContent='Вибрано: '+e.dataTransfer.files[0].name;$('#add-text').value='';}});
+
+$('#add-submit').onclick=async()=>{
+  const text=$('#add-text').value.trim(), file=fileInput.files[0];
+  if(!text&&!file){toast('Введіть текст або виберіть фото');return;}
+  const btn=$('#add-submit'), orig=btn.textContent; btn.disabled=true;
+  try{
+    let rep;
+    if(file){
+      btn.textContent='Зчитування (OCR)…';
+      const base64=await new Promise((res,rej)=>{const rd=new FileReader();rd.onload=()=>res(rd.result);rd.onerror=rej;rd.readAsDataURL(file);});
+      rep=await api('/ingest/image',{method:'POST',headers:{'Content-Type':'application/json'},
+        body:JSON.stringify({image_base64:base64,kind:$('#add-kind').value})});
+    }else{
+      btn.textContent='Опрацювання…';
+      rep=await api('/ingest',{method:'POST',headers:{'Content-Type':'application/json'},
+        body:JSON.stringify({id:'doc-'+Date.now(),text,kind:$('#add-kind').value})});
+    }
+    $('#add-text').value='';fileInput.value='';
+    $('#dropzone-text').textContent='Перетягніть фото сюди або натисніть для вибору';
+    $('#add-form').classList.remove('show');
+    await refresh();
+    toast(rep.decision.escalate?'Оброблено · ескалація до людини':'Оброблено · авто');
+  }catch(e){toast('Помилка: '+e.message);}
+  finally{btn.disabled=false;btn.textContent=orig;}
+};
+
+$('#ask').onclick=()=>ask();
+$('#q').addEventListener('keydown',e=>{if(e.key==='Enter')ask();});
+const CHIPS=['Що з нирками за останній рік?','Який був калій?','Які ліки приймає і чи є взаємодії?','Що з HbA1c?'];
+$('#chips').innerHTML=CHIPS.map(c=>`<button class="chip">${c}</button>`).join('');
+$('#chips').querySelectorAll('.chip').forEach(b=>b.onclick=()=>ask(b.textContent));
+
+refresh();
+</script>
+</body>
+</html>

livemedcard/stores.py

@@ -0,0 +1,191 @@
+"""Два сховища над спільними FHIR-ресурсами.
+
+* ``FactStore`` (KV-T) — джерело істини для кількісного; на ньому детерміновано
+  рахуються сигнали L2a/L1.
+* ``KnowledgeGraph`` — семантичні зв'язки та провенанс; живить grounded Q&A.
+
+Межа: сигнали безпеки формуються на FactStore детерміновано, а не обходом графа
+генеративною моделлю.
+"""
+from __future__ import annotations
+
+from datetime import datetime
+from typing import Optional
+
+import networkx as nx
+from pydantic import BaseModel
+
+from .fhir import (
+    CodeableConcept,
+    Condition,
+    Encounter,
+    MedicationRequest,
+    Observation,
+    Patient,
+    loinc_of,
+)
+
+
+class KVTFact(BaseModel):
+    """Атомарний факт keyword–value–timestamp (проекція Observation)."""
+
+    obs_id: Optional[str] = None
+    keyword: str
+    loinc: Optional[str]
+    value: float
+    unit: Optional[str]
+    ts: datetime
+    source_doc_id: Optional[str] = None
+
+
+def _concept_label(cc: Optional[CodeableConcept], fallback: str) -> str:
+    """Людська назва з CodeableConcept: text → перший display → fallback.
+
+    Гарантує рядок навіть коли є лише коди без ``text`` (напр. з реального
+    екстрактора), уникаючи None-міток вузлів графа.
+    """
+    if cc is not None:
+        if cc.text:
+            return cc.text
+        for c in cc.coding:
+            if c.display:
+                return c.display
+    return fallback
+
+
+def observation_to_kvt(o: Observation) -> Optional[KVTFact]:
+    """Проекція Observation → KVTFact (None, якщо немає значення/часу)."""
+    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")
+    return KVTFact(
+        obs_id=o.id,
+        keyword=kw,
+        loinc=loinc_of(o),
+        value=o.valueQuantity.value,
+        unit=o.valueQuantity.unit,
+        ts=o.effectiveDateTime,
+        source_doc_id=o.provenance.source_doc_id if o.provenance else None,
+    )
+
+
+class FactStore:
+    """KV-T факт-стор — джерело істини для кількісних показників.
+
+    Ідемпотентний за id обзервації: повторне додавання тієї самої обзервації
+    (напр. повторний прогін документа) не дублює факт.
+    """
+
+    def __init__(self) -> None:
+        self._facts: list[KVTFact] = []
+        self._seen_ids: set[str] = set()
+        # Індекс за LOINC: series()/loincs() без лінійного проходу всього стору.
+        self._by_loinc: dict[str, list[KVTFact]] = {}
+
+    def add_observation(self, o: Observation) -> Optional[KVTFact]:
+        if o.id in self._seen_ids:
+            return None
+        fact = observation_to_kvt(o)
+        if fact is not None:
+            self._facts.append(fact)
+            self._seen_ids.add(o.id)
+            if fact.loinc:
+                self._by_loinc.setdefault(fact.loinc, []).append(fact)
+        return fact
+
+    def add_observations(self, obs: list[Observation]) -> None:
+        for o in obs:
+            self.add_observation(o)
+
+    def all_facts(self) -> list[KVTFact]:
+        return list(self._facts)
+
+    def series(self, loinc: str) -> list[KVTFact]:
+        """Часовий ряд одного показника, відсортований за часом (свіжа копія)."""
+        return sorted(self._by_loinc.get(loinc, []), key=lambda f: f.ts)
+
+    def loincs(self) -> list[str]:
+        """Унікальні LOINC-коди, наявні у сторі (у порядку першої появи)."""
+        return list(self._by_loinc)
+
+
+class KnowledgeGraph:
+    """Граф контексту (networkx DiGraph) — зв'язки + провенанс."""
+
+    def __init__(self) -> None:
+        self.g = nx.DiGraph()
+
+    def add_patient(self, p: Patient) -> str:
+        nid = f"Patient/{p.id}"
+        self.g.add_node(nid, type="Patient", gender=p.gender)
+        return nid
+
+    def add_document(self, doc_id: str, summary_text: str) -> str:
+        """Явний вузол документа з текстом summary — ціль ребер ``derived_from``.
+
+        Раніше вузол ``Document/{id}`` існував лише як порожня мішень ребра; тепер
+        несе free-text (Stage 1 SGR-summary), тож провенанс стає доказовим.
+        """
+        nid = f"Document/{doc_id}"
+        self.g.add_node(nid, type="Document", text=summary_text)
+        return nid
+
+    def add_encounter(self, e: Encounter, patient_id: str) -> str:
+        nid = f"Encounter/{e.id}"
+        self.g.add_node(nid, type="Encounter", status=e.status)
+        self.g.add_edge(f"Patient/{patient_id}", nid, rel="has_encounter")
+        return nid
+
+    def add_observation(self, o: Observation, patient_id: str) -> str:
+        nid = f"Observation/{o.id}"
+        label = _concept_label(o.code, "obs")
+        self.g.add_node(nid, type="Observation", label=label)
+        self.g.add_edge(f"Patient/{patient_id}", nid, rel="has_observation")
+        if o.provenance:
+            self.g.add_edge(
+                nid, f"Document/{o.provenance.source_doc_id}", rel="derived_from"
+            )
+        return nid
+
+    def add_condition(self, c: Condition, patient_id: str) -> str:
+        nid = f"Condition/{c.id}"
+        label = _concept_label(c.code, "condition")
+        self.g.add_node(nid, type="Condition", label=label)
+        self.g.add_edge(f"Patient/{patient_id}", nid, rel="has_condition")
+        if c.provenance:
+            self.g.add_edge(
+                nid, f"Document/{c.provenance.source_doc_id}", rel="derived_from"
+            )
+        return nid
+
+    def add_medication(self, m: MedicationRequest, patient_id: str) -> str:
+        nid = f"MedicationRequest/{m.id}"
+        label = _concept_label(m.medicationCodeableConcept, "medication")
+        self.g.add_node(nid, type="MedicationRequest", label=label, status=m.status)
+        self.g.add_edge(f"Patient/{patient_id}", nid, rel="prescribed")
+        if m.reason:
+            self.g.add_edge(nid, m.reason.reference, rel="indicated_for")
+        if m.provenance:
+            self.g.add_edge(
+                nid, f"Document/{m.provenance.source_doc_id}", rel="derived_from"
+            )
+        return nid
+
+    # ── запити ────────────────────────────────────────────────────────────────
+    def provenance_of(self, node_id: str) -> list[str]:
+        """Документи-джерела, з яких виведено вузол."""
+        return [
+            v
+            for _, v, d in self.g.out_edges(node_id, data=True)
+            if d.get("rel") == "derived_from"
+        ]
+
+    def indication_of(self, medication_node_id: str) -> Optional[str]:
+        """Стан (Condition), заради якого призначено препарат."""
+        for _, v, d in self.g.out_edges(medication_node_id, data=True):
+            if d.get("rel") == "indicated_for":
+                return v
+        return None
+
+    def nodes_of_type(self, node_type: str) -> list[str]:
+        return [n for n, d in self.g.nodes(data=True) if d.get("type") == node_type]