Spaces:
Running on Zero
Running on Zero
| 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 | |
| [](https://www.python.org/downloads/) | |
| [](https://pytorch.org/) | |
| [](https://opensource.org/licenses/MIT) | |
| [](https://fastapi.tiangolo.com) | |
| [](https://doi.org/10.5281/zenodo.22269466) | |
| [](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). | |