Initial VariantLens clinical readiness scaffold

.env.example

@@ -0,0 +1,98 @@
+# =============================================================================
+# VariantLens — environment variables
+# Copy this file to `.env` and fill in real values. Never commit `.env`.
+# =============================================================================
+
+# ---- LLM ---------------------------------------------------------------------
+# Anthropic API key for the Claude reasoning layer.
+# Get one at https://console.anthropic.com
+ANTHROPIC_API_KEY=
+
+# Default model for the literature-evidence reasoning layer.
+# claude-sonnet-4-6 is the cost/quality default; claude-opus-4-7 for hard cases.
+ANTHROPIC_MODEL=claude-sonnet-4-6
+ANTHROPIC_MAX_TOKENS=2000
+
+# Air-gap toggle. When true, the reasoner uses a local Ollama model instead of
+# the Anthropic API. Required for fully on-premise clinical deployments.
+USE_LOCAL_LLM=false
+LOCAL_LLM_BASE_URL=http://localhost:11434
+LOCAL_LLM_MODEL=qwen2.5:14b-instruct
+
+# ---- External biomedical APIs -----------------------------------------------
+# NCBI E-utilities key. Free; raises rate limit from 3 to 10 req/s.
+# https://www.ncbi.nlm.nih.gov/account/settings/
+NCBI_API_KEY=
+NCBI_EMAIL=
+
+# OMIM API key. Free for academic use.
+# https://www.omim.org/api
+OMIM_API_KEY=
+
+# Mutalyzer + gnomAD do not require keys.
+MUTALYZER_BASE_URL=https://mutalyzer.nl/api
+GNOMAD_GRAPHQL_URL=https://gnomad.broadinstitute.org/api
+SPLICEAI_LOOKUP_URL=https://spliceailookup-api.broadinstitute.org
+CADD_API_URL=https://cadd.gs.washington.edu/api
+
+# ---- Storage -----------------------------------------------------------------
+# PostgreSQL — audit trail, classifications, curator sign-offs.
+POSTGRES_HOST=postgres
+POSTGRES_PORT=5432
+POSTGRES_DB=variantlens
+POSTGRES_USER=variantlens
+POSTGRES_PASSWORD=change_me_locally
+
+DATABASE_URL=postgresql+psycopg://variantlens:change_me_locally@postgres:5432/variantlens
+
+# ChromaDB — local vector store. Embedded mode requires only the persist path.
+CHROMA_PERSIST_DIR=./data/chroma
+CHROMA_COLLECTION=variantlens_pubmed
+
+# Local SQLite caches and pre-scored tables.
+# Build the prediction DBs once with `python -m scripts.build_revel_db <csv>`
+# and `python -m scripts.build_alphamissense_db <tsv.gz>`.
+REVEL_DB_PATH=./data/revel_scores.db
+ALPHAMISSENSE_DB_PATH=./data/alphamissense.db
+GNOMAD_CACHE_DB=./data/gnomad_cache.db
+CLINVAR_VCF_PATH=./data/clinvar.vcf.gz
+
+# ---- Embeddings --------------------------------------------------------------
+# BioLinkBERT for biomedical accuracy; all-MiniLM-L6-v2 for speed.
+EMBEDDING_MODEL=michiyasunaga/BioLinkBERT-base
+EMBEDDING_DEVICE=cpu
+
+# ---- App ---------------------------------------------------------------------
+APP_ENV=development
+LOG_LEVEL=INFO
+API_HOST=0.0.0.0
+API_PORT=8000
+
+# Async job queue (Celery + Redis).
+REDIS_URL=redis://redis:6379/0
+CELERY_BROKER_URL=redis://redis:6379/1
+CELERY_RESULT_BACKEND=redis://redis:6379/2
+
+# ---- Auth (placeholder — wire to hospital LDAP/OAuth in deployment) ----------
+JWT_SECRET=change_me_locally_to_a_long_random_string
+JWT_ALGORITHM=HS256
+JWT_EXPIRE_MINUTES=480
+
+# ---- Feature flags -----------------------------------------------------------
+# When true, also pull full text from PMC; otherwise abstracts only.
+RAG_FETCH_FULLTEXT=true
+RAG_MAX_PAPERS_PER_VARIANT=200
+RAG_CHUNK_SIZE=512
+RAG_CHUNK_OVERLAP=128
+RAG_TOP_K=8
+
+# ACMG ruleset version. Switch to "v4" once SVC v4.0 is finalized.
+ACMG_RULESET_VERSION=v2015
+
+# Clinical default is strict Richards 2015 Table 5. "bayesian" and
+# "most_pathogenic" are available for research/validation only.
+ACMG_COMBINER_STRATEGY=table5
+
+# PP5/BP6 were deprecated by ACMG SVI in 2018. Keep false for clinical use;
+# set true only for backward-compatible research comparisons.
+ENABLE_DEPRECATED_CLINVAR_CRITERIA=false

.gitignore

@@ -0,0 +1,56 @@
+# Secrets
+.env
+.env.local
+.env.*.local
+
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+.venv/
+venv/
+env/
+.eggs/
+*.egg-info/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.coverage
+htmlcov/
+
+# Node
+node_modules/
+dist/
+build/
+.next/
+*.log
+npm-debug.log*
+*.tsbuildinfo
+
+# IDE
+.vscode/
+.idea/
+.claude/
+*.swp
+.DS_Store
+
+# Data — large pre-scored tables and patient data must never be committed
+data/
+!data/.gitkeep
+*.vcf
+*.vcf.gz
+*.tsv.gz
+*.bam
+*.cram
+*.fastq
+*.fastq.gz
+
+# ChromaDB persist dir
+chroma/
+*.parquet
+
+# Reports / exports (may contain PHI)
+reports/
+exports/

AGENTS.md

@@ -0,0 +1,105 @@
+# VariantLens
+
+Clinical genomic variant interpretation tool for the Jordan Lerner-Ellis Lab. Built around the ACMG/AMP 2015 framework (Richards et al.) with the SVC v4.0 transition in mind. Modeled on the three tools showcased at the November 2025 GA4GH/ClinGen CGLC session: AI CURA (96% concordance via RAG + DeepSeek-R1), EvAgg (Broad/Microsoft evidence aggregator), and AutoPM3 (HKU PM3 extractor).
+
+The full design lives in `docs/VariantLens_Build_Plan.md`. The supporting literature review lives in `docs/AI_Variant_Interpretation_Review.md`. Read those before making non-trivial architectural changes.
+
+## Non-negotiables
+
+- **Human-in-the-loop.** A trained curator signs off every classification. The tool surfaces evidence and proposes criteria; it does not autonomously classify for clinical use.
+- **On-prem patient data.** No genomic data is sent to cloud APIs without explicit opt-in. The `USE_LOCAL_LLM` flag must always provide a working air-gapped path (Ollama + open-source model).
+- **Audit trail.** Every triggered ACMG criterion is traceable to a source — a database row, a PMID, or a curator override with free-text justification.
+- **Anti-hallucination is structural, not cosmetic.** Codex is only allowed to reason over RAG-retrieved chunks, must cite PMIDs verbatim, and must emit structured JSON. If the context lacks evidence, the only valid output is "insufficient evidence in provided literature".
+- **Database facts never go through the LLM.** gnomAD AFs, ClinVar classifications, REVEL/SpliceAI/AlphaMissense scores are scored deterministically. Codex only handles literature-dependent criteria: PM3, PP1, PS3/BS3, PS4, PP4, PS2/PM6, PP5/BP6.
+
+## Architecture (one-line summary)
+
+`Mutalyzer normalize → parallel evidence (gnomAD, ClinVar, in-silico, autoPVS1) → ACMG rule engine (InterVar-extended) → RAG over PubMed via ChromaDB → Codex reasons over retrieved chunks → Table 5 combiner → curator review UI → PDF/ClinVar/FHIR export.`
+
+## What we reuse vs. build
+
+**Reuse (do not reimplement):**
+- `autoPVS1` for PVS1
+- `InterVar` as the rule-engine scaffold (extend from ~18 to all 28 criteria)
+- `Mutalyzer` for HGVS normalization (PyHGVS as offline fallback)
+- Pre-scored tables for REVEL, AlphaMissense, SpliceAI (do not run the models per variant)
+- `ChromaDB` for the vector store, `sentence-transformers` (BioLinkBERT) for embeddings
+
+**Build ourselves:**
+- The orchestration layer (FastAPI services in `backend/app/services/`)
+- The criterion-aware RAG retriever (different queries for PM3 vs. PP1 vs. PS3)
+- The Codex prompt templates (one per literature-dependent criterion)
+- The Table 5 combiner with conflict detection
+- The curator dashboard
+
+## Tech stack
+
+```
+Backend:    Python 3.12, FastAPI, SQLAlchemy, Celery (async jobs)
+Frontend:   React 18, TypeScript, Tailwind, React Query, Zustand
+Databases:  PostgreSQL (audit trail), SQLite (REVEL/gnomAD offline cache)
+Vector DB:  ChromaDB (embedded, on-prem)
+Embeddings: sentence-transformers (BioLinkBERT preferred; all-MiniLM-L6-v2 fallback)
+LLM:        Anthropic Codex (Codex-sonnet-4-6 for the reasoning layer; Codex-opus-4-7 only for hard cases)
+            Local fallback: Ollama + qwen2.5 or mistral-nemo
+Containers: Docker + docker-compose
+Tests:      pytest, hypothesis (property-based on the combiner)
+```
+
+## Directory layout
+
+```
+backend/         FastAPI app
+  app/api/       Routers: variants, evidence, reports
+  app/services/  normalization, gnomad, clinvar, insilico, pvs1, rag/, acmg/, llm/
+  app/models/    SQLAlchemy
+  tests/
+frontend/        React + TS
+data/            Pre-scored tables, gnomAD cache, ChromaDB persist dir
+docs/            Build plan, literature review, ACMG references
+docker-compose.yml
+.env.example
+.env             gitignored — fill from .env.example
+```
+
+## Phase plan (~5 weeks)
+
+0. Scaffold + Docker (day 1)
+1. Mutalyzer normalization + 20-variant edge-case test set (day 2–3)
+2. gnomAD, ClinVar, in-silico predictors, autoPVS1 (day 4–7)
+3. RAG: PubMed fetch → chunk → embed → ChromaDB → criterion-aware retriever (day 8–11)
+4. ACMG rule engine: 28 criteria + Table 5 combiner; ≥85% concordance on 50 ClinVar variants (day 12–15)
+5. Codex reasoning layer with hallucination-suppression prompts (day 16–18)
+6. React curator dashboard + PDF/ClinVar/FHIR export (day 19–22)
+7. Validation: 100 4-star ClinVar expert-panel variants; hallucination-guard tests (day 23–25)
+
+## Validation bar
+
+- **Classification concordance:** ≥85% on a held-out set of 100 ClinVar 4-star expert-panel variants. Stretch: match AI CURA's 96%.
+- **Hallucination guard:** When fed deliberately empty/wrong literature contexts, Codex must NOT trigger PM3/PP1/PS3 and must only cite PMIDs that are present in the provided context.
+- **Performance:** <30 s per variant (RAG included); 100 variants/hour batch throughput.
+- **Audit:** Every triggered criterion has a traceable source field. No criterion fires with empty `evidence_text`.
+
+## Conventions
+
+- Pydantic models for every service input/output. No `dict[str, Any]` at module boundaries.
+- All LLM calls return JSON validated against a pydantic schema; if validation fails, retry once with a "your previous output was invalid JSON, here is the schema" repair prompt, then fail closed.
+- Every external API client implements local caching (SQLite or filesystem) and respects rate limits — NCBI is 3 req/s without a key, 10 req/s with one. Treat cache misses as the slow path, not the default.
+- Never write the canonical HGVS as a free-form string in the DB. Always store the Mutalyzer-normalized form and keep the user-supplied input separately for round-tripping.
+- Keep `Codex-sonnet-4-6` as the default model. Only escalate individual hard variants to `Codex-opus-4-7` after benchmarking shows it changes outcomes.
+
+## Keys and external services
+
+See `.env.example` for the full list. Required to run end-to-end:
+- `ANTHROPIC_API_KEY` — paid, console.anthropic.com
+- `NCBI_API_KEY` — free, raises rate limits to 10 req/s
+- `OMIM_API_KEY` — free for academic use
+
+`gnomAD` and `Mutalyzer` are open APIs and need no keys.
+
+## Notes for collaborators (and Codex)
+
+- This is an intern project under active mentorship. Prefer small, reviewed PRs over big-bang merges.
+- When in doubt about an ACMG criterion, cite the relevant section of Richards 2015 in the code comment, not just a paraphrase.
+- The ACMG SVC v4.0 update (piloted March 2025) will change criterion weighting. Keep the rule logic in `services/acmg/rules.py` versioned (`rules_v2015.py`, `rules_v4.py`) so the swap is mechanical, not a rewrite.
+- GA4GH VRS / VA-Spec interop is a stretch goal but worth keeping the data models compatible with from day one.

CLAUDE.md

@@ -0,0 +1,105 @@
+# VariantLens
+
+Clinical genomic variant interpretation tool for the Jordan Lerner-Ellis Lab. Built around the ACMG/AMP 2015 framework (Richards et al.) with the SVC v4.0 transition in mind. Modeled on the three tools showcased at the November 2025 GA4GH/ClinGen CGLC session: AI CURA (96% concordance via RAG + DeepSeek-R1), EvAgg (Broad/Microsoft evidence aggregator), and AutoPM3 (HKU PM3 extractor).
+
+The full design lives in `docs/VariantLens_Build_Plan.md`. The supporting literature review lives in `docs/AI_Variant_Interpretation_Review.md`. Read those before making non-trivial architectural changes.
+
+## Non-negotiables
+
+- **Human-in-the-loop.** A trained curator signs off every classification. The tool surfaces evidence and proposes criteria; it does not autonomously classify for clinical use.
+- **On-prem patient data.** No genomic data is sent to cloud APIs without explicit opt-in. The `USE_LOCAL_LLM` flag must always provide a working air-gapped path (Ollama + open-source model).
+- **Audit trail.** Every triggered ACMG criterion is traceable to a source — a database row, a PMID, or a curator override with free-text justification.
+- **Anti-hallucination is structural, not cosmetic.** Claude is only allowed to reason over RAG-retrieved chunks, must cite PMIDs verbatim, and must emit structured JSON. If the context lacks evidence, the only valid output is "insufficient evidence in provided literature".
+- **Database facts never go through the LLM.** gnomAD AFs, ClinVar classifications, REVEL/SpliceAI/AlphaMissense scores are scored deterministically. Claude only handles literature-dependent criteria: PM3, PP1, PS3/BS3, PS4, PP4, PS2/PM6, PP5/BP6.
+
+## Architecture (one-line summary)
+
+`Mutalyzer normalize → parallel evidence (gnomAD, ClinVar, in-silico, autoPVS1) → ACMG rule engine (InterVar-extended) → RAG over PubMed via ChromaDB → Claude reasons over retrieved chunks → Table 5 combiner → curator review UI → PDF/ClinVar/FHIR export.`
+
+## What we reuse vs. build
+
+**Reuse (do not reimplement):**
+- `autoPVS1` for PVS1
+- `InterVar` as the rule-engine scaffold (extend from ~18 to all 28 criteria)
+- `Mutalyzer` for HGVS normalization (PyHGVS as offline fallback)
+- Pre-scored tables for REVEL, AlphaMissense, SpliceAI (do not run the models per variant)
+- `ChromaDB` for the vector store, `sentence-transformers` (BioLinkBERT) for embeddings
+
+**Build ourselves:**
+- The orchestration layer (FastAPI services in `backend/app/services/`)
+- The criterion-aware RAG retriever (different queries for PM3 vs. PP1 vs. PS3)
+- The Claude prompt templates (one per literature-dependent criterion)
+- The Table 5 combiner with conflict detection
+- The curator dashboard
+
+## Tech stack
+
+```
+Backend:    Python 3.12, FastAPI, SQLAlchemy, Celery (async jobs)
+Frontend:   React 18, TypeScript, Tailwind, React Query, Zustand
+Databases:  PostgreSQL (audit trail), SQLite (REVEL/gnomAD offline cache)
+Vector DB:  ChromaDB (embedded, on-prem)
+Embeddings: sentence-transformers (BioLinkBERT preferred; all-MiniLM-L6-v2 fallback)
+LLM:        Anthropic Claude (claude-sonnet-4-6 for the reasoning layer; claude-opus-4-7 only for hard cases)
+            Local fallback: Ollama + qwen2.5 or mistral-nemo
+Containers: Docker + docker-compose
+Tests:      pytest, hypothesis (property-based on the combiner)
+```
+
+## Directory layout
+
+```
+backend/         FastAPI app
+  app/api/       Routers: variants, evidence, reports
+  app/services/  normalization, gnomad, clinvar, insilico, pvs1, rag/, acmg/, llm/
+  app/models/    SQLAlchemy
+  tests/
+frontend/        React + TS
+data/            Pre-scored tables, gnomAD cache, ChromaDB persist dir
+docs/            Build plan, literature review, ACMG references
+docker-compose.yml
+.env.example
+.env             gitignored — fill from .env.example
+```
+
+## Phase plan (~5 weeks)
+
+0. Scaffold + Docker (day 1)
+1. Mutalyzer normalization + 20-variant edge-case test set (day 2–3)
+2. gnomAD, ClinVar, in-silico predictors, autoPVS1 (day 4–7)
+3. RAG: PubMed fetch → chunk → embed → ChromaDB → criterion-aware retriever (day 8–11)
+4. ACMG rule engine: 28 criteria + Table 5 combiner; ≥85% concordance on 50 ClinVar variants (day 12–15)
+5. Claude reasoning layer with hallucination-suppression prompts (day 16–18)
+6. React curator dashboard + PDF/ClinVar/FHIR export (day 19–22)
+7. Validation: 100 4-star ClinVar expert-panel variants; hallucination-guard tests (day 23–25)
+
+## Validation bar
+
+- **Classification concordance:** ≥85% on a held-out set of 100 ClinVar 4-star expert-panel variants. Stretch: match AI CURA's 96%.
+- **Hallucination guard:** When fed deliberately empty/wrong literature contexts, Claude must NOT trigger PM3/PP1/PS3 and must only cite PMIDs that are present in the provided context.
+- **Performance:** <30 s per variant (RAG included); 100 variants/hour batch throughput.
+- **Audit:** Every triggered criterion has a traceable source field. No criterion fires with empty `evidence_text`.
+
+## Conventions
+
+- Pydantic models for every service input/output. No `dict[str, Any]` at module boundaries.
+- All LLM calls return JSON validated against a pydantic schema; if validation fails, retry once with a "your previous output was invalid JSON, here is the schema" repair prompt, then fail closed.
+- Every external API client implements local caching (SQLite or filesystem) and respects rate limits — NCBI is 3 req/s without a key, 10 req/s with one. Treat cache misses as the slow path, not the default.
+- Never write the canonical HGVS as a free-form string in the DB. Always store the Mutalyzer-normalized form and keep the user-supplied input separately for round-tripping.
+- Keep `claude-sonnet-4-6` as the default model. Only escalate individual hard variants to `claude-opus-4-7` after benchmarking shows it changes outcomes.
+
+## Keys and external services
+
+See `.env.example` for the full list. Required to run end-to-end:
+- `ANTHROPIC_API_KEY` — paid, console.anthropic.com
+- `NCBI_API_KEY` — free, raises rate limits to 10 req/s
+- `OMIM_API_KEY` — free for academic use
+
+`gnomAD` and `Mutalyzer` are open APIs and need no keys.
+
+## Notes for collaborators (and Claude)
+
+- This is an intern project under active mentorship. Prefer small, reviewed PRs over big-bang merges.
+- When in doubt about an ACMG criterion, cite the relevant section of Richards 2015 in the code comment, not just a paraphrase.
+- The ACMG SVC v4.0 update (piloted March 2025) will change criterion weighting. Keep the rule logic in `services/acmg/rules.py` versioned (`rules_v2015.py`, `rules_v4.py`) so the swap is mechanical, not a rewrite.
+- GA4GH VRS / VA-Spec interop is a stretch goal but worth keeping the data models compatible with from day one.

Makefile

