Sydney — Systematic Yielding of Disease-associated Genomic Evidence and DiscoverY

AI-Powered Biomedical Variant Intelligence Platform

Sydney is a lightweight web application that helps researchers, students, and clinicians understand genetic variants by aggregating evidence from ClinVar, PubMed, and biomedical literature. It generates structured reports with confidence scoring, AI summaries, and research gap analysis — without hallucinating results.

Supported genes (14): BRCA1, BRCA2, TP53, CDH1, PALB2, CHEK2, ATM, PTEN, EGFR, KRAS, ALK, BRAF, MLH1, MSH2 — covering breast, ovarian, gastric, lung, colorectal, and related hereditary cancer syndromes.

Why I Built This

Genetic variant interpretation is one of the most consequential tasks in modern medicine — a single classification of "Pathogenic" or "Uncertain significance" can change a patient's surgical decisions, screening schedule, and family planning. Yet the evidence behind these classifications is scattered across ClinVar, PubMed, and dozens of specialist databases, with no single tool that aggregates, scores, and explains it in one place.

I built Sydney to solve that aggregation problem — and to learn how to build a production-grade full-stack application along the way. It gave me hands-on experience with:

Integrating real biomedical APIs (NCBI E-utilities, gnomAD GraphQL) that have quirks, rate limits, and undocumented edge cases (non-breaking spaces in XML, deprecated rettype formats)
Designing a transparent, explainable scoring system where every number can be traced back to a source — no black boxes
Building AI features responsibly: hallucination prevention, evidence-grounded prompts, and graceful degradation when the API is unavailable
Writing tests and benchmarks for a data pipeline where "correct" depends on live external data

The name Sydney is a backronym: Systematic Yielding of Disease-associated Genomic Evidence and DiscoverY.

Architecture Overview

┌───────────────────────────────────────────────────────────────────┐
│                        Browser                                    │
│  ┌─────────────────────────────────────────────────────────────┐  │
│  │  Next.js 15 App Router                                      │  │
│  │  • React 19 + TypeScript                                    │  │
│  │  • Tailwind CSS + Dark Mode                                 │  │
│  │  • React Query (caching, refetch)                           │  │
│  │  • Recharts (evidence charts)                               │  │
│  │  • SVG graph (knowledge relationships)                      │  │
│  └──────────────────────┬──────────────────────────────────────┘  │
└─────────────────────────┼─────────────────────────────────────────┘
                          │ HTTP (localhost:3000 → localhost:8000)
                          ▼
┌───────────────────────────────────────────────────────────────────────┐
│  FastAPI Backend                                                      │
│                                                                       │
│  ┌──────────────┐    ┌──────────────┐    ┌────────────────────┐       │
│  │ API Routes   │───▶│ Services     │───▶│ Database           │       │
│  │ (routes.py)  │    │ (10 services)│    │ (SQLAlchemy/SQLite)│       │
│  └──────┬───────┘    └──────┬───────┘    └────────────────────┘       │
│         │                   │                                         │
│         │                   ├── ClinVar Service ──▶ NCBI E-utilities  │
│         │                   ├── PubMed Service  ──▶ NCBI E-utilities  │
│         │                   ├── AI Summary      ──▶ Groq API          │
│         │                   ├── gnomAD Service  ──▶ Broad gnomAD v4   │
│         │                   └── PDF Generator   ──▶ ReportLab         │
│         ▼                                                             │
│  OpenAPI: /docs                                                       │
└───────────────────────────────────────────────────────────────────────┘

Component Responsibilities

Layer	Technology	Role
Frontend	Next.js 15, TypeScript, Tailwind, React Query	Search UI, evidence dashboard, knowledge graph, PDF download
Backend API	FastAPI, Pydantic	REST endpoints, input validation, OpenAPI docs
Business Logic	Python services	Variant parsing, evidence scoring, confidence calculation
Database	SQLite (dev) / PostgreSQL (prod), SQLAlchemy	Variants, papers, evidence, reports
External APIs	NCBI E-utilities, Groq	ClinVar queries, PubMed search, AI summary generation

Data Pipeline (End to End)

When a user searches for a variant (e.g., TP53 R175H), the following pipeline executes:

