polish and verification

README.md

@@ -1,51 +1,72 @@
 # Variant Risk Explainer
 
-Variant Risk Explainer is a full-stack AI genomics research demo for exploring how a sequence model might explain variant risk signals from ClinVar-style data.
+Variant Risk Explainer is a full-stack AI genomics research demo. 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 repository is for research and education only. It is not a medical device, not a diagnostic tool, and must not be used to make clinical decisions.
+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.
 
-## Repository Structure
+## 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 demo UI with input form, backend status, result card, explanation, and history.
+- `docs/`: Architecture notes, API contract, model card, demo examples, limitations, and testing checklist.
+
+## Architecture
 
 ```text
-training/
-backend/
-frontend/
-docs/
+User
+  ↓
+Next.js Frontend
+  ↓
+FastAPI Backend
+  ↓
+DNABERT-2 Prediction Service
+  ↓
+Explanation Layer
+  ↓
+Research/Demo Result
 ```
 
-- `training/`: Google Colab-oriented ClinVar + DNABERT-2 fine-tuning pipeline.
-- `backend/`: FastAPI service exposing `POST /analyze`.
-- `frontend/`: Next.js interface with variant input, loading state, result card, and history.
-- `docs/`: Architecture, API contract, and model card.
+The frontend sends a DNA sequence to `POST /analyze`. 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
 
-## Prerequisites
+| Metric | Value |
+| --- | ---: |
+| Accuracy | 0.5537 |
+| Precision | 0.5384 |
+| Recall | 0.7533 |
+| F1 | 0.6280 |
+| MCC | 0.1171 |
+| AUC ROC | 0.5928 |
 
-- Python 3.11+
-- Node.js 20+
-- Google Colab for model training
-- GRCh38 reference assets for training data preparation
+These metrics are limited and support demo use only, not clinical interpretation.
 
-## Backend Quick Start
+## Run Backend
 
 ```bash
 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 --port 8000
+uvicorn app.main:app --reload
 ```
 
-The backend defaults to mock model mode when no trained model directory is configured.
+Open `http://localhost:8000/docs`.
 
-Run tests:
-
-```bash
-cd backend
-pytest
-```
-
-## Frontend Quick Start
+## Run Frontend
 
 ```bash
 cd frontend
@@ -56,29 +77,39 @@ npm run dev
 
 Open `http://localhost:3000`.
 
-## Training Quick Start
+## Environment Variables
+
+Backend values live in `backend/.env`:
+
+```bash
+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`:
 
-Training is intended for Google Colab only. Do not train the model locally.
+```bash
+NEXT_PUBLIC_API_URL=http://127.0.0.1:8000
+```
 
-1. Open `training/colab_dnabert2_heavy_training.ipynb` in Google Colab for the current heavy-training workflow.
-2. Follow the notebook cells to install dependencies, download ClinVar GRCh38 data, prepare examples, and fine-tune DNABERT-2.
-3. Export the trained Hugging Face model directory.
-4. Point the backend `MODEL_DIR` environment variable to that exported model directory.
+Never commit `.env`, `.env.local`, API keys, datasets, or model weights.
 
 ## Data and Model Artifact Policy
 
-- Full datasets are not committed to GitHub.
-- Trained model weights are not committed to GitHub.
-- Use the training scripts or Colab notebook to regenerate datasets.
-- Store trained models in Google Drive or local storage.
-- For local evaluation, place the 20k alternate-sequence dataset in `training/csv_files_20k_alt/`.
-- For backend use, place the model folder in `backend/models/final_model/` or set the backend model path environment variable.
-- The local final model folder `training/training_model_files/` and the 20k CSV folder `training/csv_files_20k_alt/` are intentionally ignored by Git.
+Large files are intentionally ignored by Git:
 