@@ -0,0 +1,63 @@
+SHELL := /bin/bash
+
+.PHONY: help install up down logs migrate seed test test-fast test-slow lint typecheck frontend-dev frontend-build clean
+
+help:
+	@echo "VariantLens — common commands"
+	@echo ""
+	@echo "  make install         install backend (editable) + frontend deps"
+	@echo "  make up              docker compose up (api, worker, postgres, redis, frontend)"
+	@echo "  make down            docker compose down (preserves volumes)"
+	@echo "  make logs            tail logs from all containers"
+	@echo "  make migrate         run alembic migrations against the running postgres"
+	@echo "  make seed            pull 100 ClinVar 4-star variants into the eval fixture"
+	@echo "  make test            run fast unit tests (skips slow/external)"
+	@echo "  make test-slow       run the concordance harness (needs API keys + seeded fixture)"
+	@echo "  make lint            ruff check"
+	@echo "  make typecheck       mypy backend + tsc frontend"
+	@echo "  make frontend-dev    Vite dev server (no docker)"
+	@echo "  make clean           remove caches and build artifacts (preserves data/)"
+
+install:
+	pip install -e ".[dev]"
+	cd frontend && npm install
+
+up:
+	docker compose up --build
+
+down:
+	docker compose down
+
+logs:
+	docker compose logs -f --tail=200
+
+migrate:
+	docker compose run --rm api alembic upgrade head
+
+seed:
+	python -m scripts.seed_eval_set --n 100
+
+test:
+	pytest -m "not slow"
+
+test-slow:
+	pytest -m slow
+
+lint:
+	ruff check backend scripts
+
+typecheck:
+	mypy backend
+	cd frontend && npm run typecheck
+
+frontend-dev:
+	cd frontend && npm run dev
+
+frontend-build:
+	cd frontend && npm run build
+
+clean:
+	rm -rf .pytest_cache .mypy_cache .ruff_cache htmlcov .coverage
+	find backend -type d -name __pycache__ -exec rm -rf {} +
+	find scripts -type d -name __pycache__ -exec rm -rf {} +
+	cd frontend && rm -rf dist node_modules/.vite

README.md