Step 1: Input Validation (VariantAnalysisService.parse_variant)

User Input: "TP53 R175H"
  ↓
Regex matching against 14 supported genes and 6 notation patterns:
  • c. notation:   BRCA1 c.5266dupC, CDH1 c.1901C>T
  • p. notation:   TP53 p.R175H
  • 1-letter code: TP53 R175H
  • 3-letter code: TP53 Arg175His
  • Legacy:        BRCA1 185delAG
  • Alias:         P53 R175H → TP53
  ↓
If no match → 400 error with helpful message
If match → { gene: "TP53", change: "R175H" }

Step 2: Gene Resolution

Gene symbol "TP53", "BRCA1", "BRCA2", "CDH1", "PALB2", "CHEK2", "ATM", "PTEN", "EGFR", "KRAS", "ALK", "BRAF", "MLH1", "MSH2" (or alias P53 → TP53)
  ↓
Query genes table → if not found, create with metadata:
  • symbol, full_name, chromosome, description

Step 3: Variant Lookup/Creation

gene + change
  ↓
Query variants table by HGVS c. or protein change
  ↓
If not found → Create variant record:
  • gene_id, hgvs_c, protein_change, variant_type

Step 4: ClinVar Retrieval (ClinVarService)

gene + variant
  ↓
1. Check local disk cache (data/cache/clinvar/)
   ↓ if cache miss:
2. ESearch: NCBI E-utilities → get ClinVar ID
   • Query: "TP53[gene] AND R175H[variant] OR R175H[All Fields]"
   • Fallback: "TP53 R175H"
3. EFetch: rettype=vcv, retmode=xml
   • VCV accession (zero-padded to 9 digits): VCV000012374
4. Parse VCV XML for:
   • <GermlineClassification> → <Description> → "Pathogenic"
   • <ReviewStatus> → "reviewed by expert panel"
   • <VariationArchive VariationName="...">
   • <TraitSet> → disease names
5. Cache result as JSON
   ↓
Update variant record:
  • clinical_significance, clinvar_id, review_status, clinvar_data

Step 5: gnomAD Population Frequency (GnomadService)

gene + variant + clinvar_data (genomic coordinates)
  ↓
1. Check local disk cache (data/cache/gnomad/)
   ↓ if cache miss:
2. Extract genomic coordinates from ClinVar response
   • { chr: "17", pos: 7675094, ref: "G", alt: "A" }
3. Build gnomAD v4 variant ID: "17-7675094-G-A"
4. Query gnomAD GraphQL API: https://gnomad.broadinstitute.org/api
   • Returns: allele_frequency, allele_count, allele_number,
     homozygote_count, population_frequencies (by ancestry)
5. Store in variant record:
   • variant.gnomad_af = allele_frequency
   • variant.gnomad_data = full API response
6. Cache result as JSON
   ↓
If variant not found in gnomAD → graceful None (no error)

Step 6: PubMed Retrieval (PubMedService)

gene + variant + disease (mapped per gene — see table below)
  ↓
1. Check local disk cache (data/cache/pubmed/)
   ↓ if cache miss:
2. ESearch example: "(TP53[Title/Abstract]) AND (R175H[Text Word]) AND (cancer[MeSH])"
   • Disease term is gene-specific: BRCA1→"breast cancer", EGFR→"lung cancer", etc.
   • Limit: 20 results, sorted by relevance
3. EFetch: Get XML with titles, authors, abstracts
4. Infer study type via batched Groq call (all papers in one prompt):
   • Sends title + abstract for each paper, requests JSON array of study types
   • On success: classifies each paper accordingly
   • On failure (Groq unavailable, JSON parse error, array length mismatch):
     → Falls back entire batch to keyword-based matching (see table below)
5. Cache results as JSON
   ↓
For each paper (all 14 genes share the same pipeline — no gene-specific logic needed beyond the symbol):
  • Create Paper record (pmid, title, authors, journal, year, abstract, study_type)
  • Create Evidence record (variant_id, paper_id, evidence_type="literature")

Step 7: Evidence Scoring (EvidenceScoringService)

For each evidence item:
  ↓
