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.
2026-09-12 08:30:44 +01:00
parent abde5ec6e4
commit 07a01715fd
47 changed files with 2159 additions and 539 deletions
@@ -1,4 +1,4 @@
-.PHONY: up down clean migrate test lint data loader pipeline annotate images kind serverless-deploy serverless-destroy gcp-configure gcp-secrets
+.PHONY: up down clean migrate test lint data hpo demo-case loader pipeline annotate images kind serverless-deploy serverless-destroy gcp-configure gcp-secrets
 VCF ?= data/example.vcf.gz
 TAG ?= latest
@@ -30,6 +30,12 @@ lint:
 data:  ## download the public demo slice: GIAB HG002 + ClinVar, chr22 (see docs/data.md)
 	scripts/fetch-demo-data.sh
 hpo:  ## load HPO gene-to-phenotype annotations, which the ranking matches against
 	scripts/load-hpo.py
 demo-case:  ## build the simulated proband: GIAB background + one ClinVar pathogenic variant
 	scripts/make-demo-case.sh
 loader:
 	docker build -t rarelens/loader:dev -f pipeline/loader.Dockerfile pipeline
@@ -1,8 +1,11 @@
 # rarelens
 A small, end-to-end variant interpretation platform for rare genetic disease research.
-Scientists upload a VCF, a Nextflow workflow annotates it with Ensembl VEP, a machine
+A case is a proband: a VCF plus the patient's phenotype (HPO terms). A Nextflow workflow
-learning model scores each variant, and results are browsable in a web app.
+annotates the variants with Ensembl VEP, a model scores each one, and the app narrows
 thousands of variants to a handful of candidates ranked against that phenotype — each
 carrying the evidence for its rank, and each able to be shortlisted or dismissed with a
 reason that ends up in a case report.
 This repository is a **self-training lab**. It exists so that one engineer can learn, in
 public, how a modern life-sciences platform is built end to end: full-stack application,
@@ -28,11 +31,15 @@ clinical tool and makes no diagnostic claims.
 ```bash
 make up          # postgres + api + web + mlflow via docker-compose
 make migrate     # alembic upgrade head
-make data        # real public data: GIAB HG002 + ClinVar, chr22 (needs bcftools)
+make hpo         # HPO gene-to-phenotype annotations: what the ranking matches against
 make demo-case   # a simulated proband: GIAB background + one ClinVar pathogenic variant
 make test        # api, ml, loader and web tests (no Docker needed for the DB tests)
 ```
-Then open http://localhost:5173.
+Then open http://localhost:5173, create a case pointing at `data/proband-simulated.vcf.gz`,
 give it the phenotype of the planted disease (for the default NF2 case: bilateral vestibular
 schwannoma, sensorineural hearing impairment, tinnitus, meningioma, cataract), and analyse it.
 The planted variant should come back ranked first.
 The docker-compose API has no Nextflow, so "Run VEP annotation" marks the job failed with the
 command to run instead. With Nextflow and Docker on the host, a VEP cache in `pipeline/cache/vep`
@@ -0,0 +1,73 @@
 """cases, phenotypes and triage decisions
 Samples become cases (a proband: a VCF plus observed phenotype terms), and triage gains the two
 things it needs: HPO annotations to rank against, and somewhere to record the reviewer's calls.
 Revision ID: 9a1c2d3e4f50
 Revises: 5f2c8e1b9d04
 Create Date: 2026-09-12 09:00:00.000000
 """
 from collections.abc import Sequence
 import sqlalchemy as sa
 from alembic import op
 revision: str = '9a1c2d3e4f50'
 down_revision: str | None = '5f2c8e1b9d04'
 branch_labels: str | Sequence[str] | None = None
 depends_on: str | Sequence[str] | None = None
 def upgrade() -> None:
    op.rename_table('samples', 'cases')
    op.alter_column('jobs', 'sample_id', new_column_name='case_id')
    op.create_table(
        'case_phenotypes',
        sa.Column('id', sa.Integer(), autoincrement=True, nullable=False),
        sa.Column('case_id', sa.UUID(), nullable=False),
        sa.Column('hpo_id', sa.String(length=20), nullable=False),
        sa.Column('label', sa.String(length=200), nullable=False),
        sa.ForeignKeyConstraint(['case_id'], ['cases.id'], ondelete='CASCADE'),
        sa.PrimaryKeyConstraint('id'),
        sa.UniqueConstraint('case_id', 'hpo_id', name='uq_case_phenotypes_case_term'),
    )
    op.create_index(op.f('ix_case_phenotypes_case_id'), 'case_phenotypes', ['case_id'])
    op.create_table(
        'gene_phenotypes',
        sa.Column('id', sa.Integer(), autoincrement=True, nullable=False),
        sa.Column('gene_symbol', sa.String(length=60), nullable=False),
        sa.Column('hpo_id', sa.String(length=20), nullable=False),
        sa.Column('hpo_name', sa.String(length=200), nullable=False),
        sa.PrimaryKeyConstraint('id'),
        sa.UniqueConstraint('gene_symbol', 'hpo_id', name='uq_gene_phenotypes_gene_term'),
    )
    op.create_index(op.f('ix_gene_phenotypes_gene_symbol'), 'gene_phenotypes', ['gene_symbol'])
    op.create_index(op.f('ix_gene_phenotypes_hpo_id'), 'gene_phenotypes', ['hpo_id'])
    op.create_table(
        'variant_decisions',
        sa.Column('id', sa.Integer(), autoincrement=True, nullable=False),
        sa.Column('variant_id', sa.Integer(), nullable=False),
        sa.Column('state', sa.Enum('shortlisted', 'dismissed', name='decisionstate'), nullable=False),
        sa.Column('reason', sa.String(length=120), nullable=True),
        sa.Column('note', sa.Text(), nullable=True),
        sa.Column('decided_at', sa.DateTime(timezone=True), server_default=sa.text('now()'), nullable=False),
        sa.ForeignKeyConstraint(['variant_id'], ['variants.id'], ondelete='CASCADE'),
        sa.PrimaryKeyConstraint('id'),
        sa.UniqueConstraint('variant_id'),
    )
 def downgrade() -> None:
    op.drop_table('variant_decisions')
    sa.Enum(name='decisionstate').drop(op.get_bind(), checkfirst=True)
    op.drop_index(op.f('ix_gene_phenotypes_hpo_id'), table_name='gene_phenotypes')
    op.drop_index(op.f('ix_gene_phenotypes_gene_symbol'), table_name='gene_phenotypes')
    op.drop_table('gene_phenotypes')
    op.drop_index(op.f('ix_case_phenotypes_case_id'), table_name='case_phenotypes')
    op.drop_table('case_phenotypes')
    op.alter_column('jobs', 'case_id', new_column_name='sample_id')
    op.rename_table('cases', 'samples')
@@ -4,7 +4,7 @@ from fastapi import APIRouter, FastAPI
 from fastapi.middleware.cors import CORSMiddleware
 from app.config import settings