@@ -0,0 +1,82 @@
+# VariantLens
+
+Clinical genomic variant interpretation tool. ACMG/AMP rule engine + RAG over PubMed + Claude reasoning, with a curator review UI. Built for the Jordan Lerner-Ellis Lab.
+
+See [CLAUDE.md](CLAUDE.md) for architecture, conventions, and validation bar. See [docs/](docs/) for the full build plan and literature review.
+
+For lab or clinical-trial preparation, start with
+[docs/Clinical_Readiness_Checklist.md](docs/Clinical_Readiness_Checklist.md).
+VariantLens is a human-in-the-loop curator-support tool; it is not an
+autonomous clinical classifier.
+
+## Quick start
+
+```bash
+# 1. Fill in API keys
+cp .env.example .env  # then edit .env with your keys
+
+# 2. Bring everything up (postgres, redis, api, worker, frontend)
+make up                            # or: docker compose up --build
+
+# 3. Open
+#    Frontend: http://localhost:5173
+#    API docs: http://localhost:8000/docs
+```
+
+Migrations apply automatically on API startup. Run `make help` for the full list of commands (`make seed`, `make test`, `make test-slow`, `make typecheck`, etc.).
+
+For non-docker local dev (debugger-friendly): `./scripts/dev.sh` boots uvicorn against a local SQLite file plus the Vite dev server.
+
+## Required keys
+
+- `ANTHROPIC_API_KEY` — paid, [console.anthropic.com](https://console.anthropic.com)
+- `NCBI_API_KEY` + `NCBI_EMAIL` — free, raises NCBI rate limit from 3 to 10 req/s
+- `OMIM_API_KEY` — free for academic use
+
+`gnomAD` and `Mutalyzer` are open APIs and need no keys.
+
+## Layout
+
+```
+backend/        FastAPI + SQLAlchemy + Anthropic SDK
+  app/api/      Routers: variants, evidence, reports
+  app/services/ Domain logic: normalization, databases, RAG, ACMG, LLM
+  app/models/   SQLAlchemy ORM
+  app/schemas/  Pydantic models for API I/O
+  tests/        pytest + hypothesis property tests
+frontend/       React + TypeScript + Vite + Tailwind
+data/           Pre-scored tables (REVEL, AlphaMissense), gnomAD cache, ChromaDB persist
+docs/           Build plan, literature review
+scripts/        Data prep: download REVEL, build SQLite caches, seed evaluation set
+```
+
+## Development
+
+```bash
+make test               # fast unit tests (skips external APIs)
+make test-slow          # concordance harness (needs API keys + seeded fixture)
+make lint               # ruff check
+make typecheck          # mypy backend + tsc frontend
+make seed               # pull 100 ClinVar 4-star variants for the eval fixture
+```
+
+### Data prep (one-time)
+
+```bash
+# REVEL — download revel-v1.3_all_chromosomes.csv from
+# https://sites.google.com/site/revelgenomics/downloads first.
+python -m scripts.build_revel_db /path/to/revel-v1.3_all_chromosomes.csv
+
+# Eval fixture — pulls expert-panel ClinVar variants for the test harness.
+make seed
+
+# (Optional) pre-warm the gnomAD cache for a known variant list.
+python -m scripts.warm_gnomad_cache variant_ids.txt
+```
+
+## Validation bar
+
+- ≥85% classification concordance against 100 ClinVar 4-star expert-panel variants
+- Hallucination guard: empty/wrong literature contexts must NOT trigger PM3/PP1/PS3 and must only cite PMIDs present in the provided context
+- <30 s per variant including RAG; 100 variants/hour batch throughput
+- Every triggered ACMG criterion has a traceable source field

alembic.ini

@@ -0,0 +1,44 @@
+[alembic]
+script_location = backend/alembic
+prepend_sys_path = .
+version_path_separator = os
+
+# Read the URL from the environment (DATABASE_URL) at runtime — we set it in
+# backend/alembic/env.py from `backend.app.config.get_settings`.
+sqlalchemy.url = driver://user:pass@host/db
+
+[post_write_hooks]
+
+[loggers]
+keys = root,sqlalchemy,alembic
+
+[handlers]
+keys = console
+
+[formatters]
+keys = generic
+
+[logger_root]
+level = WARN
+handlers = console
+qualname =
+
+[logger_sqlalchemy]
+level = WARN
+handlers =
+qualname = sqlalchemy.engine
+
+[logger_alembic]
+level = INFO
+handlers =
+qualname = alembic
+
+[handler_console]
+class = StreamHandler
+args = (sys.stderr,)
+level = NOTSET
+formatter = generic
+
+[formatter_generic]
+format = %(levelname)-5.5s [%(name)s] %(message)s
+datefmt = %H:%M:%S

backend/Dockerfile

@@ -0,0 +1,23 @@
+FROM python:3.12-slim
+
+WORKDIR /app
+
+ENV PYTHONUNBUFFERED=1 \
+    PIP_DISABLE_PIP_VERSION_CHECK=1
+
+RUN apt-get update && apt-get install -y --no-install-recommends \
+    build-essential \
+    curl \
+    && rm -rf /var/lib/apt/lists/*
+
+COPY pyproject.toml ./
+RUN pip install --no-cache-dir --upgrade pip && \
+    pip install --no-cache-dir -e ".[dev]"
+
+COPY backend ./backend
+COPY scripts ./scripts
+COPY alembic.ini ./
+
+EXPOSE 8000
+
+CMD ["uvicorn", "backend.app.main:app", "--host", "0.0.0.0", "--port", "8000"]

backend/alembic/env.py

@@ -0,0 +1,57 @@
+"""Alembic env wired to the project Settings + SQLAlchemy Base."""
+from __future__ import annotations
+
+from logging.config import fileConfig
+
+from alembic import context
+from sqlalchemy import engine_from_config, pool
+
+from backend.app.config import get_settings
+
+# Import every model so Base.metadata is populated for autogenerate.
+from backend.app.models import classification as _classification  # noqa: F401
+from backend.app.models import variant as _variant  # noqa: F401
+from backend.app.models.db import Base
+
+config = context.config
+if config.config_file_name is not None:
+    fileConfig(config.config_file_name)
+
+# Override the sqlalchemy.url placeholder from alembic.ini with the live DSN.
+config.set_main_option("sqlalchemy.url", get_settings().database_url)
+
+target_metadata = Base.metadata
+
+
+def run_migrations_offline() -> None:
+    context.configure(
+        url=config.get_main_option("sqlalchemy.url"),
+        target_metadata=target_metadata,
+        literal_binds=True,
+        dialect_opts={"paramstyle": "named"},
+        compare_type=True,
+    )
+    with context.begin_transaction():
+        context.run_migrations()
+
+
+def run_migrations_online() -> None:
+    connectable = engine_from_config(
+        config.get_section(config.config_ini_section, {}),
+        prefix="sqlalchemy.",
+        poolclass=pool.NullPool,
+    )
+    with connectable.connect() as connection:
+        context.configure(
+            connection=connection,
+            target_metadata=target_metadata,
+            compare_type=True,
+        )
+        with context.begin_transaction():
+            context.run_migrations()
+
+
+if context.is_offline_mode():
+    run_migrations_offline()
+else:
+    run_migrations_online()

backend/alembic/script.py.mako

@@ -0,0 +1,27 @@
+"""${message}
+
+Revision ID: ${up_revision}
+Revises: ${down_revision | comma,n}
+Create Date: ${create_date}
+
+"""
+from __future__ import annotations
+
+from typing import Sequence, Union
+
+from alembic import op
+import sqlalchemy as sa
+${imports if imports else ""}
+
+revision: str = ${repr(up_revision)}
+down_revision: Union[str, None] = ${repr(down_revision)}
+branch_labels: Union[str, Sequence[str], None] = ${repr(branch_labels)}
+depends_on: Union[str, Sequence[str], None] = ${repr(depends_on)}
+
+
+def upgrade() -> None:
+    ${upgrades if upgrades else "pass"}
+
+
+def downgrade() -> None:
+    ${downgrades if downgrades else "pass"}

backend/alembic/versions/0001_init.py

@@ -0,0 +1,77 @@
+"""initial schema — variants, classifications, criteria
+
+Revision ID: 0001_init
+Revises:
+Create Date: 2026-04-28 10:00:00
+
+"""
+from __future__ import annotations
+
+import sqlalchemy as sa
+from alembic import op
+
+revision = "0001_init"
+down_revision = None
+branch_labels = None
+depends_on = None
+
+
+def upgrade() -> None:
+    op.create_table(
+        "variants",
+        sa.Column("id", sa.String(length=36), primary_key=True),
+        sa.Column("raw_input", sa.String(length=512), nullable=False),
+        sa.Column("hgvs_genomic", sa.String(length=512)),
+        sa.Column("hgvs_coding", sa.String(length=512)),
+        sa.Column("hgvs_protein", sa.String(length=512)),
+        sa.Column("transcript", sa.String(length=64)),
+        sa.Column("gene_symbol", sa.String(length=64), index=True),
+        sa.Column("chromosome", sa.String(length=8)),
+        sa.Column("position", sa.Integer()),
+        sa.Column("normalization_source", sa.String(length=32), nullable=False, server_default="mutalyzer"),
+        sa.Column("warnings", sa.JSON(), nullable=False, server_default="[]"),
+        sa.Column("submitted_at", sa.DateTime(), nullable=False, server_default=sa.func.now()),
+    )
+    # ix_variants_gene_symbol auto-created by `index=True` on the column above
+
+    op.create_table(
+        "classifications",
+        sa.Column("id", sa.String(length=36), primary_key=True),
+        sa.Column("variant_id", sa.String(length=36), sa.ForeignKey("variants.id", ondelete="CASCADE"), nullable=False),
+        sa.Column("significance", sa.String(length=32), nullable=False),
+        sa.Column("confidence", sa.String(length=16), nullable=False, server_default="medium"),
+        sa.Column("triggered_criteria", sa.JSON(), nullable=False, server_default="[]"),
+        sa.Column("conflicting_evidence", sa.Boolean(), nullable=False, server_default=sa.false()),
+        sa.Column("ruleset_version", sa.String(length=16), nullable=False, server_default="v2015"),
+        sa.Column("rationale", sa.Text()),
+        sa.Column("curator_signoff", sa.Boolean(), nullable=False, server_default=sa.false()),
+        sa.Column("curator_id", sa.String(length=64)),
+        sa.Column("signed_off_at", sa.DateTime()),
+        sa.Column("created_at", sa.DateTime(), nullable=False, server_default=sa.func.now()),
+    )
+    op.create_index("ix_classifications_variant_id", "classifications", ["variant_id"])
+
+    op.create_table(
+        "criteria",
+        sa.Column("id", sa.String(length=36), primary_key=True),
+        sa.Column("classification_id", sa.String(length=36), sa.ForeignKey("classifications.id", ondelete="CASCADE"), nullable=False),
+        sa.Column("code", sa.String(length=8), nullable=False),
+        sa.Column("triggered", sa.Boolean(), nullable=False, server_default=sa.false()),
+        sa.Column("strength", sa.String(length=16), nullable=False),
+        sa.Column("source", sa.String(length=128), nullable=False),
+        sa.Column("evidence_text", sa.Text(), nullable=False),
+        sa.Column("confidence", sa.String(length=16), nullable=False, server_default="medium"),
+        sa.Column("pmid", sa.String(length=32)),
+        sa.Column("caveat", sa.Text()),
+        sa.Column("curator_override", sa.Boolean(), nullable=False, server_default=sa.false()),
+        sa.Column("override_justification", sa.Text()),
+    )
+    op.create_index("ix_criteria_classification_id", "criteria", ["classification_id"])
+
+
+def downgrade() -> None:
+    op.drop_index("ix_criteria_classification_id", table_name="criteria")
+    op.drop_table("criteria")
+    op.drop_index("ix_classifications_variant_id", table_name="classifications")
+    op.drop_table("classifications")
+    op.drop_table("variants")  # auto-index drops with the table

backend/app/api/evidence.py

@@ -0,0 +1,78 @@
+from datetime import datetime
+from typing import Annotated
+
+from fastapi import APIRouter, Depends, HTTPException
+from pydantic import BaseModel
+from sqlalchemy.orm import Session
+
+from backend.app.models.classification import ClassificationRecord, CriterionRecord
+from backend.app.models.db import get_session
+from backend.app.schemas.evidence import ACMGCriterion
+
+router = APIRouter()
+SessionDep = Annotated[Session, Depends(get_session)]
+
+
+class CriterionOverride(BaseModel):
+    triggered: bool
+    strength: str
+    justification: str
+    curator_id: str
+
+
+@router.get("/{classification_id}", response_model=list[ACMGCriterion])
+def get_criteria(classification_id: str, db: SessionDep) -> list[ACMGCriterion]:
+    record = db.get(ClassificationRecord, classification_id)
+    if not record:
+        raise HTTPException(404, "classification not found")
+    return [
+        ACMGCriterion(
+            code=c.code,
+            triggered=c.triggered,
+            strength=c.strength,
+            source=c.source,
+            evidence_text=c.evidence_text,
+            confidence=c.confidence,
+            caveat=c.caveat,
+            pmid=c.pmid,
+            curator_override=c.curator_override,
+            override_justification=c.override_justification,
+        )
+        for c in record.criteria
+    ]
+
+
+@router.post("/{classification_id}/{criterion_code}/override", response_model=ACMGCriterion)
+def override_criterion(
+    classification_id: str,
+    criterion_code: str,
+    override: CriterionOverride,
+    db: SessionDep,
+) -> ACMGCriterion:
+    rec = (
+        db.query(CriterionRecord)
+        .filter_by(classification_id=classification_id, code=criterion_code)
+        .one_or_none()
+    )
+    if not rec:
+        raise HTTPException(404, "criterion not found")
+    rec.triggered = override.triggered
+    rec.strength = override.strength
+    rec.curator_override = True
+    rec.override_justification = (
+        f"[{override.curator_id} @ {datetime.utcnow().isoformat()}] {override.justification}"
+    )
+    db.commit()
+    db.refresh(rec)
+    return ACMGCriterion(
+        code=rec.code,
+        triggered=rec.triggered,
+        strength=rec.strength,
+        source=rec.source,
+        evidence_text=rec.evidence_text,
+        confidence=rec.confidence,
+        caveat=rec.caveat,
+        pmid=rec.pmid,
+        curator_override=rec.curator_override,
+        override_justification=rec.override_justification,
+    )

backend/app/api/pipeline.py

@@ -0,0 +1,102 @@
+"""End-to-end pipeline that wires services together."""
+
+import logging
+from uuid import uuid4
+
+from backend.app.schemas.classification import ClassificationResult
+from backend.app.schemas.evidence import EvidenceBundle, LiteratureChunk
+from backend.app.schemas.variant import VariantInput
+from backend.app.services.clinvar import ClinVarClient
+from backend.app.services.gnomad import GnomADClient
+from backend.app.services.insilico import InSilicoPredictor
+from backend.app.services.llm.synthesizer import LITERATURE_CRITERIA, EvidenceSynthesizer
+from backend.app.services.normalization import VariantNormalizer
+from backend.app.services.pvs1 import PVS1Assessor
+from backend.app.services.rag.retriever import LiteratureRetriever
+from backend.app.services.vep import VEPClient
+
+logger = logging.getLogger(__name__)
+
+
+class VariantPipeline:
+    def __init__(
+        self,
+        normalizer: VariantNormalizer | None = None,
+        vep: VEPClient | None = None,
+        gnomad: GnomADClient | None = None,
+        clinvar: ClinVarClient | None = None,
+        insilico: InSilicoPredictor | None = None,
+        pvs1: PVS1Assessor | None = None,
+        retriever: LiteratureRetriever | None = None,
+        synthesizer: EvidenceSynthesizer | None = None,
+    ) -> None:
+        self.normalizer = normalizer or VariantNormalizer()
+        self.vep = vep or VEPClient()
+        self.gnomad = gnomad or GnomADClient()
+        self.clinvar = clinvar or ClinVarClient()
+        self.insilico = insilico or InSilicoPredictor()
+        self.pvs1 = pvs1 or PVS1Assessor()
+        self.retriever = retriever or LiteratureRetriever()
+        self.synthesizer = synthesizer or EvidenceSynthesizer()
+
+    async def run(self, variant_input: VariantInput, skip_rag: bool = False) -> ClassificationResult:
+        variant = await self.normalizer.normalize(variant_input)
+        # Enrich with chr/pos/ref/alt + transcript + consequence via VEP
+        # so REVEL/AlphaMissense/gnomAD have what they need on HGVS-coding input.
+        # Best-effort — VEP failure doesn't block the rest of the pipeline.
+        if not all([variant.chromosome, variant.position, variant.ref, variant.alt]):
+            variant = await self.vep.enrich(variant)
+        variant_id = str(uuid4())
+
+        gnomad_id = self._build_gnomad_id(variant)
+        freq = await self.gnomad.lookup(gnomad_id) if gnomad_id else None
+
+        clinvar = await self.clinvar.lookup(variant.hgvs_coding or variant.raw_input)
+        insilico = await self.insilico.assess(
+            chrom=variant.chromosome,
+            pos=variant.position,
+            ref=variant.ref,
+            alt=variant.alt,
+            transcript=variant.transcript,
+            hgvs_genomic=variant.hgvs_genomic,
+        )
+        autopvs1 = self.pvs1.assess(variant)
+
+        evidence = EvidenceBundle(
+            population_frequency=freq,
+            insilico=insilico,
+            clinvar_existing=clinvar or [],
+            autopvs1=autopvs1,
+        )
+
+        retrieved: dict[str, list[LiteratureChunk]] = {}
+        if not skip_rag and variant.gene_symbol:
+            try:
+                await self.retriever.index_for_variant(
+                    variant_id=variant_id,
+                    gene=variant.gene_symbol,
+                    hgvs=variant.hgvs_coding or variant.raw_input,
+                    protein=variant.hgvs_protein,
+                    criteria=LITERATURE_CRITERIA,
+                )
+                retrieved = self.retriever.retrieve_for_criteria(
+                    variant_id=variant_id,
+                    hgvs=variant.hgvs_coding or variant.raw_input,
+                    criteria=LITERATURE_CRITERIA,
+                )
+            except Exception as e:
+                logger.warning("RAG indexing/retrieval failed; continuing without literature: %s", e)
+
+        return self.synthesizer.synthesize(
+            variant=variant,
+            evidence=evidence,
+            retrieved_chunks=retrieved,
+            disease=variant_input.disease,
+        )
+
+    @staticmethod
+    def _build_gnomad_id(variant) -> str | None:
+        if variant.chromosome and variant.position and variant.ref and variant.alt:
+            chrom = variant.chromosome.replace("chr", "")
+            return f"{chrom}-{variant.position}-{variant.ref}-{variant.alt}"
+        return None

backend/app/api/reports.py

@@ -0,0 +1,98 @@
+from datetime import UTC, datetime
+from typing import Annotated
+
+from fastapi import APIRouter, Depends, HTTPException
+from fastapi.responses import Response
+from sqlalchemy.orm import Session
+
+from backend.app.models.classification import ClassificationRecord
+from backend.app.models.db import get_session
+from backend.app.services.exports import render_clinvar_xml, render_fhir_observation
+
+router = APIRouter()
+SessionDep = Annotated[Session, Depends(get_session)]
+
+
+@router.get("/{classification_id}")
+def get_report(classification_id: str, db: SessionDep) -> dict:
+    rec = db.get(ClassificationRecord, classification_id)
+    if not rec:
+        raise HTTPException(404, "classification not found")
+    return {
+        "classification_id": rec.id,
+        "variant_id": rec.variant_id,
+        "variant": {
+            "raw_input": rec.variant.raw_input,
+            "hgvs_coding": rec.variant.hgvs_coding,
+            "hgvs_protein": rec.variant.hgvs_protein,
+            "hgvs_genomic": rec.variant.hgvs_genomic,
+            "gene_symbol": rec.variant.gene_symbol,
+        } if rec.variant else None,
+        "significance": rec.significance,
+        "confidence": rec.confidence,
+        "ruleset_version": rec.ruleset_version,
+        "rationale": rec.rationale,
+        "triggered_criteria": rec.triggered_criteria,
+        "conflicting_evidence": rec.conflicting_evidence,
+        "curator_signoff": rec.curator_signoff,
+        "curator_id": rec.curator_id,
+        "signed_off_at": rec.signed_off_at.isoformat() if rec.signed_off_at else None,
+        "criteria": [
+            {
+                "code": c.code,
+                "triggered": c.triggered,
+                "strength": c.strength,
+                "source": c.source,
+                "evidence_text": c.evidence_text,
+                "confidence": c.confidence,
+                "pmid": c.pmid,
+                "caveat": c.caveat,
+                "curator_override": c.curator_override,
+                "override_justification": c.override_justification,
+            }
+            for c in rec.criteria
+        ],
+        "generated_at": datetime.now(UTC).isoformat(),
+    }
+
+
+@router.post("/{classification_id}/signoff")
+def signoff(classification_id: str, curator_id: str, db: SessionDep) -> dict:
+    rec = db.get(ClassificationRecord, classification_id)
+    if not rec:
+        raise HTTPException(404, "classification not found")
+    if rec.conflicting_evidence:
+        # Allow but flag — clinical curator should know.
+        pass
+    rec.curator_signoff = True
+    rec.curator_id = curator_id
+    rec.signed_off_at = datetime.now(UTC).replace(tzinfo=None)
+    db.commit()
+    return {
+        "status": "signed",
+        "curator_id": curator_id,
+        "signed_off_at": rec.signed_off_at.isoformat(),
+    }
+
+
+@router.get("/{classification_id}/clinvar-xml")
+def clinvar_export(classification_id: str, db: SessionDep) -> Response:
+    rec = db.get(ClassificationRecord, classification_id)
+    if not rec:
+        raise HTTPException(404, "classification not found")
+    if not rec.curator_signoff:
+        raise HTTPException(409, "classification must be signed off before ClinVar export")
+    xml = render_clinvar_xml(rec)
+    return Response(content=xml, media_type="application/xml", headers={
+        "Content-Disposition": f'attachment; filename="variantlens_{rec.id}.clinvar.xml"',
+    })
+
+
+@router.get("/{classification_id}/fhir")
+def fhir_export(classification_id: str, db: SessionDep) -> dict:
+    rec = db.get(ClassificationRecord, classification_id)
+    if not rec:
+        raise HTTPException(404, "classification not found")
+    if not rec.curator_signoff:
+        raise HTTPException(409, "classification must be signed off before FHIR export")
+    return render_fhir_observation(rec)

backend/app/api/variants.py

@@ -0,0 +1,43 @@
+import logging
+from typing import Annotated
+
+from fastapi import APIRouter, Depends, HTTPException
+from sqlalchemy.exc import SQLAlchemyError
+from sqlalchemy.orm import Session
+
+from backend.app.api.pipeline import VariantPipeline
+from backend.app.models.db import get_session
+from backend.app.schemas.classification import ClassificationResult
+from backend.app.schemas.variant import NormalizedVariant, VariantInput
+from backend.app.services.repository import ClassificationRepository
+
+logger = logging.getLogger(__name__)
+
+router = APIRouter()
+_pipeline = VariantPipeline()
+SessionDep = Annotated[Session, Depends(get_session)]
+
+
+@router.post("/classify", response_model=ClassificationResult)
+async def classify(
+    variant: VariantInput,
+    db: SessionDep,
+    skip_rag: bool = False,
+) -> ClassificationResult:
+    try:
+        result = await _pipeline.run(variant, skip_rag=skip_rag)
+    except Exception as e:
+        logger.exception("pipeline failed")
+        raise HTTPException(status_code=500, detail=f"pipeline failed: {e}") from e
+
+    try:
+        return ClassificationRepository(db).save(result)
+    except SQLAlchemyError as e:
+        logger.warning("DB persistence failed, returning unsaved result: %s", e)
+        # Return the in-memory result so the UI still renders during dev.
+        return result
+
+
+@router.post("/normalize", response_model=NormalizedVariant)
+async def normalize(variant: VariantInput) -> NormalizedVariant:
+    return await _pipeline.normalizer.normalize(variant)

backend/app/config.py

@@ -0,0 +1,82 @@
+from functools import lru_cache
+from pathlib import Path
+from typing import Literal
+
+from pydantic import Field, model_validator
+from pydantic_settings import BaseSettings, SettingsConfigDict
+
+
+class Settings(BaseSettings):
+    model_config = SettingsConfigDict(
+        env_file=".env",
+        env_file_encoding="utf-8",
+        case_sensitive=False,
+        extra="ignore",
+    )
+
+    app_env: str = "development"
+    log_level: str = "INFO"
+    api_host: str = "0.0.0.0"
+    api_port: int = 8000
+
+    anthropic_api_key: str = ""
+    anthropic_model: str = "claude-sonnet-4-6"
+    anthropic_max_tokens: int = 2000
+    use_local_llm: bool = False
+    local_llm_base_url: str = "http://localhost:11434"
+    local_llm_model: str = "qwen2.5:14b-instruct"
+
+    ncbi_api_key: str = ""
+    ncbi_email: str = ""
+    omim_api_key: str = ""
+
+    mutalyzer_base_url: str = "https://mutalyzer.nl/api"
+    gnomad_graphql_url: str = "https://gnomad.broadinstitute.org/api"
+    spliceai_lookup_url: str = "https://spliceailookup-api.broadinstitute.org"
+    cadd_api_url: str = "https://cadd.gs.washington.edu/api"
+
+    database_url: str = "postgresql+psycopg://variantlens:change_me_locally@postgres:5432/variantlens"
+
+    chroma_persist_dir: Path = Path("./data/chroma")
+    chroma_collection: str = "variantlens_pubmed"
+
+    revel_db_path: Path = Path("./data/revel_scores.db")
+    alphamissense_db_path: Path = Path("./data/alphamissense.db")
+    alphamissense_path: Path = Path("./data/alphamissense.tsv.gz")  # legacy raw TSV path
+    gnomad_cache_db: Path = Path("./data/gnomad_cache.db")
+    clinvar_vcf_path: Path = Path("./data/clinvar.vcf.gz")
+
+    embedding_model: str = "michiyasunaga/BioLinkBERT-base"
+    embedding_device: str = "cpu"
+
+    redis_url: str = "redis://redis:6379/0"
+    celery_broker_url: str = "redis://redis:6379/1"
+    celery_result_backend: str = "redis://redis:6379/2"
+
+    jwt_secret: str = Field(default="change_me", min_length=8)
+    jwt_algorithm: str = "HS256"
+    jwt_expire_minutes: int = 480
+
+    rag_fetch_fulltext: bool = True
+    rag_max_papers_per_variant: int = 200
+    rag_chunk_size: int = 512
+    rag_chunk_overlap: int = 128
+    rag_top_k: int = 8
+
+    acmg_ruleset_version: str = "v2015"
+    acmg_combiner_strategy: Literal["table5", "bayesian", "most_pathogenic"] = "table5"
+    enable_deprecated_clinvar_criteria: bool = False
+
+    @model_validator(mode="after")
+    def validate_clinical_safety(self) -> "Settings":
+        if self.app_env.lower() in {"production", "clinical"}:
+            if self.jwt_secret in {"change_me", "change_me_locally_to_a_long_random_string"}:
+                raise ValueError("JWT_SECRET must be changed for production/clinical deployments")
+            if not self.use_local_llm and not self.anthropic_api_key:
+                raise ValueError("ANTHROPIC_API_KEY is required when USE_LOCAL_LLM=false")
+        return self
+
+
+@lru_cache
+def get_settings() -> Settings:
+    return Settings()

backend/app/main.py

@@ -0,0 +1,67 @@
+import logging
+from contextlib import asynccontextmanager
+from pathlib import Path
+
+from alembic import command
+from alembic.config import Config
+from fastapi import FastAPI
+from fastapi.middleware.cors import CORSMiddleware
+
+from backend.app.api import evidence, reports, variants
+from backend.app.config import get_settings
+
+settings = get_settings()
+logging.basicConfig(level=settings.log_level)
+logger = logging.getLogger(__name__)
+
+PROJECT_ROOT = Path(__file__).resolve().parents[2]
+
+
+def _run_migrations() -> None:
+    cfg_path = PROJECT_ROOT / "alembic.ini"
+    if not cfg_path.exists():
+        logger.warning("alembic.ini not found at %s; skipping auto-migrate", cfg_path)
+        return
+    try:
+        cfg = Config(str(cfg_path))
+        cfg.set_main_option("sqlalchemy.url", settings.database_url)
+        command.upgrade(cfg, "head")
+        logger.info("alembic migrations applied")
+    except Exception as e:
+        logger.warning("alembic auto-migrate failed (continuing): %s", e)
+
+
+@asynccontextmanager
+async def lifespan(app: FastAPI):
+    _run_migrations()
+    yield
+
+
+app = FastAPI(
+    title="VariantLens",
+    description="Clinical genomic variant interpretation tool with ACMG rule engine and Claude RAG reasoning.",
+    version="0.1.0",
+    lifespan=lifespan,
+)
+
+app.add_middleware(
+    CORSMiddleware,
+    allow_origins=["http://localhost:5173", "http://localhost:3000"],
+    allow_credentials=True,
+    allow_methods=["*"],
+    allow_headers=["*"],
+)
+
+app.include_router(variants.router, prefix="/variants", tags=["variants"])
+app.include_router(evidence.router, prefix="/evidence", tags=["evidence"])
+app.include_router(reports.router, prefix="/reports", tags=["reports"])
+
+
+@app.get("/health")
+async def health() -> dict[str, str]:
+    return {"status": "ok", "env": settings.app_env}
+
+
+@app.get("/")
+async def root() -> dict[str, str]:
+    return {"name": "VariantLens", "version": "0.1.0", "docs": "/docs"}

backend/app/models/__init__.py

@@ -0,0 +1,5 @@
+from backend.app.models.classification import ClassificationRecord, CriterionRecord
+from backend.app.models.db import Base, get_session
+from backend.app.models.variant import VariantRecord
+
+__all__ = ["Base", "get_session", "VariantRecord", "ClassificationRecord", "CriterionRecord"]

backend/app/models/classification.py

@@ -0,0 +1,51 @@
+from datetime import datetime
+from uuid import uuid4
+
+from sqlalchemy import JSON, Boolean, DateTime, ForeignKey, String, Text
+from sqlalchemy.orm import Mapped, mapped_column, relationship
+
+from backend.app.models.db import Base
+from backend.app.models.variant import VariantRecord  # noqa: F401  — needed for relationship
+
+
+class ClassificationRecord(Base):
+    __tablename__ = "classifications"
+
+    id: Mapped[str] = mapped_column(String(36), primary_key=True, default=lambda: str(uuid4()))
+    variant_id: Mapped[str] = mapped_column(String(36), ForeignKey("variants.id"), index=True)
+    significance: Mapped[str] = mapped_column(String(32), nullable=False)
+    confidence: Mapped[str] = mapped_column(String(16), default="medium")
+    triggered_criteria: Mapped[list] = mapped_column(JSON, default=list)
+    conflicting_evidence: Mapped[bool] = mapped_column(Boolean, default=False)
+    ruleset_version: Mapped[str] = mapped_column(String(16), default="v2015")
+    rationale: Mapped[str | None] = mapped_column(Text)
+    curator_signoff: Mapped[bool] = mapped_column(Boolean, default=False)
+    curator_id: Mapped[str | None] = mapped_column(String(64))
+    signed_off_at: Mapped[datetime | None] = mapped_column(DateTime)
+    created_at: Mapped[datetime] = mapped_column(DateTime, default=datetime.utcnow)
+
+    criteria: Mapped[list["CriterionRecord"]] = relationship(
+        back_populates="classification", cascade="all, delete-orphan"
+    )
+    variant: Mapped["VariantRecord"] = relationship("VariantRecord", lazy="joined")
+
+
+class CriterionRecord(Base):
+    __tablename__ = "criteria"
+
+    id: Mapped[str] = mapped_column(String(36), primary_key=True, default=lambda: str(uuid4()))
+    classification_id: Mapped[str] = mapped_column(
+        String(36), ForeignKey("classifications.id"), index=True
+    )
+    code: Mapped[str] = mapped_column(String(8), nullable=False)
+    triggered: Mapped[bool] = mapped_column(Boolean, default=False)
+    strength: Mapped[str] = mapped_column(String(16))
+    source: Mapped[str] = mapped_column(String(128))
+    evidence_text: Mapped[str] = mapped_column(Text)
+    confidence: Mapped[str] = mapped_column(String(16), default="medium")
+    pmid: Mapped[str | None] = mapped_column(String(32))
+    caveat: Mapped[str | None] = mapped_column(Text)
+    curator_override: Mapped[bool] = mapped_column(Boolean, default=False)
+    override_justification: Mapped[str | None] = mapped_column(Text)
+
+    classification: Mapped["ClassificationRecord"] = relationship(back_populates="criteria")

backend/app/models/db.py

@@ -0,0 +1,23 @@
+from collections.abc import Generator
+
+from sqlalchemy import create_engine
+from sqlalchemy.orm import DeclarativeBase, Session, sessionmaker
+
+from backend.app.config import get_settings
+
+settings = get_settings()
+
+engine = create_engine(settings.database_url, pool_pre_ping=True)
+SessionLocal = sessionmaker(autocommit=False, autoflush=False, bind=engine)
+
+
+class Base(DeclarativeBase):
+    pass
+
+
+def get_session() -> Generator[Session, None, None]:
+    db = SessionLocal()
+    try:
+        yield db
+    finally:
+        db.close()

backend/app/models/variant.py

@@ -0,0 +1,24 @@
+from datetime import datetime
+from uuid import uuid4
+
+from sqlalchemy import JSON, DateTime, String
+from sqlalchemy.orm import Mapped, mapped_column
+
+from backend.app.models.db import Base
+
+
+class VariantRecord(Base):
+    __tablename__ = "variants"
+
+    id: Mapped[str] = mapped_column(String(36), primary_key=True, default=lambda: str(uuid4()))
+    raw_input: Mapped[str] = mapped_column(String(512), nullable=False)
+    hgvs_genomic: Mapped[str | None] = mapped_column(String(512))
+    hgvs_coding: Mapped[str | None] = mapped_column(String(512))
+    hgvs_protein: Mapped[str | None] = mapped_column(String(512))
+    transcript: Mapped[str | None] = mapped_column(String(64))
+    gene_symbol: Mapped[str | None] = mapped_column(String(64), index=True)
+    chromosome: Mapped[str | None] = mapped_column(String(8))
+    position: Mapped[int | None] = mapped_column()
+    normalization_source: Mapped[str] = mapped_column(String(32), default="mutalyzer")
+    warnings: Mapped[list] = mapped_column(JSON, default=list)
+    submitted_at: Mapped[datetime] = mapped_column(DateTime, default=datetime.utcnow)

backend/app/schemas/__init__.py

@@ -0,0 +1,33 @@
+from backend.app.schemas.classification import (
+    Classification,
+    ClassificationResult,
+    ClinicalSignificance,
+)
+from backend.app.schemas.evidence import (
+    ACMGCriterion,
+    CriterionStrength,
+    EvidenceBundle,
+    InSilicoResult,
+    LiteratureChunk,
+    PopulationFrequency,
+)
+from backend.app.schemas.variant import (
+    NormalizedVariant,
+    VariantInput,
+    VariantOutput,
+)
+
+__all__ = [
+    "VariantInput",
+    "VariantOutput",
+    "NormalizedVariant",
+    "ACMGCriterion",
+    "CriterionStrength",
+    "EvidenceBundle",
+    "InSilicoResult",
+    "LiteratureChunk",
+    "PopulationFrequency",
+    "Classification",
+    "ClassificationResult",
+    "ClinicalSignificance",
+]

backend/app/schemas/classification.py

@@ -0,0 +1,38 @@
+from typing import Literal
+
+from pydantic import BaseModel, Field
+
+from backend.app.schemas.evidence import ACMGCriterion, EvidenceBundle
+from backend.app.schemas.variant import NormalizedVariant
+
+ClinicalSignificance = Literal[
+    "Pathogenic",
+    "Likely Pathogenic",
+    "Uncertain Significance",
+    "Likely Benign",
+    "Benign",
+]
+
+
+class Classification(BaseModel):
+    significance: ClinicalSignificance
+    confidence: Literal["high", "medium", "low"] = "medium"
+    triggered_criteria: list[str] = Field(default_factory=list)
+    conflicting_evidence: bool = False
+    rationale: str | None = None
+
+
+class ClassificationResult(BaseModel):
+    id: str | None = None
+    variant: NormalizedVariant
+    evidence: EvidenceBundle
+    classification: Classification
+    ruleset_version: str = "v2015"
+    curator_signoff: bool = False
+    curator_id: str | None = None
+    signed_off_at: str | None = None
+    analysed_at: str | None = None
+
+    @property
+    def auditable_criteria(self) -> list[ACMGCriterion]:
+        return [c for c in self.evidence.criteria if c.triggered]

backend/app/schemas/evidence.py

@@ -0,0 +1,97 @@
+from typing import Literal
+
+from pydantic import BaseModel, ConfigDict, Field
+
+CriterionStrength = Literal["very_strong", "strong", "moderate", "supporting", "standalone"]
+CriterionConfidence = Literal["high", "medium", "low"]
+
+ACMG_CRITERIA = [
+    "PVS1",
+    "PS1", "PS2", "PS3", "PS4",
+    "PM1", "PM2", "PM3", "PM4", "PM5", "PM6",
+    "PP1", "PP2", "PP3", "PP4", "PP5",
+    "BA1",
+    "BS1", "BS2", "BS3", "BS4",
+    "BP1", "BP2", "BP3", "BP4", "BP5", "BP6", "BP7",
+]
+
+
+class ACMGCriterion(BaseModel):
+    code: str = Field(..., description="ACMG criterion code (e.g., PVS1, PM2)")
+    triggered: bool
+    strength: CriterionStrength
+    source: str = Field(..., description="Database name, PMID, or 'curator'")
+    evidence_text: str = Field(..., description="Quote, numeric value, or rule trace")
+    confidence: CriterionConfidence = "medium"
+    caveat: str | None = None
+    pmid: str | None = None
+    curator_override: bool = False
+    override_justification: str | None = None
+
+
+class PopulationFrequency(BaseModel):
+    overall_af: float | None = None
+    by_population: dict[str, float] = Field(default_factory=dict)
+    homozygote_count: int | None = None
+    coverage_warning: str | None = None
+    source: str = "gnomAD v4.1"
+
+
+class InSilicoResult(BaseModel):
+    revel: float | None = None
+    alphamissense: float | None = None
+    spliceai_max: float | None = None
+    cadd_phred: float | None = None
+    concordant_pathogenic: bool | None = None
+    concordant_benign: bool | None = None
+    pp3_triggered: bool = False
+    bp4_triggered: bool = False
+
+
+class ClinVarSubmission(BaseModel):
+    accession: str
+    submitter: str = "unknown"
+    classification: str
+    stars: int = 0
+    date: str = ""
+    condition: str = ""
+
+
+class AutoPVS1Step(BaseModel):
+    model_config = ConfigDict(populate_by_name=True)
+
+    step: int
+    label: str
+    value: str
+    pass_: bool = Field(..., alias="pass")
+
+
+class AutoPVS1Result(BaseModel):
+    triggered: bool
+    strength: CriterionStrength = "very_strong"
+    rule: str = "PVS1"
+    reasoning: list[AutoPVS1Step] = Field(default_factory=list)
+    conclusion: str = ""
+    source: str = "autoPVS1"
+    caveats: list[str] = Field(default_factory=list)
+
+
+class LiteratureChunk(BaseModel):
+    pmid: str
+    year: int | None = None
+    title: str | None = None
+    journal: str | None = None
+    chunk_text: str
+    criteria_relevance: list[str] = Field(default_factory=list)
+    score: float | None = None
+    ai_interpretation: str | None = None
+    ai_confidence: str | None = None
+
+
+class EvidenceBundle(BaseModel):
+    population_frequency: PopulationFrequency | None = None
+    insilico: InSilicoResult | None = None
+    clinvar_existing: list[ClinVarSubmission] = Field(default_factory=list)
+    autopvs1: AutoPVS1Result | None = None
+    literature_chunks: list[LiteratureChunk] = Field(default_factory=list)
+    criteria: list[ACMGCriterion] = Field(default_factory=list)

backend/app/schemas/variant.py

@@ -0,0 +1,34 @@
+from typing import Literal
+
+from pydantic import BaseModel, Field
+
+
+class VariantInput(BaseModel):
+    raw: str = Field(..., description="User-supplied variant string (HGVS, VCF, or protein notation)")
+    notation: Literal["hgvs", "vcf", "protein", "auto"] = "auto"
+    gene_symbol: str | None = None
+    disease: str | None = None
+    hpo_terms: list[str] = Field(default_factory=list)
+    inheritance: Literal["AD", "AR", "XL", "MT", "unknown"] | None = None
+
+
+class NormalizedVariant(BaseModel):
+    raw_input: str
+    hgvs_genomic: str | None = None
+    hgvs_coding: str | None = None
+    hgvs_protein: str | None = None
+    transcript: str | None = None
+    gene_symbol: str | None = None
+    chromosome: str | None = None
+    position: int | None = None
+    ref: str | None = None
+    alt: str | None = None
+    consequence: str | None = None
+    normalization_source: Literal["mutalyzer", "pyhgvs", "passthrough"] = "mutalyzer"
+    warnings: list[str] = Field(default_factory=list)
+
+
+class VariantOutput(BaseModel):
+    id: str
+    normalized: NormalizedVariant
+    submitted_at: str

backend/app/services/acmg/__init__.py

@@ -0,0 +1,4 @@
+from backend.app.services.acmg.combiner import combine_criteria
+from backend.app.services.acmg.rules import RuleEngine
+
+__all__ = ["RuleEngine", "combine_criteria"]

backend/app/services/acmg/combiner.py

@@ -0,0 +1,218 @@
+"""ACMG/AMP variant classification combiner.
+
+This module implements two classifiers:
+
+1. **Strict Table 5** (Richards 2015) — the original combinatorial rules.
+   This is the clinical default because it is auditable and conservative.
+
+2. **Bayesian point system** (Tavtigian 2018; ClinGen SVI 2020) — assigns
+   numeric points to each triggered criterion based on its strength, then
+   classifies by total. This can be enabled explicitly for validation and
+   research cohorts.
+
+Point thresholds (Tavtigian 2018, Genet Med 20:1054):
+   ≥10 → Pathogenic
+   6-9 → Likely Pathogenic
+   0-5 → VUS
+   -6 to -1 → Likely Benign
+   ≤-7 → Benign
+
+Point values:
+   very_strong=8, strong=4, moderate=2, supporting=1
+   standalone=-8, benign equivalents flip sign
+
+The previous implementation selected the more pathogenic result by default.
+That is useful for exploration, but too permissive for lab-facing defaults.
+"""
+
+from backend.app.config import get_settings
+from backend.app.schemas.classification import Classification, ClinicalSignificance
+from backend.app.schemas.evidence import ACMGCriterion
+
+PATHOGENIC_PREFIX = ("PVS", "PS", "PM", "PP")
+BENIGN_PREFIX = ("BA", "BS", "BP")
+
+POINTS_PATH = {"very_strong": 8, "strong": 4, "moderate": 2, "supporting": 1}
+POINTS_BEN = {"standalone": 8, "strong": 4, "moderate": 2, "supporting": 1}
+
+
+def _bayesian_score(criteria: list[ACMGCriterion]) -> int:
+    """Tavtigian 2018 point system. Pathogenic criteria add, benign subtract."""
+    score = 0
+    for c in criteria:
+        if not c.triggered:
+            continue
+        if c.code.startswith(PATHOGENIC_PREFIX):
+            score += POINTS_PATH.get(c.strength, 0)
+        elif c.code.startswith(BENIGN_PREFIX):
+            score -= POINTS_BEN.get(c.strength, 0)
+    return score
+
+
+def _bayesian_significance(score: int) -> ClinicalSignificance:
+    if score >= 10:
+        return "Pathogenic"
+    if score >= 6:
+        return "Likely Pathogenic"
+    if score >= 0:
+        return "Uncertain Significance"
+    if score >= -6:
+        return "Likely Benign"
+    return "Benign"
+
+
+SIGNIFICANCE_RANK = {
+    "Benign": 0,
+    "Likely Benign": 1,
+    "Uncertain Significance": 2,
+    "Likely Pathogenic": 3,
+    "Pathogenic": 4,
+}
+
+
+def _bucket(criteria: list[ACMGCriterion]) -> dict[str, int]:
+    triggered = [c for c in criteria if c.triggered]
+    return {
+        "very_strong": sum(1 for c in triggered if c.strength == "very_strong"),
+        "strong_path": sum(1 for c in triggered if c.strength == "strong" and c.code.startswith(PATHOGENIC_PREFIX)),
+        "moderate_path": sum(1 for c in triggered if c.strength == "moderate" and c.code.startswith(PATHOGENIC_PREFIX)),
+        "supporting_path": sum(1 for c in triggered if c.strength == "supporting" and c.code.startswith(PATHOGENIC_PREFIX)),
+        "standalone": sum(1 for c in triggered if c.strength == "standalone"),
+        "strong_benign": sum(1 for c in triggered if c.strength == "strong" and c.code.startswith(BENIGN_PREFIX)),
+        "moderate_benign": sum(1 for c in triggered if c.strength == "moderate" and c.code.startswith(BENIGN_PREFIX)),
+        "supporting_benign": sum(1 for c in triggered if c.strength == "supporting" and c.code.startswith(BENIGN_PREFIX)),
+    }
+
+
+def _is_pathogenic(b: dict[str, int]) -> bool:
+    if b["very_strong"] >= 1:
+        if b["strong_path"] >= 1:
+            return True
+        if b["moderate_path"] >= 2:
+            return True
+        if b["moderate_path"] >= 1 and b["supporting_path"] >= 1:
+            return True
+        if b["supporting_path"] >= 2:
+            return True
+    if b["strong_path"] >= 2:
+        return True
+    if b["strong_path"] >= 1:
+        if b["moderate_path"] >= 3:
+            return True
+        if b["moderate_path"] >= 2 and b["supporting_path"] >= 2:
+            return True
+        return b["moderate_path"] >= 1 and b["supporting_path"] >= 4
+    return False
+
+
+def _is_likely_pathogenic(b: dict[str, int]) -> bool:
+    if b["very_strong"] >= 1 and b["moderate_path"] >= 1:
+        return True
+    if b["strong_path"] >= 1 and 1 <= b["moderate_path"] <= 2:
+        return True
+    if b["strong_path"] >= 1 and b["supporting_path"] >= 2:
+        return True
+    if b["moderate_path"] >= 3:
+        return True
+    if b["moderate_path"] >= 2 and b["supporting_path"] >= 2:
+        return True
+    return b["moderate_path"] >= 1 and b["supporting_path"] >= 4
+
+
+def _is_benign(b: dict[str, int]) -> bool:
+    if b["standalone"] >= 1:
+        return True
+    return b["strong_benign"] >= 2
+
+
+def _is_likely_benign(b: dict[str, int]) -> bool:
+    if b["strong_benign"] >= 1 and b["supporting_benign"] >= 1:
+        return True
+    return b["supporting_benign"] >= 2
+
+
+def combine_criteria(criteria: list[ACMGCriterion]) -> Classification:
+    """Combine ACMG criteria using the configured combiner strategy.
+
+    Conflict detection still uses the strict bucketing — if pathogenic
+    AND benign criteria both fire, we surface VUS regardless of points.
+    """
+    strategy = get_settings().acmg_combiner_strategy
+    triggered = [c for c in criteria if c.triggered]
+    b = _bucket(criteria)
+
+    table5_pathogenic = _is_pathogenic(b)
+    table5_likely_pathogenic = _is_likely_pathogenic(b)
+    table5_benign = _is_benign(b)
+    table5_likely_benign = _is_likely_benign(b)
+
+    table5_sig: ClinicalSignificance = (
+        "Pathogenic" if table5_pathogenic else
+        "Likely Pathogenic" if table5_likely_pathogenic else
+        "Benign" if table5_benign else
+        "Likely Benign" if table5_likely_benign else
+        "Uncertain Significance"
+    )
+
+    points = _bayesian_score(criteria)
+    bayes_sig = _bayesian_significance(points)
+
+    if strategy == "bayesian":
+        significance: ClinicalSignificance = bayes_sig
+        used_classifier = f"Bayesian {points:+d} pts"
+    elif strategy == "most_pathogenic" and SIGNIFICANCE_RANK[bayes_sig] >= SIGNIFICANCE_RANK[table5_sig]:
+        significance = bayes_sig
+        used_classifier = f"Bayesian {points:+d} pts"
+    else:
+        significance = table5_sig
+        used_classifier = "Richards 2015 Table 5"
+
+    has_path_evidence = b["very_strong"] + b["strong_path"] + b["moderate_path"] + b["supporting_path"] > 0
+    has_benign_evidence = b["standalone"] + b["strong_benign"] + b["moderate_benign"] + b["supporting_benign"] > 0
+    conflicting = has_path_evidence and has_benign_evidence
+
+    if conflicting:
+        significance = "Uncertain Significance"
+
+    avg_low = sum(1 for c in triggered if c.confidence == "low")
+    if not triggered or avg_low >= 2:
+        confidence = "low"
+    elif all(c.confidence == "high" for c in triggered):
+        confidence = "high"
+    else:
+        confidence = "medium"
+
+    return Classification(
+        significance=significance,
+        confidence=confidence,
+        triggered_criteria=[c.code for c in triggered],
+        conflicting_evidence=conflicting,
+        rationale=_build_rationale(b, significance, points, used_classifier),
+    )
+
+
+def _build_rationale(
+    b: dict[str, int],
+    significance: ClinicalSignificance,
+    points: int,
+    classifier: str,
+) -> str:
+    parts = []
+    if b["very_strong"]:
+        parts.append(f"{b['very_strong']}× Very Strong")
+    if b["strong_path"]:
+        parts.append(f"{b['strong_path']}× Strong (P)")
+    if b["moderate_path"]:
+        parts.append(f"{b['moderate_path']}× Moderate (P)")
+    if b["supporting_path"]:
+        parts.append(f"{b['supporting_path']}× Supporting (P)")
+    if b["standalone"]:
+        parts.append(f"{b['standalone']}× Stand-alone (B)")
+    if b["strong_benign"]:
+        parts.append(f"{b['strong_benign']}× Strong (B)")
+    if b["moderate_benign"]:
+        parts.append(f"{b['moderate_benign']}× Moderate (B)")
+    if b["supporting_benign"]:
+        parts.append(f"{b['supporting_benign']}× Supporting (B)")
+    counts = " + ".join(parts) if parts else "no triggered criteria"
+    return f"{significance} ({classifier}, {points:+d} pts) — {counts}"

backend/app/services/acmg/rules.py

@@ -0,0 +1,215 @@
+import logging
+
+from backend.app.config import get_settings
+from backend.app.schemas.evidence import (
+    ACMGCriterion,
+    AutoPVS1Result,
+    ClinVarSubmission,
+    EvidenceBundle,
+    InSilicoResult,
+    PopulationFrequency,
+)
+
+logger = logging.getLogger(__name__)
+settings = get_settings()
+
+PM2_THRESHOLD = 0.0001
+BS1_THRESHOLD = 0.005
+BA1_THRESHOLD = 0.05
+BS2_HOM_THRESHOLD = 2
+
+# PM2 strength — Richards 2015 originally specified MODERATE.
+# ClinGen SVI 2020 recommended downgrading to SUPPORTING for general use,
+# but most clinical labs and ClinGen VCEPs still apply MODERATE in practice.
+# Switch via env if you want the SVI 2020 behavior.
+PM2_STRENGTH = "moderate"
+
+
+class RuleEngine:
+    """Auto-scorers for database-derived ACMG criteria. Literature criteria
+    (PM3, PP1, PS3, PS4, PP4, PS2/PM6, PP5/BP6) are populated by the LLM layer."""
+
+    def score_pvs1(self, autopvs1_result: AutoPVS1Result | None) -> ACMGCriterion | None:
+        if not autopvs1_result or not autopvs1_result.triggered:
+            return None
+        return ACMGCriterion(
+            code="PVS1",
+            triggered=True,
+            strength=autopvs1_result.strength,
+            source=autopvs1_result.source,
+            evidence_text=autopvs1_result.conclusion,
+            confidence="high",
+            caveat="; ".join(autopvs1_result.caveats) or None,
+        )
+
+    def score_population(self, freq: PopulationFrequency | None) -> list[ACMGCriterion]:
+        if not freq or freq.overall_af is None:
+            logger.warning("Population frequency missing; PM2 not triggered until coverage is verified")
+            return []
+
+        out: list[ACMGCriterion] = []
+        af = freq.overall_af or 0.0
+
+        if af >= BA1_THRESHOLD:
+            out.append(ACMGCriterion(
+                code="BA1",
+                triggered=True,
+                strength="standalone",
+                source="gnomAD v4.1",
+                evidence_text=f"overall AF = {af:.4f} ≥ 5%",
+                confidence="high",
+            ))
+        elif af >= BS1_THRESHOLD:
+            out.append(ACMGCriterion(
+                code="BS1",
+                triggered=True,
+                strength="strong",
+                source="gnomAD v4.1",
+                evidence_text=f"overall AF = {af:.4f} > expected",
+                confidence="medium",
+                caveat="compare against disease-specific BS1 threshold",
+            ))
+        elif af < PM2_THRESHOLD:
+            out.append(ACMGCriterion(
+                code="PM2",
+                triggered=True,
+                strength="supporting",
+                source="gnomAD v4.1",
+                evidence_text=f"overall AF = {af:.6f} < 0.0001",
+                confidence="high",
+            ))
+
+        if (freq.homozygote_count or 0) >= BS2_HOM_THRESHOLD:
+            out.append(ACMGCriterion(
+                code="BS2",
+                triggered=True,
+                strength="strong",
+                source="gnomAD v4.1",
+                evidence_text=f"{freq.homozygote_count} healthy homozygotes",
+                confidence="high",
+            ))
+        return out
+
+    def score_insilico(self, ins: InSilicoResult | None) -> list[ACMGCriterion]:
+        """Modulate PP3/BP4 strength using ClinGen SVI 2022 recommendations
+        (Pejaver et al. 2022, AJHG) — REVEL ≥ 0.932 + concordant signals
+        upgrade to PP3_strong; ≥ 0.773 to PP3_moderate; otherwise supporting.
+        Mirror thresholds for BP4.
+        """
+        if not ins:
+            return []
+        out = []
+        if ins.pp3_triggered:
+            strength = self._pp3_strength(ins)
+            out.append(ACMGCriterion(
+                code="PP3",
+                triggered=True,
+                strength=strength,
+                source="REVEL+AlphaMissense+SpliceAI concordant",
+                evidence_text=f"REVEL={ins.revel}, AM={ins.alphamissense}, SpliceAI={ins.spliceai_max} → {strength}",
+                confidence="high" if strength in ("strong", "moderate") else "medium",
+            ))
+        if ins.bp4_triggered:
+            strength = self._bp4_strength(ins)
+            out.append(ACMGCriterion(
+                code="BP4",
+                triggered=True,
+                strength=strength,
+                source="REVEL+AlphaMissense+SpliceAI concordant",
+                evidence_text=f"REVEL={ins.revel}, AM={ins.alphamissense}, SpliceAI={ins.spliceai_max} → {strength}",
+                confidence="high" if strength in ("strong", "moderate") else "medium",
+            ))
+        return out
+
+    @staticmethod
+    def _pp3_strength(ins: "InSilicoResult") -> str:
+        # Pejaver et al. 2022 calibration — REVEL stratification for PP3
+        revel = ins.revel or 0.0
+        am = ins.alphamissense or 0.0
+        if revel >= 0.932 and am >= 0.95:
+            return "strong"
+        if revel >= 0.773 or am >= 0.834:
+            return "moderate"
+        return "supporting"
+
+    @staticmethod
+    def _bp4_strength(ins: "InSilicoResult") -> str:
+        revel = ins.revel if ins.revel is not None else 1.0
+        am = ins.alphamissense if ins.alphamissense is not None else 1.0
+        if revel <= 0.183 and am <= 0.099:
+            return "strong"
+        if revel <= 0.290 or am <= 0.099:
+            return "moderate"
+        return "supporting"
+
+    def score_clinvar(self, submissions: list[ClinVarSubmission] | None) -> list[ACMGCriterion]:
+        """Map ClinVar consensus to optional PP5/BP6 evidence.
+
+        The first submission is the AGGREGATE consensus from ClinVar (the
+        green-star verdict). ACMG SVI deprecated PP5/BP6 as standalone
+        criteria in 2018, so VariantLens does not auto-trigger them unless
+        explicitly enabled for research/backward-compatibility validation.
+        """
+        if not submissions:
+            return []
+        if not settings.enable_deprecated_clinvar_criteria:
+            logger.info("ClinVar PP5/BP6 auto-scoring disabled; retaining ClinVar as evidence only")
+            return []
+
+        # First submission is the aggregate consensus (see clinvar.py); rest are lab-level
+        consensus = submissions[0]
+        cls = consensus.classification.lower()
+        stars = consensus.stars
+        is_path = "pathogenic" in cls and "conflicting" not in cls
+        is_benign = "benign" in cls and "conflicting" not in cls
+
+        if not (is_path or is_benign):
+            return []
+
+        # Strength scales with ClinGen review-status stars:
+        #   4★ practice guideline   → strong
+        #   3★ expert panel         → strong
+        #   2★ multi-submitter ok   → moderate
+        #   1★ single submitter     → supporting
+        #   0★ no criteria          → supporting (downgraded)
+        strength = (
+            "strong" if stars >= 3 else
+            "moderate" if stars == 2 else
+            "supporting"
+        )
+        confidence: str = "high" if stars >= 3 else ("medium" if stars >= 1 else "low")
+
+        out: list[ACMGCriterion] = []
+        if is_path:
+            out.append(ACMGCriterion(
+                code="PP5",
+                triggered=True,
+                strength=strength,
+                source=f"ClinVar consensus {consensus.accession} ({stars}★)",
+                evidence_text=f"Aggregate ClinVar classification: {consensus.classification} — {stars}★ review",
+                confidence=confidence,
+                caveat=("ACMG SVI 2018 deprecated PP5 as standalone — verify before final sign-off"
+                        if stars < 3 else None),
+            ))
+        elif is_benign:
+            out.append(ACMGCriterion(
+                code="BP6",
+                triggered=True,
+                strength=strength,
+                source=f"ClinVar consensus {consensus.accession} ({stars}★)",
+                evidence_text=f"Aggregate ClinVar classification: {consensus.classification} — {stars}★ review",
+                confidence=confidence,
+                caveat=("ACMG SVI 2018 deprecated BP6 as standalone — verify before final sign-off"
+                        if stars < 3 else None),
+            ))
+        return out
+
+    def score_all(self, evidence: EvidenceBundle) -> list[ACMGCriterion]:
+        criteria: list[ACMGCriterion] = []
+        pvs1 = self.score_pvs1(evidence.autopvs1)
+        if pvs1:
+            criteria.append(pvs1)
+        criteria.extend(self.score_population(evidence.population_frequency))
+        criteria.extend(self.score_insilico(evidence.insilico))
+        criteria.extend(self.score_clinvar(evidence.clinvar_existing))
+        return criteria

backend/app/services/clinvar.py

@@ -0,0 +1,218 @@
+"""ClinVar lookup — aggregate consensus + per-submitter assertions.
+
+The previous implementation only fetched `ids[0]` from esearch, which often
+isn't the canonical VariationArchive (esearch ranks by recency, not by
+match quality). It also ignored the aggregate `GermlineClassification`
+field, so a variant with 50 Pathogenic assertions and a 3-star expert-panel
+review status would render as the first lab-level submission found — often
+a discordant single-lab call.
+
+This module now:
+  1. Fetches all matching variation IDs from esearch (up to MAX_IDS).
+  2. Extracts the aggregate `Classifications/GermlineClassification` from
+     each — that's the curated consensus that ClinGen uses for the green
+     star ratings.
+  3. Picks the entry whose review status carries the highest weight.
+  4. Returns it as the primary `ClinVarSubmission`, plus up to N
+     supporting per-submitter assertions for the UI's evidence list.
+"""
+from __future__ import annotations
+
+import logging
+import xml.etree.ElementTree as ET
+from typing import Any
+
+import httpx
+from tenacity import retry, stop_after_attempt, wait_exponential
+
+from backend.app.config import get_settings
+from backend.app.schemas.evidence import ClinVarSubmission
+
+logger = logging.getLogger(__name__)
+settings = get_settings()
+
+EUTILS = "https://eutils.ncbi.nlm.nih.gov/entrez/eutils"
+MAX_IDS = 10
+MAX_ASSERTIONS = 10
+
+REVIEW_STATUS_STARS: dict[str, int] = {
+    "practice guideline": 4,
+    "reviewed by expert panel": 3,
+    "criteria provided, multiple submitters, no conflicts": 2,
+    "criteria provided, multiple submitters": 2,
+    "criteria provided, single submitter": 1,
+    "criteria provided, conflicting classifications": 1,
+    "criteria provided, conflicting interpretations": 1,
+    "no assertion criteria provided": 0,
+    "no classification provided": 0,
+    "no assertion provided": 0,
+    "no classifications from unflagged records": 0,
+}
+
+
+def _stars_for(review_status: str | None) -> int:
+    if not review_status:
+        return 0
+    return REVIEW_STATUS_STARS.get(review_status.strip().lower(), 0)
+
+
+class ClinVarClient:
+    def __init__(self, api_key: str | None = None, email: str | None = None) -> None:
+        self.api_key = api_key or settings.ncbi_api_key
+        self.email = email or settings.ncbi_email
+
+    def _params(self, **extra: Any) -> dict[str, Any]:
+        params = {"db": "clinvar", "tool": "VariantLens", "email": self.email}
+        if self.api_key:
+            params["api_key"] = self.api_key
+        return {**params, **extra}
+
+    @retry(stop=stop_after_attempt(3), wait=wait_exponential(min=1, max=8), reraise=True)
+    async def search(self, hgvs: str) -> list[str]:
+        async with httpx.AsyncClient(timeout=15.0) as client:
+            r = await client.get(
+                f"{EUTILS}/esearch.fcgi",
+                params=self._params(term=hgvs, retmode="json", retmax=MAX_IDS),
+            )
+            r.raise_for_status()
+            return r.json().get("esearchresult", {}).get("idlist", [])
+
+    @retry(stop=stop_after_attempt(3), wait=wait_exponential(min=1, max=8), reraise=True)
+    async def _efetch(self, variation_ids: list[str]) -> str:
+        """Bulk-fetch up to N variation IDs in one call. ClinVar's efetch
+        supports comma-separated IDs and returns a single ClinVarResult
+        document containing one VariationArchive per ID."""
+        async with httpx.AsyncClient(timeout=30.0) as client:
+            r = await client.get(
+                f"{EUTILS}/efetch.fcgi",
+                params=self._params(
+                    id=",".join(variation_ids),
+                    rettype="vcv",
+                    is_variationid="true",
+                ),
+            )
+            r.raise_for_status()
+            return r.text
+
+    def _parse_aggregate(self, vcv: ET.Element) -> ClinVarSubmission | None:
+        """Extract the canonical aggregate consensus from a VariationArchive.
+
+        This corresponds to the green-star review at the top of the ClinVar
+        web page — the single line of consensus that the ACMG SVI and most
+        clinical labs treat as the authoritative ClinVar verdict.
+        """
+        accession = vcv.get("Accession") or vcv.get("VariationID") or "unknown"
+
+        # GRCh38 RefSeq accessions are direct children, not nested deeper
+        cls_node = vcv.find(".//Classifications/GermlineClassification/Description")
+        review_node = vcv.find(".//Classifications/GermlineClassification/ReviewStatus")
+        date_node = vcv.find(".//Classifications/GermlineClassification")
+        cond_nodes = vcv.findall(".//Classifications/GermlineClassification/ConditionList/TraitSet/Trait/Name/ElementValue")
+
+        if cls_node is None or not cls_node.text:
+            return None
+
+        review = review_node.text if review_node is not None else None
+        date = ""
+        if date_node is not None:
+            date = date_node.get("DateLastEvaluated") or date_node.get("DateCreated") or ""
+
+        condition = "not specified"
+        for n in cond_nodes:
+            if n.get("Type") == "Preferred" and n.text:
+                condition = n.text
+                break
+        if condition == "not specified" and cond_nodes and cond_nodes[0].text:
+            condition = cond_nodes[0].text
+
+        return ClinVarSubmission(
+            accession=accession,
+            submitter="ClinVar aggregate",
+            classification=cls_node.text,
+            stars=_stars_for(review),
+            date=date,
+            condition=condition,
+        )
+
+    def _parse_assertions(self, vcv: ET.Element, limit: int) -> list[ClinVarSubmission]:
+        """Pull individual lab-level assertions for the UI's evidence list.
+
+        Aggregated separately from the consensus so the rule engine doesn't
+        double-count a single ClinVar entry into 50 distinct PP5 hits.
+        """
+        out: list[ClinVarSubmission] = []
+        for scv in vcv.iter("ClinicalAssertion"):
+            if len(out) >= limit:
+                break
+            acc_node = scv.find(".//ClinVarAccession")
+            acc = acc_node.get("Accession") if acc_node is not None else "unknown"
+            submitter = acc_node.get("SubmitterName") if acc_node is not None else "unknown"
+
+            cls_node = scv.find("Classification/GermlineClassification")
+            if cls_node is None or not cls_node.text:
+                continue
+            classification = cls_node.text
+
+            review_node = scv.find("Classification/ReviewStatus")
+            review = review_node.text if review_node is not None else None
+
+            date_node = scv.find("Classification")
+            date = date_node.get("DateLastEvaluated") if date_node is not None else ""
+
+            cond_node = scv.find(".//TraitSet/Trait/Name/ElementValue")
+            condition = cond_node.text if cond_node is not None and cond_node.text else "not specified"
+
+            out.append(ClinVarSubmission(
+                accession=acc or "unknown",
+                submitter=submitter or "unknown",
+                classification=classification,
+                stars=_stars_for(review),
+                date=date or "",
+                condition=condition,
+            ))
+        return out
+
+    def _parse(self, xml_text: str) -> list[ClinVarSubmission]:
+        """Parse all VariationArchives in the ClinVar response.
+
+        Returns the strongest aggregate consensus first, then up to
+        MAX_ASSERTIONS per-submitter assertions from the same archive.
+        """
+        try:
+            root = ET.fromstring(xml_text)
+        except ET.ParseError as e:
+            logger.warning("clinvar xml parse failure: %s", e)
+            return []
+
+        # Pick the VariationArchive with the highest-star aggregate consensus —
+        # esearch sometimes returns several IDs (alternative alleles, related
+        # variants) and we want the canonical one for THIS variant.
+        archives_with_consensus: list[tuple[ET.Element, ClinVarSubmission]] = []
+        for vcv in root.iter("VariationArchive"):
+            agg = self._parse_aggregate(vcv)
+            if agg is not None:
+                archives_with_consensus.append((vcv, agg))
+
+        if not archives_with_consensus:
+            return []
+
+        archives_with_consensus.sort(key=lambda t: -t[1].stars)
+        canonical_vcv, consensus = archives_with_consensus[0]
+        return [consensus] + self._parse_assertions(canonical_vcv, MAX_ASSERTIONS)
+
+    async def lookup(self, hgvs: str) -> list[ClinVarSubmission]:
+        try:
+            ids = await self.search(hgvs)
+        except (httpx.HTTPError, httpx.TimeoutException) as e:
+            logger.warning("ClinVar search failed for %s: %s", hgvs, e)
+            return []
+        if not ids:
+            return []
+
+        try:
+            xml = await self._efetch(ids[:MAX_IDS])
+        except (httpx.HTTPError, httpx.TimeoutException) as e:
+            logger.warning("ClinVar efetch failed for %s: %s", hgvs, e)
+            return []
+
+        return self._parse(xml)

backend/app/services/exports.py

@@ -0,0 +1,208 @@
+"""Export classifications to standard interchange formats.
+
+ClinVar XML — Submission Schema v1.16 (https://www.ncbi.nlm.nih.gov/clinvar/docs/submit/).
+FHIR R4    — Observation resource with LOINC 53037-8 (genetic clinical significance).
+
+Both renderers read from a persisted `ClassificationRecord` so the audit
+trail is intact (sign-off and curator overrides are reflected in the export).
+"""
+from __future__ import annotations
+
+import xml.etree.ElementTree as ET
+from datetime import UTC, datetime
+from typing import Any
+from xml.dom import minidom
+
+from backend.app.models.classification import ClassificationRecord
+
+CLINVAR_SIG_MAP = {
+    "Pathogenic":              "Pathogenic",
+    "Likely Pathogenic":       "Likely pathogenic",
+    "Uncertain Significance":  "Uncertain significance",
+    "Likely Benign":           "Likely benign",
+    "Benign":                  "Benign",
+}
+
+LOINC_CLINSIG = {
+    "Pathogenic":              {"system": "http://loinc.org", "code": "LA6668-3", "display": "Pathogenic"},
+    "Likely Pathogenic":       {"system": "http://loinc.org", "code": "LA26332-9", "display": "Likely pathogenic"},
+    "Uncertain Significance":  {"system": "http://loinc.org", "code": "LA26333-7", "display": "Uncertain significance"},
+    "Likely Benign":           {"system": "http://loinc.org", "code": "LA26334-5", "display": "Likely benign"},
+    "Benign":                  {"system": "http://loinc.org", "code": "LA6675-8", "display": "Benign"},
+}
+
+
+def _today() -> str:
+    return datetime.now(UTC).strftime("%Y-%m-%d")
+
+
+def render_clinvar_xml(rec: ClassificationRecord, *, submitter_org_id: str = "VARIANTLENS_LAB") -> str:
+    """Render a minimal ClinVar SCV submission for a single variant.
+
+    The output validates against the ClinVar Submission Schema's
+    `ClinvarSubmissionSet > ClinVarSubmission > ClinVarAssertion` path.
+    """
+    root = ET.Element("ClinvarSubmissionSet", attrib={"Date": _today()})
+    submission = ET.SubElement(root, "ClinvarSubmission", attrib={
+        "ID": rec.id,
+        "SubmissionDate": _today(),
+    })
+
+    assertion = ET.SubElement(submission, "ClinVarAssertion")
+
+    # ClinVarAccession — submitter assigned IDs
+    ET.SubElement(assertion, "ClinVarAccession", attrib={
+        "Acc": f"SCV-LOCAL-{rec.id}",
+        "Type": "SCV",
+        "OrgID": submitter_org_id,
+    })
+
+    # RecordStatus
+    rs = ET.SubElement(assertion, "RecordStatus")
+    rs.text = "current"
+
+    # ClinicalSignificance — the actual call
+    cs = ET.SubElement(assertion, "ClinicalSignificance", attrib={
+        "DateLastEvaluated": (rec.signed_off_at.strftime("%Y-%m-%d")
+                              if rec.signed_off_at
+                              else _today()),
+    })
+    review = ET.SubElement(cs, "ReviewStatus")
+    review.text = ("criteria provided, single submitter"
+                   if rec.curator_signoff
+                   else "no assertion criteria provided")
+    desc = ET.SubElement(cs, "Description")
+    desc.text = CLINVAR_SIG_MAP.get(rec.significance, rec.significance)
+    if rec.rationale:
+        comment = ET.SubElement(cs, "Comment", attrib={"Type": "ConvertedByNCBI"})
+        comment.text = rec.rationale
+
+    # AssertionMethod — the ruleset
+    method = ET.SubElement(assertion, "AssertionMethod")
+    method_name = ET.SubElement(method, "MethodName")
+    method_name.text = f"ACMG/AMP guidelines (Richards 2015) — VariantLens {rec.ruleset_version}"
+
+    # ObservedIn — placeholder for the proband
+    obs_in = ET.SubElement(assertion, "ObservedIn")
+    sample = ET.SubElement(obs_in, "Sample")
+    origin = ET.SubElement(sample, "Origin")
+    origin.text = "germline"
+    species = ET.SubElement(sample, "Species", attrib={"TaxonomyId": "9606"})
+    species.text = "human"
+    affected = ET.SubElement(sample, "AffectedStatus")
+    affected.text = "yes"
+    method_obs = ET.SubElement(obs_in, "Method")
+    method_type = ET.SubElement(method_obs, "MethodType")
+    method_type.text = "clinical testing"
+    obs_data = ET.SubElement(obs_in, "ObservedData")
+    obs_attr = ET.SubElement(obs_data, "Attribute", attrib={"Type": "Description"})
+    obs_attr.text = (f"Variant interpreted by VariantLens with "
+                     f"{len(rec.triggered_criteria or [])} ACMG criteria triggered.")
+
+    # MeasureSet — the variant itself
+    measure_set = ET.SubElement(assertion, "MeasureSet", attrib={"Type": "Variant"})
+    measure = ET.SubElement(measure_set, "Measure", attrib={"Type": "Variation"})
+    if rec.variant_id and hasattr(rec, "variant") and rec.variant is not None:
+        # Use the raw HGVS coding string from the related variant if available
+        for attr_name, attr_type in [
+            ("hgvs_coding", "HGVS, coding"),
+            ("hgvs_protein", "HGVS, protein"),
+            ("hgvs_genomic", "HGVS, genomic"),
+        ]:
+            val = getattr(rec.variant, attr_name, None)
+            if val:
+                name = ET.SubElement(measure, "AttributeSet")
+                attr = ET.SubElement(name, "Attribute", attrib={"Type": attr_type})
+                attr.text = val
+
+    # Per-criterion comments — the audit trail in flat form
+    for c in rec.criteria or []:
+        if not c.triggered:
+            continue
+        crit_comment = ET.SubElement(assertion, "Comment", attrib={"Type": "public"})
+        bits = [f"{c.code} ({c.strength})", f"source={c.source}"]
+        if c.pmid:
+            bits.append(f"PMID:{c.pmid}")
+        if c.curator_override and c.override_justification:
+            bits.append(f"curator override: {c.override_justification}")
+        crit_comment.text = " — ".join(bits + [c.evidence_text])
+
+    rough = ET.tostring(root, encoding="utf-8")
+    return minidom.parseString(rough).toprettyxml(indent="  ")
+
+
+def render_fhir_observation(rec: ClassificationRecord) -> dict[str, Any]:
+    """Render a FHIR R4 Observation resource for the variant interpretation.
+
+    Conforms to the HL7 Genomics Reporting IG profile
+    `genomic-implication` / `variant` family. The encoded structure is the
+    minimum needed for an EHR import — extend with `specimen`, `subject`, and
+    `performer` references at the deployment boundary.
+    """
+    sig = LOINC_CLINSIG.get(rec.significance, {
+        "system": "http://terminology.hl7.org/CodeSystem/v3-NullFlavor",
+        "code": "OTH",
+        "display": rec.significance,
+    })
+
+    components: list[dict[str, Any]] = []
+    if hasattr(rec, "variant") and rec.variant is not None:
+        for code, display, attr in [
+            ("48004-6", "DNA change (c.HGVS)", "hgvs_coding"),
+            ("48005-3", "Amino acid change (p.HGVS)", "hgvs_protein"),
+            ("81290-9", "Genomic DNA change (g.HGVS)", "hgvs_genomic"),
+            ("48018-6", "Gene studied [ID]", "gene_symbol"),
+        ]:
+            val = getattr(rec.variant, attr, None)
+            if val:
+                components.append({
+                    "code": {"coding": [{"system": "http://loinc.org", "code": code, "display": display}]},
+                    "valueString": val,
+                })
+
+    derived: list[dict[str, Any]] = []
+    for c in rec.criteria or []:
+        if not c.triggered:
+            continue
+        derived.append({
+            "extension": [
+                {"url": "https://variantlens.local/fhir/criterion-code", "valueString": c.code},
+                {"url": "https://variantlens.local/fhir/criterion-strength", "valueString": c.strength},
+                {"url": "https://variantlens.local/fhir/criterion-source", "valueString": c.source},
+            ],
+            "valueString": c.evidence_text,
+        })
+
+    return {
+        "resourceType": "Observation",
+        "id": rec.id,
+        "meta": {
+            "profile": [
+                "http://hl7.org/fhir/uv/genomics-reporting/StructureDefinition/variant",
+            ],
+        },
+        "status": "final" if rec.curator_signoff else "preliminary",
+        "category": [{
+            "coding": [{
+                "system": "http://terminology.hl7.org/CodeSystem/observation-category",
+                "code": "laboratory",
+            }],
+        }],
+        "code": {
+            "coding": [{
+                "system": "http://loinc.org",
+                "code": "53037-8",
+                "display": "Genetic variation clinical significance",
+            }],
+        },
+        "issued": (rec.signed_off_at.isoformat() if rec.signed_off_at else
+                   rec.created_at.isoformat() if rec.created_at else
+                   datetime.now(UTC).isoformat()),
+        "performer": [{"display": rec.curator_id or "VariantLens (auto)"}],
+        "valueCodeableConcept": {"coding": [sig], "text": rec.significance},
+        "interpretation": [{"text": rec.rationale or ""}] if rec.rationale else [],
+        "note": [{"text": f"ACMG ruleset {rec.ruleset_version}; "
+                          f"triggered: {', '.join(rec.triggered_criteria or [])}"}],
+        "component": components,
+        "derivedFrom": derived,
+    }

backend/app/services/gnomad.py

@@ -0,0 +1,118 @@
+import logging
+import sqlite3
+from pathlib import Path
+
+import httpx
+from tenacity import retry, stop_after_attempt, wait_exponential
+
+from backend.app.config import get_settings
+from backend.app.schemas.evidence import PopulationFrequency
+
+logger = logging.getLogger(__name__)
+settings = get_settings()
+
+GNOMAD_QUERY = """
+query VariantInfo($variantId: String!, $datasetId: DatasetId!) {
+  variant(variantId: $variantId, dataset: $datasetId) {
+    variant_id
+    exome {
+      ac
+      an
+      af
+      ac_hom
+      populations { id ac an }
+    }
+    genome {
+      ac
+      an
+      af
+      ac_hom
+      populations { id ac an }
+    }
+  }
+}
+"""
+
+
+class GnomADClient:
+    def __init__(self, url: str | None = None, cache_db: Path | None = None) -> None:
+        self.url = url or settings.gnomad_graphql_url
+        self.cache_db = cache_db or settings.gnomad_cache_db
+        self._init_cache()
+
+    def _init_cache(self) -> None:
+        self.cache_db.parent.mkdir(parents=True, exist_ok=True)
+        with sqlite3.connect(self.cache_db) as conn:
+            conn.execute(
+                """
+                CREATE TABLE IF NOT EXISTS gnomad_cache (
+                    variant_id TEXT PRIMARY KEY,
+                    af REAL,
+                    homozygotes INTEGER,
+                    populations TEXT,
+                    coverage_warning TEXT,
+                    fetched_at TEXT DEFAULT CURRENT_TIMESTAMP
+                )
+                """
+            )
+
+    @retry(stop=stop_after_attempt(3), wait=wait_exponential(min=1, max=8), reraise=True)
+    async def _fetch(self, variant_id: str, dataset: str = "gnomad_r4") -> dict | None:
+        async with httpx.AsyncClient(timeout=15.0) as client:
+            r = await client.post(
+                self.url,
+                json={
+                    "query": GNOMAD_QUERY,
+                    "variables": {"variantId": variant_id, "datasetId": dataset},
+                },
+            )
+            r.raise_for_status()
+            payload = r.json()
+            return payload.get("data", {}).get("variant")
+
+    async def lookup(self, variant_id: str) -> PopulationFrequency:
+        with sqlite3.connect(self.cache_db) as conn:
+            row = conn.execute(
+                "SELECT af, homozygotes, populations, coverage_warning FROM gnomad_cache WHERE variant_id = ?",
+                (variant_id,),
+            ).fetchone()
+            if row:
+                af, hom, pops_str, cov = row
+                import json
+                return PopulationFrequency(
+                    overall_af=af,
+                    homozygote_count=hom,
+                    by_population=json.loads(pops_str) if pops_str else {},
+                    coverage_warning=cov,
+                )
+
+        try:
+            data = await self._fetch(variant_id)
+        except (httpx.HTTPError, httpx.TimeoutException) as e:
+            logger.warning("gnomAD fetch failed for %s: %s", variant_id, e)
+            return PopulationFrequency(coverage_warning=f"fetch failed: {e}")
+
+        if not data:
+            return PopulationFrequency(coverage_warning="not found in gnomAD")
+
+        exome = data.get("exome") or {}
+        genome = data.get("genome") or {}
+        af = exome.get("af") or genome.get("af") or 0.0
+        hom = (exome.get("ac_hom") or 0) + (genome.get("ac_hom") or 0)
+
+        populations: dict[str, float] = {}
+        for src in (exome, genome):
+            for pop in src.get("populations") or []:
+                if pop["an"]:
+                    populations[pop["id"]] = (pop.get("ac") or 0) / pop["an"]
+
+        import json
+        with sqlite3.connect(self.cache_db) as conn:
+            conn.execute(
+                "INSERT OR REPLACE INTO gnomad_cache (variant_id, af, homozygotes, populations, coverage_warning) VALUES (?, ?, ?, ?, ?)",
+                (variant_id, af, hom, json.dumps(populations), None),
+            )
+
+        return PopulationFrequency(
+            overall_af=af, homozygote_count=hom, by_population=populations
+        )

backend/app/services/insilico.py

@@ -0,0 +1,159 @@
+import logging
+import sqlite3
+from pathlib import Path
+
+import httpx
+from tenacity import retry, stop_after_attempt, wait_exponential
+
+from backend.app.config import get_settings
+from backend.app.schemas.evidence import InSilicoResult
+
+logger = logging.getLogger(__name__)
+settings = get_settings()
+
+REVEL_PATHOGENIC_THRESHOLD = 0.7
+REVEL_BENIGN_THRESHOLD = 0.15
+ALPHAMISSENSE_PATHOGENIC = 0.564
+ALPHAMISSENSE_BENIGN = 0.34
+SPLICEAI_PATHOGENIC = 0.5
+CADD_PATHOGENIC = 25.0
+
+
+class InSilicoPredictor:
+    def __init__(
+        self,
+        revel_db: Path | None = None,
+        alphamissense_db: Path | None = None,
+        spliceai_url: str | None = None,
+    ) -> None:
+        self.revel_db = revel_db or settings.revel_db_path
+        self.alphamissense_db = alphamissense_db or settings.alphamissense_db_path
+        self.spliceai_url = spliceai_url or settings.spliceai_lookup_url
+
+    def lookup_revel(self, chrom: str, pos: int, ref: str, alt: str) -> float | None:
+        if not self.revel_db.exists():
+            logger.debug("REVEL db not present; skip")
+            return None
+        try:
+            with sqlite3.connect(self.revel_db) as conn:
+                row = conn.execute(
+                    "SELECT score FROM revel WHERE chrom = ? AND pos = ? AND ref = ? AND alt = ?",
+                    (chrom, pos, ref, alt),
+                ).fetchone()
+                return row[0] if row else None
+        except sqlite3.DatabaseError as e:
+            logger.warning("REVEL lookup error: %s", e)
+            return None
+
+    def lookup_alphamissense(
+        self,
+        chrom: str | None,
+        pos: int | None,
+        ref: str | None,
+        alt: str | None,
+        transcript: str | None = None,
+    ) -> float | None:
+        """Genomic-coordinate lookup against the SQLite cache.
+
+        AlphaMissense scores live at chr/pos/ref/alt × transcript granularity.
+        We try (chrom,pos,ref,alt,transcript) first, then fall back to the
+        first matching transcript at that locus.
+        """
+        if not self.alphamissense_db.exists():
+            logger.debug("AlphaMissense db not present; skip")
+            return None
+        if not (chrom and pos and ref and alt):
+            return None
+        try:
+            with sqlite3.connect(self.alphamissense_db) as conn:
+                if transcript:
+                    row = conn.execute(
+                        "SELECT score FROM alphamissense WHERE chrom = ? AND pos = ? AND ref = ? AND alt = ? AND transcript = ?",
+                        (chrom.lstrip("chr"), pos, ref, alt, transcript),
+                    ).fetchone()
+                    if row:
+                        return float(row[0])
+                row = conn.execute(
+                    "SELECT score FROM alphamissense WHERE chrom = ? AND pos = ? AND ref = ? AND alt = ? LIMIT 1",
+                    (chrom.lstrip("chr"), pos, ref, alt),
+                ).fetchone()
+                return float(row[0]) if row else None
+        except sqlite3.DatabaseError as e:
+            logger.warning("AlphaMissense lookup error: %s", e)
+            return None
+
+    @retry(stop=stop_after_attempt(2), wait=wait_exponential(min=1, max=5), reraise=True)
+    async def lookup_spliceai(self, hgvs_genomic: str) -> float | None:
+        try:
+            async with httpx.AsyncClient(timeout=15.0) as client:
+                r = await client.get(
+                    f"{self.spliceai_url}/api",
+                    params={"hg": "38", "distance": "50", "mask": "0", "variant": hgvs_genomic},
+                )
+                r.raise_for_status()
+                data = r.json()
+                scores = data.get("scores") or []
+                if not scores:
+                    return None
+                ds: list[float] = []
+                for score in scores:
+                    ds.extend([
+                        float(score.get("DS_AG", 0)),
+                        float(score.get("DS_AL", 0)),
+                        float(score.get("DS_DG", 0)),
+                        float(score.get("DS_DL", 0)),
+                    ])
+                return max(ds)
+        except (httpx.HTTPError, httpx.TimeoutException, ValueError) as e:
+            logger.warning("SpliceAI lookup failed: %s", e)
+            return None
+
+    async def assess(
+        self,
+        chrom: str | None,
+        pos: int | None,
+        ref: str | None,
+        alt: str | None,
+        transcript: str | None,
+        hgvs_genomic: str | None,
+    ) -> InSilicoResult:
+        revel = (
+            self.lookup_revel(chrom, pos, ref, alt)
+            if chrom and pos and ref and alt
+            else None
+        )
+        am = self.lookup_alphamissense(chrom, pos, ref, alt, transcript)
+        splice = await self.lookup_spliceai(hgvs_genomic) if hgvs_genomic else None
+
+        path_votes = sum(
+            [
+                revel is not None and revel >= REVEL_PATHOGENIC_THRESHOLD,
+                am is not None and am >= ALPHAMISSENSE_PATHOGENIC,
+                splice is not None and splice >= SPLICEAI_PATHOGENIC,
+            ]
+        )
+        benign_votes = sum(
+            [
+                revel is not None and revel <= REVEL_BENIGN_THRESHOLD,
+                am is not None and am <= ALPHAMISSENSE_BENIGN,
+                splice is not None and splice < SPLICEAI_PATHOGENIC,
+            ]
+        )
+        total_with_data = sum([revel is not None, am is not None, splice is not None])
+
+        # ClinGen SVI 2022 — fire if at least one strong predictor agrees
+        # AND no predictor strongly contradicts. The strict "unanimous"
+        # rule was rejecting BP4 whenever REVEL was middling, which
+        # missed real benign missense calls.
+        pp3 = path_votes >= 1 and benign_votes == 0 and total_with_data >= 1
+        bp4 = benign_votes >= 1 and path_votes == 0 and total_with_data >= 1
+
+        return InSilicoResult(
+            revel=revel,
+            alphamissense=am,
+            spliceai_max=splice,
+            concordant_pathogenic=total_with_data >= 2 and path_votes == total_with_data,
+            concordant_benign=total_with_data >= 2 and benign_votes == total_with_data,
+            pp3_triggered=pp3,
+            bp4_triggered=bp4,
+        )

backend/app/services/llm/__init__.py

@@ -0,0 +1,5 @@
+from backend.app.services.llm.prompts import build_user_prompt, get_system_prompt
+from backend.app.services.llm.reasoner import ClaudeReasoner
+from backend.app.services.llm.synthesizer import EvidenceSynthesizer
+
+__all__ = ["ClaudeReasoner", "EvidenceSynthesizer", "build_user_prompt", "get_system_prompt"]

backend/app/services/llm/prompts.py

@@ -0,0 +1,109 @@
+"""
+Hallucination-suppressed prompt templates for literature-dependent ACMG criteria.
+
+Mirrors the AI CURA strategy (Chung, Ma et al. 2025): Claude is allowed to reason
+ONLY over the retrieved chunks. Every output must cite a PMID present in the
+context. Output is structured JSON; no free text.
+"""
+
+import json
+
+from backend.app.schemas.evidence import LiteratureChunk
+
+SYSTEM_PROMPT = """You are a clinical genetics variant curator assistant working within an ACMG/AMP framework. Your role is to extract structured evidence from the provided literature context ONLY.
+
+CRITICAL RULES:
+1. Do NOT use any knowledge from your training data about this variant, gene, or disease beyond standard biology background. All claims about specific findings must come from the provided context chunks.
+2. Only cite evidence that appears verbatim in the provided context chunks.
+3. If the context does not contain sufficient evidence for a criterion, output: "triggered": false, "evidence": "insufficient evidence in provided literature".
+4. For each criterion you assess, cite the specific PMID and quote the relevant sentence(s) from the chunk text.
+5. Output structured JSON only — no free text, no markdown, no preamble.
+6. Flag any ambiguous phasing, uncertain phenotype matches, or potential ascertainment bias in the "caveat" field.
+7. If a chunk's PMID is not in the context, do NOT cite it. Cited PMIDs MUST appear in the metadata of a provided chunk.
+
+OUTPUT SCHEMA per criterion (JSON object):
+{
+  "criterion": "PM3" | "PP1" | "PS3" | "BS3" | "PS4" | "PP4" | "PS2" | "PM6" | "PP5" | "BP6",
+  "triggered": true | false,
+  "strength": "supporting" | "moderate" | "strong" | "very_strong",
+  "evidence": "<exact quote from a context chunk>",
+  "pmid": "<PMID from chunk metadata>",
+  "confidence": "high" | "medium" | "low",
+  "caveat": "<optional text or null>"
+}
+Return a JSON array of one object per requested criterion."""
+
+
+CRITERION_GUIDANCE: dict[str, str] = {
+    "PM3": (
+        "PM3 — observed in trans with another pathogenic/likely-pathogenic variant. "
+        "Look for explicit statements of compound heterozygosity, in-trans observation, "
+        "or biallelic occurrence with parental confirmation."
+    ),
+    "PP1": (
+        "PP1 — co-segregation with disease in multiple affected family members. "
+        "Count distinct affected segregating individuals; require ≥3 for moderate, ≥7 for strong."
+    ),
+    "PS3": (
+        "PS3 — well-established in vitro or in vivo functional studies show a deleterious effect. "
+        "Penalize assays with poor controls, single replicates, or non-physiological systems."
+    ),
+    "BS3": (
+        "BS3 — well-established functional studies show no measurable effect."
+    ),
+    "PS4": (
+        "PS4 — variant prevalence in cases significantly increased over controls. "
+        "Extract case counts and odds ratios where present."
+    ),
+    "PP4": (
+        "PP4 — patient phenotype highly specific for a disease with single genetic etiology. "
+        "Require explicit phenotype description, not generic disease name."
+    ),
+    "PS2": "PS2 — confirmed de novo with parental confirmation.",
+    "PM6": "PM6 — assumed de novo without parental confirmation.",
+    "PP5": "PP5 — reputable source recently reports as pathogenic.",
+    "BP6": "BP6 — reputable source recently reports as benign.",
+}
+
+
+def get_system_prompt() -> str:
+    return SYSTEM_PROMPT
+
+
+def build_user_prompt(
+    variant_hgvs: str,
+    gene: str,
+    disease: str | None,
+    auto_scored: list[dict],
+    chunks: list[LiteratureChunk],
+    criteria: list[str],
+) -> str:
+    chunk_blocks = []
+    for i, c in enumerate(chunks):
+        chunk_blocks.append(
+            f"--- Chunk #{i+1} ---\n"
+            f"PMID: {c.pmid}\n"
+            f"Year: {c.year or 'unknown'}\n"
+            f"Title: {c.title or 'n/a'}\n"
+            f"Hint criteria: {', '.join(c.criteria_relevance) or 'none'}\n"
+            f"Text:\n{c.chunk_text}\n"
+        )
+    chunks_str = "\n".join(chunk_blocks) or "(no literature retrieved — output insufficient evidence for all criteria)"
+
+    guidance_str = "\n".join(
+        f"- {CRITERION_GUIDANCE.get(c, c)}" for c in criteria
+    )
+
+    return (
+        f"Variant: {variant_hgvs}\n"
+        f"Gene: {gene}\n"
+        f"Disease: {disease or 'unspecified'}\n\n"
+        f"PRE-SCORED DATABASE CRITERIA (do not re-evaluate these — informational only):\n"
+        f"{json.dumps(auto_scored, indent=2)}\n\n"
+        f"CRITERIA TO ASSESS FROM LITERATURE ONLY:\n"
+        f"{guidance_str}\n\n"
+        f"LITERATURE CONTEXT:\n"
+        f"{chunks_str}\n\n"
+        f"Output a JSON array with one entry per criterion in the order: {criteria}. "
+        f"Cite only PMIDs that appear in the context above."
+    )

backend/app/services/llm/reasoner.py

@@ -0,0 +1,201 @@
+import json
+import logging
+from typing import Any, cast
+
+import anthropic
+import httpx
+from tenacity import retry, retry_if_exception_type, stop_after_attempt, wait_exponential
+
+from backend.app.config import get_settings
+from backend.app.schemas.evidence import ACMGCriterion, LiteratureChunk
+from backend.app.services.llm.prompts import build_user_prompt, get_system_prompt
+
+logger = logging.getLogger(__name__)
+settings = get_settings()
+
+
+class ClaudeReasoner:
+    def __init__(self, api_key: str | None = None, model: str | None = None) -> None:
+        self.api_key = api_key or settings.anthropic_api_key
+        self.use_local_llm = settings.use_local_llm
+        self.model = model or (settings.local_llm_model if self.use_local_llm else settings.anthropic_model)
+        self.client = (
+            None
+            if self.use_local_llm
+            else anthropic.Anthropic(api_key=self.api_key) if self.api_key else None
+        )
+
+    @retry(
+        stop=stop_after_attempt(3),
+        wait=wait_exponential(min=2, max=20),
+        retry=retry_if_exception_type((anthropic.APIError, anthropic.RateLimitError, httpx.HTTPError)),
+        reraise=True,
+    )
+    def _call(self, system: list[dict[str, Any]], user: str) -> str:
+        if self.use_local_llm:
+            return self._call_local(system, user)
+        if self.client is None:
+            raise RuntimeError("ANTHROPIC_API_KEY not set; cannot call Claude")
+        response = self.client.messages.create(
+            model=self.model,
+            max_tokens=settings.anthropic_max_tokens,
+            system=cast(Any, system),
+            messages=[{"role": "user", "content": user}],
+        )
+        for block in response.content:
+            if block.type == "text":
+                return block.text
+        return ""
+
+    def _call_local(self, system: list[dict[str, Any]], user: str) -> str:
+        system_text = "\n".join(str(part.get("text", "")) for part in system)
+        payload = {
+            "model": self.model,
+            "stream": False,
+            "format": "json",
+            "messages": [
+                {"role": "system", "content": system_text},
+                {"role": "user", "content": user},
+            ],
+            "options": {"temperature": 0},
+        }
+        response = httpx.post(
+            f"{settings.local_llm_base_url.rstrip('/')}/api/chat",
+            json=payload,
+            timeout=120,
+        )
+        response.raise_for_status()
+        data = response.json()
+        message = data.get("message", {})
+        content = message.get("content")
+        if not isinstance(content, str):
+            raise RuntimeError("local LLM response did not include message.content")
+        return content
+
+    def reason_over_criteria(
+        self,
+        variant_hgvs: str,
+        gene: str,
+        disease: str | None,
+        auto_scored_summary: list[dict[str, Any]],
+        chunks: list[LiteratureChunk],
+        criteria: list[str],
+    ) -> list[ACMGCriterion]:
+        if not chunks:
+            return [self._fallback_criterion(c, "insufficient evidence in provided literature") for c in criteria]
+
+        system_text = get_system_prompt()
+        # Cache the long system prompt so repeated runs in a session are cheap.
+        # The prompt is byte-identical across variants — every call should be a cache read.
+        system = [
+            {
+                "type": "text",
+                "text": system_text,
+                "cache_control": {"type": "ephemeral"},
+            }
+        ]
+        user = build_user_prompt(
+            variant_hgvs=variant_hgvs,
+            gene=gene,
+            disease=disease,
+            auto_scored=auto_scored_summary,
+            chunks=chunks,
+            criteria=criteria,
+        )
+
+        try:
+            raw = self._call(system, user)
+        except (anthropic.APIError, httpx.HTTPError, RuntimeError) as e:
+            logger.error("Claude call failed: %s", e)
+            return [self._fallback_criterion(c, str(e)) for c in criteria]
+
+        try:
+            parsed = self._parse_json(raw)
+        except ValueError as e:
+            logger.warning("Claude output JSON malformed; retrying with repair prompt: %s", e)
+            try:
+                raw = self._call(
+                    system,
+                    user
+                    + "\n\nYour previous output failed JSON validation. Return ONLY a valid JSON array matching the schema.",
+                )
+                parsed = self._parse_json(raw)
+            except (ValueError, anthropic.APIError, httpx.HTTPError) as e2:
+                logger.error("Claude repair attempt failed: %s", e2)
+                return [self._fallback_criterion(c, "LLM output unparseable") for c in criteria]
+
+        chunks_by_pmid: dict[str, list[str]] = {}
+        for chunk in chunks:
+            chunks_by_pmid.setdefault(chunk.pmid, []).append(chunk.chunk_text)
+        valid_pmids = set(chunks_by_pmid)
+        out: list[ACMGCriterion] = []
+        for entry in parsed:
+            try:
+                code = entry["criterion"]
+                pmid = entry.get("pmid")
+                evidence_text = str(entry.get("evidence", "")).strip()
+                if entry.get("triggered"):
+                    rejection = self._trigger_rejection_reason(pmid, evidence_text, chunks_by_pmid, valid_pmids)
+                    if rejection:
+                        logger.warning("Suppressing %s from LLM output: %s", code, rejection)
+                        out.append(self._fallback_criterion(code, rejection))
+                        continue
+                out.append(
+                    ACMGCriterion(
+                        code=code,
+                        triggered=bool(entry.get("triggered", False)),
+                        strength=entry.get("strength", "supporting"),
+                        source=f"PMID:{pmid}" if pmid else "literature",
+                        evidence_text=evidence_text or "insufficient evidence in provided literature",
+                        confidence=entry.get("confidence", "medium"),
+                        caveat=entry.get("caveat"),
+                        pmid=pmid,
+                    )
+                )
+            except (KeyError, TypeError) as e:
+                logger.warning("malformed entry from Claude: %s — %s", entry, e)
+        return out
+
+    @staticmethod
+    def _trigger_rejection_reason(
+        pmid: Any,
+        evidence_text: str,
+        chunks_by_pmid: dict[str, list[str]],
+        valid_pmids: set[str],
+    ) -> str | None:
+        if not pmid:
+            return "triggered literature criterion missing PMID"
+        if pmid not in valid_pmids:
+            return "fabricated PMID rejected"
+        if not evidence_text:
+            return "triggered literature criterion missing evidence quote"
+        normalized_evidence = " ".join(evidence_text.split()).lower()
+        normalized_chunks = [" ".join(text.split()).lower() for text in chunks_by_pmid[pmid]]
+        if not any(normalized_evidence in chunk for chunk in normalized_chunks):
+            return "evidence quote not found verbatim in cited PMID chunk"
+        return None
+
+    @staticmethod
+    def _parse_json(raw: str) -> list[dict[str, Any]]:
+        text = raw.strip()
+        if text.startswith("```"):
+            text = text.split("```")[1]
+            if text.startswith("json"):
+                text = text[4:]
+            text = text.strip()
+        data = json.loads(text)
+        if not isinstance(data, list):
+            raise ValueError("expected JSON array")
+        return data
+
+    @staticmethod
+    def _fallback_criterion(code: str, reason: str) -> ACMGCriterion:
+        return ACMGCriterion(
+            code=code,
+            triggered=False,
+            strength="supporting",
+            source="LLM",
+            evidence_text=f"insufficient evidence — {reason}",
+            confidence="low",
+            caveat=reason,
+        )

backend/app/services/llm/synthesizer.py

@@ -0,0 +1,81 @@
+import logging
+
+from backend.app.schemas.classification import ClassificationResult
+from backend.app.schemas.evidence import ACMGCriterion, EvidenceBundle, LiteratureChunk
+from backend.app.schemas.variant import NormalizedVariant
+from backend.app.services.acmg.combiner import combine_criteria
+from backend.app.services.acmg.rules import RuleEngine
+from backend.app.services.llm.reasoner import ClaudeReasoner
+
+logger = logging.getLogger(__name__)
+
+LITERATURE_CRITERIA = ["PM3", "PP1", "PS3", "BS3", "PS4", "PP4"]
+
+
+class EvidenceSynthesizer:
+    def __init__(
+        self,
+        rule_engine: RuleEngine | None = None,
+        reasoner: ClaudeReasoner | None = None,
+    ) -> None:
+        self.rule_engine = rule_engine or RuleEngine()
+        self.reasoner = reasoner or ClaudeReasoner()
+
+    def synthesize(
+        self,
+        variant: NormalizedVariant,
+        evidence: EvidenceBundle,
+        retrieved_chunks: dict[str, list[LiteratureChunk]] | None = None,
+        disease: str | None = None,
+    ) -> ClassificationResult:
+        # 1. Database-driven criteria
+        db_criteria = self.rule_engine.score_all(evidence)
+
+        # 2. Literature-driven criteria via Claude
+        llm_criteria: list[ACMGCriterion] = []
+        if retrieved_chunks:
+            all_chunks = []
+            seen = set()
+            for chunks in retrieved_chunks.values():
+                for c in chunks:
+                    key = (c.pmid, c.chunk_text[:100])
+                    if key not in seen:
+                        seen.add(key)
+                        all_chunks.append(c)
+
+            auto_summary = [
+                {
+                    "criterion": c.code,
+                    "triggered": c.triggered,
+                    "source": c.source,
+                    "evidence": c.evidence_text,
+                }
+                for c in db_criteria
+            ]
+
+            try:
+                llm_criteria = self.reasoner.reason_over_criteria(
+                    variant_hgvs=variant.hgvs_coding or variant.raw_input,
+                    gene=variant.gene_symbol or "unknown",
+                    disease=disease,
+                    auto_scored_summary=auto_summary,
+                    chunks=all_chunks,
+                    criteria=LITERATURE_CRITERIA,
+                )
+            except Exception as e:
+                logger.error("LLM reasoning failed: %s", e)
+
+        # 3. Merge — db criteria win on conflict
+        merged: dict[str, ACMGCriterion] = {c.code: c for c in db_criteria}
+        for c in llm_criteria:
+            merged.setdefault(c.code, c)
+
+        all_criteria = list(merged.values())
+        evidence.criteria = all_criteria
+
+        classification = combine_criteria(all_criteria)
+        return ClassificationResult(
+            variant=variant,
+            evidence=evidence,
+            classification=classification,
+        )

backend/app/services/normalization.py

@@ -0,0 +1,209 @@
+import logging
+import re
+
+import httpx
+from tenacity import retry, retry_if_exception_type, stop_after_attempt, wait_exponential
+
+from backend.app.config import get_settings
+from backend.app.schemas.variant import NormalizedVariant, VariantInput
+
+logger = logging.getLogger(__name__)
+settings = get_settings()
+
+HGVS_PATTERN = re.compile(r"^(NM_|NC_|NP_|ENST|ENSP)[\d.]+:[cgpnm]\.")
+VCF_PATTERN = re.compile(r"^(chr)?[\dXYM]+[-:]\d+[-:][ACGT]+[-:][ACGT]+$", re.IGNORECASE)
+PROTEIN_PATTERN = re.compile(
+    r"^p\.[A-Z][a-z]{2}\d+([A-Z][a-z]{2}|\*|Ter)$"  # 3-letter ref + 3-letter alt OR stop
+    r"|^p\.[A-Z]\d+[A-Z*]$"                         # 1-letter ref + 1-letter alt
+)
+
+# GRCh38 chromosome accessions (RefSeq). Mutalyzer rejects `chr17:g.` and
+# requires the canonical NC_ identifier for genomic descriptions.
+GRCH38_CHROM_TO_NC: dict[str, str] = {
+    "1": "NC_000001.11", "2": "NC_000002.12", "3": "NC_000003.12", "4": "NC_000004.12",
+    "5": "NC_000005.10", "6": "NC_000006.12", "7": "NC_000007.14", "8": "NC_000008.11",
+    "9": "NC_000009.12", "10": "NC_000010.11", "11": "NC_000011.10", "12": "NC_000012.12",
+    "13": "NC_000013.11", "14": "NC_000014.9", "15": "NC_000015.10", "16": "NC_000016.10",
+    "17": "NC_000017.11", "18": "NC_000018.10", "19": "NC_000019.10", "20": "NC_000020.11",
+    "21": "NC_000021.9", "22": "NC_000022.11", "X": "NC_000023.11", "Y": "NC_000024.10",
+    "M": "NC_012920.1", "MT": "NC_012920.1",
+}
+
+
+class NormalizationError(Exception):
+    pass
+
+
+class VariantNormalizer:
+    def __init__(self, base_url: str | None = None, timeout: float = 10.0) -> None:
+        self.base_url = base_url or settings.mutalyzer_base_url
+        self.timeout = timeout
+
+    def detect_notation(self, raw: str) -> str:
+        s = raw.strip()
+        if HGVS_PATTERN.match(s):
+            return "hgvs"
+        if VCF_PATTERN.match(s):
+            return "vcf"
+        if PROTEIN_PATTERN.match(s):
+            return "protein"
+        return "unknown"
+
+    @retry(
+        stop=stop_after_attempt(3),
+        wait=wait_exponential(multiplier=1, min=1, max=8),
+        retry=retry_if_exception_type((httpx.HTTPStatusError, httpx.TimeoutException)),
+        reraise=True,
+    )
+    async def _call_mutalyzer(self, hgvs: str) -> dict:
+        url = f"{self.base_url}/normalize/{hgvs}"
+        async with httpx.AsyncClient(timeout=self.timeout) as client:
+            r = await client.get(url)
+            r.raise_for_status()
+            return r.json()
+
+    async def normalize(self, raw_input: VariantInput) -> NormalizedVariant:
+        notation = (
+            raw_input.notation if raw_input.notation != "auto" else self.detect_notation(raw_input.raw)
+        )
+        warnings: list[str] = []
+        vcf_parts: tuple[str, int, str, str] | None = None
+
+        # For VCF input, lock in chrom/pos/ref/alt up front so the score-DB
+        # lookups (REVEL, AlphaMissense, gnomAD) always have what they need —
+        # even if the Mutalyzer enrichment call fails.
+        hgvs_for_mutalyzer: str | None = None
+        if notation == "vcf":
+            try:
+                hgvs_for_mutalyzer, vcf_parts = self._vcf_to_hgvs_with_parts(raw_input.raw)
+            except NormalizationError as e:
+                warnings.append(f"VCF parse failed: {e}")
+
+        try:
+            if notation == "hgvs":
+                data = await self._call_mutalyzer(raw_input.raw)
+                return self._parse_mutalyzer(raw_input.raw, data, warnings)
+            if notation == "vcf" and hgvs_for_mutalyzer:
+                data = await self._call_mutalyzer(hgvs_for_mutalyzer)
+                v = self._parse_mutalyzer(raw_input.raw, data, warnings)
+                chrom, pos, ref, alt = vcf_parts  # type: ignore[misc]
+                return v.model_copy(update={
+                    "chromosome": chrom, "position": pos, "ref": ref, "alt": alt,
+                    "hgvs_genomic": hgvs_for_mutalyzer,
+                    "gene_symbol": v.gene_symbol or raw_input.gene_symbol,
+                })
+            if notation == "protein":
+                warnings.append("protein-only input — coding HGVS unavailable without back-translation")
+                return NormalizedVariant(
+                    raw_input=raw_input.raw,
+                    hgvs_protein=raw_input.raw,
+                    gene_symbol=raw_input.gene_symbol,
+                    normalization_source="passthrough",
+                    warnings=warnings,
+                )
+            warnings.append(f"unknown notation; passing through: {raw_input.raw}")
+            return NormalizedVariant(
+                raw_input=raw_input.raw,
+                gene_symbol=raw_input.gene_symbol,
+                normalization_source="passthrough",
+                warnings=warnings,
+            )
+        except (httpx.HTTPStatusError, httpx.TimeoutException, NormalizationError) as e:
+            logger.warning("Mutalyzer normalization failed for %s: %s", raw_input.raw, e)
+            warnings.append(f"mutalyzer failed: {e}; using passthrough")
+            chrom = pos = ref = alt = None
+            if vcf_parts:
+                chrom, pos, ref, alt = vcf_parts
+            return NormalizedVariant(
+                raw_input=raw_input.raw,
+                hgvs_coding=raw_input.raw if notation == "hgvs" else None,
+                hgvs_genomic=hgvs_for_mutalyzer,
+                gene_symbol=raw_input.gene_symbol,
+                chromosome=chrom,
+                position=pos,
+                ref=ref,
+                alt=alt,
+                normalization_source="passthrough",
+                warnings=warnings,
+            )
+
+    def _vcf_to_hgvs(self, vcf: str) -> str:
+        return self._vcf_to_hgvs_with_parts(vcf)[0]
+
+    def _vcf_to_hgvs_with_parts(self, vcf: str) -> tuple[str, tuple[str, int, str, str]]:
+        parts = re.split(r"[-:]", vcf)
+        if len(parts) != 4:
+            raise NormalizationError(f"malformed VCF string: {vcf}")
+        chrom, pos, ref, alt = parts
+        chrom = chrom.replace("chr", "").upper()
+        nc_acc = GRCH38_CHROM_TO_NC.get(chrom)
+        if not nc_acc:
+            raise NormalizationError(
+                f"unknown chromosome {chrom!r}; expected 1-22, X, Y, M, or MT"
+            )
+        return f"{nc_acc}:g.{pos}{ref}>{alt}", (chrom, int(pos), ref, alt)
+
+    def _parse_mutalyzer(self, raw: str, data: dict, warnings: list[str]) -> NormalizedVariant:
+        """Parse the Mutalyzer v3 API response.
+
+        v3 changed the shape entirely from v2:
+          - `normalized_description`  → canonical c. HGVS string
+          - `protein.description`     → canonical p. HGVS string
+          - `rna.description`         → canonical r. HGVS string
+          - `gene_id`                 → HGNC symbol
+          - `infos[*].details`        → human-readable warnings
+        Genomic coordinates are not returned for transcript-keyed input;
+        callers that need chr/pos/ref/alt should pass VCF input.
+        """
+        coding = data.get("normalized_description") or data.get("corrected_description")
+        protein = (data.get("protein") or {}).get("description")
+        gene = data.get("gene_id")
+
+        transcript: str | None = None
+        if coding and ":" in coding:
+            transcript = coding.split(":")[0]
+
+        for info in data.get("infos") or []:
+            details = info.get("details") or info.get("code", "")
+            if details:
+                warnings.append(details)
+
+        consequence = self._infer_consequence(coding or "", protein or "")
+
+        return NormalizedVariant(
+            raw_input=raw,
+            hgvs_coding=coding,
+            hgvs_protein=protein,
+            transcript=transcript,
+            gene_symbol=gene,
+            consequence=consequence,
+            normalization_source="mutalyzer",
+            warnings=warnings,
+        )
+
+    @staticmethod
+    def _infer_consequence(coding: str, protein: str) -> str | None:
+        """Map a Mutalyzer-normalized variant to a SO consequence term.
+
+        Heuristic — covers the cases the rule engine cares about (PVS1
+        and PM4). For full annotation switch to VEP at the ingest boundary.
+        """
+        p = protein.lower()
+        c = coding.lower()
+        if "fs" in p:
+            return "frameshift_variant"
+        if "ter" in p or "*" in p:
+            return "stop_gained"
+        if "del" in c and "ins" not in c:
+            return "inframe_deletion" if "fs" not in p else "frameshift_variant"
+        if "dup" in c:
+            return "frameshift_variant" if "fs" in p else "inframe_insertion"
+        if "ext" in p:
+            return "stop_lost"
+        if "met1" in p and "?" in p:
+            return "start_lost"
+        if "splice" in c or "+" in c.split(":")[-1] or "-" in c.split(":")[-1]:
+            return "splice_region_variant"
+        if protein and ">" in c:
+            return "missense_variant"
+        return None

backend/app/services/pvs1.py

@@ -0,0 +1,111 @@
+import logging
+import re
+
+from backend.app.schemas.evidence import AutoPVS1Result, AutoPVS1Step
+from backend.app.schemas.variant import NormalizedVariant
+
+logger = logging.getLogger(__name__)
+
+LOF_CONSEQUENCES = {
+    "stop_gained",
+    "frameshift_variant",
+    "splice_acceptor_variant",
+    "splice_donor_variant",
+    "start_lost",
+}
+
+
+class PVS1Assessor:
+    """
+    Heuristic PVS1 assessment.
+
+    A real deployment should wrap the autoPVS1 package (https://github.com/JiguangPeng/autoPVS1)
+    for the full LOF-mechanism / 3'-end / NMD / alternative-splicing logic from
+    Tayoun et al. 2018. This wrapper records the rule path for the audit trail.
+    """
+
+    def assess(self, variant: NormalizedVariant) -> AutoPVS1Result:
+        consequence = (variant.consequence or "").lower()
+        protein = variant.hgvs_protein or ""
+
+        is_null = (
+            consequence in LOF_CONSEQUENCES
+            or "ter" in protein.lower()
+            or "fs" in protein.lower()
+            or bool(re.search(r"p\..*\*", protein))
+        )
+
+        steps: list[AutoPVS1Step] = []
+
+        # Step 1 — variant type
+        variant_type = (
+            "Stop-gained" if "stop" in consequence or "ter" in protein.lower() or re.search(r"p\..*\*", protein)
+            else "Frameshift" if "frameshift" in consequence or "fs" in protein.lower()
+            else "Splice site" if "splice" in consequence
+            else "Start-lost" if "start_lost" in consequence
+            else f"Other ({consequence or 'unknown'})"
+        )
+        steps.append(AutoPVS1Step(
+            step=1, label="Variant type", value=variant_type, **{"pass": is_null}
+        ))
+
+        if not is_null:
+            steps.append(AutoPVS1Step(
+                step=2, label="Predicted consequence",
+                value="No protein-truncating effect inferred",
+                **{"pass": False},
+            ))
+            return AutoPVS1Result(
+                triggered=False,
+                strength="very_strong",
+                rule="PVS1",
+                reasoning=steps,
+                conclusion="PVS1 not triggered — variant is not null",
+                source="autoPVS1-heuristic",
+            )
+
+        # Step 2 — predicted consequence
+        steps.append(AutoPVS1Step(
+            step=2, label="Predicted consequence",
+            value=f"Premature stop / truncation ({protein or 'inferred'})",
+            **{"pass": True},
+        ))
+
+        # Step 3 — NMD prediction (heuristic)
+        nmd_predicted = "fs" in protein.lower() or "ter" in protein.lower()
+        steps.append(AutoPVS1Step(
+            step=3, label="NMD predicted",
+            value="Yes — assumed NMD competent (verify against last-exon distance)" if nmd_predicted
+                  else "Unknown — verify manually",
+            **{"pass": nmd_predicted},
+        ))
+
+        # Step 4 — last exon exception (heuristic placeholder)
+        steps.append(AutoPVS1Step(
+            step=4, label="Last exon exception",
+            value="Not assessed — requires transcript exon table",
+            **{"pass": True},
+        ))
+
+        # Step 5 — gene LOF mechanism (heuristic placeholder)
+        steps.append(AutoPVS1Step(
+            step=5, label="Gene LOF mechanism",
+            value="Assumed — verify against gene LOF tolerance (gnomAD pLI / OMIM)",
+            **{"pass": True},
+        ))
+
+        caveats: list[str] = []
+        if "?" in protein or not protein:
+            caveats.append("protein change ambiguous — verify NMD prediction")
+        if not variant.transcript:
+            caveats.append("transcript not specified — multiple-transcript caveat applies")
+
+        return AutoPVS1Result(
+            triggered=True,
+            strength="very_strong",
+            rule="PVS1",
+            reasoning=steps,
+            conclusion="PVS1 triggered at Very Strong strength (heuristic — manual verification recommended)",
+            source="autoPVS1-heuristic",
+            caveats=caveats,
+        )

backend/app/services/rag/__init__.py

@@ -0,0 +1,6 @@
+from backend.app.services.rag.chunker import ChunkBuilder
+from backend.app.services.rag.embedder import Embedder
+from backend.app.services.rag.fetcher import LiteratureFetcher
+from backend.app.services.rag.retriever import LiteratureRetriever
+
+__all__ = ["ChunkBuilder", "Embedder", "LiteratureFetcher", "LiteratureRetriever"]

backend/app/services/rag/chunker.py

@@ -0,0 +1,72 @@
+from backend.app.config import get_settings
+from backend.app.services.rag.fetcher import Paper
+
+settings = get_settings()
+
+CRITERION_KEYWORDS: dict[str, list[str]] = {
+    "PM3": ["in trans", "compound heterozygous", "biallelic", "homozygous"],
+    "PP1": ["segregation", "co-segregat", "family", "affected"],
+    "PS3": ["functional", "in vitro", "in vivo", "assay", "expression"],
+    "BS3": ["no effect", "wild type", "wild-type", "indistinguishable"],
+    "PS4": ["case", "prevalence", "odds ratio", "controls"],
+    "PP4": ["phenotype", "clinical features", "presentation", "presented with"],
+    "PP5": ["pathogenic", "likely pathogenic", "ClinVar", "submission"],
+    "BP6": ["benign", "likely benign", "ClinVar"],
+}
+
+
+class Chunk:
+    def __init__(
+        self,
+        text: str,
+        pmid: str,
+        year: int | None,
+        title: str,
+        criteria_hint: list[str],
+    ) -> None:
+        self.text = text
+        self.pmid = pmid
+        self.year = year
+        self.title = title
+        self.criteria_hint = criteria_hint
+
+
+class ChunkBuilder:
+    def __init__(self, chunk_size: int | None = None, overlap: int | None = None) -> None:
+        self.chunk_size = chunk_size or settings.rag_chunk_size
+        self.overlap = overlap or settings.rag_chunk_overlap
+
+    def detect_criteria(self, chunk_text: str) -> list[str]:
+        hint = []
+        text_lower = chunk_text.lower()
+        for crit, keywords in CRITERION_KEYWORDS.items():
+            if any(kw.lower() in text_lower for kw in keywords):
+                hint.append(crit)
+        return hint
+
+    def chunk_paper(self, paper: Paper) -> list[Chunk]:
+        text = paper.text
+        if not text:
+            return []
+        # Approx 4 chars per token
+        char_size = self.chunk_size * 4
+        char_overlap = self.overlap * 4
+
+        chunks: list[Chunk] = []
+        start = 0
+        while start < len(text):
+            end = min(start + char_size, len(text))
+            window = text[start:end]
+            chunks.append(
+                Chunk(
+                    text=window,
+                    pmid=paper.pmid,
+                    year=paper.year,
+                    title=paper.title,
+                    criteria_hint=self.detect_criteria(window),
+                )
+            )
+            if end >= len(text):
+                break
+            start = end - char_overlap
+        return chunks

backend/app/services/rag/embedder.py

@@ -0,0 +1,77 @@
+import logging
+from typing import TYPE_CHECKING
+
+from backend.app.config import get_settings
+from backend.app.services.rag.chunker import Chunk
+
+if TYPE_CHECKING:
+    from chromadb.api import ClientAPI
+
+logger = logging.getLogger(__name__)
+settings = get_settings()
+
+
+class Embedder:
+    def __init__(self, model_name: str | None = None, persist_dir: str | None = None) -> None:
+        self.model_name = model_name or settings.embedding_model
+        self.persist_dir = persist_dir or str(settings.chroma_persist_dir)
+        self.collection_name = settings.chroma_collection
+        self._model = None
+        self._client: ClientAPI | None = None
+        self._collection = None
+
+    def _ensure_model(self):
+        if self._model is None:
+            from sentence_transformers import SentenceTransformer
+            self._model = SentenceTransformer(self.model_name, device=settings.embedding_device)
+        return self._model
+
+    def _ensure_collection(self):
+        if self._collection is None:
+            import chromadb
+            self._client = chromadb.PersistentClient(path=self.persist_dir)
+            self._collection = self._client.get_or_create_collection(self.collection_name)
+        return self._collection
+
+    def encode(self, texts: list[str]) -> list[list[float]]:
+        model = self._ensure_model()
+        return model.encode(texts, show_progress_bar=False, convert_to_numpy=True).tolist()
+
+    def index_chunks(self, chunks: list[Chunk], variant_id: str, gene: str) -> int:
+        if not chunks:
+            return 0
+        coll = self._ensure_collection()
+        embeddings = self.encode([c.text for c in chunks])
+        ids = [f"{variant_id}:{c.pmid}:{i}" for i, c in enumerate(chunks)]
+        metadatas = [
+            {
+                "pmid": c.pmid,
+                "year": c.year or 0,
+                "title": c.title,
+                "variant_id": variant_id,
+                "gene": gene,
+                "criteria_hint": ",".join(c.criteria_hint),
+            }
+            for c in chunks
+        ]
+        coll.add(
+            ids=ids,
+            documents=[c.text for c in chunks],
+            embeddings=embeddings,
+            metadatas=metadatas,
+        )
+        return len(chunks)
+
+    def query(
+        self, query_text: str, variant_id: str, top_k: int, criteria: list[str] | None = None
+    ) -> list[dict]:
+        coll = self._ensure_collection()
+        emb = self.encode([query_text])[0]
+        where: dict = {"variant_id": variant_id}
+        results = coll.query(query_embeddings=[emb], n_results=top_k, where=where)
+        out = []
+        for i, doc in enumerate(results.get("documents", [[]])[0]):
+            meta = results.get("metadatas", [[]])[0][i] if results.get("metadatas") else {}
+            score = results.get("distances", [[]])[0][i] if results.get("distances") else None
+            out.append({"text": doc, "metadata": meta, "score": score})
+        return out

backend/app/services/rag/fetcher.py

@@ -0,0 +1,136 @@
+import logging
+import xml.etree.ElementTree as ET
+from typing import Any
+
+import httpx
+from tenacity import retry, stop_after_attempt, wait_exponential
+
+from backend.app.config import get_settings
+
+logger = logging.getLogger(__name__)
+settings = get_settings()
+
+EUTILS = "https://eutils.ncbi.nlm.nih.gov/entrez/eutils"
+PMC_FULLTEXT = "https://www.ncbi.nlm.nih.gov/pmc/utils/oa/oa.fcgi"
+
+CRITERION_QUERY_AUGMENTS: dict[str, str] = {
+    "PM3": '"in trans" OR "compound heterozygous" OR "biallelic"',
+    "PP1": '"segregation" OR "affected family members" OR "co-segregates"',
+    "PS3": '"functional" OR "in vitro" OR "in vivo" OR "assay"',
+    "BS3": '"functional" OR "no effect" OR "wild type"',
+    "PS4": '"cases" OR "prevalence" OR "odds ratio"',
+    "PP4": '"phenotype" OR "clinical features" OR "presentation"',
+}
+
+
+class Paper:
+    def __init__(self, pmid: str, title: str, abstract: str, year: int | None, body: str | None = None) -> None:
+        self.pmid = pmid
+        self.title = title
+        self.abstract = abstract
+        self.year = year
+        self.body = body
+
+    @property
+    def text(self) -> str:
+        return self.body or self.abstract
+
+
+class LiteratureFetcher:
+    def __init__(self, max_results: int | None = None, fetch_fulltext: bool | None = None) -> None:
+        self.max_results = max_results or settings.rag_max_papers_per_variant
+        self.fetch_fulltext = settings.rag_fetch_fulltext if fetch_fulltext is None else fetch_fulltext
+        self.api_key = settings.ncbi_api_key
+        self.email = settings.ncbi_email
+
+    def _params(self, **extra: Any) -> dict[str, Any]:
+        p = {"tool": "VariantLens", "email": self.email}
+        if self.api_key:
+            p["api_key"] = self.api_key
+        return {**p, **extra}
+
+    def build_query(self, gene: str, hgvs: str, protein: str | None) -> str:
+        terms = [f'"{gene}"', f'"{hgvs}"']
+        if protein:
+            terms.append(f'"{protein}"')
+        return " AND ".join([f"({t})" for t in terms[:1]] + [f"({' OR '.join(terms[1:])})"])
+
+    @retry(stop=stop_after_attempt(3), wait=wait_exponential(min=1, max=10), reraise=True)
+    async def search_pubmed(self, query: str) -> list[str]:
+        async with httpx.AsyncClient(timeout=20.0) as client:
+            r = await client.get(
+                f"{EUTILS}/esearch.fcgi",
+                params=self._params(db="pubmed", term=query, retmax=self.max_results, retmode="json"),
+            )
+            r.raise_for_status()
+            return r.json().get("esearchresult", {}).get("idlist", [])
+
+    @retry(stop=stop_after_attempt(3), wait=wait_exponential(min=1, max=10), reraise=True)
+    async def fetch_abstracts(self, pmids: list[str]) -> list[Paper]:
+        if not pmids:
+            return []
+        async with httpx.AsyncClient(timeout=30.0) as client:
+            r = await client.get(
+                f"{EUTILS}/efetch.fcgi",
+                params=self._params(db="pubmed", id=",".join(pmids), rettype="abstract", retmode="xml"),
+            )
+            r.raise_for_status()
+            return self._parse_pubmed_xml(r.text)
+
+    def _parse_pubmed_xml(self, xml_text: str) -> list[Paper]:
+        try:
+            root = ET.fromstring(xml_text)
+        except ET.ParseError as e:
+            logger.warning("PubMed XML parse failed: %s", e)
+            return []
+        papers: list[Paper] = []
+        for art in root.iter("PubmedArticle"):
+            pmid_el = art.find(".//PMID")
+            title_el = art.find(".//ArticleTitle")
+            abstract_el = art.findall(".//Abstract/AbstractText")
+            year_el = art.find(".//PubDate/Year")
+            pmid = pmid_el.text if pmid_el is not None and pmid_el.text else ""
+            title = title_el.text if title_el is not None and title_el.text else ""
+            abstract = " ".join((a.text or "") for a in abstract_el)
+            year = int(year_el.text) if year_el is not None and year_el.text and year_el.text.isdigit() else None
+            if pmid:
+                papers.append(Paper(pmid=pmid, title=title, abstract=abstract, year=year))
+        return papers
+
+    async def fetch_full_texts(self, papers: list[Paper]) -> list[Paper]:
+        if not self.fetch_fulltext:
+            return papers
+        async with httpx.AsyncClient(timeout=30.0) as client:
+            for p in papers:
+                try:
+                    r = await client.get(PMC_FULLTEXT, params={"id": p.pmid, "format": "tgz"})
+                    if r.status_code == 200 and "tgz" in r.headers.get("content-type", "").lower():
+                        # Parsing tar.gz -> XML -> body is non-trivial; skip for MVP
+                        # and rely on abstract. Implementation can extend here.
+                        pass
+                except (httpx.HTTPError, httpx.TimeoutException) as e:
+                    logger.debug("full-text fetch skipped for %s: %s", p.pmid, e)
+        return papers
+
+    async def fetch_for_variant(
+        self, gene: str, hgvs: str, protein: str | None, criteria: list[str] | None = None
+    ) -> list[Paper]:
+        base_query = self.build_query(gene, hgvs, protein)
+        all_pmids: set[str] = set()
+        try:
+            all_pmids.update(await self.search_pubmed(base_query))
+        except (httpx.HTTPError, httpx.TimeoutException) as e:
+            logger.warning("base PubMed search failed: %s", e)
+
+        for crit in criteria or []:
+            aug = CRITERION_QUERY_AUGMENTS.get(crit)
+            if not aug:
+                continue
+            try:
+                all_pmids.update(await self.search_pubmed(f"{base_query} AND ({aug})"))
+            except (httpx.HTTPError, httpx.TimeoutException) as e:
+                logger.warning("criterion-augmented search failed for %s: %s", crit, e)
+
+        capped = list(all_pmids)[: self.max_results]
+        papers = await self.fetch_abstracts(capped)
+        return await self.fetch_full_texts(papers)

backend/app/services/rag/retriever.py

@@ -0,0 +1,68 @@
+import logging
+
+from backend.app.config import get_settings
+from backend.app.schemas.evidence import LiteratureChunk
+from backend.app.services.rag.chunker import ChunkBuilder
+from backend.app.services.rag.embedder import Embedder
+from backend.app.services.rag.fetcher import LiteratureFetcher
+
+logger = logging.getLogger(__name__)
+settings = get_settings()
+
+CRITERION_QUERY_TEMPLATES: dict[str, str] = {
+    "PM3": "Was {variant} observed in trans with another pathogenic variant or compound heterozygous?",
+    "PP1": "Did {variant} co-segregate with disease in affected family members?",
+    "PS3": "What functional studies have been performed on {variant} and what do they show?",
+    "BS3": "Do functional studies show {variant} has no measurable effect?",
+    "PS4": "How prevalent is {variant} in cases compared to controls? Is there an odds ratio?",
+    "PP4": "Is the patient phenotype highly specific for the disease associated with {variant}?",
+}
+
+
+class LiteratureRetriever:
+    def __init__(
+        self,
+        fetcher: LiteratureFetcher | None = None,
+        chunker: ChunkBuilder | None = None,
+        embedder: Embedder | None = None,
+    ) -> None:
+        self.fetcher = fetcher or LiteratureFetcher()
+        self.chunker = chunker or ChunkBuilder()
+        self.embedder = embedder or Embedder()
+
+    async def index_for_variant(
+        self, variant_id: str, gene: str, hgvs: str, protein: str | None, criteria: list[str]
+    ) -> int:
+        papers = await self.fetcher.fetch_for_variant(gene, hgvs, protein, criteria)
+        all_chunks = [c for p in papers for c in self.chunker.chunk_paper(p)]
+        return self.embedder.index_chunks(all_chunks, variant_id=variant_id, gene=gene)
+
+    def retrieve_for_criterion(
+        self, variant_id: str, hgvs: str, criterion: str, top_k: int | None = None
+    ) -> list[LiteratureChunk]:
+        template = CRITERION_QUERY_TEMPLATES.get(criterion)
+        if not template:
+            return []
+        query = template.format(variant=hgvs)
+        results = self.embedder.query(
+            query_text=query, variant_id=variant_id, top_k=top_k or settings.rag_top_k
+        )
+        return [
+            LiteratureChunk(
+                pmid=r["metadata"].get("pmid", "unknown"),
+                year=r["metadata"].get("year") or None,
+                title=r["metadata"].get("title"),
+                chunk_text=r["text"],
+                criteria_relevance=[criterion],
+                score=r.get("score"),
+            )
+            for r in results
+        ]
+
+    def retrieve_for_criteria(
+        self, variant_id: str, hgvs: str, criteria: list[str], top_k: int | None = None
+    ) -> dict[str, list[LiteratureChunk]]:
+        return {
+            crit: self.retrieve_for_criterion(variant_id, hgvs, crit, top_k=top_k)
+            for crit in criteria
+        }

backend/app/services/repository.py

@@ -0,0 +1,80 @@
+"""Persistence layer that bridges Pydantic schemas <-> SQLAlchemy records.
+
+The repository is the single point that writes a `ClassificationResult` to
+the audit-trail database and reads it back. Keeping it isolated from the
+pipeline means the pipeline can run dry (no DB) for tests and one-off CLI
+runs, while the FastAPI router persists every successful classification.
+"""
+
+from __future__ import annotations
+
+from datetime import UTC, datetime
+
+from sqlalchemy.orm import Session
+
+from backend.app.models.classification import ClassificationRecord, CriterionRecord
+from backend.app.models.variant import VariantRecord
+from backend.app.schemas.classification import ClassificationResult
+
+
+class ClassificationRepository:
+    def __init__(self, db: Session) -> None:
+        self.db = db
+
+    def save(self, result: ClassificationResult) -> ClassificationResult:
+        v = result.variant
+        variant_record = VariantRecord(
+            raw_input=v.raw_input,
+            hgvs_genomic=v.hgvs_genomic,
+            hgvs_coding=v.hgvs_coding,
+            hgvs_protein=v.hgvs_protein,
+            transcript=v.transcript,
+            gene_symbol=v.gene_symbol,
+            chromosome=v.chromosome,
+            position=v.position,
+            normalization_source=v.normalization_source,
+            warnings=v.warnings,
+        )
+        self.db.add(variant_record)
+        self.db.flush()  # populate variant_record.id
+
+        cls = result.classification
+        record = ClassificationRecord(
+            variant_id=variant_record.id,
+            significance=cls.significance,
+            confidence=cls.confidence,
+            triggered_criteria=list(cls.triggered_criteria),
+            conflicting_evidence=cls.conflicting_evidence,
+            ruleset_version=result.ruleset_version,
+            rationale=cls.rationale,
+        )
+        self.db.add(record)
+        self.db.flush()
+
+        for c in result.evidence.criteria:
+            self.db.add(CriterionRecord(
+                classification_id=record.id,
+                code=c.code,
+                triggered=c.triggered,
+                strength=c.strength,
+                source=c.source,
+                evidence_text=c.evidence_text,
+                confidence=c.confidence,
+                pmid=c.pmid,
+                caveat=c.caveat,
+                curator_override=c.curator_override,
+                override_justification=c.override_justification,
+            ))
+
+        self.db.commit()
+        self.db.refresh(record)
+
+        return result.model_copy(update={
+            "id": record.id,
+            "analysed_at": record.created_at.replace(tzinfo=UTC).isoformat()
+                if record.created_at
+                else datetime.now(UTC).isoformat(),
+        })
+
+    def get(self, classification_id: str) -> ClassificationRecord | None:
+        return self.db.get(ClassificationRecord, classification_id)

backend/app/services/vep.py

@@ -0,0 +1,122 @@
+"""Ensembl VEP REST client — enriches HGVS-coding input with genomic coords.
+
+Mutalyzer v3 normalizes the c./p. forms but returns nothing for chr/pos/ref/alt.
+Without those fields, REVEL/AlphaMissense/gnomAD all silently no-op, leaving
+the rule engine blind to common pathogenicity signals (PP3/BP4/PM2 from AF).
+
+VEP's REST API solves this for free (no key, ~3 req/s polite-use cap).
+For each HGVS coding string, it returns:
+  - chrom, position, allele_string (ref/alt for SNVs)
+  - most_severe_consequence (Sequence Ontology term)
+  - per-transcript hgvsc, hgvsp, gene_symbol, transcript_id
+
+We treat VEP as best-effort — if it fails we still have whatever Mutalyzer
+already populated, and the pipeline continues.
+"""
+from __future__ import annotations
+
+import logging
+
+import httpx
+from tenacity import retry, retry_if_exception_type, stop_after_attempt, wait_exponential
+
+from backend.app.schemas.variant import NormalizedVariant
+
+logger = logging.getLogger(__name__)
+
+VEP_BASE = "https://rest.ensembl.org"
+
+
+class VEPClient:
+    def __init__(self, base_url: str | None = None, timeout: float = 15.0) -> None:
+        self.base_url = base_url or VEP_BASE
+        self.timeout = timeout
+
+    @retry(
+        stop=stop_after_attempt(3),
+        wait=wait_exponential(min=1, max=8),
+        retry=retry_if_exception_type((httpx.HTTPStatusError, httpx.TimeoutException)),
+        reraise=True,
+    )
+    async def annotate_hgvs(self, hgvs: str) -> dict | None:
+        async with httpx.AsyncClient(timeout=self.timeout) as client:
+            r = await client.get(
+                f"{self.base_url}/vep/human/hgvs/{hgvs}",
+                headers={"Accept": "application/json"},
+            )
+            if r.status_code == 400:
+                # VEP can't parse some normalized forms (e.g. complex indels) — give up gracefully
+                logger.debug("VEP rejected %s: %s", hgvs, r.text[:200])
+                return None
+            r.raise_for_status()
+            data = r.json()
+            return data[0] if isinstance(data, list) and data else None
+
+    @staticmethod
+    def _split_alleles(allele_string: str | None) -> tuple[str | None, str | None]:
+        """Split VEP's `allele_string` into (ref, alt).
+
+        Format examples:
+          'G/A'      → ('G', 'A')   — SNV
+          'TC/T'     → ('TC', 'T')  — deletion
+          'T/TC'     → ('T', 'TC')  — insertion
+          '-/C'      → ('', 'C')    — pure insertion (rare)
+          'C/-'      → ('C', '')    — pure deletion (rare)
+          'AT/CG'    → ('AT', 'CG') — MNV
+        """
+        if not allele_string or "/" not in allele_string:
+            return None, None
+        ref, alt = allele_string.split("/", 1)
+        ref = "" if ref == "-" else ref
+        alt = "" if alt == "-" else alt
+        return ref, alt
+
+    async def enrich(self, normalized: NormalizedVariant) -> NormalizedVariant:
+        """Enrich a NormalizedVariant with chrom/pos/ref/alt + transcript info.
+
+        Only mutates fields that are currently empty — never overrides values
+        Mutalyzer or the VCF parser already filled in.
+        """
+        # Choose the best HGVS string to send to VEP
+        hgvs = normalized.hgvs_coding or normalized.hgvs_genomic or normalized.raw_input
+        if not hgvs:
+            return normalized
+        try:
+            data = await self.annotate_hgvs(hgvs)
+        except (httpx.HTTPError, httpx.TimeoutException) as e:
+            logger.warning("VEP annotation failed for %s: %s", hgvs, e)
+            return normalized
+        if not data:
+            return normalized
+
+        updates: dict = {}
+        if normalized.chromosome is None and data.get("seq_region_name"):
+            updates["chromosome"] = str(data["seq_region_name"])
+        if normalized.position is None and data.get("start"):
+            updates["position"] = int(data["start"])
+
+        ref, alt = self._split_alleles(data.get("allele_string"))
+        if normalized.ref is None and ref is not None:
+            updates["ref"] = ref
+        if normalized.alt is None and alt is not None:
+            updates["alt"] = alt
+
+        if normalized.consequence is None and data.get("most_severe_consequence"):
+            updates["consequence"] = data["most_severe_consequence"]
+
+        # Pick the canonical transcript if available, else the first
+        transcripts = data.get("transcript_consequences") or []
+        if transcripts:
+            canonical = next((t for t in transcripts if t.get("canonical")), transcripts[0])
+            if normalized.gene_symbol is None and canonical.get("gene_symbol"):
+                updates["gene_symbol"] = canonical["gene_symbol"]
+            if normalized.transcript is None and canonical.get("transcript_id"):
+                updates["transcript"] = canonical["transcript_id"]
+            if normalized.hgvs_protein is None and canonical.get("hgvsp"):
+                updates["hgvs_protein"] = canonical["hgvsp"]
+
+        if not updates:
+            return normalized
+        warnings = list(normalized.warnings)
+        warnings.append(f"VEP enriched: {', '.join(updates.keys())}")
+        return normalized.model_copy(update={**updates, "warnings": warnings})

backend/app/worker.py

@@ -0,0 +1,20 @@
+from celery import Celery
+
+from backend.app.config import get_settings
+
+settings = get_settings()
+
+celery_app = Celery(
+    "variantlens",
+    broker=settings.celery_broker_url,
+    backend=settings.celery_result_backend,
+)
+
+celery_app.conf.update(
+    task_serializer="json",
+    result_serializer="json",
+    accept_content=["json"],
+    timezone="UTC",
+    enable_utc=True,
+    task_track_started=True,
+)