relevance = keyword overlap between paper and variant (0.5 - 1.0)
study_quality = STUDY_QUALITY_MAP[paper.study_type]
  • Meta-Analysis: 0.95
  • Clinical Trial: 0.90
  • Cohort Study:   0.75
  • Case Report:    0.35
recency = max(0, 1.0 - (current_year - paper_year) * 0.05)
  ↓
evidence_score = (0.50 × relevance) + (0.30 × study_quality) + (0.20 × recency)
  ↓
Score range: 0.0 - 1.0 (displayed as 0-100)

Step 8: Confidence Calculation (ConfidenceEngine)

All evidence items for variant
  ↓
evidence_volume = count of papers
  • 0 papers → 0.0
  • 1-2 papers → 0.2
  • 3-4 papers → 0.4
  • 5-9 papers → 0.6
  • 10-19 papers → 0.8
  • 20+ papers → 1.0
  ↓
evidence_quality = average study_quality_score across all papers
  ↓
study_agreement = consistency of clinical_significance across papers
  ↓
confidence_score = (0.20 × volume) + (0.40 × quality) + (0.30 × agreement) + (0.10 × clinvar_review_strength)
  ↓
Level mapping:
  score >= 0.70 → High
  score >= 0.40 → Moderate
  score < 0.40 → Low
  score == 0   → Insufficient Evidence

Step 9: Report Generation

variant + evidence + confidence
  ↓
Create Report record with all scores and metadata
  ↓
PDF generation (on demand):
  • ReportLab → professional scientific PDF
  • Sections: Executive Summary, Clinical Significance,
    Evidence Overview, Supporting Studies, Disease Associations,
    Confidence Assessment

Step 10: AI Summary (optional, requires Groq API key)

variant + evidence + confidence
  ↓
Build context string with all paper titles, PMIDs, scores, findings
  ↓
Groq API call: Llama 3.3 70B
  • System prompt: evidence-based, no hallucinations, cite PMIDs
  • Temperature: 0.3 (low creativity, high accuracy)
  • Generates sections: Executive Summary, Clinical Significance,
    Disease Associations, Mechanism of Action, Evidence Overview,
    Confidence Assessment

Step 11: Research Gap Detection (ResearchGapDetector)

Analyze evidence distribution
  ↓
Rule-based checks:
  • No clinical trials found?
  • No functional studies?
  • Fewer than 3 high-quality papers?
  • Total papers < 5?
  • Predominantly case reports?
  • No recent studies (post-2020)?
  ↓
Generate gap list + summary
  ↓
Optional AI analysis of research directions

Database Schema

Entity Relationship

┌───────────────┐       ┌──────────────────┐       ┌──────────────────┐
│     genes     │       │    variants      │       │    evidence      │
├───────────────┤       ├──────────────────┤       ├──────────────────┤
│ id (PK)       │──1:N──│ id (PK)          │──1:N──│ id (PK)          │
│ symbol (UQ)   │       │ gene_id (FK)     │       │ variant_id (FK)  │
│ full_name     │       │ hgvs_c (idx)     │       │ paper_id (FK)    │
│ chromosome    │       │ hgvs_p (idx)     │       │ evidence_type    │
│ description   │       │ protein_change   │       │ relevance_score  │
│ created_at    │       │ variant_type     │       │ study_quality    │
└───────────────┘       │ description      │       │ recency_score    │
        │               │ clin_sig         │       │ evidence_score   │
        │               │ clinvar_id       │       │ key_findings     │
        │               │ clinvar_data(J)  │       │ source           │
        │               │ review_status    │       │ created_at       │
        │               │ created_at       │       └────────┬─────────┘
        │               │ updated_at       │                │
        │               └────────┬─────────┘                │
        │                        │                          │
        │        ┌───────────────┴─────────┐       ┌────────┴─────────┐
        │        │            reports      │       │     papers       │
        │        ├─────────────────────────┤       ├──────────────────┤
        │        │ id (PK)                 │       │ id (PK)          │
        │        │ variant_id (FK)         │       │ pmid (UQ, idx)   │
        │        │ confidence_level        │       │ title            │
        │        │ confidence_score        │       │ authors          │
        │        │ evidence_volume         │       │ journal          │
        │        │ evidence_quality        │       │ year             │
        │        │ study_agreement         │       │ abstract         │
        │        │ exec_summary            │       │ doi              │
        │        │ clin_sig                │       │ study_type       │
        │        │ disease_assoc(J)        │       │ keywords (JSON)  │
        │        │ mechanism               │       │ created_at       │
        │        │ evidence_overview       │       └──────────────────┘
        │        │ confidence_assess       │
        │        │ clinvar_review_strength │
        │        │        research_gaps(J) │
        │        │ ai_summary              │
        │        │ report_data (J)         │
        │        │ created_at              │
        │        └─────────────────────────┘
        │
        ├─── gene_papers (M:N join) ─── papers
        │
        └─── disease_papers (M:N join) ─── papers

  ┌───────────────┐
  │   diseases    │
  ├───────────────┤
  │ id (PK)       │
  │ name (idx)    │
  │ mondo_id      │
  │ description   │
  │ created_at    │
  └───────────────┘
  (J) = JSON column
  (FK) = Foreign Key
  (PK) = Primary Key
  (UQ) = Unique
  (idx) = Indexed

