Можливості
Декларативний rule engine для онкологічних рекомендацій. JSON-профіль на вході — Plan із двома альтернативними треками (стандартний + агресивний) на виході, кожна claim з citation на джерело.
2026-06-27 09:39 UTC.
Один JSON-профіль → два плани лікування з citation під кожною claim.
Без LLM у клінічному рішенні. Без серверу. Patient JSON залишається на машині. Час обробки одного профілю — 50-200 мс.
# приклад: DLBCL disease: DLBCL-NOS line_of_therapy: 1L biomarkers: CD79B_mut: true MYC_rearr: false COO: ABC findings: ipi: 3 ecog: 1 ldh_ratio: 1.8
- Resolve algorithm
- Flatten findings
- Eval 594 RedFlags
- Walk decision tree
- Materialize tracks
- Resolve regimens
revise_plan() оновлює рекомендацію щойно з'являються нові біомаркери чи findings.Coverage matrix
Сторінка /ukr/diseases.html — per-disease таблиця:
counts по біомаркерах / препаратах / показаннях / red flags, checkmarks 1L+2L, fill% і verified%.
Згрупована за лімфоїдною, мієлоїдною гематологією і солідними пухлинами. Канонічна UI-поверхня
для /disease_coverage.json.
→ Дивитись матрицю
/ukr/gallery.html — 586 кейсів
(159 hand-curated + 362 verified variant profiles + 65 auto-base). Кожен — повний Plan або
Diagnostic Brief з усіма citation. Disease-grouped drill-down.
→ Дивитись приклади
6 стадій обробки запиту
Лікар дає engine'у JSON-профіль. Engine виконує 6 послідовних стадій і повертає Plan з ≥2 tracks (CHARTER §15.2 C6 — alternative не сховано).
disease.id + line_of_therapy + disease_state → Algorithm entity.any_of/all_of/none_of з threshold-ами).CIViC actionability
Раніше actionability приходила з OncoKB — ToS заборонив non-commercial public derivatives (конфлікт з CHARTER §2).
Мігрували на CIViC (CC0) WashU. Engine читає локальний nightly YAML snapshot
(knowledge_base/hosted/civic/<date>/) — детермінізм + офлайн. Fusion-aware matcher
обробляє і point mutations (BRAF V600E), і fusions (BCR::ABL1). Render: ESCAT tier — primary,
CIViC evidence rating — у details. Monthly refresh CI відкриває PR з diff'ом.
Multi-phase regimens
Regimen.phases — впорядкований список named blocks (induction → consolidation → maintenance),
кожен зі своїм cycle schedule і тригером переходу. Реальні протоколи (R-CHOP × 6 → maintenance,
AML 7+3 → HiDAC consolidation, axi-cel bridging → infusion). bridging_options — список
регіменів-мостів між фазами (для CAR-T). Старі однофазні YAMLs auto-wrap у one-phase form через
auto_wrap_legacy_components().
Citation guard — 3 layers
Трирівнева система — три точки, де ловимо claims без джерел:
| Layer | Де ловить | Що робить |
|---|---|---|
| L1 · Loader | YAML load (Pydantic) | SRC-* referential integrity. Невідомий SRC-ID → load fail. |
| L2 · Verifier | Contributor PR (CI) | Three-layer grounding: source exists, paraphrase grounded, anchor in section. |
| L3 · Render | HTML output | Без citation → warn-badge (lenient) або skip cell (strict_citation_guard=True). |
Три способи запуску
python -m knowledge_base.engine.cli --patient profile.json --render plan.html.
Offline.
Python WASM + micropip + engine bundle (~2.4 МБ). Перший запуск 8-15 сек, далі — як CLI. Service worker для offline.
from knowledge_base.engine import generate_plan, revise_plan —
EHR / CSV / batch testing. Stateless, deterministic.
Що engine читає з profile
Лише structured поля з чіткою семантикою. Невпізнані поля ігноруються — ніяких прихованих ефектів.
| Категорія | Поля | Як використовуємо |
|---|---|---|
| Disease (вхідна точка) | disease.id · icd_o_3_morphology · line_of_therapy · disease_state |
визначає який Algorithm запускати |
| Diagnostic mode | suspicion.lineage_hint · tissue_locations · presentation |
вмикає DiagnosticPlan замість Plan |
| Demographics | age · ecog · fit_for_transplant · decompensated_cirrhosis · pregnancy_status |
filter у Indication.applicable_to.demographic_constraints |
| Biomarkers | будь-які BIO-X з KB: BIO-CLL-HIGH-RISK-GENETICS, BIO-HCV-RNA, … |
тригерять RedFlags, filter'ять Indications, мапляться у CIViC |
| Findings | сотні structured полів — dominant_nodal_mass_cm, ldh_ratio_to_uln, tp53_mutation, … |
thresholds у RedFlag triggers |
| Prior tests | prior_tests_completed: [TEST-IDs] |
виключає вже зроблені тести з workup_steps |
Що engine повертає — Plan
| Поле | Що містить |
|---|---|
tracks[] | ≥2 alternative tracks (default first): indication + regimen (+ phases) + monitoring + supportive_care + contraindications |
access_matrix | per-track agg: UA-реєстрації, НСЗУ-покриття, cost (₴), AccessPathway. Stale-cost warn > 180 днів. |
experimental_options | третій трек — enumerate_experimental_options() запитує ClinicalTrials.gov v2. 7-day TTL cache. |
actionability_hits | CIViC matches з ESCAT-primary + variant, evidence rating, clinical significance, source citations |
fda_compliance | FDA Criterion 4 fields: intended_use, patient_population_match, algorithm_summary, automation_bias_warning |
trace | покрокова історія walk_algorithm: step / outcome / branch / fired_red_flags |
warnings | schema/ref errors, time_critical disqualifications, missing data hints, citation-guard warnings |
supersedes / superseded_by | версійний chain між plans для одного пацієнта |
Опціонально вмикається MDT brief — orchestrate_mdt() додає
required/recommended/optional ролі з 16 віртуальних спеціалістів + open questions + provenance graph.
Оновлення плану — revise_plan()
Три легальні переходи + одна заборона. Попередній plan не мутується — повертається deep copy
з superseded_by. Per CHARTER §10.2 — стара версія зберігається indefinitely.
| Із | Зміна | Перехід | Результат |
|---|---|---|---|
| DiagnosticPlan vN | тільки suspicion | diagnostic → diagnostic | DiagnosticPlan v(N+1) |
| DiagnosticPlan vN | підтверджена histology | diagnostic → treatment (promotion) | Plan v1 |
| Plan vN | оновлення з histology | treatment → treatment | Plan v(N+1) |
| Plan vN | видалено histology | ILLEGAL — ValueError, CHARTER §15.2 C7 | |
Plan.knowledge_base_state.algorithm_version фіксує версію KB →
same input + same KB = same output.
Open Questions — engine відмовляється від рішень без даних
Замість мовчазного default'у engine явно фіксує які поля бракує і якого тесту чи висновку потребує (MDT_ORCHESTRATOR_SPEC §3). Рендеряться у Plan як окрема section, не сховано.
| Code | Тригер | Що emit'ить engine |
|---|---|---|
| Q1 | Histology not confirmed | «Treatment Plan generated against ICD-O-3 code only; confirm primary histology before therapy» |
| Q2 | Stage missing | «Lugano/Ann Arbor stage required for confident risk-stratification» |
| Q3 | RF clause incomplete | «Cytogenetic panel incomplete; high-risk status assessed with partial data» |
| Q4 | Biomarker missing | «IGHV mutation status + FISH del(17p) required to confirm 1L recommendation» |
| Q5 | Performance status missing | «ECOG required for transplant-eligibility assessment»; fall на conservative default |
| Q6 | Drug not NSZU-reimbursed | «D-VRd: daratumumab not currently NSZU-reimbursed; verify funding pathway» |
| DQ1-4 | Diagnostic-mode: tissue / lineage / presentation / hypotheses missing | знижує confidence workup match; lineage_hint + tissue превалює |
Gap-и персоналізації — навмисні
«Персоналізація» в OpenOnco — це rule-based вибір з фіксованих варіантів, не AI-генерація. Це навмисна архітектурна позиція (CHARTER §8.3).
Без per-patient dose calc
Regimen зберігає стандартну дозу (bortezomib 1.3 mg/m²), не множиться на BSA і не зменшується під CrCl 30 автоматично. Принципово — уникнути FDA device classification.
Без response-adapted cycles
Regimen фіксує total_cycles: 6 + 2 maintenance. Не адаптується на основі response (PR vs CR після PET2). Re-staging через окремий revise_plan.
Genomic matching обмежений CIViC
Поза CIViC (rare, novel variants) emits warning «no actionability evidence», без «creative» інтерпретацій.
SupportiveCare однакова
PJP prophylaxis attached до D-VRd для всіх — engine не знає альтернатив (dapsone замість bactrim). Лікар substitute'ить.
Без cumulative-toxicity tracking
2L plan для пацієнта що отримав bortezomib у 1L з grade 2 нейропатією — profile не carrier'ить prior_treatment_history structured; лікар сам інтерпретує.
CHARTER-обмеження — will not change
Принципові архітектурні рішення, що гатекіпять FDA / клінічну безпеку.
LLM не приймає клінічні рішення
LLM лише: boilerplate, doc drafts, extraction (з human verification), translation з clinical review. Не: вибір режиму, дози, інтерпретація biomarker.
Без histology — без Plan
Treatment Plan тільки якщо disease.id підтверджено. Інакше DiagnosticPlan mode. revise_plan treatment → diagnostic — заборонено.
Без time-critical
Не призначений для emergency oncology (oncologic emergencies). Indication з time_critical: true → disqualification warning.
Two-reviewer merge
Будь-яка зміна clinical content потребує 2 з 3 Clinical Co-Lead approvals. Без цього — STUB.
Anti automation-bias
Завжди ≥2 tracks side-by-side. Alternative не buried, не «click to expand». Лікар бачить вибір, не директиву.
Patient data ніколи у repo
patient_plans/ gitignored. Site показує тільки synthetic examples. Telemetry заборонена без consent.
Never list — що engine ніколи не робить
Не сховує alternative track
Обидві рекомендації завжди показані. UI не має «expand to see alternative».
Не генерує Indication LLM-ом
Усе з curated KB. Немає Indication → warning, не «creative invention».
Не модифікує дози
Дози зі стандартного NCCN/ESMO. Adjustments тільки через явні dose_modification_rules.
Не оцінює «що краще»
Algorithm обирає default, але не вирішує що default кращий. Лікар має автономію — automation_bias_warning.
Не інтерпретує imaging
«Bulky disease» приходить як structured field. Image analysis = device classification.
Не робить cohort matching
«У базі з N пацієнтів M% обрали X» — потребує persisted patient registry + privacy review. Не зараз.
Поточне покриття — де STUB і чого немає
| Категорія | Стан | Що це означає |
|---|---|---|
| Хвороби з повним ланцюгом | 77 / 92 | Решта частково модельовані |
| Indications 1L | 230 | Перша лінія для всіх 92 хвороб |
| Indications 2L+ | 172 | 34 гематол. + 21 солід. Решта solid 2L+ частково |
| Pediatric oncology | 0 | Out of scope MVP — окремий track |
| Радіотерапія | частково | RT у мультимодальних Indications; як окрема сутність — не моделюється |
| Хірургія | не модельовано | Surgical oncology indications відсутні |
| НСЗУ formulary live-feed | статичний flag | Hard-coded на режимах; не auto-refresh |
| Reviewer dual sign-off | 15/806 | Основна bottleneck-метрика — capacity план: 806 → ≥85% verified |
| Live gap dashboard | → link | Build-generated audit (sign-off, solid 2L+, surgery, RT, supportive) |
Workflow для лікаря
Engine — підготовка до tumor-board, не заміна. Лікар: 1) перевіряє sources
(кожна claim з citation, guard відсікав комірки без джерел) → 2) заповнює Open Questions
(замовляє тести, revise_plan) → 3) адаптує під пацієнта (дози, supportive care,
UA-availability) → 4) обговорює на tumor board (MDT brief — structured agenda).
Engine — draft, лікар — final.
TaskTorrent — верифікувати алгоритми токенами вашого AI
Найбільший gap — 15/806 dual-reviewer sign-off. Bottleneck не вирішується новим кодом — він вирішується контрибуторами з AI-tool'ами, що беруть structured chunks роботи.
Maintainer публікує «чанк» — одну завершену задачу (~100k–300k токенів): «реверифікувати BMA evidence для DLBCL × 17 entities» або «backfill source-license для 8 sources». Контрибутор бере чанк, AI виконує, відкриває PR.
AI-tool з token budget (Claude Code Pro+, Codex, Cursor, ChatGPT з web). GitHub + gh CLI.
Python 3.10+. ~1-3 години. Без клінічної експертизи — ви тригерите drafting,
лікарі-co-leads signoff'ять.
Скопіюйте 8-рядковий промпт з
CONTRIBUTOR_QUICKSTART.md
у AI-агент. Він знайде доступний chunk, claim'не, виконає, прогоне валідатор, відкриє PR.
Maintainer перевіряє mechanical (валідатор, schema). Clinical Co-Lead — sample review semantic
(CHARTER §6.1). Merge → sidecar landing → upsert у hosted KB → render. Атрибуція у
_contribution_meta.yaml.
Активність останніх днів
За 4 дні TaskTorrent — 7 хвиль, десятки chunks, ~73 BMA-кандидати, 23 BMA-драфти готові до clinical signoff, 53 source stubs, 1,251 UA-language fields drafted. Останні структурні апдейти:
- CIViC pivot — engine + 29 BIO + 399 BMA YAMLs мігровано з OncoKB-схеми; monthly snapshot refresh CI.
- Multi-phase regimens (PR1-3) —
Regimen.phases,bridging_options, phases-aware render, back-compat auto-wrap. - Citation guard L3 — render-time перевірка кожної BMA-комірки.
- Coverage matrix — /ukr/diseases.html per-disease drill-down.
- 586 кейсів у gallery — Phase 2 chunked feat: ~60 нових hand-curated за 4 дні.