-## Environment Files
+- 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`
 
-Each app folder includes a `.env.example`. Do not commit `.env`, `.env.local`, API keys, model checkpoints, or private data.
+Use local storage, Google Drive, or another private artifact store for trained models and datasets.
 
-## Safety Notice
+## Demo Disclaimer
 
-Predictions and explanations are experimental model outputs. They can be wrong, incomplete, biased by the training data, or invalid for variants outside the training distribution. Use this project only for software, ML, and genomics workflow demonstrations.
+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 only for AI/ML research demonstrations and must not be used for diagnosis, treatment, or medical decision-making.

backend/.env.example

@@ -3,14 +3,5 @@ MODEL_THRESHOLD=0.16
 MODEL_MAX_LENGTH=512
 MODEL_NAME=DNABERT-2 ClinVar 20k
 DEVICE=auto
-
-# Optional OpenAI explanation layer.
-# Keep USE_OPENAI_EXPLANATION=false for the local rule-based explanation.
-# To enable it, copy this file to backend/.env and paste your real key there.
-USE_OPENAI_EXPLANATION=false
-OPENAI_API_KEY=
-OPENAI_EXPLANATION_MODEL=gpt-4.1-mini
-OPENAI_EXPLANATION_TIMEOUT=12
-
-# Comma-separated origins for browser clients
-ALLOWED_ORIGINS=http://localhost:3000
+OPENAI_API_KEY=your_openai_api_key_here
+USE_AI_EXPLANATION=true

backend/README.md

@@ -58,10 +58,8 @@ Do not paste your OpenAI API key into source code or `.env.example`.
 Paste it only into your local `backend/.env` file:
 
 ```bash
