README.md

metadata

title: Genomic Variant Clinical Classifier
emoji: 🧬
colorFrom: purple
colorTo: indigo
sdk: gradio
sdk_version: 5.9.1
app_file: app.py
pinned: false
license: mit
short_description: AI genomic variant ACMG classification system
python_version: '3.10'

🧬 Genomic Variant Clinical Significance Classifier

🔗 Live n8n Workflow

An n8n-powered clinical genomics automation agent that receives VCF files from sequencing labs via webhook, parses variants, queries ClinVar and gnomAD for population and clinical data, applies ACMG/AMP 2015 classification criteria using GPT-4o-mini, and delivers physician and genetic counselor reports within minutes of sequencing completion.

What It Does

The agent triggers on every new VCF submission and automatically:

1. Receives VCF file via webhook — patient metadata, panel type, lab accession, and raw variant data
2. Parses VCF variants — extracts chromosome, position, ref/alt alleles, zygosity, consequence, and allele frequency
3. Queries ClinVar — retrieves existing clinical significance classifications for known variants
4. Queries gnomAD — pulls population allele frequencies from 730,000+ exomes and genomes
5. Applies ACMG criteria — GPT-4o-mini evaluates PVS1, PS1–4, PM1–6, PP1–5, BA1, BS1–4, BP1–7 per variant
6. Routes by pathogenicity — Pathogenic and Likely Pathogenic findings trigger urgent counselor alert
7. Delivers clinical reports — physician report with full interpretation for all classification tiers

n8n Workflow Architecture

flowchart TD
    A[Webhook Trigger\nVCF File from Lab] --> B[Extract Case Data\nPatient + Metadata]
    B --> C[Parse VCF Variants\nCode Node]
    C --> D[Query ClinVar\nNCBI eUtils API]
    D --> E[Query gnomAD\nPopulation Frequencies]
    E --> F[ACMG Variant Classification\nGPT-4o-mini]
    F --> G[Extract Classification Results\nSet Node]
    G --> H{Pathogenic\nFindings?}
    H -->|YES| I[URGENT Alert\nGenetic Counselor - Gmail]
    I --> J[Email Physician\nFull Genomic Report]
    H -->|NO| K[Email Physician\nRoutine Report]

Setup Instructions

1. Clone or fork this Space

git clone https://huggingface.co/spaces/Darkweb007/genomic-classifier-agent
cd genomic-classifier-agent

2. Install dependencies

pip install -r requirements.txt

3. Configure Secrets

In your Hugging Face Space settings, add the following secret:

Secret Name	Description	Required
OPENAI_API_KEY	OpenAI API key for GPT-4o-mini	Yes (for Tab 2)

Navigate to: Space Settings → Variables and Secrets → New Secret

4. Run locally

python app.py

5. Deploy to HF Spaces

Push to your Space repository — it will build and deploy automatically.

n8n Integration

To connect this UI to a real n8n workflow:

1. Open the live n8n workflow linked above
2. Copy the webhook URL from the trigger node
3. Configure your LIMS or sequencing pipeline to POST VCF data to this webhook
4. Set physician and genetic counselor email addresses in the Gmail nodes
5. Add Gmail OAuth2 credentials
6. Activate the workflow — it processes each submission automatically

Supported Systems

System	Action
LIMS / Sequencing Pipeline	VCF submission via webhook POST
ClinVar (NCBI eUtils)	Clinical significance for known variants
gnomAD (Broad Institute)	Population allele frequencies (v4)
Gmail	Urgent counselor alert + physician clinical report
OpenAI GPT-4o-mini	ACMG/AMP criteria application and clinical interpretation

ACMG Classification Tiers

Class	Criteria	Clinical Action
🔴 Pathogenic	PVS1 + strong OR multiple moderate	Immediate genetic counseling + management
🟠 Likely Pathogenic	PVS1 + moderate OR supporting criteria	Genetic counseling + family screening
🟡 VUS	Insufficient evidence	Document, reclassify as evidence emerges
🔵 Likely Benign	Supporting benign criteria	No clinical action required
🟢 Benign	BA1 OR strong benign evidence	Document and close

Disclaimer

This application is for research and demonstration purposes only. Classifications generated by this tool must not be used for clinical decision-making without review by a board-certified clinical molecular geneticist. Always comply with applicable laboratory regulations (CLIA, CAP) and institutional policies.

License

MIT