README.md

---
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](https://aravind5.app.n8n.cloud/workflow/gP95wBIukRTN7rKM)**

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

```mermaid
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

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

### 2. Install dependencies

```bash
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

```bash
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