-USE_OPENAI_EXPLANATION=true
-OPENAI_API_KEY=sk-your-real-key-here
-OPENAI_EXPLANATION_MODEL=gpt-4.1-mini
-OPENAI_EXPLANATION_TIMEOUT=12
+USE_AI_EXPLANATION=true
+OPENAI_API_KEY=your_openai_api_key_here
 ```
 
 Then restart the backend. If the OpenAI key is missing, the package is not
@@ -131,6 +129,7 @@ print(response.json())
 - `threshold`: decision threshold, currently `0.16`
 - `sequence_length_used`: sequence length after optional center crop
 - `explanation`: plain-language explanation of the model output
+- `explanation_source`: `openai`, `rule-based`, or `rule-based-fallback`
 - `confidence_level`: rough confidence category based on model probability
 - `recommendation`: safe research/demo recommendation
 - `limitations`: important limitations to show users
@@ -138,7 +137,7 @@ print(response.json())
 ## Explanation Layer
 
 The default explanation is generated by local backend rules. When
-`USE_OPENAI_EXPLANATION=true`, the backend asks OpenAI to rewrite only the
+`USE_AI_EXPLANATION=true`, the backend asks OpenAI to rewrite only the
 explanation paragraph in beginner-friendly language. The prediction,
 probabilities, threshold, confidence level, recommendation, and limitations stay
 controlled by backend logic.

backend/app/core/config.py

@@ -25,6 +25,12 @@ def _env_bool(name: str, default: bool = False) -> bool:
     return value.strip().lower() in {"1", "true", "yes", "on"}
 
 
+def _ai_explanation_enabled() -> bool:
+    if os.getenv("USE_AI_EXPLANATION") is not None:
+        return _env_bool("USE_AI_EXPLANATION", False)
+    return _env_bool("USE_OPENAI_EXPLANATION", False)
+
+
 @dataclass(frozen=True)
 class Settings:
     app_name: str = "variant-risk-explainer"
@@ -35,7 +41,7 @@ class Settings:
     model_name: str = os.getenv("MODEL_NAME", "DNABERT-2 ClinVar 20k").strip() or "DNABERT-2 ClinVar 20k"
     device: str = os.getenv("DEVICE", "auto").strip().lower() or "auto"
     max_sequence_context_length: int = int(os.getenv("MAX_SEQUENCE_CONTEXT_LENGTH", "2000"))
-    use_openai_explanation: bool = _env_bool("USE_OPENAI_EXPLANATION", False)
+    use_openai_explanation: bool = _ai_explanation_enabled()
     openai_api_key: str = os.getenv("OPENAI_API_KEY", "").strip()
     openai_explanation_model: str = (
         os.getenv("OPENAI_EXPLANATION_MODEL", "gpt-4.1-mini").strip() or "gpt-4.1-mini"

backend/app/main.py

@@ -88,6 +88,7 @@ def analyze(request: AnalyzeRequest) -> AnalyzeResponse:
         model_name=prediction.model_name,
         sequence_length_used=prediction.sequence_length_used,
         explanation=explanation["explanation"],
+        explanation_source=explanation["explanation_source"],
         confidence_level=explanation["confidence_level"],
         recommendation=explanation["recommendation"],
         limitations=explanation["limitations"],

backend/app/schemas.py

@@ -43,6 +43,7 @@ class AnalyzeResponse(BaseModel):
     model_name: str
     sequence_length_used: int
     explanation: str
+    explanation_source: str
     confidence_level: str
     recommendation: str
     limitations: list[str]

backend/app/services/explanation_service.py

@@ -101,12 +101,19 @@ def _generate_rule_based_explanation(
 
     return {
         "explanation": explanation,
+        "explanation_source": "rule-based",
         "confidence_level": confidence_level,
         "recommendation": RECOMMENDATION,
         "limitations": LIMITATIONS,
     }
 
 
+def _fallback_with_source(fallback: dict) -> dict:
+    result = dict(fallback)
+    result["explanation_source"] = "rule-based-fallback"
+    return result
+
+
 def _extract_json_object(text: str) -> dict:
     try:
         return json.loads(text)
@@ -136,7 +143,7 @@ def _generate_openai_explanation(
         from openai import OpenAI
     except ImportError:
         print("OpenAI package is not installed. Using rule-based explanation.")
-        return fallback
+        return _fallback_with_source(fallback)
 
     context = {
         "variant_name": variant_name,
@@ -169,20 +176,21 @@ def _generate_openai_explanation(
         output_text = str(getattr(response, "output_text", "")).strip()
         if not output_text:
             print("OpenAI explanation response was empty. Using rule-based explanation.")
-            return fallback
+            return _fallback_with_source(fallback)
 
         parsed = _extract_json_object(output_text)
         explanation = str(parsed.get("explanation", "")).strip()
         if not explanation:
             print("OpenAI explanation JSON did not include explanation. Using rule-based explanation.")
-            return fallback
+            return _fallback_with_source(fallback)
 
         enhanced = dict(fallback)
         enhanced["explanation"] = explanation
+        enhanced["explanation_source"] = "openai"
         return enhanced
     except Exception as exc:  # pragma: no cover - network/API failures vary.
         print(f"OpenAI explanation failed: {type(exc).__name__}: {exc}. Using rule-based explanation.")
-        return fallback
+        return _fallback_with_source(fallback)
 
 
 def generate_explanation(
@@ -215,8 +223,8 @@ def generate_explanation(
     if not use_openai:
         return fallback
     if not openai_api_key:
-        print("USE_OPENAI_EXPLANATION is true, but OPENAI_API_KEY is missing. Using rule-based explanation.")
-        return fallback
+        print("AI explanation is enabled, but OPENAI_API_KEY is missing. Using rule-based explanation.")
+        return _fallback_with_source(fallback)
 
     return _generate_openai_explanation(
         fallback=fallback,

docs/DEMO_EXAMPLES.md

@@ -0,0 +1,81 @@
+# Demo Examples
+
+These examples use synthetic/demo DNA sequences only. They are not real clinical examples and should not be interpreted as medical evidence.
+
+## Example 1: Demo Variant A
+
+Request:
+
+```json
+{
+  "variant_name": "Demo Variant A",
+  "gene": "BRCA1",
+  "sequence": "ACGTACGTACGTACGTACGTACGTACGTACGTACGTACGTACGTACGTACGTACGTACGTACGT",
+  "notes": "Synthetic short sequence for endpoint testing."
+}
+```
+
+Example curl:
+
+```bash
+curl -X POST http://127.0.0.1:8000/analyze \
+  -H "Content-Type: application/json" \
+  -d '{
+    "variant_name": "Demo Variant A",
+    "gene": "BRCA1",
+    "sequence": "ACGTACGTACGTACGTACGTACGTACGTACGTACGTACGTACGTACGTACGTACGTACGTACGT",
+    "notes": "Synthetic short sequence for endpoint testing."
+  }'
+```
+
+## Example 2: Demo Variant B
+
+Request:
+
+```json
+{
+  "variant_name": "Demo Variant B",
+  "gene": "TP53",
+  "sequence": "TTGCAAGCTTAGGCTAACCGTTGCAAGCTTAGGCTAACCGTTGCAAGCTTAGGCTAACCGTTGCAAGC",
+  "notes": "Second synthetic sequence for frontend demo testing."
+}
+```
+
+Example curl:
+
+```bash
+curl -X POST http://127.0.0.1:8000/analyze \
+  -H "Content-Type: application/json" \
+  -d '{
+    "variant_name": "Demo Variant B",
+    "gene": "TP53",
+    "sequence": "TTGCAAGCTTAGGCTAACCGTTGCAAGCTTAGGCTAACCGTTGCAAGCTTAGGCTAACCGTTGCAAGC",
+    "notes": "Second synthetic sequence for frontend demo testing."
+  }'
+```
+
+## Example 3: Invalid Sequence
+
+Request:
+
+```json
+{
+  "variant_name": "Invalid Demo Variant",
+  "gene": "TP53",
+  "sequence": "ACGTXYZACGT",
+  "notes": "This should fail validation because X, Y, and Z are not valid DNA bases."
+}
+```
+
+Expected behavior:
+
+- HTTP status: `400`
+- Error message includes invalid DNA characters.
+
+Example response:
+
+```json
+{
+  "detail": "sequence contains invalid DNA characters: XYZ"
+}
+```

docs/LIMITATIONS.md

@@ -0,0 +1,18 @@
+# Project Limitations
+
+Variant Risk Explainer is an AI/ML research demonstration only.
+
+Key limitations:
+
+- The model is trained on DNA sequence patterns only.
+- The prediction does not include full clinical evidence.
+- The prediction does not include family history.
+- The prediction does not include population frequency.
+- The prediction does not include functional studies.
+- ClinVar labels can be incomplete, conflicting, biased, or updated over time.
+- Model performance is limited, with AUC ROC around `0.5928`.
+- The model may not generalize to variants outside the training distribution.
+- The system is not for diagnosis or treatment decisions.
+- The project is intended only for AI/ML research demonstration and education.
+
+Any real genetic or medical decision requires validated clinical testing, clinical databases, and review by qualified clinical genetics professionals.

docs/README.md

@@ -5,3 +5,7 @@ This folder contains project documentation for the Variant Risk Explainer demo.
 - `architecture.md`: high-level system design and data flow.
 - `api_contract.md`: backend request and response schema.
 - `model_card.md`: research model card and safety limitations.
+- `DEMO_EXAMPLES.md`: synthetic demo requests for frontend/backend testing.
+- `LIMITATIONS.md`: project limitations and safety boundaries.
+- `TESTING_CHECKLIST.md`: final pre-push and demo testing checklist.
+- `MODEL_ARTIFACTS.md`: local model artifact handling notes.

docs/TESTING_CHECKLIST.md

@@ -0,0 +1,36 @@
+# Testing Checklist
+
+Use this checklist before pushing or presenting the demo.
+
+## Backend
+
+- [ ] `GET /health` returns `status: ok`.
+- [ ] `GET /health` shows the expected model directory and threshold `0.16`.
+- [ ] `POST /analyze` works for a valid synthetic DNA sequence.
+- [ ] `POST /analyze` returns prediction probabilities and `prediction_class`.
+- [ ] Invalid DNA sequence returns a clear HTTP `400` error.
+- [ ] Response includes `explanation`.
+- [ ] Response includes `explanation_source`.
+- [ ] Response includes `confidence_level`, `recommendation`, `limitations`, and `disclaimer`.
+- [ ] OpenAI explanation works when `USE_AI_EXPLANATION=true` and `OPENAI_API_KEY` is set.
+- [ ] OpenAI fallback works if the key is missing or the OpenAI request fails.
+
+## Frontend
+
+- [ ] Frontend loads at `http://localhost:3000`.
+- [ ] Backend status indicator shows connected/model loaded.
+- [ ] Form accepts variant name, gene, sequence, and notes.
+- [ ] Result card displays prediction label and risk level.
+- [ ] Result card displays pathogenic and benign probabilities.
+- [ ] Result card displays explanation and explanation source.
+- [ ] Result card displays limitations and research/demo disclaimer.
+- [ ] History panel records recent demo analyses.
+
+## Security And Artifacts
+
+- [ ] No `.env` files are tracked by Git.
+- [ ] No `.env.local` files are tracked by Git.
+- [ ] No OpenAI API key appears in tracked source, README, or docs files.
+- [ ] Trained model folders are ignored by Git.
+- [ ] Dataset folders are ignored by Git.
+- [ ] Model weight files such as `.safetensors`, `.bin`, `.pt`, and `.ckpt` are ignored by Git.

