# Open Bio Variant Annotator

**A Privacy-First macOS Desktop Application and Model Context Protocol (MCP) Toolkit for Clinical Variant Triage from NGS Spreadsheet Outputs**

[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
[![Platform: macOS](https://img.shields.io/badge/Platform-macOS-000000.svg)](#installation--quick-start)
[![Python: 3.10+](https://img.shields.io/badge/Python-3.10%2B-3776AB.svg)](#running-from-source)

---

## Overview (English)

**Open Bio Variant Annotator** is a local-first desktop application for macOS (`.app` / `.dmg`) and a **Model Context Protocol (MCP)** server designed for diagnostic genetics laboratories working with tabular variant callsets (such as **Ion Torrent S5** `.xls` / `.xlsx` exports on `hg19/GRCh37`).

### Key Capabilities
1. **Strict Local Privacy (Zero Cloud File Uploads):** Complete patient spreadsheets never leave the local computer. Working files, job history, and local annotation caches are stored strictly in `~/.openbio/` (`0700` permissions). Only individual de-identified genomic coordinates (`chr:pos`) are queried against public NCBI Entrez E-utilities.
2. **Bring-Your-Own-Key (BYOK) NCBI Authentication:** No API keys are hardcoded in the software. On first launch, the application guides the user to configure their personal, free NCBI API key (`https://www.ncbi.nlm.nih.gov/account/settings/`), enabling rate-limited queries up to 9–10 requests/second while storing credentials locally in `~/.openbio/config.json` (`0600` permissions).
3. **Indel & Coordinate Normalization (`hg19`/`GRCh37`):** Automatically detects both standard Excel workbooks (`.xlsx`/`.xls`) and tab-separated `.xls` files exported by Ion Torrent Torrent Suite, resolving left-shifted vs. right-shifted indels and selecting the ClinVar record with the highest review status.
4. **Automated Triage & Color-Coded Clinical Reports:** Generates standardized 13-column Excel reports color-coded by clinical significance:
   - **Red (`#FF4C4C`):** *Pathogenic / Likely pathogenic*
   - **Orange (`#ED7D31`):** *Uncertain significance (VUS)*
   - **Blue (`#9FC5E8`):** *Conflicting classifications of pathogenicity*
   - **White (`#FFFFFF`):** *Benign / Likely benign* (automatically filtering out ~95% of benign polymorphisms in multigene panels)
   - **Yellow (`#FFE599`):** *Not found in ClinVar* (highlighting novel/unannotated variants for rapid downstream evaluation via pre-built **gnomAD r2.1** and **VarSome ACMG** links).
5. **Model Context Protocol (MCP) Server (`mcp_server.py`):** Exposes variant lookup and batch spreadsheet annotation tools (`search_variant`, `get_variant_by_id`, `inspect_excel`, `batch_query_clinvar`, `batch_query_folder`) to MCP-compatible AI assistants.

---

## Installation & Quick Start (For Reviewers and Users)

### Option A: Native macOS Application (`.dmg`)
1. Download **`Open Bio Variant Annotator.dmg`** from the [**GitHub Releases**](../../releases) page.
2. Open the `.dmg` image and drag **Open Bio Variant Annotator.app** into your `Applications` folder.
3. Launch the app. On first launch, click **Impostazioni / Settings → API key NCBI** (or click the built-in link to `https://www.ncbi.nlm.nih.gov/account/settings/`) and paste your free NCBI API key.
4. Load the included sample dataset: [`sample_data/sample_variants_hg19.xls`](sample_data/sample_variants_hg19.xls).
5. Inspect the interactive results table and click **Salva report Excel** to save the color-coded `.xlsx` report via the native macOS Save dialog.

### Option B: Running from Source (Python 3.10+)
```bash
git clone https://github.com/Francescopad/openbio-variant-annotator.git
cd openbio-variant-annotator
pip install -r requirements.txt

# Launch the native macOS desktop window (pywebview + FastAPI)
python3 openbio_app.py
```

### Testing with the Included Sample Dataset
The repository includes [`sample_data/sample_variants_hg19.xls`](sample_data/sample_variants_hg19.xls), an anonymized Ion Torrent-compatible benchmark file (`hg19/GRCh37`) containing 7 reference variants:
- *BRAF* V600E (`chr7:140453136 A>T`) — *Pathogenic*
- *MTHFR* C677T (`chr1:11856378 G>A`) — *Benign / Drug response*
- *BRCA1* c.68_69delAG (`chr17:41277277 CT>C`) — *Pathogenic complex indel*
- *CFTR* p.Phe508del (`chr7:117199644 ATCT>A`) — *Pathogenic deletion*
- *HFE* C282Y (`chr6:26093141 G>A`) — *Pathogenic / Conflicting*
- *TTN* missense (`chr2:179415516 G>A`) — *Uncertain significance (VUS)*
- *TTN* synthetic novel coordinate (`chr2:179432185 A>G`) — *Not found in ClinVar* (demonstrating novel variant triage with direct gnomAD/VarSome links).

---

## Repository Structure

```
openbio/
├── openbio_app.py       # Native macOS desktop launcher (pywebview + native menus & file dialogs)
├── local_server.py      # Local FastAPI server (127.0.0.1 ephemeral port, analysis & history API)
├── mcp_server.py        # Model Context Protocol (MCP) server for AI agent integration
├── job_store.py         # Persistent local job & report store (~/.openbio/)
├── config_manager.py    # Secure local BYOK API key manager (~/.openbio/config.json, chmod 0600)
├── clinvar_client.py    # Async NCBI E-utilities ClinVar client with indel & hg19 resolution
├── gnomad_client.py     # gnomAD r2.1 (GRCh37) direct variant link builder
├── varsome_client.py    # VarSome ACMG client and URL builder
├── excel_handler.py     # Reader/writer for Excel (.xlsx/.xls) and Ion Torrent TSV outputs
├── clinvar_batch.py     # Batch folder & file processor with shared local caching
├── sample_data/
│   └── sample_variants_hg19.xls  # Anonymized benchmark dataset for testing & peer review
├── static/              # Frontend UI assets (index.html, style.css, app.js, dna.svg)
├── build_mac_app.py     # PyInstaller build script for macOS .app and .dmg distribution
├── requirements.txt     # Python dependencies
└── LICENSE              # MIT License (free for academic and non-commercial use)
```

---

## Guida in Italiano

App desktop macOS per l'annotazione di varianti genomiche da file Excel (**Ion Torrent S5** o tabelle `hg19/GRCh37`).
**Elaborazione locale** — file e report restano sul tuo Mac (`~/.openbio/`); solo le singole coordinate delle varianti vengono inviate a NCBI per interrogare ClinVar tramite la tua API key personale.

### Sviluppo e Build del DMG su macOS
```bash
pip install -r requirements.txt
python3 openbio_app.py        # Avvia l'app in modalità sviluppo
python3 build_mac_app.py      # Genera Open Bio Variant Annotator.app e .dmg in dist/
```

## License
Released under the [MIT License](LICENSE). Free for academic, research, and non-commercial clinical use.