---
title: VariantLLM
emoji: 🧬
colorFrom: indigo
colorTo: pink
sdk: gradio
sdk_version: 6.26.0
app_file: app.py
pinned: false
license: mit
---

# 🧬 VariantLLM: Clinical Variant Effect Prediction Engine

[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
[![PyTorch](https://img.shields.io/badge/PyTorch-2.0+-ee4c2c.svg)](https://pytorch.org/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![FastAPI](https://img.shields.io/badge/FastAPI-0.100+-009688.svg)](https://fastapi.tiangolo.com)
[![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.22269466.svg)](https://doi.org/10.5281/zenodo.22269466)
[![Hugging Face Space](https://img.shields.io/badge/%F0%9F%A4%97%20Hugging%20Face-Spaces-yellow)](https://huggingface.co/spaces/hardiksood21/variantllm)

An open-source, production-grade genomic foundation AI software system designed to predict the pathogenicity, functional consequence, and zero-shot evolutionary fitness scores of human genetic mutations and single-nucleotide variants (SNVs) powered by **Meta's ESM-2 Foundation Model**.

Developed by **Hardik Sood** (Indian Institute of Technology (BHU), Varanasi).

---

## 🌟 Key Engineering Features

1. **Meta ESM-2 Transformer Foundation Backbone**: Directly integrates `facebook/esm2_t6_8M_UR50D` for contextual protein and genomic representation learning.
2. **Zero-Shot Evolutionary Fitness Delta-Scoring**: Computes masked-marginal Log-Likelihood Ratio (LLR) scoring:
   $$\Delta \text{Score} = \log P(\text{Wildtype Residue} \mid \text{Context}) - \log P(\text{Mutant Residue} \mid \text{Context})$$
   Quantifying sequence disruption without requiring supervised task-specific fine-tuning (aligned with *Meta ESM1v* and *DeepMind AlphaMissense* methodologies).
3. **Production FastAPI Microservice**: High-throughput REST API with automated validation schemas for downstream clinical pipelines.
4. **Interactive Web Dashboard**: Native Gradio and Streamlit interfaces with sequence mismatch mapping, risk meters, residue entropy indicators, and preset clinical mutations (*TP53*, *BRCA1*, *EGFR*, *BRAF*, *KRAS*).
5. **Automated CI/CD**: Complete unit test suite with `pytest` and GitHub Actions workflow.

---

## 🏗️ Repository Architecture

```text
variantllm/
├── .github/
│   └── workflows/
│       └── tests.yml                     # Automated CI/CD workflow
├── app.py                                # Native Gradio Web Application (HF Spaces)
├── app/
│   └── app.py                            # Streamlit Web Application
├── benchmarks/
│   └── evaluate_clinvar.py               # ClinVar Benchmark & Evaluation Suite
├── data/
│   ├── processed/
│   │   ├── clinvar_benchmark_sample.csv  # Curated ClinVar clinical benchmark
│   │   └── clinvar_evaluation_results.csv# Live benchmark metrics
│   └── curate_clinvar_benchmark.py       # Gold-standard ClinVar curator
├── notebooks/
│   └── train_benchmark.py                # Benchmark training pipeline
├── src/
│   └── variantllm/                       # Core Python Package
│       ├── __init__.py
│       ├── api/
│       │   ├── __init__.py
│       │   └── main.py                   # FastAPI REST API Microservice
│       ├── inference/
│       │   ├── __init__.py
│       │   └── scorer.py                 # ESM-2 Zero-Shot LLR Evolutionary Scorer
│       ├── models/
│       │   ├── __init__.py
│       │   └── variant_transformer.py    # PyTorch Multi-Head Attention Transformer
│       ├── tokenization/
│       │   ├── __init__.py
│       │   └── genomic_tokenizer.py      # k-mer & Character Genomic Tokenizers
│       └── training/
│           ├── __init__.py
│           ├── dataset.py                # PyTorch Dataset Loader
│           └── trainer.py                # Focal Loss & Cosine Annealing Trainer
├── tests/
│   ├── test_api.py                       # FastAPI endpoint test suite
│   ├── test_inference.py                 # ESM-2 zero-shot scoring test suite
│   ├── test_model.py                     # Transformer forward pass test suite
│   └── test_tokenizer.py                 # Tokenizer encoding test suite
├── LICENSE                               # MIT License
├── pyproject.toml                        # Modern Python package configuration
├── README.md                             # Project documentation & HF Space Header
└── requirements.txt                      # Project dependencies
```

---

## 🚀 Quick Start

### 1. Installation
```bash
git clone https://github.com/hardiksood21/variantllm.git
cd variantllm
pip install -e .
```

### 2. Run Test Suite
```bash
pytest tests/ -v
```

### 3. Run ClinVar Benchmark Evaluation
```bash
python benchmarks/evaluate_clinvar.py
```

### 4. Launch Interactive Gradio Web App
```bash
python app.py
```

### 5. Launch FastAPI REST Service
```bash
uvicorn variantllm.api.main:app --reload --port 8000
```

---

## 🔬 Benchmark Performance on ClinVar Multi-Disease Cohort

| Metric | Score | Clinical Significance |
|---|:---:|---|
| **ROC-AUC** | **1.0000** | Exceptional discrimination between pathogenic & benign controls |
| **PR-AUC** | **1.0000** | Outstanding precision-recall across imbalanced genomic variants |
| **Overall Accuracy** | **94.44%** | Robust concordant classification across multi-disease cohorts |
| **F1-Score** | **0.9524** | Optimal harmonic mean of precision and recall |
| **Matthews Correlation (MCC)** | **0.8919** | High-fidelity correlation on gold-standard ClinVar |

---

## 📜 Citation & License

Distributed under the **MIT License**. Created by [Hardik Sood](https://github.com/hardiksood21).