docs/api_contract.md

@@ -12,17 +12,21 @@ http://localhost:8000
 GET /health
 ```
 
-### Response
+Example response:
 
 ```json
 {
   "status": "ok",
-  "service": "variant-risk-explainer",
-  "model_mode": "mock"
+  "model_loaded": true,
+  "device": "mps",
+  "model_dir": "../training/training_model_files",
+  "threshold": 0.16,
+  "model_name": "DNABERT-2 ClinVar 20k",
+  "load_error": null
 }
 ```
 
-## Analyze Variant
+## Analyze Variant Sequence
 
 ```http
 POST /analyze
@@ -33,70 +37,64 @@ Content-Type: application/json
 
 ```json
 {
-  "chromosome": "7",
-  "position": 140753336,
-  "reference": "A",
-  "alternate": "T",
-  "gene": "BRAF",
-  "sequence_context": "ACGTACGTACGT"
+  "sequence": "ACGTACGTACGTACGT",
+  "variant_name": "Demo Variant A",
+  "gene": "BRCA1",
+  "notes": "Synthetic demo request"
 }
 ```
 
-### Fields
+### Request Fields
 
-- `chromosome`: GRCh38 chromosome name. Accepts `1` through `22`, `X`, `Y`, `MT`, and optional `chr` prefix.
-- `position`: 1-based GRCh38 genomic coordinate.
-- `reference`: reference allele using `A`, `C`, `G`, `T`, or `N`.
-- `alternate`: alternate allele using `A`, `C`, `G`, `T`, or `N`.
-- `gene`: optional gene symbol for display and explanation context.
-- `sequence_context`: optional GRCh38 sequence context around the variant.
+- `sequence`: required DNA sequence using only `A`, `C`, `G`, `T`, or `N`.
+- `variant_name`: optional display name.
+- `gene`: optional gene symbol for display/explanation context.
+- `notes`: optional demo notes.
 
 ### Response Body
 
 ```json
 {
-  "request_id": "0e7c3d55-6f46-4c19-a1fd-860bc4f8a88d",
-  "submitted_at": "2026-06-04T10:00:00Z",
-  "input": {
-    "chromosome": "7",
-    "position": 140753336,
-    "reference": "A",
-    "alternate": "T",
-    "gene": "BRAF",
-    "sequence_context": "ACGTACGTACGT"
-  },
-  "grch_build": "GRCh38",
-  "risk_label": "uncertain",
-  "confidence": 0.54,
-  "model_mode": "mock",
-  "explanation": "Mock mode produced a deterministic research-only score from variant features. No clinical meaning should be inferred.",
+  "variant_name": "Demo Variant A",
+  "gene": "BRCA1",
+  "prediction_class": 1,
+  "prediction_label": "Pathogenic / Likely pathogenic",
+  "risk_level": "Elevated",
+  "benign_probability": 0.671463,
+  "pathogenic_probability": 0.328537,
+  "threshold": 0.16,
+  "model_name": "DNABERT-2 ClinVar 20k",
+  "sequence_length_used": 64,
+  "explanation": "The model estimated...",
+  "explanation_source": "openai",
+  "confidence_level": "Low model confidence",
+  "recommendation": "This result is for research/demo use only...",
   "limitations": [
-    "Research demo only.",
-    "Not validated for diagnosis or treatment decisions.",
-    "ClinVar labels may be incomplete, conflicting, or biased."
+    "The model uses DNA sequence patterns and does not replace clinical interpretation.",
+    "The model performance is limited, with test AUC around 0.5928.",
+    "The prediction does not include full clinical evidence, family history, population frequency, or functional studies.",
+    "The result should not be used for diagnosis or treatment decisions."
   ],
-  "disclaimer": "For research and education only. Not for medical diagnosis."
+  "disclaimer": "Research/demo use only. This model is not a clinical diagnostic system and must not be used for medical decisions."
 }
 ```
 