Features

1. Variant Search (Feature 1)

The search interface accepts multiple variant notation formats:

Format	Example	Pattern
HGVS coding	`BRCA1 c.5266dupC`	`gene + c.` prefix + position + change
HGVS protein	`TP53 p.R175H`	`gene + p.` prefix + amino acid change
1-letter protein	`TP53 R175H`	`gene + [A-Z]\d+[A-Z*]`
3-letter protein	`TP53 Arg175His`	`gene + [A-Z][a-z]{2}\d+[A-Za-z*]`
Legacy	`BRCA1 185delAG`	`gene + \d+del[A-Z]+`
Alias	`P53 R175H`	Auto-normalized to TP53

Invalid inputs return a 400 error with a helpful message: "Could not parse variant. Use format like: BRCA1 c.5266dupC, TP53 R175H, BRCA2 c.5946delT, CDH1 c.1901C>T, PALB2 c.1592delT"

Recent searches are stored in localStorage (client-side only) and displayed as clickable badges.

2. ClinVar Integration (Feature 3)

Endpoint: NCBI E-utilities (https://eutils.ncbi.nlm.nih.gov/entrez/eutils/)

Flow:

esearch.fcgi — Search for ClinVar records using gene[variant] query
efetch.fcgi?rettype=vcv — Fetch VCV XML (the modern ClinVar format, not the deprecated rettype=variation)
Parse XML for clinical significance, review status, disease names

VCV Accession Format:

Numeric IDs from esearch are zero-padded to 9 digits
Example: ID 12374 → VCV000012374
This is required by NCBI's API

Caching:

JSON responses cached to data/cache/clinvar/
TTL: 24 hours (configurable via CACHE_TTL_HOURS)
Cache key: {gene}_{variant} with special characters sanitized

Parsed Fields:

XML Path	Field	Example
`VariationArchive/@VariationName`	description	`NM_000546.6(TP53):c.524G>A (p.Arg175His)`
`VariationArchive/@Accession`	accession	`VCV000012374`
`GermlineClassification/Description`	clinical_significance	`Pathogenic`
`GermlineClassification/ReviewStatus`	review_status	`reviewed by expert panel`
`OncogenicityClassification/Description`	clinical_significance (fallback)	`Oncogenic`
`TraitSet/Trait/Name`	diseases (if non-empty)	`Li-Fraumeni syndrome`

3. PubMed Retrieval (Feature 4)

Endpoint: NCBI E-utilities

Search Query Construction:

(gene[Title/Abstract]) AND (variant[Text Word]) AND (disease[MeSH])

Disease term is mapped per gene: BRCA1/BRCA2/PALB2 → breast cancer, CDH1 → gastric cancer, EGFR/ALK → lung cancer, KRAS → pancreatic cancer, BRAF → melanoma, PTEN → Cowden syndrome, MLH1/MSH2 → colorectal cancer, others → cancer.

Result Limit: 20 papers (configurable via MAX_PUBMED_RESULTS)

Parsed Fields:

XML Path	Field
`PMID`	pmid
`ArticleTitle`	title
`Author/LastName` + `ForeName`	authors (first 10)
`Journal/Title`	journal
`PubDate/Year`	year
`AbstractText`	abstract (with Label attributes)
`ELocationId[@EIdType="doi"]`	doi
`Keyword`	keywords array

Study Type Inference: Papers are classified in a single batched Groq call (Llama 3.3 70B, temperature 0.1). The prompt sends each paper's title and abstract, requesting a JSON array of study types. If Groq is unavailable, the response is not valid JSON, or the array length doesn't match the paper count, the entire batch falls back to keyword-based matching:

Fallback Keyword Mapping:

Keywords in Abstract	Study Type	Quality Score
"clinical trial", "randomized", "phase I/II/III"	Clinical Trial	0.90
"meta-analysis", "systematic review"	Meta-Analysis	0.95
"case report", "case study"	Case Report	0.35
"cohort", "case-control", "longitudinal"	Cohort Study	0.75
"review", "overview"	Review	0.50
"in vitro", "cell line", "functional study"	Functional Study	0.70
"genome-wide", "gwas", "association study"	Genome-Wide Study	0.80
None of the above	Research Article	0.50

Caching: Same scheme as ClinVar, stored in data/cache/pubmed/ with 24-hour TTL.

4. gnomAD v4 Population Frequency (Feature 5)

Endpoint: Broad Institute gnomAD GraphQL API (https://gnomad.broadinstitute.org/api)

Flow:

After ClinVar retrieves variant data, genomic coordinates are extracted from the ClinVar response
Coordinates formatted as {chr}-{pos}-{ref}-{alt} gnomAD variant ID
GraphQL query requests genome & exome AF (computed from ac/an), AC, AN, homozygote_count, and per-population breakdowns
Genome AF preferred; exome AF used as fallback

GraphQL Query:

query VariantFrequency($datasetId: DatasetId!, $variantId: String!) {
  variant(variantId: $variantId, dataset: $datasetId) {
    variant_id
    genome {
      af ac an homozygote_count
      populations { id af ac an }
    }
    exome {
      af ac an homozygote_count
      populations { id af ac an }
    }
  }
}

Dataset: gnomad_r4

Database Fields:

Column	Type	Description
`gnomad_af`	FLOAT	Global allele frequency (genome or exome)
`gnomad_data`	JSON	Full API response including per-population breakdown

Color Coding (Frontend):

AF Range	Color	Badge Label
< 0.0001	Red	Rare
0.0001–0.001	Amber	Low
> 0.001	Green	Common
Not found	Grey outline	Absent from gnomAD

Caching: Same scheme as ClinVar, stored in data/cache/gnomad/ with 24-hour TTL. Cache key: {gene}_{variant}.

API Endpoint: GET /api/v1/variants/{id}/gnomad — returns full population breakdown by ancestry group.

Configuration: No additional environment variables required. Uses the existing ClinVar data pipeline for coordinate extraction.

5. Evidence Scoring Engine (Feature 6)

Formula:

EvidenceScore = 0.50 × relevance + 0.30 × study_quality + 0.20 × recency

Components:

Component	Weight	Calculation
Relevance	50%	Keyword overlap between paper keywords and variant key findings. Baseline: 0.5, bonus: up to +0.5 for keyword matches. Range: 0.5–1.0
Study Quality	30%	Mapped from study type (0.35 for Case Report up to 0.95 for Meta-Analysis)
Recency	20%	`max(0, 1.0 - (current_year - paper_year) × 0.05)`. A paper from 2026 scores 1.0, from 2020 scores 0.7, from 2010 scores 0.2

Score Display: Scores are multiplied by 100 for the UI (0–100 scale).

6. Confidence Engine (Feature 10)

Formula:

ConfidenceScore = (0.20 × volume_score) + (0.40 × quality_score) + (0.30 × agreement_score) + (0.10 × clinvar_review_strength)

Components:

Component	Weight	Calculation
Evidence Volume	20%	Logarithmic scale based on paper count: 0 papers = 0.0, 1-2 = 0.2, 3-4 = 0.4, 5-9 = 0.6, 10-19 = 0.8, 20+ = 1.0
Evidence Quality	40%	Average `study_quality_score` across all papers (0.0–1.0)
Study Agreement	30%	Proportion of papers with the same clinical significance classification (0.0–1.0)
ClinVar Review Strength	10%	Maps `review_status` to a score: expert panel = 1.0, multi-submitter = 0.9, single submitter = 0.7, conflicting = 0.5, no assertion criteria = 0.3, no assertion = 0.0

Levels:

Score Range	Level	Meaning
0.70–1.00	High	Well-characterized variant with strong, consistent evidence
0.40–0.69	Moderate	Some evidence available, but gaps remain
0.01–0.39	Low	Limited evidence, further studies needed
0.00	Insufficient Evidence	No supporting papers found; no hallucination

7. AI Research Summary (Feature 9)

Provider: Groq API with Llama 3.3 70B (requires GROQ_API_KEY)

Generation: Triggered via /api/v1/variants/{id}/summary

Prompt Engineering:

System prompt instructs the model to be evidence-based and cite specific PMIDs
Context includes all paper titles, PMIDs, years, study types, evidence scores, and key findings
Temperature set to 0.3 (minimal creativity, prioritizes accuracy)

Output Sections:

Executive Summary
Clinical Significance
Disease Associations
Mechanism of Action
Evidence Overview
Confidence Assessment

Hallucination Prevention:

Model explicitly instructed: "Only use the provided evidence. Do not hallucinate."
No retrieved evidence → model returns "No evidence available for this variant"
All claims should reference supporting PMIDs

8. Knowledge Relationships View (Feature 8)

Implementation: Custom SVG-based graph visualization (no external graph library dependency)

Entity Types (color-coded):

Type	Color	Description
Gene	Blue (#3b82f6)	BRCA1, BRCA2, TP53, CDH1, PALB2, CHEK2, ATM, PTEN, EGFR, KRAS, ALK, BRAF, MLH1, MSH2
Variant	Purple (#8b5cf6)	The specific mutation
Paper	Green (#059669)	PubMed articles
Disease	Amber (#d97706)	Associated conditions

Relationships: has variant, evidence, associated with

Layout: Force-directed layout with gene at top, variant in center, papers and diseases arranged radially.

Data Source: /api/v1/graph/{variant_id} endpoint constructs nodes and edges from the database.

9. Research Gap Detection (Feature 11)

Rule-Based Analysis (ResearchGapDetector.analyze_gaps):

Check	Condition	Gap Message
Clinical trials	Count == 0	"No clinical trials found for this variant"
Functional studies	Count == 0	"Functional characterization studies are limited"
High-quality studies	Count < 3	"Only N high-quality studies available (need 3+)"
Total evidence	Count < 5	"Limited evidence volume (N papers)"
Case report dominance	Case reports > 50% of total	"Evidence is predominantly case reports; larger cohort studies needed"
Recent publications	Post-2020 papers < 2	"Recent studies (post-2020) are lacking"
All checks pass	None triggered	"Relatively well-studied; further meta-analyses could strengthen evidence"

Output: Gap list + well-studied boolean + summary text + study type distribution.

10. PDF Report Export (Feature 12)

Library: ReportLab

Sections:

Variant Header — Gene, HGVS notation, clinical significance, confidence level
Executive Summary — AI-generated or evidence overview
Clinical Significance — ClinVar data with review status
gnomAD Frequency — Population allele frequency with 1-in-N formatting (or "Absent from gnomAD")
Evidence Overview — Volume, quality, agreement scores
Supporting Studies — Top 10 papers with titles, PMIDs, years, scores
Disease Associations — Disease names from ClinVar
Confidence Assessment — Level + score + detailed breakdown

Generation: Synchronous, returns PDF as download (~4KB for average reports).

API Reference

Base URL

http://localhost:8000/api/v1

Endpoints

Method	Path	Description	Auth
`GET`	`/health`	Health check	None
`GET`	`/dashboard`	Platform statistics	None
`POST`	`/variants/search`	Search and analyze a variant	None
`GET`	`/variants`	List all variants	None
`GET`	`/variants/{id}`	Variant detail with evidence	None
`GET`	`/variants/{id}/evidence`	Evidence list with scores	None
`GET`	`/variants/{id}/report`	Confidence report	None
`POST`	`/variants/{id}/summary`	Generate AI summary (Groq)	None
`GET`	`/variants/{id}/gaps`	Research gap analysis	None
`GET`	`/variants/{id}/evidence-provenance`	Per-paper score contribution breakdown	None
`GET`	`/variants/{id}/acmg`	ACMG-inferred variant classification	None
`GET`	`/variants/{id}/classification-timeline`	Historical ClinVar classification changes	None
`GET`	`/variants/{id}/gnomad`	gnomAD v4 allele frequency by ancestry	None
`GET`	`/variants/{id}/report/pdf`	Download PDF report	None
`GET`	`/graph/{id}`	Knowledge graph data	None
`POST`	`/compare`	Compare two variants side by side	None
`DELETE`	`/variants/{id}`	Delete variant and its cache files	None

Request/Response Examples

POST /variants/search

// Request
{ "query": "TP53 R175H" }

// Response (200)
{
  "id": 1,
  "hgvs_c": null,
  "hgvs_p": null,
  "protein_change": "R175H",
  "gene": "TP53",
  "gene_full_name": "Tumor Protein P53",
  "variant_type": "snv",
  "clinical_significance": "Pathogenic",
  "clinvar_id": "12374",
  "review_status": "reviewed by expert panel",
  "diseases": ["Li-Fraumeni syndrome"]
}

// Response (400 - invalid)
{
  "detail": "Could not parse variant. Use format like: BRCA1 c.5266dupC, TP53 R175H, BRCA2 c.5946delT, CDH1 c.1901C>T, PALB2 c.1592delT"
}

// Response (400 - unsupported gene)
{
  "detail": "Could not parse variant. Use format like: BRCA1 c.5266dupC, TP53 R175H, BRCA2 c.5946delT, CDH1 c.1901C>T, PALB2 c.1592delT"
}

GET /variants/{id}/report

{
  "id": 1,
  "variant_id": 1,
  "confidence_level": "High",
  "confidence_score": 0.76,
  "evidence_volume": 18,
  "evidence_quality": 0.55,
  "study_agreement": 0.89,
  "executive_summary": "TP53 R175H is a well-characterized pathogenic variant...",
  "clinical_significance": "Pathogenic",
  "disease_associations": [{"name": "Li-Fraumeni syndrome"}],
  "evidence_overview": "Found 18 supporting papers. Average evidence score: 0.55...",
  "confidence_assessment": "Based on 18 supporting papers; evidence volume score: 0.80...",
  "research_gaps": [],
  "ai_summary": "## Executive Summary\nThe TP53 R175H mutation...",
  "created_at": "2026-06-16T12:00:00"
}

Full OpenAPI documentation at http://localhost:8000/docs (Swagger UI) or http://localhost:8000/redoc (ReDoc).

Services Deep Dive

`VariantAnalysisService`

The orchestrator — coordinates all other services for a single variant analysis.

Key Methods:

parse_variant(query) → Parses user input using regex patterns
get_or_create_gene(symbol) → Returns existing gene or creates with metadata
analyze_variant(query) → Full pipeline: parse → gene → variant → ClinVar → PubMed → evidence
get_variant_detail(variant_id) → Returns variant + gene + evidence with scores

Regex Patterns (in priority order):

r"^(GENE)\s+(c\.\d+[A-Za-z_>delinsup*]{1,30})$"     # HGVS c.
r"^(GENE)\s+(p\.[A-Za-z]{1,3}\d+[A-Za-z*]{1,5})$"   # HGVS p.
r"^(GENE)\s+([A-Z][a-z]{2}\d+[A-Za-z*]{1,5})$"      # 3-letter protein
r"^(GENE)\s+([A-Z]\d+[A-Z*]{1,3})$"                 # 1-letter protein
r"^(GENE)\s+(\d+del[A-Z]+)$"                         # Legacy del notation
r"^(GENE)\s+(\d+ins[A-Z]+)$"                         # Legacy ins notation