README.md

metadata

title: Variant Risk Explainer
emoji: 🧬
colorFrom: blue
colorTo: indigo
sdk: docker
app_port: 7860
pinned: false

Variant Risk Explainer

Variant Risk Explainer is a full-stack AI-powered genomic variant analysis system. It uses a fine-tuned DNABERT-2 model to estimate whether a submitted DNA sequence looks more similar to benign/likely benign or pathogenic/likely pathogenic ClinVar examples.

This project is for AI/ML research and education only. It is not a medical device, not a diagnostic system, and must not be used for clinical decisions.

Project Overview

• training/: ClinVar GRCh38 data preparation, DNABERT-2 training notebooks, local evaluation scripts.
• backend/: FastAPI inference API with DNABERT-2 prediction and explanation services.
• frontend/: Next.js analysis interface with input form, service status, result card, explanation, and history.
• docs/: Architecture notes, API contract, model card, demo examples, limitations, and testing checklist.

Architecture

User
  ↓
Next.js Frontend
  ↓
FastAPI Backend
  ↓
DNABERT-2 Prediction Service
  ↓
Explanation Layer
  ↓
AI-Assisted Result

The frontend sends a DNA sequence to POST /api/analyze in the combined deployment. The backend cleans and crops the sequence, runs the DNABERT-2 classifier, applies the tuned threshold, then returns probabilities, a research-only label, and a cautious explanation.

Model Training Summary

• Base model: DNABERT-2
• Dataset: 20k ClinVar alternate-sequence dataset
• Genome build: GRCh38
• Task: binary research classification
• Label 0: Benign / Likely benign
• Label 1: Pathogenic / Likely pathogenic
• Decision threshold: 0.16

Final Metrics

Metric	Value
Accuracy	0.5537
Precision	0.5384
Recall	0.7533
F1	0.6280
MCC	0.1171
AUC ROC	0.5928

These metrics are limited and support educational and research-oriented analysis only, not clinical interpretation.

Run Backend

cd backend
python -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip
pip install -r requirements.txt
cp .env.example .env
uvicorn app.main:app --reload

Open http://localhost:8000/docs.

Run Frontend

cd frontend
npm install
cp .env.example .env.local
npm run dev

Open http://localhost:3000.

Environment Variables

Backend values live in backend/.env:

MODEL_DIR=../training/training_model_files
MODEL_THRESHOLD=0.16
MODEL_MAX_LENGTH=512
MODEL_NAME=DNABERT-2 ClinVar 20k
DEVICE=auto
OPENAI_API_KEY=your_openai_api_key_here
USE_AI_EXPLANATION=true

Frontend values live in frontend/.env.local:

NEXT_PUBLIC_API_URL=http://127.0.0.1:8000

Leave NEXT_PUBLIC_API_URL empty when the frontend and backend are served from the same origin.

Never commit .env, .env.local, API keys, datasets, or model weights.

Hugging Face Spaces

This repository includes a Docker deployment that:

1. builds the Next.js application as a static export
2. copies the export into FastAPI
3. serves the UI and API from port 7860
4. loads the model from either models/final_model/ or a Hugging Face model repository

See docs/HUGGINGFACE_DEPLOYMENT.md for Space variables, secrets, model upload choices, local Docker testing, and push instructions.

Data and Model Artifact Policy

Large files are intentionally ignored by Git:

• trained model folders such as training/training_model_files/
• generated datasets such as training/csv_files_20k_alt/
• model weight files such as .safetensors, .bin, .pt, and .ckpt
• local environment files such as .env and .env.local

Use local storage, Google Drive, or another private artifact store for trained models and datasets.

Responsible Use

Predictions and explanations are experimental model outputs. They can be wrong, incomplete, biased by ClinVar labels, or invalid outside the training distribution. This project is intended for educational and research-oriented AI/ML analysis and must not be used for diagnosis, treatment, or medical decision-making.