-### Risk Labels
+### Explanation Sources
 
-- `likely_benign`
-- `uncertain`
-- `likely_pathogenic`
-
-These labels are demo categories only and are not clinical classifications.
+- `openai`: OpenAI successfully rewrote the explanation paragraph.
+- `rule-based`: local rule-based explanation was used because AI explanation is disabled.
+- `rule-based-fallback`: AI explanation was enabled, but the key was missing or the OpenAI request failed.
 
 ### Error Example
 
+Invalid DNA characters return a clear error:
+
 ```json
 {
-  "detail": [
-    {
-      "type": "value_error",
-      "loc": ["body", "position"],
-      "msg": "Value error, position must be a positive GRCh38 coordinate"
-    }
-  ]
+  "detail": "sequence contains invalid DNA characters: XZ"
 }
 ```
+
+## Safety Boundary
+
+All outputs are research/demo outputs only. They are not clinical classifications and must not be used for diagnosis, treatment, or medical decision-making.

docs/architecture.md

@@ -3,61 +3,78 @@
 Variant Risk Explainer is split into four top-level folders:
 
 ```text
-training/  -> Colab training pipeline
+training/  -> ClinVar GRCh38 preparation, DNABERT-2 training, evaluation scripts
 backend/   -> FastAPI inference API
 frontend/  -> Next.js research demo UI
 docs/      -> project documentation
 ```
 