-from app.routers import jobs, predictions, samples, variants
+from app.routers import cases, jobs, phenotypes, variants
@asynccontextmanager
@@ -23,10 +23,10 @@ app.add_middleware(
 # The ingress forwards /api/* to this service unchanged, and local dev uses the same prefix.
 api = APIRouter(prefix="/api")
-api.include_router(samples.router, prefix="/samples", tags=["samples"])
+api.include_router(cases.router, prefix="/cases", tags=["cases"])
 api.include_router(jobs.router, prefix="/jobs", tags=["jobs"])
 api.include_router(variants.router, prefix="/variants", tags=["variants"])
-api.include_router(predictions.router, prefix="/predictions", tags=["predictions"])
+api.include_router(phenotypes.router, prefix="/phenotypes", tags=["phenotypes"])
 app.include_router(api)
@@ -1,12 +1,23 @@
 """SQLAlchemy 2.0 declarative models.
-One sample -> many jobs; one job -> many variants; one variant -> one prediction (latest).
+A case is a proband: a VCF plus the phenotype terms observed in that patient. One case -> many
 jobs (pipeline runs); one job -> many variants; one variant -> one prediction and one decision.
 """
 import enum
 import uuid
 from datetime import datetime
-from sqlalchemy import DateTime, Enum, Float, ForeignKey, Integer, String, Text, func
+from sqlalchemy import (
    DateTime,
    Enum,
    Float,
    ForeignKey,
    Integer,
    String,
    Text,
    UniqueConstraint,
    func,
 )
 from sqlalchemy.dialects.postgresql import JSONB, UUID
 from sqlalchemy.orm import DeclarativeBase, Mapped, mapped_column, relationship
@@ -22,27 +33,58 @@ class JobStatus(str, enum.Enum):
    failed = "failed"
-class Sample(Base):
+class DecisionState(str, enum.Enum):
-    __tablename__ = "samples"
+    shortlisted = "shortlisted"
    dismissed = "dismissed"
 class Case(Base):
    __tablename__ = "cases"
    id: Mapped[uuid.UUID] = mapped_column(UUID(as_uuid=True), primary_key=True, default=uuid.uuid4)
    name: Mapped[str] = mapped_column(String(120), unique=True)
    vcf_uri: Mapped[str] = mapped_column(Text)
    assembly: Mapped[str] = mapped_column(String(10), default="GRCh38")
    created_at: Mapped[datetime] = mapped_column(DateTime(timezone=True), server_default=func.now())
-    jobs: Mapped[list["Job"]] = relationship(back_populates="sample")
+    jobs: Mapped[list["Job"]] = relationship(back_populates="case")
    phenotypes: Mapped[list["CasePhenotype"]] = relationship(
        back_populates="case", cascade="all, delete-orphan", order_by="CasePhenotype.hpo_id"
    )
 class CasePhenotype(Base):
    """An HPO term observed in this patient; the ranking matches these against gene annotations."""
    __tablename__ = "case_phenotypes"
    __table_args__ = (UniqueConstraint("case_id", "hpo_id", name="uq_case_phenotypes_case_term"),)
    id: Mapped[int] = mapped_column(Integer, primary_key=True, autoincrement=True)
    case_id: Mapped[uuid.UUID] = mapped_column(ForeignKey("cases.id", ondelete="CASCADE"), index=True)
    hpo_id: Mapped[str] = mapped_column(String(20))
    label: Mapped[str] = mapped_column(String(200))
    case: Mapped[Case] = relationship(back_populates="phenotypes")
 class GenePhenotype(Base):
    """HPO's gene-to-phenotype annotations (scripts/load-hpo.py); read-only reference data."""
    __tablename__ = "gene_phenotypes"
    __table_args__ = (UniqueConstraint("gene_symbol", "hpo_id", name="uq_gene_phenotypes_gene_term"),)
    id: Mapped[int] = mapped_column(Integer, primary_key=True, autoincrement=True)
    gene_symbol: Mapped[str] = mapped_column(String(60), index=True)
    hpo_id: Mapped[str] = mapped_column(String(20), index=True)
    hpo_name: Mapped[str] = mapped_column(String(200))
 class Job(Base):
    __tablename__ = "jobs"
    id: Mapped[uuid.UUID] = mapped_column(UUID(as_uuid=True), primary_key=True, default=uuid.uuid4)
-    sample_id: Mapped[uuid.UUID] = mapped_column(ForeignKey("samples.id", ondelete="CASCADE"))
+    case_id: Mapped[uuid.UUID] = mapped_column(ForeignKey("cases.id", ondelete="CASCADE"))
    status: Mapped[JobStatus] = mapped_column(Enum(JobStatus), default=JobStatus.queued)
    workflow_ref: Mapped[str | None] = mapped_column(String(200))   # Argo workflow name / nf run id
    vep_version: Mapped[str | None] = mapped_column(String(40))
    log: Mapped[str | None] = mapped_column(Text)
    created_at: Mapped[datetime] = mapped_column(DateTime(timezone=True), server_default=func.now())
    finished_at: Mapped[datetime | None] = mapped_column(DateTime(timezone=True))
-    sample: Mapped[Sample] = relationship(back_populates="jobs")
+    case: Mapped[Case] = relationship(back_populates="jobs")
    variants: Mapped[list["Variant"]] = relationship(back_populates="job")
@@ -64,6 +106,7 @@ class Variant(Base):
    annotations: Mapped[dict] = mapped_column(JSONB, default=dict)   # full VEP CSQ record
    job: Mapped[Job] = relationship(back_populates="variants")
    prediction: Mapped["Prediction | None"] = relationship(back_populates="variant", uselist=False)
    decision: Mapped["VariantDecision | None"] = relationship(back_populates="variant", uselist=False)
 class Prediction(Base):
@@ -75,3 +118,16 @@ class Prediction(Base):
    score: Mapped[float] = mapped_column(Float)         # P(pathogenic)
    created_at: Mapped[datetime] = mapped_column(DateTime(timezone=True), server_default=func.now())
    variant: Mapped[Variant] = relationship(back_populates="prediction")
 class VariantDecision(Base):
    """A reviewer's triage call. No authentication here, so decisions are shared by all visitors."""
    __tablename__ = "variant_decisions"
    id: Mapped[int] = mapped_column(Integer, primary_key=True, autoincrement=True)
    variant_id: Mapped[int] = mapped_column(ForeignKey("variants.id", ondelete="CASCADE"), unique=True)
    state: Mapped[DecisionState] = mapped_column(Enum(DecisionState))
    reason: Mapped[str | None] = mapped_column(String(120))
    note: Mapped[str | None] = mapped_column(Text)
    decided_at: Mapped[datetime] = mapped_column(DateTime(timezone=True), server_default=func.now())
    variant: Mapped[Variant] = relationship(back_populates="decision")
@@ -0,0 +1,225 @@
 import logging
 import uuid
 from dataclasses import asdict
 from datetime import UTC, datetime
 from fastapi import APIRouter, HTTPException, Query, status
 from sqlalchemy import func, select
 from sqlalchemy.exc import IntegrityError
 from sqlalchemy.orm import selectinload
 from app.db import SessionDep
 from app.models import (
    Case,
    CasePhenotype,
    DecisionState,
    Job,
    JobStatus,
    Variant,
    VariantDecision,
 )
 from app.schemas import (
    CandidateOut,
    CandidatePage,
    CaseCreate,
    CaseOut,
    FunnelOut,
    JobOut,
    ProvenanceOut,
    ReportOut,
    ScoreOut,
 )
 from app.services import candidates as case_view
 from app.services import events, triage
 from app.services.scoring import score_job
 logger = logging.getLogger(__name__)
 router = APIRouter()
 async def _case_or_404(session: SessionDep, case_id: uuid.UUID) -> Case:
    case = await case_view.get_case(session, case_id)
    if case is None:
        raise HTTPException(404, "case not found")
    return case
 async def _shortlisted_counts(session: SessionDep, case_ids: list[uuid.UUID]) -> dict[uuid.UUID, int]:
    if not case_ids:
        return {}
    rows = await session.execute(
        select(Job.case_id, func.count(VariantDecision.id))
        .join(Variant, Variant.job_id == Job.id)
        .join(VariantDecision, VariantDecision.variant_id == Variant.id)
        .where(Job.case_id.in_(case_ids), VariantDecision.state == DecisionState.shortlisted)
        .group_by(Job.case_id)
    )
    return dict(rows.all())  # type: ignore[arg-type]
 async def _latest_jobs(session: SessionDep, case_ids: list[uuid.UUID]) -> dict[uuid.UUID, Job]:
    if not case_ids:
        return {}
    jobs = await session.scalars(
        select(Job).where(Job.case_id.in_(case_ids)).order_by(Job.created_at.desc())
    )
    latest: dict[uuid.UUID, Job] = {}
    for job in jobs:  # ordered newest first, so the first one wins
        latest.setdefault(job.case_id, job)
    return latest
 def _as_case_out(case: Case, job: Job | None, shortlisted: int) -> CaseOut:
    out = CaseOut.model_validate(case)
    out.latest_job = JobOut.model_validate(job) if job is not None else None
    out.shortlisted = shortlisted
    return out
@router.get("", response_model=list[CaseOut])
 async def list_cases(session: SessionDep):
    cases = (
        await session.scalars(
            select(Case).order_by(Case.created_at.desc()).options(selectinload(Case.phenotypes))
        )
    ).all()
    ids = [c.id for c in cases]
    jobs, counts = await _latest_jobs(session, ids), await _shortlisted_counts(session, ids)
    return [_as_case_out(c, jobs.get(c.id), counts.get(c.id, 0)) for c in cases]
@router.post("", response_model=CaseOut, status_code=status.HTTP_201_CREATED)
 async def create_case(payload: CaseCreate, session: SessionDep):
    case = Case(
        name=payload.name,
        vcf_uri=payload.vcf_uri,
        assembly=payload.assembly,
        phenotypes=[CasePhenotype(hpo_id=p.hpo_id, label=p.label) for p in payload.phenotypes],
    )
    session.add(case)
    try:
        await session.commit()
    except IntegrityError:  # cases.name is unique
        await session.rollback()
        raise HTTPException(409, f"a case named {payload.name!r} already exists") from None
    await session.refresh(case, attribute_names=["phenotypes"])
    return _as_case_out(case, None, 0)
@router.get("/{case_id}", response_model=CaseOut)
 async def get_case(case_id: uuid.UUID, session: SessionDep):
    case = await _case_or_404(session, case_id)
    counts = await _shortlisted_counts(session, [case_id])
    return _as_case_out(case, await case_view.latest_job(session, case_id), counts.get(case_id, 0))
@router.get("/{case_id}/jobs", response_model=list[JobOut])
 async def list_jobs(case_id: uuid.UUID, session: SessionDep):
    result = await session.scalars(
        select(Job).where(Job.case_id == case_id).order_by(Job.created_at.desc())
    )
    return result.all()
@router.post("/{case_id}/annotate", response_model=JobOut, status_code=status.HTTP_202_ACCEPTED)
 async def annotate(case_id: uuid.UUID, session: SessionDep):
    case = await _case_or_404(session, case_id)
    # Commit `running` before launching: a local run that dies instantly is marked failed by its
    # watcher, and a later status write here would overwrite that.
    job = Job(case_id=case.id, status=JobStatus.running)
    session.add(job)
    await session.commit()
    try:
        job.workflow_ref = await events.launch(job.id, case.vcf_uri, case.assembly)
    except events.LaunchError as e:
        job.status = JobStatus.failed
        job.log = str(e)
        job.finished_at = datetime.now(UTC)
    await session.commit()
    await session.refresh(job)
    return job
@router.post("/{case_id}/score", response_model=ScoreOut)
 async def score(case_id: uuid.UUID, session: SessionDep):
    await _case_or_404(session, case_id)
    job = await case_view.latest_job(session, case_id, status=JobStatus.succeeded)
    if job is None:
        raise HTTPException(409, "no finished annotation to score")
    try:
        scored, version = await score_job(job.id, session)
    except Exception as e:
        # No registry, no model behind the alias, a model that will not load: all of these are
        # the environment being unready, not a bug in the request. Say so rather than throwing 500.
        logger.exception("scoring case %s failed", case_id)
        raise HTTPException(503, f"could not score with the model: {e}") from e
    return ScoreOut(case_id=case_id, scored=scored, model_version=version)
@router.get("/{case_id}/candidates", response_model=CandidatePage)
 async def list_candidates(
    case_id: uuid.UUID,
    session: SessionDep,
    gene: str | None = None,
    impact: str | None = Query(None, pattern="^(HIGH|MODERATE|LOW|MODIFIER)$"),
    max_af: float | None = Query(None, ge=0, le=1),
    state: str | None = Query(None, pattern="^(shortlisted|dismissed|undecided)$"),
    limit: int = Query(50, ge=1, le=500),
    offset: int = Query(0, ge=0),
 ) -> CandidatePage:
    case = await _case_or_404(session, case_id)
    view = await case_view.build(session, case)
    items = view.candidates
    if gene:
        items = [c for c in items if (c.variant.gene or "").upper() == gene.upper()]
    if impact:
        items = [c for c in items if c.variant.impact == impact]
    if max_af is not None:
        items = [c for c in items if c.variant.gnomad_af is None or c.variant.gnomad_af <= max_af]
    if state == "undecided":
        items = [c for c in items if c.variant.decision is None]
    elif state is not None:
        items = [c for c in items if c.variant.decision and c.variant.decision.state.value == state]
    labels = view.labels
    return CandidatePage(
        # The funnel describes the whole case, not the filtered view.
        funnel=FunnelOut(**asdict(view.funnel)),
        weights=triage.WEIGHTS,
        items=[CandidateOut.from_candidate(c, labels) for c in items[offset : offset + limit]],
        total=len(items),
        limit=limit,
        offset=offset,
    )
@router.get("/{case_id}/report", response_model=ReportOut)
 async def report(case_id: uuid.UUID, session: SessionDep) -> ReportOut:
    case = await _case_or_404(session, case_id)
    view = await case_view.build(session, case)
    labels = view.labels
    def decided(state: DecisionState) -> list[CandidateOut]:
        return [
            CandidateOut.from_candidate(c, labels)
            for c in view.candidates
            if c.variant.decision is not None and c.variant.decision.state == state
        ]
    shortlisted, dismissed = decided(DecisionState.shortlisted), decided(DecisionState.dismissed)
    prediction = next((c.variant.prediction for c in view.candidates if c.variant.prediction), None)
    return ReportOut(
        case=_as_case_out(case, view.job, len(shortlisted)),
        funnel=FunnelOut(**asdict(view.funnel)),
        generated_at=datetime.now(UTC),
        provenance=ProvenanceOut(
            job_id=view.job.id if view.job else None,
            vep_version=view.job.vep_version if view.job else None,
            finished_at=view.job.finished_at if view.job else None,
            model_name=prediction.model_name if prediction else None,
            model_version=prediction.model_version if prediction else None,
        ),
        shortlisted=shortlisted,
        dismissed=dismissed,
    )
@@ -0,0 +1,25 @@
 from fastapi import APIRouter, Query
 from sqlalchemy import select
 from app.db import SessionDep
 from app.models import GenePhenotype
 from app.schemas import PhenotypeTerm
 router = APIRouter()
@router.get("", response_model=list[PhenotypeTerm])
 async def search(
    session: SessionDep,
    q: str = Query(min_length=2, max_length=100),
    limit: int = Query(20, ge=1, le=100),
 ) -> list[PhenotypeTerm]:
    """Type-ahead over the HPO terms that are annotated to at least one gene."""
    rows = await session.execute(
        select(GenePhenotype.hpo_id, GenePhenotype.hpo_name)
        .where(GenePhenotype.hpo_name.ilike(f"%{q}%"))
        .distinct()
        .order_by(GenePhenotype.hpo_name)
        .limit(limit)
    )
    return [PhenotypeTerm(hpo_id=hpo_id, label=name) for hpo_id, name in rows]
@@ -1,22 +0,0 @@
 import uuid
 from fastapi import APIRouter, HTTPException
 from app.db import SessionDep
 from app.models import Job, JobStatus
 from app.schemas import ScoreOut
 from app.services.scoring import score_job
 router = APIRouter()
@router.post("/score/{job_id}", response_model=ScoreOut)
 async def score(job_id: uuid.UUID, session: SessionDep) -> ScoreOut:
    """Score every variant of a finished job with the model behind the registry alias."""
    job = await session.get(Job, job_id)
    if job is None:
        raise HTTPException(404, "job not found")
    if job.status != JobStatus.succeeded:
        raise HTTPException(409, f"job is {job.status.value}; only succeeded jobs can be scored")
    n, version = await score_job(job_id, session)
    return ScoreOut(job_id=job_id, scored=n, model_version=version)
@@ -1,61 +0,0 @@
 import uuid
 from datetime import UTC, datetime
 from fastapi import APIRouter, HTTPException, status
 from sqlalchemy import select
 from sqlalchemy.exc import IntegrityError
 from app.db import SessionDep
 from app.models import Job, JobStatus, Sample
 from app.schemas import JobOut, SampleCreate, SampleOut
 from app.services import events
 router = APIRouter()
@router.get("", response_model=list[SampleOut])
 async def list_samples(session: SessionDep):
    result = await session.scalars(select(Sample).order_by(Sample.created_at.desc()))
    return result.all()
@router.post("", response_model=SampleOut, status_code=status.HTTP_201_CREATED)
 async def create_sample(payload: SampleCreate, session: SessionDep):
    sample = Sample(**payload.model_dump())
    session.add(sample)
    try:
        await session.commit()
    except IntegrityError:  # samples.name is unique
        await session.rollback()
        raise HTTPException(409, f"a sample named {payload.name!r} already exists") from None
    await session.refresh(sample)
    return sample
@router.get("/{sample_id}/jobs", response_model=list[JobOut])
 async def list_jobs(sample_id: uuid.UUID, session: SessionDep):
    result = await session.scalars(
        select(Job).where(Job.sample_id == sample_id).order_by(Job.created_at.desc())
    )
    return result.all()
@router.post("/{sample_id}/annotate", response_model=JobOut, status_code=status.HTTP_202_ACCEPTED)
 async def annotate(sample_id: uuid.UUID, session: SessionDep):
    sample = await session.get(Sample, sample_id)
    if sample is None:
        raise HTTPException(404, "sample not found")
    # Commit `running` before launching: a local run that dies instantly is marked failed by its
    # watcher, and a later status write here would overwrite that.
    job = Job(sample_id=sample.id, status=JobStatus.running)
    session.add(job)
    await session.commit()
    try:
        job.workflow_ref = await events.launch(job.id, sample.vcf_uri, sample.assembly)
    except events.LaunchError as e:
        job.status = JobStatus.failed
        job.log = str(e)
        job.finished_at = datetime.now(UTC)
    await session.commit()
    await session.refresh(job)
    return job
@@ -1,60 +1,63 @@
-import uuid
+from fastapi import APIRouter, HTTPException
-
+from sqlalchemy import func, select
-from fastapi import APIRouter, Query
+from sqlalchemy.dialects.postgresql import insert
 from sqlalchemy import Integer, case, cast, func, select
 from sqlalchemy.orm import selectinload
 from app.db import SessionDep
-from app.models import Prediction, Variant
+from app.models import Variant, VariantDecision
-from app.schemas import VariantOut, VariantPage
+from app.schemas import CandidateOut, DecisionIn, DecisionOut, VariantDetailOut
 from app.services import candidates as case_view
 from app.services import triage
 router = APIRouter()
 # Karyotype order (1..22, X, Y, MT) instead of text order, where "10" sorts before "2".
 _chrom = func.regexp_replace(Variant.chrom, "^chr", "", "i")
 CHROM_ORDER = case(
    (_chrom.regexp_match("^[0-9]+$"), cast(_chrom, Integer)),
    (_chrom == "X", 23),
    (_chrom == "Y", 24),
    (_chrom.in_(["M", "MT"]), 25),
    else_=26,
 )
-
+@router.get("/{variant_id}", response_model=VariantDetailOut)
-@router.get("", response_model=VariantPage)
+async def get_variant(variant_id: int, session: SessionDep) -> VariantDetailOut:
-async def list_variants(
+    """Every piece of evidence for one variant, including the raw VEP record."""
-    job_id: uuid.UUID,
+    variant = await session.scalar(
-    session: SessionDep,
+        select(Variant)
-    gene: str | None = None,
+        .where(Variant.id == variant_id)
-    impact: str | None = Query(None, pattern="^(HIGH|MODERATE|LOW|MODIFIER)$"),
+        .options(
-    max_af: float | None = Query(None, ge=0, le=1),
+            selectinload(Variant.prediction),
-    min_score: float | None = Query(None, ge=0, le=1),
+            selectinload(Variant.decision),
-    limit: int = Query(50, ge=1, le=500),
+            selectinload(Variant.job),
    offset: int = Query(0, ge=0),
 ) -> VariantPage:
    stmt = select(Variant).where(Variant.job_id == job_id)
    if gene:
        stmt = stmt.where(Variant.gene == gene.upper())
    if impact:
        stmt = stmt.where(Variant.impact == impact)
    if max_af is not None:
        stmt = stmt.where((Variant.gnomad_af.is_(None)) | (Variant.gnomad_af <= max_af))
    if min_score is not None:
        stmt = stmt.join(Prediction, Prediction.variant_id == Variant.id).where(
            Prediction.score >= min_score
        )
    )
    if variant is None:
        raise HTTPException(404, "variant not found")
    case = await case_view.get_case(session, variant.job.case_id)
    terms = [p.hpo_id for p in case.phenotypes] if case else []
    gene_terms = await case_view.gene_terms_for(session, {variant.gene} if variant.gene else set())
-    total = await session.scalar(select(func.count()).select_from(stmt.subquery()))
+    # evaluate, not rank: the panel must work for a variant that did not make the candidate list.
-    rows = await session.scalars(
+    scored = triage.evaluate(variant, terms, gene_terms)
-        stmt.options(selectinload(Variant.prediction))
+    labels = {p.hpo_id: p.label for p in case.phenotypes} if case else {}
-        # id breaks ties between split multiallelics at one position, keeping pages stable.
+    base = CandidateOut.from_candidate(scored, labels).model_dump()
-        .order_by(CHROM_ORDER, Variant.chrom, Variant.pos, Variant.id)
+    return VariantDetailOut(**base, annotations=variant.annotations or {})
-        .limit(limit)
+
-        .offset(offset)
+
@router.post("/{variant_id}/decision", response_model=DecisionOut)
 async def decide(variant_id: int, payload: DecisionIn, session: SessionDep) -> DecisionOut:
    if await session.get(Variant, variant_id) is None:
        raise HTTPException(404, "variant not found")
    stmt = insert(VariantDecision).values(
        variant_id=variant_id, state=payload.state, reason=payload.reason, note=payload.note
    )
-    return VariantPage(
+    # Changing your mind replaces the call rather than failing on the unique constraint.
-        items=[VariantOut.model_validate(v) for v in rows],
+    await session.execute(
-        total=total or 0,
+        stmt.on_conflict_do_update(
-        limit=limit,
+            index_elements=[VariantDecision.variant_id],
-        offset=offset,
+            set_={
                "state": stmt.excluded.state,
                "reason": stmt.excluded.reason,
                "note": stmt.excluded.note,
                "decided_at": func.now(),
            },
        )
    )
    await session.commit()
    decision = await session.scalar(
        select(VariantDecision).where(VariantDecision.variant_id == variant_id)
    )
    return DecisionOut.model_validate(decision)
@@ -2,12 +2,15 @@ import re
 import uuid
 from datetime import datetime
 from pathlib import PurePosixPath
-from typing import Literal
+from typing import TYPE_CHECKING, Literal
 from pydantic import BaseModel, ConfigDict, Field, field_validator
 from app.config import settings
-from app.models import JobStatus
+from app.models import DecisionState, JobStatus
 if TYPE_CHECKING:
    from app.services.triage import Candidate
 class ORMModel(BaseModel):
@@ -19,11 +22,18 @@ VCF_SUFFIXES = (".vcf", ".vcf.gz", ".vcf.bgz", ".bcf")
 GCS_URI = re.compile(r"gs://[a-z0-9][a-z0-9._-]{1,220}[a-z0-9]/\S+")
-class SampleCreate(BaseModel):
+class PhenotypeTerm(ORMModel):
    """An HPO term: the id is what ranking matches on, the label is for people."""
    hpo_id: str = Field(pattern=r"^HP:\d{7}$")
    label: str = Field(min_length=1, max_length=200)
 class CaseCreate(BaseModel):
    name: str = Field(min_length=1, max_length=120)
    vcf_uri: str
    # Passed to VEP --assembly; the VEP cache must contain it.
    assembly: Assembly = "GRCh38"
    phenotypes: list[PhenotypeTerm] = Field(default_factory=list, max_length=100)
    @field_validator("vcf_uri")
    @classmethod
@@ -44,17 +54,9 @@ class SampleCreate(BaseModel):
        return v
 class SampleOut(ORMModel):
    id: uuid.UUID
    name: str
    vcf_uri: str
    assembly: str
    created_at: datetime
 class JobOut(ORMModel):
    id: uuid.UUID
-    sample_id: uuid.UUID
+    case_id: uuid.UUID
    status: JobStatus
    workflow_ref: str | None
    vep_version: str | None
@@ -63,6 +65,17 @@ class JobOut(ORMModel):
    finished_at: datetime | None
 class CaseOut(ORMModel):
    id: uuid.UUID
    name: str
    vcf_uri: str
    assembly: str
    created_at: datetime
    phenotypes: list[PhenotypeTerm] = Field(default_factory=list)
    latest_job: JobOut | None = None
    shortlisted: int = 0
 class PredictionOut(ORMModel):
    model_name: str
    model_version: str
@@ -85,14 +98,81 @@ class VariantOut(ORMModel):
    prediction: PredictionOut | None = None
-class ScoreOut(BaseModel):
+class DecisionIn(BaseModel):
-    job_id: uuid.UUID
+    state: DecisionState
-    scored: int
+    reason: str | None = Field(None, max_length=120)
-    model_version: str
+    note: str | None = Field(None, max_length=2000)
-class VariantPage(BaseModel):
+class DecisionOut(ORMModel):
-    items: list[VariantOut]
+    state: DecisionState
    reason: str | None
    note: str | None
    decided_at: datetime
 class CandidateOut(BaseModel):
    variant: VariantOut
    score: float
    components: dict[str, float]
    matched_terms: list[PhenotypeTerm]
    scored: bool
    decision: DecisionOut | None = None
    @classmethod
    def from_candidate(cls, candidate: "Candidate", labels: dict[str, str]) -> "CandidateOut":
        variant = candidate.variant
        return cls(
            variant=VariantOut.model_validate(variant),
            score=round(candidate.score, 4),
            components={name: round(v, 4) for name, v in candidate.components.items()},
            matched_terms=[
                PhenotypeTerm(hpo_id=term, label=labels.get(term, term))
                for term in candidate.matched_terms
            ],
            scored=candidate.scored,
            decision=DecisionOut.model_validate(variant.decision) if variant.decision else None,
        )
 class VariantDetailOut(CandidateOut):
    annotations: dict
 class FunnelOut(BaseModel):
    total: int
    rare: int
    candidates: int
    phenotype_matched: int
 class CandidatePage(BaseModel):
    funnel: FunnelOut
    weights: dict[str, float]
    items: list[CandidateOut]
    total: int
    limit: int
    offset: int
 class ProvenanceOut(BaseModel):
    job_id: uuid.UUID | None = None
    vep_version: str | None = None
    finished_at: datetime | None = None
    model_name: str | None = None
    model_version: str | None = None
 class ReportOut(BaseModel):
    case: CaseOut
    funnel: FunnelOut
    generated_at: datetime
    provenance: ProvenanceOut
    shortlisted: list[CandidateOut]
    dismissed: list[CandidateOut]
 class ScoreOut(BaseModel):
    case_id: uuid.UUID
    scored: int
    model_version: str
@@ -0,0 +1,79 @@
 """Assemble a case's ranked candidates: load the latest results, rank them, attach decisions.
 Everything for one job is loaded at once, which is fine for a gene panel or a chromosome — the
 size of case this demo handles. A whole genome would need the narrowing pushed into SQL.
 """
 import uuid
 from dataclasses import dataclass
 from sqlalchemy import select
 from sqlalchemy.ext.asyncio import AsyncSession
 from sqlalchemy.orm import selectinload
 from app.models import Case, GenePhenotype, Job, JobStatus, Variant
 from app.services import triage
 EMPTY_FUNNEL = triage.Funnel(total=0, rare=0, candidates=0, phenotype_matched=0)
@dataclass(frozen=True)
 class CaseView:
    case: Case
    job: Job | None
    funnel: triage.Funnel
    candidates: list[triage.Candidate]
    @property
    def labels(self) -> dict[str, str]:
        return {p.hpo_id: p.label for p in self.case.phenotypes}
 async def get_case(session: AsyncSession, case_id: uuid.UUID) -> Case | None:
    return await session.scalar(
        select(Case).where(Case.id == case_id).options(selectinload(Case.phenotypes))
    )
 async def latest_job(
    session: AsyncSession, case_id: uuid.UUID, *, status: JobStatus | None = None
 ) -> Job | None:
    stmt = select(Job).where(Job.case_id == case_id).order_by(Job.created_at.desc()).limit(1)
    if status is not None:
        stmt = stmt.where(Job.status == status)
    return await session.scalar(stmt)
 async def gene_terms_for(session: AsyncSession, genes: set[str]) -> dict[str, set[str]]:
    """gene symbol -> the HPO terms annotated to it."""
    if not genes:
        return {}
    rows = await session.execute(
        select(GenePhenotype.gene_symbol, GenePhenotype.hpo_id).where(
            GenePhenotype.gene_symbol.in_(genes)
        )
    )
    index: dict[str, set[str]] = {}
    for gene, hpo_id in rows:
        index.setdefault(gene, set()).add(hpo_id)
    return index
 async def build(session: AsyncSession, case: Case) -> CaseView:
    job = await latest_job(session, case.id, status=JobStatus.succeeded)
    if job is None:
        return CaseView(case=case, job=None, funnel=EMPTY_FUNNEL, candidates=[])
    variants = (
        await session.scalars(
            select(Variant)
            .where(Variant.job_id == job.id)
            .options(selectinload(Variant.prediction), selectinload(Variant.decision))
        )
    ).all()
    case_terms = [p.hpo_id for p in case.phenotypes]
    gene_terms = await gene_terms_for(session, {v.gene for v in variants if v.gene})
    return CaseView(
        case=case,
        job=job,
        funnel=triage.funnel(variants, case_terms, gene_terms),
        candidates=triage.rank(variants, case_terms, gene_terms),
    )
@@ -0,0 +1,106 @@
 """Narrow a case's variants the way a clinical scientist does, and say why.
 The rank is a weighted sum of four parts a reviewer can audit. ClinVar is deliberately not one of
 them: it is shown beside the result as independent confirmation, so a variant never ranks highly
 merely because ClinVar already called it pathogenic.
 Rarity and consequence *filter* (the usual first pass); phenotype only *ranks*, because a real
 diagnosis can sit in a gene nobody has annotated yet and filtering on it would hide exactly that.
 """
 from collections.abc import Mapping, Sequence
 from dataclasses import dataclass
 from app.models import Variant
 WEIGHTS = {"phenotype": 0.35, "rarity": 0.25, "consequence": 0.20, "model": 0.20}
 RARE_AF = 0.001
 CANDIDATE_IMPACTS = frozenset({"HIGH", "MODERATE"})
 IMPACT_SEVERITY = {"HIGH": 1.0, "MODERATE": 0.6, "LOW": 0.2, "MODIFIER": 0.0}
 # Allele frequency ceiling -> score, rarest first.
 RARITY_STEPS = ((0.0, 1.0), (0.0001, 0.8), (0.001, 0.5), (0.01, 0.2))
@dataclass(frozen=True)
 class Funnel:
    """How many variants survive each narrowing step; the headline of the case page."""
    total: int
    rare: int
    candidates: int
    phenotype_matched: int
@dataclass(frozen=True)
 class Candidate:
    variant: Variant
    score: float
    components: dict[str, float]
    matched_terms: list[str]
    scored: bool
 def rarity_score(af: float | None) -> float:
    if af is None:  # absent from gnomAD
        return 1.0
    for ceiling, score in RARITY_STEPS:
        if af <= ceiling:
            return score
    return 0.0
 def consequence_score(impact: str | None) -> float:
    return IMPACT_SEVERITY.get(impact or "", 0.0)
 def phenotype_score(
    gene: str | None, case_terms: Sequence[str], gene_terms: Mapping[str, set[str]]
 ) -> tuple[float, list[str]]:
    """What fraction of the patient's terms HPO associates with this gene, and which ones."""
    if not gene or not case_terms:
        return 0.0, []
    annotated = gene_terms.get(gene, set())
    matched = [term for term in case_terms if term in annotated]
    return len(matched) / len(case_terms), matched
 def is_rare(variant: Variant) -> bool:
    return variant.gnomad_af is None or variant.gnomad_af < RARE_AF
 def is_candidate(variant: Variant) -> bool:
    return is_rare(variant) and variant.impact in CANDIDATE_IMPACTS
 def funnel(
    variants: Sequence[Variant], case_terms: Sequence[str], gene_terms: Mapping[str, set[str]]
 ) -> Funnel:
    rare = [v for v in variants if is_rare(v)]
    candidates = [v for v in rare if v.impact in CANDIDATE_IMPACTS]
    matched = sum(1 for v in candidates if phenotype_score(v.gene, case_terms, gene_terms)[1])
    return Funnel(len(variants), len(rare), len(candidates), matched)
 def evaluate(
    variant: Variant, case_terms: Sequence[str], gene_terms: Mapping[str, set[str]]
 ) -> Candidate:
    """Score one variant, whether or not it survived the filters."""
    phenotype, matched = phenotype_score(variant.gene, case_terms, gene_terms)
    prediction = variant.prediction
    components = {
        "phenotype": phenotype,
        "rarity": rarity_score(variant.gnomad_af),
        "consequence": consequence_score(variant.impact),
        "model": float(prediction.score) if prediction is not None else 0.0,
    }
    score = sum(WEIGHTS[name] * value for name, value in components.items())
    return Candidate(variant, score, components, matched, prediction is not None)
 def rank(
    variants: Sequence[Variant], case_terms: Sequence[str], gene_terms: Mapping[str, set[str]]
 ) -> list[Candidate]:
    candidates = [evaluate(v, case_terms, gene_terms) for v in variants if is_candidate(v)]
    # id breaks ties, so equal scores do not shuffle between requests.
    candidates.sort(key=lambda c: (-c.score, c.variant.id))
    return candidates
@@ -70,7 +70,8 @@ async def db(migrated_db: None) -> AsyncIterator[None]:
    async with engine.begin() as conn:
        await conn.execute(
-            text("TRUNCATE samples, jobs, variants, predictions RESTART IDENTITY CASCADE")
+            text("TRUNCATE cases, case_phenotypes, gene_phenotypes, jobs, variants, "
                 "predictions, variant_decisions RESTART IDENTITY CASCADE")
        )
    yield
@@ -2,20 +2,47 @@ import uuid
 from typing import Any
 from app.db import SessionLocal
-from app.models import Job, JobStatus, Sample, Variant
+from app.models import Case, CasePhenotype, GenePhenotype, Job, JobStatus, Prediction, Variant
 VARIANT_DEFAULTS: dict[str, Any] = {
    "chrom": "22", "pos": 1, "ref": "A", "alt": "G", "gene": "NF2",
    "impact": "HIGH", "consequence": "frameshift_variant", "gnomad_af": None, "annotations": {},
 }
-async def seed_job(
+async def seed_case(
-    variants: list[dict[str, Any]], status: JobStatus = JobStatus.succeeded
+    *,
-) -> uuid.UUID:
+    phenotypes: list[tuple[str, str]] | None = None,
-    """Insert a sample, a job and its variants; each variant dict overrides the defaults."""
+    variants: list[dict[str, Any]] | None = None,
    gene_terms: dict[str, list[tuple[str, str]]] | None = None,
    status: JobStatus = JobStatus.succeeded,
    name: str | None = None,
 ) -> tuple[uuid.UUID, uuid.UUID]:
    """Insert a case, its phenotypes, a job and its variants. Returns (case_id, job_id).
    `variants` entries override VARIANT_DEFAULTS; a "score" key becomes a Prediction.
    """
    async with SessionLocal() as s:
-        sample = Sample(name=f"s-{uuid.uuid4()}", vcf_uri="gs://b/x.vcf.gz", assembly="GRCh38")
+        case = Case(
-        job = Job(sample=sample, status=status)
+            name=name or f"case-{uuid.uuid4()}",
-        rows = [
+            vcf_uri="gs://bucket/proband.vcf.gz",
-            Variant(job=job, **{"chrom": "22", "pos": 1, "ref": "A", "alt": "G", "annotations": {}} | v)
+            assembly="GRCh38",
-            for v in variants
+            phenotypes=[CasePhenotype(hpo_id=hpo, label=label) for hpo, label in (phenotypes or [])],
-        ]
+        )
-        s.add_all([sample, job, *rows])
+        job = Job(case=case, status=status, vep_version="113.0")
        s.add_all([case, job])
        for gene, terms in (gene_terms or {}).items():
            s.add_all(
                GenePhenotype(gene_symbol=gene, hpo_id=hpo, hpo_name=label) for hpo, label in terms
            )
        for spec in variants or []:
            fields = VARIANT_DEFAULTS | spec
            score = fields.pop("score", None)
            variant = Variant(job=job, **fields)
            s.add(variant)
            if score is not None:
                await s.flush()
                s.add(Prediction(variant_id=variant.id, model_name="rarelens-pathogenicity",
                                 model_version="demo", score=float(score)))
        await s.commit()
-        return job.id
+        return case.id, job.id
@@ -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")
+        case = Case(name=f"c-{uuid.uuid4()}", vcf_uri="gs://bucket/x.vcf.gz", assembly="GRCh38")
-        job = Job(sample=sample, status=JobStatus.succeeded)
+        job = Job(case=case, status=JobStatus.succeeded)
-        s.add_all([sample, job])
+        s.add_all([case, job])
        await s.commit()
        job_id = job.id
@@ -0,0 +1,137 @@
 """The triage workflow: a case with a phenotype, ranked candidates, decisions, a report."""
 import uuid
 import pytest
 from factories import seed_case
 from httpx import AsyncClient
 NF2_TERMS = [("HP:0000365", "Hearing impairment"), ("HP:0009592", "Vestibular schwannoma")]
 CASE_TERMS = [*NF2_TERMS, ("HP:0002321", "Vertigo")]
 async def a_case_with_candidates() -> tuple[uuid.UUID, uuid.UUID]:
    return await seed_case(
        phenotypes=CASE_TERMS,
        gene_terms={"NF2": NF2_TERMS},
        variants=[
            {"id": 1, "gene": "NF2", "pos": 1000, "impact": "HIGH", "score": 0.94,
             "clinvar_sig": "pathogenic"},
            {"id": 2, "gene": "CHEK2", "pos": 2000, "impact": "MODERATE", "gnomad_af": 0.0004,
             "score": 0.55},
            {"id": 3, "gene": "TTN", "pos": 3000, "impact": "MODIFIER", "gnomad_af": None},
            {"id": 4, "gene": "APOE", "pos": 4000, "impact": "HIGH", "gnomad_af": 0.3},
        ],
    )
@pytest.mark.usefixtures("db")
 async def test_a_case_keeps_its_phenotype(client: AsyncClient) -> None:
    body = {
        "name": "PROBAND-01",
        "vcf_uri": "gs://bucket/proband.vcf.gz",
        "phenotypes": [{"hpo_id": h, "label": lab} for h, lab in NF2_TERMS],
    }
    r = await client.post("/api/cases", json=body)
    assert r.status_code == 201, r.text
    assert [p["label"] for p in r.json()["phenotypes"]] == [lab for _, lab in NF2_TERMS]
    listed = (await client.get("/api/cases")).json()
    assert listed[0]["name"] == "PROBAND-01"
    assert listed[0]["shortlisted"] == 0
@pytest.mark.usefixtures("db")
 async def test_the_funnel_shows_the_narrowing(client: AsyncClient) -> None:
    case_id, _ = await a_case_with_candidates()
    page = (await client.get(f"/api/cases/{case_id}/candidates")).json()
    # 4 variants -> 3 rare -> 2 rare and coding -> 1 of those in a phenotype-matched gene
    assert page["funnel"] == {"total": 4, "rare": 3, "candidates": 2, "phenotype_matched": 1}
@pytest.mark.usefixtures("db")
 async def test_the_phenotype_matched_variant_ranks_first_with_its_reasons(
    client: AsyncClient,
 ) -> None:
    case_id, _ = await a_case_with_candidates()
    page = (await client.get(f"/api/cases/{case_id}/candidates")).json()
    assert [c["variant"]["gene"] for c in page["items"]] == ["NF2", "CHEK2"]
    top = page["items"][0]
    assert [t["label"] for t in top["matched_terms"]] == ["Hearing impairment", "Vestibular schwannoma"]
    assert top["components"]["phenotype"] == pytest.approx(2 / 3, abs=1e-4)
    assert top["components"]["rarity"] == 1.0
    assert page["weights"]["phenotype"] == 0.35
    # ClinVar is evidence, not an input to the rank.
    assert top["variant"]["clinvar_sig"] == "pathogenic"
@pytest.mark.usefixtures("db")
 async def test_a_reviewer_decides_and_the_decision_sticks(client: AsyncClient) -> None:
    case_id, _ = await a_case_with_candidates()
    variant_id = (await client.get(f"/api/cases/{case_id}/candidates")).json()["items"][0]["variant"]["id"]
    r = await client.post(
        f"/api/variants/{variant_id}/decision",
        json={"state": "shortlisted", "reason": "fits the phenotype", "note": "confirm by Sanger"},
    )
    assert r.status_code == 200, r.text
    # Changing your mind replaces the decision rather than failing.
    r = await client.post(f"/api/variants/{variant_id}/decision", json={"state": "dismissed"})
    assert r.status_code == 200
    detail = (await client.get(f"/api/variants/{variant_id}")).json()
    assert detail["decision"]["state"] == "dismissed"
    assert (await client.get("/api/cases")).json()[0]["shortlisted"] == 0
@pytest.mark.usefixtures("db")
 async def test_the_variant_panel_carries_the_evidence(client: AsyncClient) -> None:
    case_id, _ = await a_case_with_candidates()
    variant_id = (await client.get(f"/api/cases/{case_id}/candidates")).json()["items"][0]["variant"]["id"]
    detail = (await client.get(f"/api/variants/{variant_id}")).json()
    assert detail["variant"]["hgvsp"] is None or isinstance(detail["variant"]["hgvsp"], str)
    assert detail["score"] > 0
    assert [t["hpo_id"] for t in detail["matched_terms"]] == [h for h, _ in NF2_TERMS]
    assert "annotations" in detail
@pytest.mark.usefixtures("db")
 async def test_the_report_is_the_decision_trail(client: AsyncClient) -> None:
    case_id, _ = await a_case_with_candidates()
    items = (await client.get(f"/api/cases/{case_id}/candidates")).json()["items"]
    await client.post(f"/api/variants/{items[0]['variant']['id']}/decision",
                      json={"state": "shortlisted", "reason": "fits the phenotype"})
    await client.post(f"/api/variants/{items[1]['variant']['id']}/decision",
                      json={"state": "dismissed", "reason": "gene unrelated to phenotype"})
    report = (await client.get(f"/api/cases/{case_id}/report")).json()
    assert report["funnel"]["candidates"] == 2
    assert [v["variant"]["gene"] for v in report["shortlisted"]] == ["NF2"]
    assert report["shortlisted"][0]["decision"]["reason"] == "fits the phenotype"
    assert [v["variant"]["gene"] for v in report["dismissed"]] == ["CHEK2"]
    assert report["provenance"]["vep_version"] == "113.0"
@pytest.mark.usefixtures("db")
 async def test_candidates_can_still_be_filtered(client: AsyncClient) -> None:
    case_id, _ = await a_case_with_candidates()
    page = (await client.get(f"/api/cases/{case_id}/candidates", params={"gene": "chek2"})).json()
    assert [c["variant"]["gene"] for c in page["items"]] == ["CHEK2"]
    # The funnel still describes the whole case, not the filtered view.
    assert page["funnel"]["total"] == 4
@pytest.mark.usefixtures("db")
 async def test_phenotype_search_backs_the_picker(client: AsyncClient) -> None:
    await seed_case(gene_terms={"NF2": NF2_TERMS}, variants=[])
    found = (await client.get("/api/phenotypes", params={"q": "vestibular"})).json()
    assert found == [{"hpo_id": "HP:0009592", "label": "Vestibular schwannoma"}]
@pytest.mark.usefixtures("db")
 async def test_candidates_before_the_pipeline_has_run(client: AsyncClient) -> None:
    r = await client.post("/api/cases", json={"name": "empty", "vcf_uri": "gs://bucket/x.vcf.gz"})
    page = (await client.get(f"/api/cases/{r.json()['id']}/candidates")).json()
    assert page["items"] == []
    assert page["funnel"]["total"] == 0
@@ -26,9 +26,9 @@ class FakeJobsClient:
        return self.result
-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
@@ -49,9 +49,9 @@ async def test_annotate_executes_the_job_with_pipeline_arguments(
 ) -> None:
    jobs = FakeJobsClient(FakeOperation("projects/p/locations/l/executions/rarelens-nextflow-abc12"))
    monkeypatch.setattr(events, "_jobs_client", lambda: jobs)
-    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"] == "running"
@@ -74,9 +74,9 @@ async def test_a_failed_execution_call_marks_the_job_failed(
    monkeypatch.setattr(
        events, "_jobs_client", lambda: FakeJobsClient(RuntimeError("403 permission 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 permission denied" in job["log"]
@@ -91,7 +91,7 @@ async def test_cloud_run_job_takes_precedence_over_pubsub(
    monkeypatch.setattr(
        events, "_publisher", lambda: pytest.fail("Pub/Sub must not be used in the serverless track")
    )
-    sample_id = await new_sample(client)
+    case_id = await new_case(client)
-    assert (await client.post(f"/api/samples/{sample_id}/annotate")).json()["status"] == "running"
+    assert (await client.post(f"/api/cases/{case_id}/annotate")).json()["status"] == "running"
    assert len(jobs.requests) == 1
@@ -5,8 +5,8 @@ from httpx import AsyncClient
@pytest.mark.usefixtures("db")
 async def test_resources_live_under_api_prefix(client: AsyncClient) -> None:
    # The ingress forwards /api/* unchanged, so the app itself must serve that prefix.
-    assert (await client.get("/api/samples")).status_code == 200
+    assert (await client.get("/api/cases")).status_code == 200
-    assert (await client.get("/samples")).status_code == 404
+    assert (await client.get("/cases")).status_code == 404
 async def test_health_stays_at_root_for_probes(client: AsyncClient) -> None:
@@ -1,18 +0,0 @@
 import pytest
 from httpx import AsyncClient
@pytest.mark.usefixtures("db")
 async def test_duplicate_sample_name_is_409_not_500(client: AsyncClient) -> None:
    body = {"name": "HG002", "vcf_uri": "gs://bucket/hg002.vcf.gz"}
    assert (await client.post("/api/samples", json=body)).status_code == 201
    r = await client.post("/api/samples", json=body)
    assert r.status_code == 409
    assert "HG002" in r.json()["detail"]
 async def test_unknown_assembly_is_rejected(client: AsyncClient) -> None:
    r = await client.post(
        "/api/samples", json={"name": "a", "vcf_uri": "gs://bucket/a.vcf.gz", "assembly": "hg19"}
    )
    assert r.status_code == 422
@@ -4,11 +4,12 @@ import uuid
 import numpy as np
 import pandas as pd
 import pytest
 from factories import seed_case
 from httpx import AsyncClient
 from sqlalchemy import select
 from app.db import SessionLocal
-from app.models import Job, JobStatus, Prediction, Sample, Variant
+from app.models import JobStatus, Prediction, Variant
 from app.services import scoring
@@ -40,20 +41,16 @@ class FakeModel:
        return np.full(len(frame), self.score)
-async def make_job(status: JobStatus, n_variants: int) -> uuid.UUID:
+async def make_case(status: JobStatus, n_variants: int) -> tuple[uuid.UUID, uuid.UUID]:
-    async with SessionLocal() as s:
+    return await seed_case(
-        sample = Sample(name=f"s-{uuid.uuid4()}", vcf_uri="gs://b/x.vcf.gz", assembly="GRCh38")
+        status=status,
-        job = Job(sample=sample, status=status)
+        variants=[{"pos": i + 1, "annotations": {}} for i in range(n_variants)],
-        s.add_all([sample, job, *(variant(job=job, pos=i + 1) for i in range(n_variants))])
+    )
        await s.commit()
        return job.id
 async def predictions(job_id: uuid.UUID) -> list[Prediction]:
    async with SessionLocal() as s:
-        rows = await s.scalars(
+        rows = await s.scalars(select(Prediction).join(Variant).where(Variant.job_id == job_id))
            select(Prediction).join(Variant).where(Variant.job_id == job_id)
        )
        return list(rows)
@@ -61,15 +58,15 @@ async def predictions(job_id: uuid.UUID) -> list[Prediction]:
 async def test_scoring_twice_updates_instead_of_failing(
    client: AsyncClient, monkeypatch: pytest.MonkeyPatch
 ) -> None:
-    job_id = await make_job(JobStatus.succeeded, n_variants=3)
+    case_id, job_id = await make_case(JobStatus.succeeded, n_variants=3)
    monkeypatch.setattr(scoring, "load_model", lambda: (FakeModel(0.9), "7"))
-    r = await client.post(f"/api/predictions/score/{job_id}")
+    r = await client.post(f"/api/cases/{case_id}/score")
    assert r.status_code == 200, r.text
-    assert r.json() == {"job_id": str(job_id), "scored": 3, "model_version": "7"}
+    assert r.json() == {"case_id": str(case_id), "scored": 3, "model_version": "7"}
    monkeypatch.setattr(scoring, "load_model", lambda: (FakeModel(0.2), "8"))
-    r = await client.post(f"/api/predictions/score/{job_id}")
+    r = await client.post(f"/api/cases/{case_id}/score")
    assert r.status_code == 200, r.text
    preds = await predictions(job_id)
@@ -78,13 +75,28 @@ async def test_scoring_twice_updates_instead_of_failing(
@pytest.mark.usefixtures("db")
-async def test_scoring_unknown_job_is_404(client: AsyncClient) -> None:
+async def test_scoring_an_unknown_case_is_404(client: AsyncClient) -> None:
-    r = await client.post(f"/api/predictions/score/{uuid.uuid4()}")
+    r = await client.post(f"/api/cases/{uuid.uuid4()}/score")
    assert r.status_code == 404
@pytest.mark.usefixtures("db")
-async def test_scoring_unfinished_job_is_409(client: AsyncClient) -> None:
+async def test_scoring_before_the_annotation_finishes_is_409(client: AsyncClient) -> None:
-    job_id = await make_job(JobStatus.running, n_variants=1)
+    case_id, _ = await make_case(JobStatus.running, n_variants=1)
-    r = await client.post(f"/api/predictions/score/{job_id}")
+    r = await client.post(f"/api/cases/{case_id}/score")
    assert r.status_code == 409
@pytest.mark.usefixtures("db")
 async def test_an_unreachable_model_registry_is_explained_not_a_500(
    client: AsyncClient, monkeypatch: pytest.MonkeyPatch
 ) -> None:
    case_id, _ = await make_case(JobStatus.succeeded, n_variants=1)
    def unreachable() -> tuple:
        raise ConnectionError("connection refused to http://localhost:5000")
    monkeypatch.setattr(scoring, "load_model", unreachable)
    r = await client.post(f"/api/cases/{case_id}/score")
    assert r.status_code == 503
    assert "connection refused" in r.json()["detail"]
@@ -2,7 +2,7 @@ import pytest
 from httpx import AsyncClient
 from pydantic import ValidationError
-from app.schemas import SampleCreate
+from app.schemas import CaseCreate
@pytest.mark.parametrize(
@@ -16,7 +16,7 @@ from app.schemas import SampleCreate
    ],
 )
 def test_vcf_uri_accepts_gcs_objects_and_files_under_the_data_root(uri: str) -> None:
-    assert SampleCreate(name="s", vcf_uri=uri).vcf_uri == uri
+    assert CaseCreate(name="s", vcf_uri=uri).vcf_uri == uri
@pytest.mark.parametrize(
@@ -36,11 +36,11 @@ def test_vcf_uri_accepts_gcs_objects_and_files_under_the_data_root(uri: str) ->
 )
 def test_vcf_uri_rejects_everything_else(uri: str) -> None:
    with pytest.raises(ValidationError):
-        SampleCreate(name="s", vcf_uri=uri)
+        CaseCreate(name="s", vcf_uri=uri)
 async def test_bad_vcf_uri_is_422_at_the_api(client: AsyncClient) -> None:
-    r = await client.post("/api/samples", json={"name": "s", "vcf_uri": "/etc/passwd"})
+    r = await client.post("/api/cases", json={"name": "s", "vcf_uri": "/etc/passwd"})
    assert r.status_code == 422
@@ -0,0 +1,101 @@
 """Ranking is the scientific claim this app makes, so it is tested as pure logic."""
 import pytest
 from app.models import Prediction, Variant
 from app.services import triage
 def variant(**kw: object) -> Variant:
    fields: dict = {
        "id": 1, "chrom": "22", "pos": 100, "ref": "A", "alt": "G",
        "gene": "NF2", "impact": "HIGH", "consequence": "frameshift_variant",
        "gnomad_af": None, "clinvar_sig": None, "annotations": {},
    }
    fields.update(kw)
    score = fields.pop("score", None)
    v = Variant(**fields)
    if score is not None:
        v.prediction = Prediction(model_name="m", model_version="1", score=float(score))
    return v
 def test_weights_sum_to_one() -> None:
    assert sum(triage.WEIGHTS.values()) == pytest.approx(1.0)
@pytest.mark.parametrize(
    ("af", "expected"),
    [(None, 1.0), (0.0, 1.0), (0.00005, 0.8), (0.0005, 0.5), (0.005, 0.2), (0.05, 0.0)],
 )
 def test_rarity_rewards_absence_from_gnomad(af: float | None, expected: float) -> None:
    assert triage.rarity_score(af) == expected
@pytest.mark.parametrize(
    ("impact", "expected"),
    [("HIGH", 1.0), ("MODERATE", 0.6), ("LOW", 0.2), ("MODIFIER", 0.0), (None, 0.0), ("?", 0.0)],
 )
 def test_consequence_severity(impact: str | None, expected: float) -> None:
    assert triage.consequence_score(impact) == expected
 def test_phenotype_match_is_the_fraction_of_the_patients_terms() -> None:
    gene_terms = {"NF2": {"HP:0000365", "HP:0009592"}}
    case_terms = ["HP:0000365", "HP:0009592", "HP:0002321", "HP:0000598"]
    score, matched = triage.phenotype_score("NF2", case_terms, gene_terms)
    assert score == 0.5
    assert matched == ["HP:0000365", "HP:0009592"]
 def test_phenotype_match_is_zero_for_genes_hpo_has_never_annotated() -> None:
    assert triage.phenotype_score("NOVEL1", ["HP:0000365"], {}) == (0.0, [])
 def test_phenotype_match_is_zero_when_no_phenotype_was_entered() -> None:
    assert triage.phenotype_score("NF2", [], {"NF2": {"HP:0000365"}}) == (0.0, [])
 def test_the_funnel_counts_each_narrowing_step() -> None:
    variants = [
        variant(id=1, gnomad_af=None, impact="HIGH", gene="NF2"),          # rare, coding, matched
        variant(id=2, gnomad_af=0.0002, impact="MODERATE", gene="CHEK2"),  # rare, coding
        variant(id=3, gnomad_af=0.3, impact="HIGH", gene="NF2"),           # common
        variant(id=4, gnomad_af=None, impact="MODIFIER", gene="NF2"),      # rare, non-coding
    ]
    funnel = triage.funnel(variants, case_terms=["HP:0000365"], gene_terms={"NF2": {"HP:0000365"}})
    assert (funnel.total, funnel.rare, funnel.candidates, funnel.phenotype_matched) == (4, 3, 2, 1)
 def test_the_diagnosis_outranks_the_noise() -> None:
    gene_terms = {"NF2": {"HP:0000365", "HP:0009592"}}
    case_terms = ["HP:0000365", "HP:0009592"]
    diagnosis = variant(id=1, gene="NF2", impact="HIGH", gnomad_af=None, score=0.94)
    plausible = variant(id=2, gene="CHEK2", impact="MODERATE", gnomad_af=0.0004, score=0.55)
    noise = variant(id=3, gene="TTN", impact="MODERATE", gnomad_af=0.0009, score=0.10)
    ranked = triage.rank([noise, plausible, diagnosis], case_terms, gene_terms)
    assert [c.variant.id for c in ranked] == [1, 2, 3]
    top = ranked[0]
    assert top.matched_terms == case_terms
    assert top.components["phenotype"] == 1.0
    assert top.score == pytest.approx(0.35 + 0.25 + 0.20 + 0.20 * 0.94)
 def test_an_unscored_variant_still_ranks_and_says_so() -> None:
    [candidate] = triage.rank([variant(id=1, gnomad_af=None)], [], {})
    assert candidate.components["model"] == 0.0
    assert candidate.scored is False
 def test_common_and_non_coding_variants_are_not_candidates() -> None:
    variants = [
        variant(id=1, gnomad_af=0.2, impact="HIGH"),
        variant(id=2, gnomad_af=None, impact="MODIFIER"),
    ]
    assert triage.rank(variants, [], {}) == []
 def test_ranking_is_deterministic_for_equal_scores() -> None:
    a = variant(id=7, gene="AAA", chrom="1", pos=10, gnomad_af=None)
    b = variant(id=3, gene="BBB", chrom="1", pos=10, gnomad_af=None)
    assert [c.variant.id for c in triage.rank([a, b], [], {})] == [3, 7]
@@ -1,46 +0,0 @@
 import uuid
 import pytest
 from factories import seed_job
 from httpx import AsyncClient
@pytest.mark.parametrize(
    "paging", [{"limit": 0}, {"limit": -1}, {"limit": 501}, {"offset": -1}]
 )
 async def test_out_of_range_paging_is_422_not_500(client: AsyncClient, paging: dict) -> None:
    r = await client.get("/api/variants", params={"job_id": str(uuid.uuid4()), **paging})
    assert r.status_code == 422
 async def positions(client: AsyncClient, job_id: uuid.UUID) -> list[tuple[str, int, str]]:
    r = await client.get("/api/variants", params={"job_id": str(job_id)})
    assert r.status_code == 200, r.text
    return [(v["chrom"], v["pos"], v["alt"]) for v in r.json()["items"]]
@pytest.mark.usefixtures("db")
 async def test_chromosomes_sort_naturally(client: AsyncClient) -> None:
    job_id = await seed_job([{"chrom": c} for c in ["10", "MT", "2", "X", "chr3", "1", "Y"]])
    assert [c for c, _, _ in await positions(client, job_id)] == [
        "1", "2", "chr3", "10", "X", "Y", "MT",
    ]
@pytest.mark.usefixtures("db")
 async def test_same_position_keeps_insertion_order_across_pages(client: AsyncClient) -> None:
    # Split multiallelics share chrom/pos; without a tiebreak, pages can repeat or skip rows.
    job_id = await seed_job([{"pos": 5, "alt": a} for a in "CGT"])
    assert [a for _, _, a in await positions(client, job_id)] == ["C", "G", "T"]
@pytest.mark.usefixtures("db")
 async def test_long_vep_strings_are_stored(client: AsyncClient) -> None:
    clin_sig = ",".join(["conflicting_classifications_of_pathogenicity"] * 8)
    consequence = (
        "splice_region_variant&splice_polypyrimidine_tract_variant&intron_variant"
        "&NMD_transcript_variant&non_coding_transcript_variant"
    )
    job_id = await seed_job([{"clinvar_sig": clin_sig, "consequence": consequence}])
    [v] = (await client.get("/api/variants", params={"job_id": str(job_id)})).json()["items"]
    assert (v["clinvar_sig"], v["consequence"]) == (clin_sig, consequence)
@@ -1,6 +1,6 @@
 # Test data
-`make data` fetches the demo slice automatically. Provenance, licences, citations and the
+`make data` fetches the demo slice and `make demo-case` builds the simulated proband. Provenance, licences, citations and the
 evaluation plan live in [../docs/data.md](../docs/data.md).
 No patient data. Use public sources only:
@@ -2,8 +2,9 @@
 ```mermaid
 flowchart LR
-  U[Scientist] -->|browser| W[SvelteKit web]
+  U[Scientist] -->|phenotype + VCF| W[SvelteKit web]
  W -->|REST /api| A[FastAPI]
  H[(HPO gene-phenotype annotations)] --> A
  A --> P[(PostgreSQL / Cloud SQL)]
  A -->|publish vcf-uploaded| Q[Pub/Sub]
  Q --> E[Argo Events sensor]
@@ -12,6 +13,7 @@ flowchart LR
  B -->|reads VCF, VEP cache| G[(GCS bucket)]
  B -->|writes variants, marks job succeeded| P
  AW -.->|exit handler marks job failed| P
  A -->|rank: phenotype, rarity, consequence, model| C[Ranked candidates -> decisions -> report]
  A -->|models:/rarelens-pathogenicity@production| M[MLflow registry]
  T[ml/train.py] --> M
  GH[GitHub Actions] -->|images via WIF| AR[Artifact Registry]
@@ -19,6 +21,33 @@ flowchart LR
  R --> CD[ArgoCD] --> K[GKE Autopilot]
 ```
 ## The triage model
 A **case** is a proband: a VCF plus the HPO terms observed in that patient. Annotation produces
 variants; the model scores them; ranking then answers the only question that matters — which few
 variants could explain *this* phenotype.
 Rarity (<0.1% in gnomAD) and consequence (HIGH or MODERATE) *filter*, which is the usual first
 pass. Phenotype only *ranks*: a real diagnosis can sit in a gene nobody has annotated yet, and
 filtering on phenotype would hide exactly that case. The rank is a weighted sum whose parts are
 shown next to every candidate (`app/services/triage.py`):
 | Component | Weight |
 |---|---|
 | phenotype terms of this patient annotated to the gene | 0.35 |
 | rarity in gnomAD | 0.25 |
 | consequence severity | 0.20 |
 | model P(pathogenic) | 0.20 |
 **ClinVar is deliberately not an input.** It sits beside the result as independent confirmation, so
 the demo never ranks a variant highly merely because ClinVar already called it pathogenic. On the
 simulated NF2 case the planted variant ranks first on phenotype, rarity and consequence alone, and
 ClinVar agrees afterwards.
 Each candidate can be shortlisted or dismissed with a reason and a note; the case report is that
 decision trail plus the funnel counts and the provenance (VEP version, model version, run time).
 There is no authentication, so decisions are shared by everyone who opens the demo.
 ## Two deployment tracks
 The same images and the same pipeline, deployed two ways (`infra/terraform/variables.tf`):
@@ -28,6 +28,7 @@ benchmarks variant callers against, so it is both realistic and unambiguously sh
 | **gnomAD** v4 | allele frequency feature and filter | `gs://gcp-public-data--gnomad`, `s3://gnomad-public-us-east-1` | free use, no restriction | Chen et al., *Nature* 625:92–100, 2024. [10.1038/s41586-023-06045-0](https://doi.org/10.1038/s41586-023-06045-0); Karczewski et al., *Nature* 581:434–443, 2020. [10.1038/s41586-020-2308-7](https://doi.org/10.1038/s41586-020-2308-7) |
 | **1000 Genomes** 30x | optional cohort/trio data | EBI FTP, `s3://1000genomes` | fully open, no access restriction | Byrska-Bishop et al., *Cell* 185(18):3426–3440.e19, 2022. [10.1016/j.cell.2022.08.004](https://doi.org/10.1016/j.cell.2022.08.004) |
 | **MANE Select** | one transcript per gene, if transcript choice ever matters | Ensembl/RefSeq | open | Morales et al., *Nature* 604:310–315, 2022. [10.1038/s41586-022-04558-8](https://doi.org/10.1038/s41586-022-04558-8) |
 | **Human Phenotype Ontology** gene-to-phenotype | what the phenotype half of the ranking matches against (`make hpo`) | `purl.obolibrary.org/obo/hp/hpoa/genes_to_phenotype.txt` | free to use with attribution | Gargano et al., *Nucleic Acids Res* 52(D1):D1333–D1346, 2024. [10.1093/nar/gkad1005](https://doi.org/10.1093/nar/gkad1005) |
 ## Tools and scores
@@ -40,6 +41,24 @@ benchmarks variant callers against, so it is both realistic and unambiguously sh
 Neither score is required: `rarelens_ml.features` treats a missing CADD or AlphaMissense value as
 NaN and LightGBM handles it, so the pipeline runs without the plugin data.
 ## The simulated proband
 `make demo-case` builds `data/proband-simulated.vcf.gz`: real GIAB HG002 variants as background
 plus one real ClinVar 2-star pathogenic variant in a disease gene (NF2 by default, giving
 neurofibromatosis type 2). Spiking a known variant into a public genome is how phenotype-driven
 triage tools are benchmarked, every input is public, and the file's header says SIMULATED. It is
 not a patient, and no part of it is invented: both the background and the planted variant are real
 published records.
 The point of it is that the case has a right answer, so the ranking can be checked rather than
 admired. Give the case the phenotype of the planted disease and the planted variant should rank
 first — on phenotype, rarity and consequence, with ClinVar agreeing only afterwards.
 **Caveat when running without a VEP cache.** `VEP_DATABASE=true` queries Ensembl's public database
 instead of the 25 GB cache. It returns no gnomAD frequencies, so every variant looks absent from
 gnomAD and the rarity term stops discriminating. Fine for showing the mechanics; use the cache for
 anything you would quote.
 ## Evaluating the model honestly
 The model trains on ClinVar labels and is scored on ClinVar-labelled variants, which is exactly
@@ -0,0 +1,65 @@
 #!/usr/bin/env python3
 """Load HPO's gene-to-phenotype annotations into the gene_phenotypes table.
 This is the reference data the ranking matches a case's phenotype against. Source file:
 https://purl.obolibrary.org/obo/hp/hpoa/genes_to_phenotype.txt (HPO release, ~20 MB).
 Cite the Human Phenotype Ontology when showing results; see docs/data.md.
 """
 import argparse
 import csv
 import io
 import os
 import sys
 import urllib.request
 from sqlalchemy import create_engine, text
 from sqlalchemy.engine import make_url
 URL = "https://purl.obolibrary.org/obo/hp/hpoa/genes_to_phenotype.txt"
 def rows(handle: io.TextIOBase) -> list[tuple[str, str, str]]:
    """Unique (gene, term) pairs; the file repeats them once per associated disease."""
    seen: set[tuple[str, str]] = set()
    out: list[tuple[str, str, str]] = []
    for row in csv.DictReader(handle, delimiter="\t"):
        gene, hpo_id, name = row["gene_symbol"], row["hpo_id"], row["hpo_name"]
        if not gene or not hpo_id or (gene, hpo_id) in seen:
            continue
        seen.add((gene, hpo_id))
        out.append((gene[:60], hpo_id[:20], name[:200]))
    return out
 def main() -> None:
    p = argparse.ArgumentParser()
    p.add_argument("--url", default=URL)
    p.add_argument("--file", help="use a local copy instead of downloading")
    a = p.parse_args()
    url = os.environ.get("DATABASE_URL")
    if not url:
        sys.exit("DATABASE_URL is not set")
    if a.file:
        with open(a.file) as fh:
            annotations = rows(fh)
    else:
        print(f"downloading {a.url}", file=sys.stderr)
        with urllib.request.urlopen(a.url) as response:  # noqa: S310 - fixed HPO release URL
            annotations = rows(io.TextIOWrapper(response, encoding="utf-8"))
    print(f"{len(annotations)} gene/term pairs", file=sys.stderr)
    engine = create_engine(make_url(url).set(drivername="postgresql+psycopg"))
    with engine.begin() as conn:
        conn.execute(text("TRUNCATE gene_phenotypes RESTART IDENTITY"))
        cursor = conn.connection.cursor()
        with cursor.copy("COPY gene_phenotypes (gene_symbol, hpo_id, hpo_name) FROM STDIN") as copy:
            for row in annotations:
                copy.write_row(row)
    print(f"loaded {len(annotations)} annotations", file=sys.stderr)
 if __name__ == "__main__":
    main()
@@ -0,0 +1,52 @@
 #!/usr/bin/env bash
 # Build a SIMULATED proband VCF: real GIAB HG002 variants as background, plus one real ClinVar
 # pathogenic variant in a disease gene, which becomes the diagnosis the triage should find.
 #
 # Spiking a known variant into a public genome is how phenotype-driven triage tools are
 # benchmarked. Every input here is public and openly licensed, and this is not a real patient.
 # Provenance and citations: docs/data.md
 set -euo pipefail
 IMAGE=${BCFTOOLS_IMAGE:-quay.io/biocontainers/bcftools:1.20--h8b25389_0}
 GENE=${GENE:-NF2}
 REGION=${REGION:-chr22:20000000-31000000}
 BACKGROUND=${BACKGROUND:-12}          # kept small: VEP's database mode is slow per variant
 OUT_DIR=${OUT_DIR:-data}
 CLINVAR=${CLINVAR:-https://ftp.ncbi.nlm.nih.gov/pub/clinvar/vcf_GRCh38/clinvar.vcf.gz}
 GIAB=${GIAB:-https://ftp-trace.ncbi.nlm.nih.gov/ReferenceSamples/giab/release/AshkenazimTrio/HG002_NA24385_son/NISTv4.2.1/GRCh38/HG002_GRCh38_1_22_v4.2.1_benchmark.vcf.gz}
 mkdir -p "$OUT_DIR"
 docker run --rm -v "$PWD/$OUT_DIR:/out" "$IMAGE" bash -eu -c "
  echo '==> background: GIAB HG002 $REGION' >&2
  bcftools view -H -r '$REGION' '$GIAB' \
    | awk '\$5 !~ /,/ && length(\$4) < 20 && length(\$5) < 20' \
    | awk 'NR % 149 == 0' \
    | head -n $BACKGROUND \
    | awk -v OFS='\t' '{ sub(/^chr/, \"\", \$1); print \$1, \$2, \".\", \$4, \$5, \".\", \"PASS\", \".\" }' \
    > /out/_background.tsv
  echo '==> diagnosis: a ClinVar pathogenic variant in $GENE' >&2
  bcftools view -H -r 22 -i 'INFO/CLNSIG ~ \"Pathogenic\" && INFO/GENEINFO ~ \"${GENE}:\" && INFO/CLNREVSTAT ~ \"multiple_submitters\"' '$CLINVAR' \
    | awk 'length(\$4) < 20 && length(\$5) < 20' \
    | head -n 1 \
    | awk -v OFS='\t' '{ print \$1, \$2, \".\", \$4, \$5, \".\", \"PASS\", \".\" }' \
    > /out/_spike.tsv
  test -s /out/_background.tsv || { echo 'no background variants found' >&2; exit 1; }
  test -s /out/_spike.tsv || { echo 'no 2-star pathogenic ClinVar variant found for $GENE' >&2; exit 1; }
  {
    printf '##fileformat=VCFv4.2\n'
    printf '##source=rarelens SIMULATED proband: GIAB HG002 background + one ClinVar pathogenic %s variant\n' '$GENE'
    printf '##contig=<ID=22,length=50818468>\n'
    printf '#CHROM\tPOS\tID\tREF\tALT\tQUAL\tFILTER\tINFO\n'
    sort -k2,2n /out/_background.tsv /out/_spike.tsv
  } | bgzip > /out/proband-simulated.vcf.gz
  tabix -f -p vcf /out/proband-simulated.vcf.gz
  rm -f /out/_background.tsv
 "
 echo
 echo "wrote $OUT_DIR/proband-simulated.vcf.gz"
 echo "the planted diagnosis (chrom pos ref alt):"
 awk '{print "  " $1, $2, $4, $5}' "$OUT_DIR/_spike.tsv"
 rm -f "$OUT_DIR/_spike.tsv"
@@ -12,7 +12,7 @@
 }
 html { background: var(--paper); color: var(--ink); font-family: var(--sans); font-size: 17px; }
 body { margin: 0; }
-main { max-width: 1100px; margin: 0 auto; padding: 2.5rem 1.5rem; }
+main { max-width: 1280px; margin: 0 auto; padding: 2.5rem 1.5rem; }
 h1 { font-weight: 600; font-size: 2rem; letter-spacing: -0.01em; margin: 0 0 0.5rem; }
 h2 { font-weight: 600; font-size: 1.25rem; margin: 2rem 0 0.75rem; }
 p.lede { color: var(--ink-soft); max-width: 60ch; margin: 0 0 2rem; }
@@ -40,3 +40,89 @@ td.coord, td.hgvs { font-family: var(--mono); font-size: 0.85rem; }  /* aligned
  .spinner { animation: spin 0.9s linear infinite; }
 }
@keyframes spin { to { transform: rotate(360deg); } }
 /* --- triage ------------------------------------------------------------------------------- */
 .muted { color: var(--ink-soft); }
 .actions { display: flex; align-items: center; gap: 1rem; }
 .reportlink { font-weight: 600; }
 .provenance { font-size: 0.85rem; margin: 0.35rem 0 0; }
 .casehead { margin-bottom: 1.25rem; }
 .casehead h1 { margin-bottom: 0.4rem; }
 .log { white-space: pre-wrap; background: white; border: 1px solid var(--line); padding: 0.75rem;
  max-height: 14rem; overflow: auto; font-size: 0.8rem; }
 .chips { display: inline-flex; flex-wrap: wrap; gap: 0.35rem; align-items: center; }
 .chip { font-size: 0.78rem; padding: 0.12rem 0.5rem; border-radius: 999px; border: 1px solid var(--line);
  background: white; color: var(--ink-soft); white-space: nowrap; }
 .chip.match { background: var(--plum-soft); border-color: transparent; color: var(--plum); font-weight: 600; }
 .chip.rare { border-color: var(--ink-soft); color: var(--ink); }
 .chip.impact { background: var(--ink); border-color: var(--ink); color: white; }
 .chip.model { border-style: dashed; color: var(--ink); }
 .chip.clinvar { background: #fdf1df; border-color: transparent; color: var(--amber); font-weight: 600; }
 .chipx { background: none; border: none; color: inherit; padding: 0 0 0 0.3rem; cursor: pointer; font: inherit; }
 /* The funnel is the headline: thousands of variants down to a handful. */
 .funnel { list-style: none; padding: 0; margin: 0 0 1.5rem; display: grid; gap: 0.35rem; }
 .funnel li { display: grid; grid-template-columns: 5rem 16rem 1fr; align-items: center; gap: 0.75rem; }
 .funnel-value { font-family: var(--mono); font-size: 1.05rem; text-align: right; font-variant-numeric: tabular-nums; }
 .funnel-label { color: var(--ink-soft); font-size: 0.9rem; }
 .funnel-track { background: white; border: 1px solid var(--line); height: 0.75rem; border-radius: 2px; }
 .funnel-bar { display: block; height: 100%; background: var(--plum); opacity: 0.75; }
 .filters { display: flex; gap: 0.5rem; flex-wrap: wrap; align-items: center; margin-bottom: 1rem; }
 .triage { display: grid; grid-template-columns: minmax(0, 1fr); gap: 1.25rem; align-items: start; }
@media (min-width: 62rem) { .triage { grid-template-columns: minmax(0, 1fr) 24rem; } }
 .candidate { display: grid; grid-template-columns: 2rem minmax(10rem, 16rem) 1fr auto auto; gap: 0.75rem;
  align-items: center; width: 100%; text-align: left; background: white; color: var(--ink);
  border: 1px solid var(--line); border-left: 3px solid transparent; border-radius: 4px;
  padding: 0.6rem 0.75rem; margin-bottom: 0.4rem; font: inherit; cursor: pointer; }
 .candidate:hover { border-left-color: var(--plum-soft); }
 .candidate.selected { border-left-color: var(--plum); background: #fbf7fa; }
 .candidate .rank { font-family: var(--mono); color: var(--ink-soft); }
 .candidate .who { display: flex; flex-direction: column; gap: 0.1rem; }
 .candidate .who .coord, .candidate .who .hgvs { font-size: 0.78rem; color: var(--ink-soft); }
 .rankscore { display: flex; align-items: center; gap: 0.5rem; }
 .scorebar { width: 4rem; height: 0.5rem; background: var(--line); border-radius: 2px; overflow: hidden; }
 .scorebar span { display: block; height: 100%; background: var(--plum); }
 .scorenum { font-family: var(--mono); font-size: 0.85rem; font-variant-numeric: tabular-nums; }
 .decision { font-size: 0.72rem; text-transform: uppercase; letter-spacing: 0.04em; font-weight: 600; }
 .decision.shortlisted { color: var(--plum); }
 .decision.dismissed { color: var(--ink-soft); }
 .panel { background: white; border: 1px solid var(--line); border-radius: 4px; padding: 1rem; position: sticky; top: 1rem; }
 .panel-head { display: flex; justify-content: space-between; align-items: start; gap: 0.5rem; }
 .panel h3 { margin: 0 0 0.5rem; font-size: 1.05rem; }
 .panel h4 { margin: 1.1rem 0 0.4rem; font-size: 0.78rem; text-transform: uppercase;
  letter-spacing: 0.05em; color: var(--ink-soft); }
 .panel input, .panel textarea { width: 100%; margin-bottom: 0.5rem; font-family: inherit; }
 .components { border: none; background: none; }
 .components th { font-weight: 400; color: var(--ink-soft); padding: 0.15rem 0.5rem 0.15rem 0; }
 .components td { padding: 0.15rem 0; font-size: 0.82rem; text-align: right; }
 .evidence { display: grid; grid-template-columns: 7rem 1fr; gap: 0.2rem 0.5rem; margin: 0; font-size: 0.88rem; }
 .evidence dt { color: var(--ink-soft); }
 .evidence dd { margin: 0; }
 .links { display: flex; gap: 0.75rem; font-size: 0.85rem; }
 .decide { display: flex; gap: 0.5rem; }
 .newcase { display: grid; gap: 0.6rem; margin-bottom: 1.5rem; }
 .newcase .row { display: flex; gap: 0.5rem; flex-wrap: wrap; }
 .newcase button { justify-self: start; }
 .picker { position: relative; display: grid; gap: 0.4rem; }
 .picker .results { list-style: none; margin: 0; padding: 0.25rem; background: white;
  border: 1px solid var(--line); border-radius: 4px; max-height: 12rem; overflow: auto; }
 .picker .results button { width: 100%; text-align: left; border: none; padding: 0.3rem 0.4rem; }
 .picker .results button:hover { background: var(--plum-soft); }
 .caselist { list-style: none; padding: 0; margin: 0; }
 .caselist li { display: flex; flex-wrap: wrap; gap: 0.75rem; align-items: center; padding: 0.7rem 0.75rem;
  background: white; border: 1px solid var(--line); border-radius: 4px; margin-bottom: 0.4rem; }
 .casename { font-weight: 600; min-width: 10rem; }
 .report { background: white; border: 1px solid var(--line); padding: 2rem; }
 .reportitem { border-top: 1px solid var(--line); padding-top: 0.75rem; margin-top: 0.75rem; }
 .reportitem h3 { margin: 0 0 0.4rem; }
 .dismissed { color: var(--ink-soft); }
 .disclaimer { margin-top: 2rem; padding-top: 1rem; border-top: 1px solid var(--line);
  color: var(--ink-soft); font-size: 0.85rem; }
@media print { .noprint, nav { display: none; } .report { border: none; padding: 0; } }
@@ -1,22 +1,71 @@
 // Dynamic, not static: the same image serves /api behind the ingress and a full URL elsewhere.
 import { env } from '$env/dynamic/public';
-import { variantQuery, type VariantFilters } from './query';
+import { candidateQuery, type CandidateFilters } from './candidates';
 export type Assembly = 'GRCh38' | 'GRCh37';
-export type Sample = { id: string; name: string; vcf_uri: string; assembly: Assembly; created_at: string };
+export type JobStatus = 'queued' | 'running' | 'succeeded' | 'failed';
 export type PhenotypeTerm = { hpo_id: string; label: string };
 export type Job = {
-  id: string; sample_id: string; status: 'queued' | 'running' | 'succeeded' | 'failed';
+  id: string; case_id: string; status: JobStatus;
-  log: string | null; created_at: string; finished_at: string | null;
+  vep_version: string | null; log: string | null; created_at: string; finished_at: string | null;
 };
 export type Case = {
  id: string; name: string; vcf_uri: string; assembly: Assembly; created_at: string;
  phenotypes: PhenotypeTerm[]; latest_job: Job | null; shortlisted: number;
 };
 export type Variant = {
  id: number; chrom: string; pos: number; ref: string; alt: string; gene: string | null;
  consequence: string | null; impact: string | null; hgvsc: string | null; hgvsp: string | null;
-  gnomad_af: number | null; clinvar_sig: string | null; prediction: { score: number; model_version: string } | null;
+  gnomad_af: number | null; clinvar_sig: string | null;
  prediction: { score: number; model_name: string; model_version: string } | null;
 };
 export type DecisionState = 'shortlisted' | 'dismissed';
 export type Decision = {
  state: DecisionState; reason: string | null; note: string | null; decided_at: string;
 };
 export type Candidate = {
  variant: Variant;
  score: number;
  components: Record<string, number>;
  matched_terms: PhenotypeTerm[];
  scored: boolean;
  decision: Decision | null;
 };
 export type VariantDetail = Candidate & { annotations: Record<string, string> };
 export type Funnel = { total: number; rare: number; candidates: number; phenotype_matched: number };
 export type CandidatePage = {
  funnel: Funnel;
  weights: Record<string, number>;
  items: Candidate[];
  total: number;
  limit: number;
  offset: number;
 };
 export type Report = {
  case: Case;
  funnel: Funnel;
  generated_at: string;
  provenance: {
    job_id: string | null; vep_version: string | null; finished_at: string | null;
    model_name: string | null; model_version: string | null;
  };
  shortlisted: Candidate[];
  dismissed: Candidate[];
 };
 export type VariantPage = { items: Variant[]; total: number; limit: number; offset: number };
 async function req<T>(path: string, init?: RequestInit): Promise<T> {
-  const r = await fetch(`${env.PUBLIC_API_URL ?? '/api'}${path}`, { headers: { 'content-type': 'application/json' }, ...init });
+  const r = await fetch(`${env.PUBLIC_API_URL ?? '/api'}${path}`, {
    headers: { 'content-type': 'application/json' },
    ...init
  });
  if (!r.ok) throw new Error(await errorReason(r));
  return r.json() as Promise<T>;
 }
@@ -34,12 +83,26 @@ async function errorReason(r: Response): Promise<string> {
  return fallback;
 }
 const post = (body?: unknown): RequestInit => ({
  method: 'POST',
  body: body === undefined ? undefined : JSON.stringify(body)
 });
 export const api = {
-  samples: () => req<Sample[]>('/samples'),
+  cases: () => req<Case[]>('/cases'),
-  createSample: (body: Pick<Sample, 'name' | 'vcf_uri' | 'assembly'>) =>
+  createCase: (body: { name: string; vcf_uri: string; assembly: Assembly; phenotypes: PhenotypeTerm[] }) =>
-    req<Sample>('/samples', { method: 'POST', body: JSON.stringify(body) }),
+    req<Case>('/cases', post(body)),
-  jobsForSample: (sampleId: string) => req<Job[]>(`/samples/${sampleId}/jobs`),
+  case: (id: string) => req<Case>(`/cases/${id}`),
-  annotate: (sampleId: string) => req<Job>(`/samples/${sampleId}/annotate`, { method: 'POST' }),
+  annotate: (id: string) => req<Job>(`/cases/${id}/annotate`, post()),
  score: (id: string) => req<{ scored: number; model_version: string }>(`/cases/${id}/score`, post()),
  job: (id: string) => req<Job>(`/jobs/${id}`),
-  variants: (filters: VariantFilters) => req<VariantPage>(`/variants?${variantQuery(filters)}`)
+  candidates: (caseId: string, filters: CandidateFilters = {}) => {
    const query = candidateQuery(filters);
    return req<CandidatePage>(`/cases/${caseId}/candidates${query ? `?${query}` : ''}`);
  },
  variant: (id: number) => req<VariantDetail>(`/variants/${id}`),
  decide: (id: number, body: { state: DecisionState; reason?: string; note?: string }) =>
    req<Decision>(`/variants/${id}/decision`, post(body)),
  report: (caseId: string) => req<Report>(`/cases/${caseId}/report`),
  phenotypes: (q: string) => req<PhenotypeTerm[]>(`/phenotypes?q=${encodeURIComponent(q)}`)
 };
@@ -0,0 +1,88 @@
 import { describe, expect, it } from 'vitest';
 import { candidateQuery, evidenceChips, funnelSteps, scoreBarPercent } from './candidates';
 import type { Candidate, Funnel } from './api';
 const candidate = (over: Partial<Candidate> = {}): Candidate => ({
  variant: {
    id: 1, chrom: '22', pos: 100, ref: 'A', alt: 'G', gene: 'NF2',
    consequence: 'frameshift_variant', impact: 'HIGH', hgvsc: null, hgvsp: 'p.Ser486fs',
    gnomad_af: null, clinvar_sig: null, prediction: null
  },
  score: 0.88,
  components: { phenotype: 0.67, rarity: 1, consequence: 1, model: 0.94 },
  matched_terms: [{ hpo_id: 'HP:0000365', label: 'Hearing impairment' }],
  scored: true,
  decision: null,
  ...over
 });
 describe('evidenceChips', () => {
  it('leads with the phenotype match, because that is what makes it a candidate', () => {
    const [first] = evidenceChips(candidate(), 3);
    expect(first).toEqual({ label: '1/3 phenotype terms', tone: 'match' });
  });
  it('says plainly when the gene has no link to the phenotype', () => {
    const chips = evidenceChips(candidate({ matched_terms: [] }), 3);
    expect(chips[0]).toEqual({ label: 'no phenotype match', tone: 'muted' });
  });
  it('calls an absent variant absent rather than showing a zero', () => {
    expect(evidenceChips(candidate(), 3)[1]).toEqual({ label: 'absent from gnomAD', tone: 'rare' });
  });
  it('shows a frequency when there is one', () => {
    const c = candidate();
    c.variant.gnomad_af = 0.00042;
    expect(evidenceChips(c, 3)[1].label).toBe('gnomAD 4.2e-4');
  });
  it('reads the consequence without the underscores', () => {
    expect(evidenceChips(candidate(), 3)[2]).toEqual({ label: 'frameshift variant', tone: 'impact' });
  });
  it('marks an unscored variant instead of implying a zero score', () => {
    const chips = evidenceChips(candidate({ scored: false }), 3);
    expect(chips[3]).toEqual({ label: 'unscored', tone: 'muted' });
  });
  it('shows ClinVar last, as confirmation rather than an input', () => {
    const c = candidate();
    c.variant.clinvar_sig = 'pathogenic';
    expect(evidenceChips(c, 3).at(-1)).toEqual({ label: 'ClinVar: pathogenic', tone: 'clinvar' });
  });
 });
 describe('funnelSteps', () => {
  it('describes each narrowing step in order', () => {
    const funnel: Funnel = { total: 1284, rare: 41, candidates: 12, phenotype_matched: 6 };
    expect(funnelSteps(funnel).map((s) => `${s.label} ${s.value}`)).toEqual([
      'variants called 1284',
      'rare (<0.1%) 41',
      'coding candidates 12',
      'in phenotype-matched genes 6'
    ]);
  });
 });
 describe('scoreBarPercent', () => {
  it('maps the 0..1 score onto a bar width', () => {
    expect(scoreBarPercent(0.884)).toBe(88);
    expect(scoreBarPercent(0)).toBe(0);
    expect(scoreBarPercent(1)).toBe(100);
  });
 });
 describe('candidateQuery', () => {
  it('sends only the filters that are set', () => {
    expect(candidateQuery({})).toBe('');
    expect(candidateQuery({ gene: ' nf2 ', impact: 'HIGH', state: 'undecided' })).toBe(
      'gene=nf2&impact=HIGH&state=undecided'
    );
  });
  it('drops a cleared allele frequency box', () => {
    expect(candidateQuery({ maxAf: null })).toBe('');
    expect(candidateQuery({ maxAf: 0.01 })).toBe('max_af=0.01');
  });
 });
@@ -0,0 +1,70 @@
 import type { Candidate, Funnel } from './api';
 export type Chip = {
  label: string;
  tone: 'match' | 'rare' | 'impact' | 'model' | 'clinvar' | 'muted';
 };
 export type CandidateFilters = {
  gene?: string;
  impact?: string;
  maxAf?: number | string | null;
  state?: 'shortlisted' | 'dismissed' | 'undecided' | '';
  limit?: number;
  offset?: number;
 };
 const formatAf = (af: number) => af.toExponential(1);
 /**
 * The reasons this variant is a candidate, in the order a reviewer reads them. ClinVar comes last
 * and is styled apart, because it confirms the ranking rather than feeding it.
 */
 export function evidenceChips(candidate: Candidate, caseTermCount: number): Chip[] {
  const { variant } = candidate;
  const chips: Chip[] = [
    candidate.matched_terms.length
      ? { label: `${candidate.matched_terms.length}/${caseTermCount} phenotype terms`, tone: 'match' }
      : { label: 'no phenotype match', tone: 'muted' },
    variant.gnomad_af === null
      ? { label: 'absent from gnomAD', tone: 'rare' }
      : { label: `gnomAD ${formatAf(variant.gnomad_af)}`, tone: 'rare' },
    {
      label: (variant.consequence ?? 'unknown consequence').split('&')[0].replace(/_/g, ' '),
      tone: 'impact'
    },
    candidate.scored && variant.prediction
      ? { label: `model ${variant.prediction.score.toFixed(2)}`, tone: 'model' }
      : { label: 'unscored', tone: 'muted' }
  ];
  if (variant.clinvar_sig) chips.push({ label: `ClinVar: ${variant.clinvar_sig}`, tone: 'clinvar' });
  return chips;
 }
 /** Thousands of variants down to a handful: the narrowing is the story. */
 export function funnelSteps(funnel: Funnel): { label: string; value: number }[] {
  return [
    { label: 'variants called', value: funnel.total },
    { label: 'rare (<0.1%)', value: funnel.rare },
    { label: 'coding candidates', value: funnel.candidates },
    { label: 'in phenotype-matched genes', value: funnel.phenotype_matched }
  ];
 }
 export const scoreBarPercent = (score: number): number =>
  Math.max(0, Math.min(100, Math.round(score * 100)));
 export function candidateQuery(filters: CandidateFilters): string {
  const q = new URLSearchParams();
  const gene = filters.gene?.trim();
  if (gene) q.set('gene', gene);
  if (filters.impact) q.set('impact', filters.impact);
  const { maxAf } = filters;
  if (maxAf !== null && maxAf !== undefined && maxAf !== '' && Number.isFinite(Number(maxAf))) {
    q.set('max_af', String(maxAf));
  }
  if (filters.state) q.set('state', filters.state);
  if (filters.limit !== undefined) q.set('limit', String(filters.limit));
  if (filters.offset !== undefined) q.set('offset', String(filters.offset));
  return q.toString();
 }
@@ -0,0 +1,38 @@
 <script lang="ts">
  import type { Candidate } from '$lib/api';
  import { evidenceChips, scoreBarPercent } from '$lib/candidates';
  import Chips from './Chips.svelte';
  let {
    candidate,
    rank,
    termCount,
    selected = false,
    onselect
  }: {
    candidate: Candidate;
    rank: number;
    termCount: number;
    selected?: boolean;
    onselect: () => void;
  } = $props();
  const v = $derived(candidate.variant);
 </script>
 <button class="candidate" class:selected onclick={onselect}>
  <span class="rank">{rank}</span>
  <span class="who">
    <strong>{v.gene ?? 'intergenic'}</strong>
    <span class="coord">{v.chrom}:{v.pos} {v.ref}&gt;{v.alt}</span>
    {#if v.hgvsp ?? v.hgvsc}<span class="hgvs">{v.hgvsp ?? v.hgvsc}</span>{/if}
  </span>
  <Chips chips={evidenceChips(candidate, termCount)} />
  <span class="rankscore">
    <span class="scorebar"><span style="width: {scoreBarPercent(candidate.score)}%"></span></span>
    <span class="scorenum">{candidate.score.toFixed(2)}</span>
  </span>
  {#if candidate.decision}
    <span class="decision {candidate.decision.state}">{candidate.decision.state}</span>
  {/if}
 </button>
@@ -0,0 +1,10 @@
 <script lang="ts">
  import type { Chip } from '$lib/candidates';
  let { chips }: { chips: Chip[] } = $props();
 </script>
 <span class="chips">
  {#each chips as chip (chip.label)}
    <span class="chip {chip.tone}">{chip.label}</span>
  {/each}
 </span>
@@ -0,0 +1,18 @@
 <script lang="ts">
  import type { Funnel } from '$lib/api';
  import { funnelSteps } from '$lib/candidates';
  let { funnel }: { funnel: Funnel } = $props();
  const steps = $derived(funnelSteps(funnel));
  const width = (value: number) => (funnel.total ? Math.max(1.5, (value / funnel.total) * 100) : 0);
 </script>
 <ol class="funnel">
  {#each steps as step (step.label)}
    <li>
      <span class="funnel-value">{step.value.toLocaleString('en-GB')}</span>
      <span class="funnel-label">{step.label}</span>
      <span class="funnel-track"><span class="funnel-bar" style="width: {width(step.value)}%"></span></span>
    </li>
  {/each}
 </ol>
@@ -0,0 +1,62 @@
 <script lang="ts">
  import { api, type PhenotypeTerm } from '$lib/api';
  let { selected = $bindable() }: { selected: PhenotypeTerm[] } = $props();
  let query = $state('');
  let results = $state<PhenotypeTerm[]>([]);
  let searching = $state(false);
  async function search() {
    if (query.trim().length < 2) {
      results = [];
      return;
    }
    searching = true;
    try {
      results = await api.phenotypes(query.trim());
    } catch {
      results = []; // the picker is a convenience; a failed lookup must not block the form
    } finally {
      searching = false;
    }
  }
  function add(term: PhenotypeTerm) {
    if (!selected.some((t) => t.hpo_id === term.hpo_id)) selected = [...selected, term];
    query = '';
    results = [];
  }
 </script>
 <div class="picker">
  <input
    placeholder="Search HPO terms, e.g. hearing"
    bind:value={query}
    oninput={search}
    aria-label="Phenotype search"
  />
  {#if searching}<span class="muted">searching…</span>{/if}
  {#if results.length}
    <ul class="results">
      {#each results as term (term.hpo_id)}
        <li>
          <button type="button" class="quiet" onclick={() => add(term)}>
            {term.label} <small class="muted">{term.hpo_id}</small>
          </button>
        </li>
      {/each}
    </ul>
  {/if}
  <span class="chips">
    {#each selected as term (term.hpo_id)}
      <span class="chip match">
        {term.label}
        <button
          type="button"
          class="chipx"
          onclick={() => (selected = selected.filter((t) => t.hpo_id !== term.hpo_id))}
          aria-label="Remove {term.label}">✕</button>
      </span>
    {/each}
  </span>
 </div>
@@ -0,0 +1,111 @@
 <script lang="ts">
  import { api, type DecisionState, type VariantDetail } from '$lib/api';
  import { evidenceChips } from '$lib/candidates';
  import Chips from './Chips.svelte';
  let {
    detail,
    termCount,
    weights,
    onclose,
    ondecided
  }: {
    detail: VariantDetail;
    termCount: number;
    weights: Record<string, number>;
    onclose: () => void;
    ondecided: (updated: VariantDetail) => void;
  } = $props();
  let reason = $state('');
  let note = $state('');
  let shownFor = $state<number | null>(null);
  let saving = $state(false);
  let error = $state<string | null>(null);
  // The panel is reused as you click through candidates: load each variant's own decision.
  $effect(() => {
    if (shownFor === detail.variant.id) return;
    shownFor = detail.variant.id;
    reason = detail.decision?.reason ?? '';
    note = detail.decision?.note ?? '';
  });
  const v = $derived(detail.variant);
  const links = $derived([
    {
      label: 'Ensembl',
      href: `https://www.ensembl.org/Homo_sapiens/Location/View?r=${v.chrom}:${v.pos}-${v.pos}`
    },
    {
      label: 'gnomAD',
      href: `https://gnomad.broadinstitute.org/region/${v.chrom}-${Math.max(1, v.pos - 25)}-${v.pos + 25}?dataset=gnomad_r4`
    },
    ...(v.gene
      ? [{ label: 'ClinVar', href: `https://www.ncbi.nlm.nih.gov/clinvar/?term=${encodeURIComponent(v.gene)}%5Bgene%5D` }]
      : [])
  ]);
  async function decide(state: DecisionState) {
    saving = true;
    error = null;
    try {
      await api.decide(v.id, { state, reason: reason || undefined, note: note || undefined });
      ondecided(await api.variant(v.id));
    } catch (e) {
      error = (e as Error).message;
    } finally {
      saving = false;
    }
  }
 </script>
 <aside class="panel">
  <header class="panel-head">
    <h3>{v.gene ?? 'intergenic'} <span class="coord">{v.chrom}:{v.pos} {v.ref}&gt;{v.alt}</span></h3>
    <button class="quiet" onclick={onclose} aria-label="Close panel">✕</button>
  </header>
  <Chips chips={evidenceChips(detail, termCount)} />
  <h4>Why it ranks {detail.score.toFixed(2)}</h4>
  <table class="components">
    <tbody>
      {#each Object.entries(detail.components) as [name, value] (name)}
        <tr>
          <th>{name}</th>
          <td class="coord">{value.toFixed(2)} × {(weights[name] ?? 0).toFixed(2)}</td>
          <td class="coord">{(value * (weights[name] ?? 0)).toFixed(3)}</td>
        </tr>
      {/each}
    </tbody>
  </table>
  {#if detail.matched_terms.length}
    <h4>Phenotype match</h4>
    <p>HPO annotates <strong>{v.gene}</strong> with {detail.matched_terms.map((t) => t.label).join(', ')}.</p>
  {/if}
  <h4>Evidence</h4>
  <dl class="evidence">
    <dt>Consequence</dt><dd>{v.consequence ?? '—'} <small class="muted">{v.impact ?? ''}</small></dd>
    <dt>HGVS</dt><dd class="hgvs">{v.hgvsp ?? v.hgvsc ?? '—'}</dd>
    <dt>gnomAD</dt><dd>{v.gnomad_af === null ? 'absent' : v.gnomad_af.toExponential(2)}</dd>
    <dt>ClinVar</dt><dd>{v.clinvar_sig ?? 'no submission'}</dd>
    <dt>Model</dt>
    <dd>{v.prediction ? `${v.prediction.score.toFixed(2)} (model ${v.prediction.model_version})` : 'unscored'}</dd>
  </dl>
  <p class="links">
    {#each links as link (link.label)}<a href={link.href} target="_blank" rel="noreferrer">{link.label}</a>{/each}
  </p>
  <h4>Decision</h4>
  {#if error}<p role="alert">{error}</p>{/if}
  <input placeholder="Reason, e.g. fits the phenotype" bind:value={reason} aria-label="Reason" />
  <textarea placeholder="Note for the report" rows="3" bind:value={note} aria-label="Note"></textarea>
  <div class="decide">
    <button onclick={() => decide('shortlisted')} disabled={saving}>Shortlist</button>
    <button class="quiet" onclick={() => decide('dismissed')} disabled={saving}>Dismiss</button>
  </div>
 </aside>
@@ -1,29 +0,0 @@
 import { describe, expect, it } from 'vitest';
 import { variantQuery } from './query';
 describe('variantQuery', () => {
  it('always includes the job id', () => {
    expect(variantQuery({ jobId: 'abc' })).toBe('job_id=abc');
  });
  it('includes filters that have values', () => {
    const q = new URLSearchParams(
      variantQuery({ jobId: 'abc', gene: ' brca1 ', impact: 'HIGH', maxAf: 0.01, limit: 100 })
    );
    expect(q.get('gene')).toBe('brca1');
    expect(q.get('impact')).toBe('HIGH');
    expect(q.get('max_af')).toBe('0.01');
    expect(q.get('limit')).toBe('100');
  });
  it('drops a cleared number input instead of sending "null"', () => {
    // Svelte binds an emptied <input type="number"> to null.
    for (const maxAf of [null, undefined, '', Number.NaN]) {
      expect(variantQuery({ jobId: 'abc', maxAf })).toBe('job_id=abc');
    }
  });
  it('drops blank gene and impact', () => {
    expect(variantQuery({ jobId: 'abc', gene: '   ', impact: '' })).toBe('job_id=abc');
  });
 });
@@ -1,22 +0,0 @@
 export type VariantFilters = {
  jobId: string;
  gene?: string;
  impact?: string;
  // An emptied <input type="number"> binds to null, so accept it and drop it.
  maxAf?: number | string | null;
  limit?: number;
  offset?: number;
 };
 export function variantQuery(f: VariantFilters): string {
  const q = new URLSearchParams({ job_id: f.jobId });
  const gene = f.gene?.trim();
  if (gene) q.set('gene', gene);
  if (f.impact) q.set('impact', f.impact);
  if (f.maxAf !== null && f.maxAf !== undefined && f.maxAf !== '' && Number.isFinite(Number(f.maxAf))) {
    q.set('max_af', String(f.maxAf));
  }
  if (f.limit !== undefined) q.set('limit', String(f.limit));
  if (f.offset !== undefined) q.set('offset', String(f.offset));
  return q.toString();
 }
@@ -1,18 +1,20 @@
 <script lang="ts">
  import { onMount } from 'svelte';
-  import { api, type Assembly, type Sample } from '$lib/api';
+  import { api, type Assembly, type Case, type PhenotypeTerm } from '$lib/api';
  import PhenotypePicker from '$lib/components/PhenotypePicker.svelte';
-  let samples = $state<Sample[]>([]);
+  let cases = $state<Case[]>([]);
  let loaded = $state(false);
  let loadError = $state<string | null>(null);
  let name = $state('');
  let vcfUri = $state('');
  let assembly = $state<Assembly>('GRCh38');
  let phenotypes = $state<PhenotypeTerm[]>([]);
  let error = $state<string | null>(null);
  async function refresh() {
    try {
-      samples = await api.samples();
+      cases = await api.cases();
      loadError = null;
    } catch (e) {
      loadError = (e as Error).message;
@@ -24,44 +26,66 @@
  async function add() {
    error = null;
-    try { await api.createSample({ name, vcf_uri: vcfUri, assembly }); name = ''; vcfUri = ''; await refresh(); }
+    try {
-    catch (e) { error = (e as Error).message; }
+      await api.createCase({ name, vcf_uri: vcfUri, assembly, phenotypes });
      name = '';
      vcfUri = '';
      phenotypes = [];
      await refresh();
    } catch (e) {
      error = (e as Error).message;
    }
  }
  const status = (c: Case) => c.latest_job?.status ?? 'not analysed';
 </script>
 <h1>rarelens</h1>
-<p class="lede">Annotate a VCF with Ensembl VEP, score each variant, and browse what came back. Public test data only.</p>
+<p class="lede">
  Rare disease triage on public data: a proband's variants narrowed against their phenotype, each
  candidate carrying the evidence for its rank. Research demo, not a diagnostic tool.
 </p>
-<h2>Add a sample</h2>
+<h2>New case</h2>
-<div style="display:flex; gap:0.5rem; flex-wrap:wrap">
+<div class="newcase">
-  <input placeholder="Sample name" bind:value={name} aria-label="Sample name" />
+  <div class="row">
-  <input placeholder="gs://bucket/sample.vcf.gz or /data/example.vcf.gz" bind:value={vcfUri} aria-label="VCF path" style="flex:1; min-width: 20rem" />
+    <input placeholder="Case name, e.g. PROBAND-01" bind:value={name} aria-label="Case name" />
-  <select bind:value={assembly} aria-label="Assembly">
+    <input
-    <option>GRCh38</option><option>GRCh37</option>
+      placeholder="gs://bucket/proband.vcf.gz or /data/proband.vcf.gz"
-  </select>
+      bind:value={vcfUri}
-  <button onclick={add} disabled={!name || !vcfUri}>Add sample</button>
+      aria-label="VCF path"
      style="flex:1; min-width: 18rem" />
    <select bind:value={assembly} aria-label="Assembly">
      <option>GRCh38</option><option>GRCh37</option>
    </select>
  </div>
  <PhenotypePicker bind:selected={phenotypes} />
  <button onclick={add} disabled={!name || !vcfUri}>Create case</button>
 </div>
-{#if error}<p role="alert">Could not add the sample: {error}</p>{/if}
+{#if error}<p role="alert">Could not create the case: {error}</p>{/if}
-<h2>Samples</h2>
+<h2>Cases</h2>
 {#if loadError}
-  <p role="alert">Could not load samples: {loadError}. <button class="quiet" onclick={refresh}>Retry</button></p>
+  <p role="alert">Could not load cases: {loadError}. <button class="quiet" onclick={refresh}>Retry</button></p>
 {:else if !loaded}
-  <p style="color:var(--ink-soft)">Loading samples…</p>
+  <p class="muted">Loading…</p>
-{:else if samples.length === 0}
+{:else if cases.length === 0}
-  <div class="empty">No samples yet. Add one above to run the annotation pipeline.</div>
+  <div class="empty">No cases yet. Create one above, then run the annotation pipeline on it.</div>
 {:else}
-  <table>
+  <ul class="caselist">
-    <thead><tr><th>Name</th><th>VCF</th><th>Assembly</th><th>Added</th></tr></thead>
+    {#each cases as c (c.id)}
-    <tbody>
+      <li>
-      {#each samples as s (s.id)}
+        <a class="casename" href="/cases/{c.id}">{c.name}</a>
-        <tr>
+        <span class="chips">
-          <td><a href="/samples/{s.id}">{s.name}</a></td>
+          {#each c.phenotypes.slice(0, 4) as term (term.hpo_id)}
-          <td class="hgvs">{s.vcf_uri}</td>
+            <span class="chip match">{term.label}</span>
-          <td>{s.assembly}</td>
+          {/each}
-          <td>{new Date(s.created_at).toLocaleDateString('en-GB')}</td>
+          {#if c.phenotypes.length > 4}<span class="chip muted">+{c.phenotypes.length - 4}</span>{/if}
-        </tr>
+          {#if c.phenotypes.length === 0}<span class="chip muted">no phenotype</span>{/if}
-      {/each}
+        </span>
-    </tbody>
+        <span class="status {c.latest_job?.status ?? ''}">{status(c)}</span>
-  </table>
+        <span class="muted">{c.shortlisted} shortlisted</span>
      </li>
    {/each}
  </ul>
 {/if}
@@ -0,0 +1,206 @@
 <script lang="ts">
  import { onDestroy, onMount } from 'svelte';
  import { api, type Candidate, type CandidatePage, type Case, type Job, type VariantDetail } from '$lib/api';
  import { poll } from '$lib/poll';
  import { formatElapsed, latestStep } from '$lib/progress';
  import CandidateRow from '$lib/components/CandidateRow.svelte';
  import Funnel from '$lib/components/Funnel.svelte';
  import VariantPanel from '$lib/components/VariantPanel.svelte';
  const POLL_MS = 3000;
  const finished = (j: Job) => j.status === 'succeeded' || j.status === 'failed';
  let { data } = $props();
  let kase = $state<Case | null>(null);
  let job = $state<Job | null>(null);
  let page = $state<CandidatePage | null>(null);
  let detail = $state<VariantDetail | null>(null);
  let gene = $state('');
  let impact = $state('');
  let maxAf = $state<number | null>(null);
  let decisionFilter = $state('');
  let busy = $state(false);
  let scoring = $state(false);
  let error = $state<string | null>(null);
  let now = $state(Date.now());
  let stopPolling: (() => void) | null = null;
  const running = $derived((!!job && !finished(job)) || scoring);
  const elapsedMs = $derived(job ? now - Date.parse(job.created_at) : 0);
  const step = $derived(scoring ? 'scoring variants with the model' : latestStep(job?.log ?? null));
  const termCount = $derived(kase?.phenotypes.length ?? 0);
  // Tick the elapsed time while a run is in flight; polling refreshes the step itself.
  $effect(() => {
    if (!running) return;
    const tick = setInterval(() => (now = Date.now()), 1000);
    return () => clearInterval(tick);
  });
  onMount(async () => {
    try {
      kase = await api.case(data.caseId);
      job = kase.latest_job;
      if (job && !finished(job)) follow(job);
      else await loadCandidates();
    } catch (e) {
      error = (e as Error).message;
    }
  });
  onDestroy(() => stopPolling?.());
  function follow(j: Job) {
    stopPolling?.();
    stopPolling = poll(() => api.job(j.id), {
      intervalMs: POLL_MS,
      done: finished,
      onValue: (next) => {
        job = next;
        if (next.status === 'succeeded') scoreThenLoad();
      },
      onError: (e) => { error = `Lost track of the run: ${(e as Error).message}`; }
    });
  }
  async function analyse() {
    busy = true;
    error = null;
    page = null;
    detail = null;
    try {
      job = await api.annotate(data.caseId);
      if (!finished(job)) follow(job);
    } catch (e) {
      error = (e as Error).message;
    } finally {
      busy = false;
    }
  }
  // Annotation and scoring are one action to the user; the API keeps them separate.
  async function scoreThenLoad() {
    scoring = true;
    try {
      await api.score(data.caseId);
    } catch (e) {
      error = `Scoring failed: ${(e as Error).message}`;
    } finally {
      scoring = false;
    }
    await loadCandidates();
  }
  async function loadCandidates() {
    try {
      page = await api.candidates(data.caseId, {
        gene,
        impact,
        maxAf,
        state: decisionFilter as never,
        limit: 100
      });
    } catch (e) {
      error = (e as Error).message;
    }
  }
  async function select(candidate: Candidate) {
    try {
      detail = await api.variant(candidate.variant.id);
    } catch (e) {
      error = (e as Error).message;
    }
  }
  async function decided(updated: VariantDetail) {
    detail = updated;
    await loadCandidates();
  }
 </script>
 <a href="/">All cases</a>
 <div class="casehead">
  <h1>{kase?.name ?? 'Case'}</h1>
  <span class="chips">
    {#each kase?.phenotypes ?? [] as term (term.hpo_id)}
      <span class="chip match">{term.label}</span>
    {/each}
    {#if kase && kase.phenotypes.length === 0}
      <span class="chip muted">no phenotype recorded — ranking falls back to rarity and consequence</span>
    {/if}
  </span>
  <p class="muted provenance">
    {kase?.assembly}
    {#if job?.vep_version}· VEP {job.vep_version}{/if}
    {#if page?.items[0]?.variant.prediction}· model {page.items[0].variant.prediction.model_version}{/if}
    {#if job?.finished_at}· analysed {new Date(job.finished_at).toLocaleString('en-GB')}{/if}
  </p>
 </div>
 {#if error}<p role="alert">{error}</p>{/if}
 {#if running}
  <p class="progress" aria-live="polite">
    <span class="spinner" aria-hidden="true"></span>
    Analysing for {formatElapsed(elapsedMs)}{#if step} · <span class="hgvs">{step}</span>{/if}
  </p>
 {:else}
  <p class="actions">
    <button onclick={analyse} disabled={busy}>{job ? 'Re-analyse case' : 'Analyse case'}</button>
    {#if page && page.funnel.total > 0}
      <a class="reportlink" href="/cases/{data.caseId}/report">Case report →</a>
    {/if}
  </p>
 {/if}
 {#if job?.status === 'failed' && job.log}
  <pre class="log hgvs">{job.log}</pre>
 {/if}
 {#if page && page.funnel.total > 0}
  <Funnel funnel={page.funnel} />
  <div class="filters">
    <input placeholder="Gene" bind:value={gene} aria-label="Gene" />
    <select bind:value={impact} aria-label="Impact">
      <option value="">Any impact</option><option>HIGH</option><option>MODERATE</option>
    </select>
    <label>Max AF <input type="number" step="0.0001" min="0" max="1" bind:value={maxAf} style="width:6rem" /></label>
    <select bind:value={decisionFilter} aria-label="Decision">
      <option value="">All decisions</option>
      <option value="undecided">Undecided</option>
      <option value="shortlisted">Shortlisted</option>
      <option value="dismissed">Dismissed</option>
    </select>
    <button class="quiet" onclick={loadCandidates}>Apply</button>
  </div>
  <div class="triage">
    <div class="candidates">
      <p class="muted">{page.total} candidates ranked by phenotype fit, rarity, consequence and model score</p>
      {#each page.items as candidate, i (candidate.variant.id)}
        <CandidateRow
          {candidate}
          rank={i + 1}
          {termCount}
          selected={detail?.variant.id === candidate.variant.id}
          onselect={() => select(candidate)} />
      {:else}
        <div class="empty">No candidates match these filters.</div>
      {/each}
    </div>
    {#if detail && page}
      <VariantPanel
        {detail}
        {termCount}
        weights={page.weights}
        onclose={() => (detail = null)}
        ondecided={decided} />
    {/if}
  </div>
 {:else if page && !running}
  <div class="empty">
    No results yet. "Analyse case" runs VEP over the VCF, scores each variant, then ranks what is
    left against the phenotype.
  </div>
 {/if}
@@ -0,0 +1,2 @@
 import type { PageLoad } from './$types';
 export const load: PageLoad = ({ params }) => ({ caseId: params.id });
@@ -0,0 +1,78 @@
 <script lang="ts">
  import { onMount } from 'svelte';
  import { api, type Report } from '$lib/api';
  import Funnel from '$lib/components/Funnel.svelte';
  import Chips from '$lib/components/Chips.svelte';
  import { evidenceChips } from '$lib/candidates';
  let { data } = $props();
  let report = $state<Report | null>(null);
  let error = $state<string | null>(null);
  onMount(async () => {
    try {
      report = await api.report(data.caseId);
    } catch (e) {
      error = (e as Error).message;
    }
  });
  const termCount = $derived(report?.case.phenotypes.length ?? 0);
 </script>
 <a class="noprint" href="/cases/{data.caseId}">← Back to triage</a>
 {#if error}<p role="alert">{error}</p>{/if}
 {#if report}
  <article class="report">
    <h1>Case report — {report.case.name}</h1>
    <p class="muted">
      Generated {new Date(report.generated_at).toLocaleString('en-GB')} ·
      {report.case.assembly}
      {#if report.provenance.vep_version}· VEP {report.provenance.vep_version}{/if}
      {#if report.provenance.model_version}· model {report.provenance.model_version}{/if}
    </p>
    <h2>Phenotype</h2>
    <span class="chips">
      {#each report.case.phenotypes as term (term.hpo_id)}
        <span class="chip match">{term.label} <small class="muted">{term.hpo_id}</small></span>
      {:else}
        <span class="chip muted">none recorded</span>
      {/each}
    </span>
    <h2>Narrowing</h2>
    <Funnel funnel={report.funnel} />
    <h2>Shortlisted ({report.shortlisted.length})</h2>
    {#each report.shortlisted as item (item.variant.id)}
      <div class="reportitem">
        <h3>{item.variant.gene ?? 'intergenic'} <span class="coord">{item.variant.chrom}:{item.variant.pos} {item.variant.ref}&gt;{item.variant.alt}</span></h3>
        <Chips chips={evidenceChips(item, termCount)} />
        <p><strong>Reason:</strong> {item.decision?.reason ?? '—'}</p>
        {#if item.decision?.note}<p class="muted">{item.decision.note}</p>{/if}
      </div>
    {:else}
      <p class="muted">Nothing shortlisted yet.</p>
    {/each}
    {#if report.dismissed.length}
      <h2>Dismissed ({report.dismissed.length})</h2>
      <ul class="dismissed">
        {#each report.dismissed as item (item.variant.id)}
          <li>
            <strong>{item.variant.gene ?? 'intergenic'}</strong>
            <span class="coord">{item.variant.chrom}:{item.variant.pos}</span>
            — {item.decision?.reason ?? 'no reason given'}
          </li>
        {/each}
      </ul>
    {/if}
    <p class="disclaimer">
      Research demonstration on public data. Computational evidence is supporting only under
      ACMG/AMP guidance and this tool makes no diagnostic claim.
    </p>
  </article>
 {/if}
@@ -0,0 +1,2 @@
 import type { PageLoad } from './$types';
 export const load: PageLoad = ({ params }) => ({ caseId: params.id });
@@ -1,141 +0,0 @@
 <script lang="ts">
  import { onDestroy, onMount } from 'svelte';
  import { api, type Job, type VariantPage } from '$lib/api';
  import { poll } from '$lib/poll';
  import { formatElapsed, latestStep } from '$lib/progress';
  const POLL_MS = 3000;
  const finished = (j: Job) => j.status === 'succeeded' || j.status === 'failed';
  let { data } = $props();
  let job = $state<Job | null>(null);
  let page = $state<VariantPage | null>(null);
  let gene = $state('');
  let impact = $state('');
  let maxAf = $state<number | null>(0.01);
  let busy = $state(false);
  let error = $state<string | null>(null);
  let stopPolling: (() => void) | null = null;
  let now = $state(Date.now());
  const running = $derived(!!job && !finished(job));
  const elapsedMs = $derived(job ? now - Date.parse(job.created_at) : 0);
  const step = $derived(latestStep(job?.log ?? null));
  // Tick the elapsed time while a run is in flight; polling refreshes the step itself.
  $effect(() => {
    if (!running) return;
    const tick = setInterval(() => (now = Date.now()), 1000);
    return () => clearInterval(tick);
  });
  onMount(async () => {
    try {
      const jobs = await api.jobsForSample(data.sampleId); // newest first
      const latest = jobs[0] ?? null;
      const lastGood = jobs.find((j) => j.status === 'succeeded') ?? null;
      // Follow a run in progress; otherwise show the latest results, else the latest failure.
      job = latest && !finished(latest) ? latest : (lastGood ?? latest);
      if (job) await follow(job);
    } catch (e) {
      error = (e as Error).message;
    }
  });
  onDestroy(() => stopPolling?.());
  async function follow(j: Job) {
    stopPolling?.();
    if (j.status === 'succeeded') return loadVariants();
    if (finished(j)) return;
    stopPolling = poll(() => api.job(j.id), {
      intervalMs: POLL_MS,
      done: finished,
      onValue: (next) => {
        job = next;
        if (next.status === 'succeeded') loadVariants();
      },
      onError: (e) => { error = `Lost track of the job: ${(e as Error).message}`; }
    });
  }
  async function runAnnotation() {
    busy = true;
    error = null;
    page = null;
    try {
      job = await api.annotate(data.sampleId);
      await follow(job);
    } catch (e) {
      error = (e as Error).message;
    } finally {
      busy = false;
    }
  }
  async function loadVariants() {
    if (!job) return;
    error = null;
    try {
      page = await api.variants({ jobId: job.id, gene, impact, maxAf, limit: 100 });
    } catch (e) {
      error = (e as Error).message;
    }
  }
  const scoreClass = (s: number) => (s >= 0.8 ? 'score high' : s >= 0.5 ? 'score mid' : 'score');
 </script>
 <a href="/">All samples</a>
 <h1>Sample {data.sampleId.slice(0, 8)}</h1>
 {#if error}<p role="alert">{error}</p>{/if}
 {#if job}
  <p>Job <span class="hgvs">{job.id.slice(0, 8)}</span>: <span class="status {job.status}">{job.status}</span></p>
  {#if running}
    <p class="progress" aria-live="polite">
      <span class="spinner" aria-hidden="true"></span>
      Annotating for {formatElapsed(elapsedMs)}{#if step} · <span class="hgvs">{step}</span>{/if}
    </p>
  {/if}
  {#if job.status === 'failed' && job.log}
    <pre class="hgvs" style="white-space:pre-wrap; background:white; border:1px solid var(--line); padding:0.75rem; max-height:16rem; overflow:auto">{job.log}</pre>
  {/if}
 {/if}
 {#if !job || job.status === 'failed'}
  <button onclick={runAnnotation} disabled={busy}>{job ? 'Run VEP annotation again' : 'Run VEP annotation'}</button>
 {/if}
 {#if job?.status === 'succeeded'}
  <h2>Variants</h2>
  <div style="display:flex; gap:0.5rem; flex-wrap:wrap; margin-bottom:0.75rem">
    <input placeholder="Gene symbol" bind:value={gene} aria-label="Gene" />
    <select bind:value={impact} aria-label="Impact">
      <option value="">Any impact</option><option>HIGH</option><option>MODERATE</option><option>LOW</option><option>MODIFIER</option>
    </select>
    <label>Max gnomAD AF <input type="number" step="0.001" min="0" max="1" bind:value={maxAf} style="width:6rem" /></label>
    <button class="quiet" onclick={loadVariants}>Apply filters</button>
  </div>
  {#if page && page.items.length === 0}
    <div class="empty">No variants match these filters. Raise the allele frequency cap or clear the gene filter.</div>
  {:else if page}
    <p style="color:var(--ink-soft)">{page.total} variants, showing {page.items.length}</p>
    <table>
      <thead><tr><th>Position</th><th>Gene</th><th>Consequence</th><th>HGVS</th><th>gnomAD AF</th><th>ClinVar</th><th>Score</th></tr></thead>
      <tbody>
        {#each page.items as v (v.id)}
          <tr>
            <td class="coord">{v.chrom}:{v.pos} {v.ref}>{v.alt}</td>
            <td>{v.gene ?? ''}</td>
            <td>{v.consequence ?? ''}<br /><small style="color:var(--ink-soft)">{v.impact ?? ''}</small></td>
            <td class="hgvs">{v.hgvsp ?? v.hgvsc ?? ''}</td>
            <td>{v.gnomad_af?.toExponential(2) ?? 'absent'}</td>
            <td>{v.clinvar_sig ?? ''}</td>
            <td>{#if v.prediction}<span class={scoreClass(v.prediction.score)}>{v.prediction.score.toFixed(2)}</span>{:else}<span style="color:var(--ink-soft)">unscored</span>{/if}</td>
          </tr>
        {/each}
      </tbody>
    </table>
  {/if}
 {/if}
@@ -1,2 +0,0 @@
 import type { PageLoad } from './$types';
 export const load: PageLoad = ({ params }) => ({ sampleId: params.id });
		`@@ -0,0 +1,2 @@`
							`import type { PageLoad } from './$types';`
							`export const load: PageLoad = ({ params }) => ({ caseId: params.id });`
		`@@ -1,2 +0,0 @@`
			`import type { PageLoad } from './$types';`
			`export const load: PageLoad = ({ params }) => ({ sampleId: params.id });`