feat: redesign around phenotype-driven triage, not variant filtering

A table with filters made the user do the work. Rare disease triage is a different task:
which few variants could explain *this* patient's phenotype, and why. The app now answers
that, and lets a reviewer act on the answer.

Domain
- a case is a proband: a VCF plus the HPO terms observed in the patient (samples -> cases)
- HPO's gene-to-phenotype annotations are loaded as reference data (scripts/load-hpo.py)
- each candidate can be shortlisted or dismissed with a reason and a note

Ranking (app/services/triage.py, 21 tests)
- weighted sum of phenotype match, rarity, consequence severity and the model's score,
  with every component shown next to the candidate
- rarity and consequence filter; phenotype only ranks, because a real diagnosis can sit in
  a gene nobody has annotated yet and filtering on it would hide exactly that case
- ClinVar is deliberately not an input: it appears beside the result as independent
  confirmation, so nothing ranks highly merely because ClinVar already said pathogenic

UI
- the funnel is the headline: variants called -> rare -> coding candidates -> phenotype-matched
- ranked candidates with evidence chips, not a grid of everything; filters are demoted
- a variant panel showing the score breakdown, the matched HPO terms, the raw VEP record and
  links out to Ensembl/gnomAD/ClinVar, with the decision controls
- a printable case report: phenotype, funnel, shortlisted variants with reasons, provenance

API: /cases with phenotypes, /cases/{id}/candidates (funnel + ranked + weights),
/variants/{id}, /variants/{id}/decision, /cases/{id}/report, /phenotypes for the picker.
Scoring moved under the case and now answers 503 with the reason when no model registry is
reachable, instead of a 500.

Verified end to end on a simulated proband (scripts/make-demo-case.sh: real GIAB HG002
background + one real ClinVar 2-star pathogenic NF2 variant). 13 variants called -> 1 coding
candidate, and the planted variant ranks first at 0.80 on phenotype 1.00, rarity 1.00 and
consequence 1.00, with ClinVar agreeing afterwards.

Tests: api 75, ml 18, loader 16, web 27; ruff, mypy, svelte-check, terraform validate, both
kustomize overlays and the Nextflow stub run all clean.
This commit is contained in:
Kemal Yaylali
2026-09-12 08:30:44 +01:00
parent abde5ec6e4
commit 07a01715fd
47 changed files with 2159 additions and 539 deletions
+18 -18
View File
@@ -8,9 +8,9 @@ from app.config import settings
from app.services import events
async def new_sample(client: AsyncClient) -> str:
async def new_case(client: AsyncClient) -> str:
r = await client.post(
"/api/samples",
"/api/cases",
json={"name": f"s-{uuid.uuid4()}", "vcf_uri": "gs://bucket/x.vcf.gz", "assembly": "GRCh37"},
)
assert r.status_code == 201, r.text
@@ -23,9 +23,9 @@ async def test_local_without_nextflow_fails_fast_with_instructions(
) -> None:
monkeypatch.setattr(settings, "pubsub_topic", None)
monkeypatch.setattr(events.shutil, "which", lambda _: None)
sample_id = await new_sample(client)
case_id = await new_case(client)
r = await client.post(f"/api/samples/{sample_id}/annotate")
r = await client.post(f"/api/cases/{case_id}/annotate")
assert r.status_code == 202
job = r.json()
assert job["status"] == "failed"
@@ -71,9 +71,9 @@ async def test_local_run_is_watched_and_a_crash_marks_the_job_failed(
return FakeProcess(1, b"ERROR ~ VEP cache not found")
monkeypatch.setattr(events.asyncio, "create_subprocess_exec", fake_exec)
sample_id = await new_sample(client)
case_id = await new_case(client)
r = await client.post(f"/api/samples/{sample_id}/annotate")
r = await client.post(f"/api/cases/{case_id}/annotate")
assert r.status_code == 202
await events.drain()
@@ -117,9 +117,9 @@ async def test_pubsub_publishes_to_the_full_topic_path(
monkeypatch.setattr(settings, "pubsub_topic", "vcf-uploaded")
monkeypatch.setattr(settings, "gcp_project", "my-proj")
monkeypatch.setattr(events, "_publisher", lambda: publisher)
sample_id = await new_sample(client)
case_id = await new_case(client)
r = await client.post(f"/api/samples/{sample_id}/annotate")
r = await client.post(f"/api/cases/{case_id}/annotate")
job = r.json()
assert (job["status"], job["workflow_ref"]) == ("running", "pubsub:msg-123")
[(topic, data)] = publisher.published
@@ -134,9 +134,9 @@ async def test_pubsub_failure_marks_the_job_failed(
monkeypatch.setattr(settings, "pubsub_topic", "vcf-uploaded")
monkeypatch.setattr(settings, "gcp_project", "my-proj")
monkeypatch.setattr(events, "_publisher", lambda: FakePublisher(RuntimeError("403 denied")))
sample_id = await new_sample(client)
case_id = await new_case(client)
job = (await client.post(f"/api/samples/{sample_id}/annotate")).json()
job = (await client.post(f"/api/cases/{case_id}/annotate")).json()
assert job["status"] == "failed"
assert "403 denied" in job["log"]
@@ -159,9 +159,9 @@ async def test_the_pipeline_gets_its_own_database_url(
return FakeProcess(0, b"")
monkeypatch.setattr(events.asyncio, "create_subprocess_exec", fake_exec)
sample_id = await new_sample(client)
case_id = await new_case(client)
await client.post(f"/api/samples/{sample_id}/annotate")
await client.post(f"/api/cases/{case_id}/annotate")
await events.drain()
assert launched["env"]["DATABASE_URL"] == "postgresql+asyncpg://u:[email protected]:5432/db"
@@ -183,9 +183,9 @@ async def test_progress_is_recorded_while_the_pipeline_runs(
])
monkeypatch.setattr(events.asyncio, "create_subprocess_exec", fake_exec)
sample_id = await new_sample(client)
case_id = await new_case(client)
r = await client.post(f"/api/samples/{sample_id}/annotate")
r = await client.post(f"/api/cases/{case_id}/annotate")
await events.drain()
job = (await client.get(f"/api/jobs/{r.json()['id']}")).json()
@@ -196,12 +196,12 @@ async def test_progress_is_recorded_while_the_pipeline_runs(
@pytest.mark.usefixtures("db")
async def test_progress_never_overwrites_a_finished_job(client: AsyncClient) -> None:
from app.db import SessionLocal
from app.models import Job, JobStatus, Sample
from app.models import Case, Job, JobStatus
async with SessionLocal() as s:
sample = Sample(name=f"s-{uuid.uuid4()}", vcf_uri="gs://b/x.vcf.gz", assembly="GRCh38")
job = Job(sample=sample, status=JobStatus.succeeded)
s.add_all([sample, job])
case = Case(name=f"c-{uuid.uuid4()}", vcf_uri="gs://bucket/x.vcf.gz", assembly="GRCh38")
job = Job(case=case, status=JobStatus.succeeded)
s.add_all([case, job])
await s.commit()
job_id = job.id