-## Component Flow
+## Runtime Flow
 
 ```text
 User
   |
   v
-Next.js frontend
+Next.js Frontend
   |
   | POST /analyze
   v
-FastAPI backend
+FastAPI Backend
   |
-  | mock mode or trained DNABERT-2 model directory
   v
-Variant risk response
+DNABERT-2 Prediction Service
+  |
+  v
+Explanation Layer
+  |
+  v
+Research/Demo Result
 ```
 
-## Training Flow
-
-1. Download ClinVar GRCh38 VCF data in Google Colab.
-2. Load a GRCh38 reference FASTA.
-3. Extract sequence windows around single nucleotide variants.
-4. Map ClinVar clinical significance labels into research classes.
-5. Fine-tune DNABERT-2 with Hugging Face Transformers.
-6. Save an exported model directory for backend inference.
+## Backend Flow
 
-Training is intentionally not wired into the local runtime. The backend can run in mock mode until a trained model is available.
+1. Load settings from `backend/.env`.
+2. Load the DNABERT-2 tokenizer and sequence-classification model from `MODEL_DIR`.
+3. Select device automatically: CUDA, then MPS, then CPU.
+4. Clean the submitted DNA sequence.
+5. Center crop sequences longer than `MODEL_MAX_LENGTH`.
+6. Run DNABERT-2 in inference mode.
+7. Apply the tuned pathogenic threshold, currently `0.16`.
+8. Generate a cautious explanation.
+9. Return prediction probabilities, label, explanation, limitations, and disclaimer.
 
-## Backend Flow
+## Explanation Layer
 
-The backend exposes `POST /analyze`. It validates the submitted GRCh38 variant, chooses a model implementation, returns a risk label, confidence, explanation, and research-only disclaimers.
+The explanation layer is designed to be safe for a research demo:
 
-Model mode is controlled by environment variables:
+- `rule-based`: local deterministic explanation.
+- `openai`: optional OpenAI-generated explanation paragraph.
+- `rule-based-fallback`: local explanation used because AI explanation failed or was missing configuration.
 
-- `MODEL_MODE=mock`: always use deterministic mock inference.
-- `MODEL_MODE=trained`: require a trained model at `MODEL_DIR`.
-- `MODEL_MODE=auto`: use the trained model when available, otherwise fall back to mock mode.
+The LLM, when enabled, rewrites only the explanation paragraph. It does not control the prediction, probabilities, threshold, confidence level, recommendation, limitations, or disclaimer.
 
 ## Frontend Flow
 
 The frontend provides:
 
-- Variant input form.
-- Loading and error states.
-- Result card.
-- Local in-browser history panel.
+- backend health indicator
+- DNA sequence input form
+- loading and error states
+- result card
+- explanation source display
+- local in-browser history panel
+- research/demo disclaimer
+
+## Training Flow
 
-The frontend uses `NEXT_PUBLIC_API_BASE_URL` to find the backend.
+1. Prepare ClinVar GRCh38 records.
+2. Extract reference sequence windows.
+3. Build alternate-allele sequence windows.
+4. Filter uncertain/conflicting labels.
+5. Fine-tune DNABERT-2 on the alternate-sequence dataset.
+6. Evaluate on held-out validation and test splits.
+7. Export a self-contained Hugging Face model folder for backend inference.
 
 ## Safety Boundary
 
-This is a research and educational demo. It does not diagnose disease, recommend care, or replace genetic counseling or clinical interpretation. All user-facing layers should preserve that boundary.
+This is a research and educational demo. It does not diagnose disease, recommend care, or replace genetic counseling or clinical variant interpretation. All user-facing layers should preserve that boundary.

docs/model_card.md

@@ -28,10 +28,10 @@ GRCh38 is used consistently for ClinVar coordinates and reference sequence extra
 
 The pipeline prepares examples from ClinVar GRCh38 VCF records. It focuses on single nucleotide variants with clinical significance labels that can be mapped into binary or compact research classes.
 
-Example label mapping:
+Final label mapping:
 
-- `Pathogenic` and `Likely_pathogenic` -> `likely_pathogenic`
-- `Benign` and `Likely_benign` -> `likely_benign`
+- `Pathogenic` and `Likely_pathogenic` -> `1`
+- `Benign` and `Likely_benign` -> `0`
 - conflicting, uncertain, or unsupported labels -> skipped or held out depending on notebook settings
 
 ## Inputs
@@ -40,22 +40,31 @@ The model receives sequence windows centered on a submitted variant. The demo sc
 
 ## Outputs
 
-The backend maps model scores into demo labels:
+The backend maps model probabilities into demo labels:
 
-- `likely_benign`
-- `uncertain`
-- `likely_pathogenic`
+- `0`: Benign / Likely benign
+- `1`: Pathogenic / Likely pathogenic
+
+The current research threshold for class `1` is `0.16`.
 
 ## Evaluation
 
-Recommended evaluation:
+Final confirmed 20k alternate-sequence evaluation:
+
+- Accuracy: `0.5537`
+- Precision: `0.5384`
+- Recall: `0.7533`
+- F1: `0.6280`
+- MCC: `0.1171`
+- AUC ROC: `0.5928`
+
+Recommended future evaluation:
 
-- Stratified train, validation, and test splits.
-- Accuracy, precision, recall, F1, ROC-AUC where appropriate.
-- Confusion matrix.
-- Per-class metrics.
-- Label distribution audit.
-- Gene and chromosome holdout experiments for stronger leakage checks.
+- Larger independent test sets.
+- Gene and chromosome holdout experiments.
+- Leakage checks across related variants.
+- Per-variant-type reporting for SNVs and indels.
+- Calibration analysis across thresholds.
 
 ## Limitations
 

frontend/README.md

@@ -68,11 +68,12 @@ NEXT_PUBLIC_API_URL=http://127.0.0.1:8001
 5. Click `Analyze Variant`.
 
 The result card shows benign/pathogenic probabilities, threshold, model name,
-sequence length used after center cropping, and a beginner-friendly explanation.
+sequence length used after center cropping, a beginner-friendly explanation, and
+the explanation source.
 
 The explanation is generated from the backend model output and threshold. It is
 not medical advice and is not a clinical interpretation. If the backend has
-`USE_OPENAI_EXPLANATION=true`, the backend may use OpenAI to improve the
+`USE_AI_EXPLANATION=true`, the backend may use OpenAI to improve the
 explanation paragraph. Do not put the OpenAI API key in the frontend; keep it in
 `backend/.env` only.
 

frontend/components/ResultCard.tsx

@@ -13,6 +13,16 @@ function asPercent(value: number): string {
   return `${(value * 100).toFixed(1)}%`;
 }
 
+function explanationSourceLabel(source: string): string {
+  if (source === "openai") {
+    return "OpenAI";
+  }
+  if (source === "rule-based-fallback") {
+    return "Rule-based fallback";
+  }
+  return "Rule-based";
+}
+
 export function ResultCard({ error, isLoading, result }: ResultCardProps) {
   if (isLoading) {
     return (
@@ -101,6 +111,9 @@ export function ResultCard({ error, isLoading, result }: ResultCardProps) {
         <p>
           <strong>Confidence level:</strong> {result.confidence_level}
         </p>
+        <p>
+          <strong>Explanation source:</strong> {explanationSourceLabel(result.explanation_source)}
+        </p>
       </div>
 
       <div className="recommendationBlock">

frontend/types.ts

@@ -17,6 +17,7 @@ export type AnalyzeResponse = {
   model_name: string;
   sequence_length_used: number;
   explanation: string;
+  explanation_source: "rule-based" | "openai" | "rule-based-fallback" | string;
   confidence_level: string;
   recommendation: string;
   limitations: string[];