Initial commit

genomic_decision_support_system_spec_v0.1.md

@@ -0,0 +1,356 @@
+
+# 個人基因風險與用藥交互作用決策支援系統 – 系統規格書
+
+- 版本：v0.1-draft  
+- 作者：Gbanyan + 助理規劃  
+- 狀態：草案，預期隨實作迭代  
+- 目的：提供給 LLM（如 Claude、Codex 等）與開發者閱讀，作為系統設計與實作的基礎規格。
+
+---
+
+## 0. 系統目標與範圍
+
+### 0.1 目標
+
+建立一套「個人化、基因驅動」的決策支援系統，核心功能：
+
+1. **從個人與父母的外顯子定序資料（BAM）出發**，產生可查詢的變異資料庫。
+2. **針對特定疾病、症狀或表型**，自動查詢相關基因與已知致病變異，並在個人資料中搜尋對應變異。
+3. 依據 **ACMG/AMP 等準則** 與公開資料庫，給出 **機器輔助、具人工介入點的變異詮釋**。
+4. 進一步整合：
+   - 基因藥物學（Pharmacogenomics, PGx）
+   - 藥–藥交互作用（DDI）
+   - 保健食品、中藥等成分的潛在交互作用與風險
+5. 提供一個自然語言問答介面，使用者可直接問：
+   - 「我有沒有 XXX 的遺傳風險？」
+   - 「以我現在吃的藥和保健食品，有沒有需要注意的交互作用？」
+
+> 系統定位為：**個人決策支援工具 / 研究工具**，而非正式醫療診斷系統。
+
+### 0.2 核心設計哲學
+
+- **分階段發展**：先穩固「基因本體」與變異詮釋，再往 PGx 與交互作用擴充。
+- **明確的人機分工**：對每個模組標記 `Auto / Auto+Review / Human-only`。
+- **可追蹤、可回溯**：每一個結論都可追蹤到所用規則、資料庫版本、人工 override。
+
+---
+
+## 1. 發展階段與整體架構
+
+### 1.1 發展階段總覽
+
+| 階段 | 名稱 | 核心產出 | 主要對象 |
+|------|------|----------|----------|
+| Phase 1 | 基因本體與變異詮釋基礎 | 個人+trio VCF、註解與疾病/基因查詢 | 單基因疾病風險 |
+| Phase 2 | 基因藥物學與 DDI | 基因–藥物對應、藥–藥交互作用分析 | 精準用藥建議 |
+| Phase 3 | 保健食品與中藥交互作用 | 成分標準化與交互作用風險層級 | 整體用藥＋補充品安全網 |
+| Phase 4 | NLP/LLM 問答介面 | 自然語言問答、報告生成 | 一般使用者 / 臨床對話 |
+
+### 1.2 高階架構圖（Mermaid）
+
+```mermaid
+flowchart TD
+
+subgraph P1[Phase 1: 基因本體]
+  A1[BAM (本人+父母)] --> A2[Variant Calling Pipeline]
+  A2 --> A3[Joint VCF (Trio)]
+  A3 --> A4[Variant Annotation (ClinVar, gnomAD, VEP...)]
+  A4 --> A5[Genomic DB / Query API]
+end
+
+subgraph P2[Phase 2: PGx & DDI]
+  B1[藥物清單] --> B2[PGx Engine]
+  A5 --> B2
+  B1 --> B3[DDI Engine]
+end
+
+subgraph P3[Phase 3: 補充品 & 中藥]
+  C1[保健食品/中藥清單] --> C2[成分標準化]
+  C2 --> C3[成分交互作用引擎]
+  B1 --> C3
+  A5 --> C3
+end
+
+subgraph P4[Phase 4: 問答與報告]
+  D1[前端 UI / CLI / API Client] --> D2[LLM Orchestrator]
+  D2 -->|疾病/症狀詢問| A5
+  D2 -->|用藥/成分詢問| B2
+  D2 --> B3
+  D2 --> C3
+  A5 --> D3[報告產生器]
+  B2 --> D3
+  B3 --> D3
+  C3 --> D3
+end
+```
+
+---
+
+## 2. 通用設計：人機分工標記
+
+所有模組需標記自動化等級：
+
+- `Auto`：可完全自動執行的步驟（例：variant calling、基本註解）。
+- `Auto+Review`：系統先產生建議，需人工複核或有條件接受（例：ACMG 部分 evidence scoring）。
+- `Human-only`：最終醫療判斷／用語／管理建議，必須由人決策（例：最終 Pathogenic 分類、臨床處置建議）。
+
+每次分析需生成一份 **machine-readable log**，紀錄：
+
+- 使用的模組與版本
+- 每一步的自動化等級
+- 哪些地方有人工 override（人員、時間、理由）
+
+---
+
+## 3. Phase 1：基因本體與變異詮釋基礎
+
+### 3.1 功能需求
+
+1. **輸入**
+   - 本人與雙親外顯子定序 BAM 檔。
+2. **輸出**
+   - 高品質 joint VCF（含 trio）
+   - 每個變異的註解資訊：
+     - 基因、轉錄本、蛋白改變
+     - 族群頻率（gnomAD 等）
+     - ClinVar 註解
+     - 功能預測（SIFT/PolyPhen/CADD 等）
+   - 對特定疾病/基因清單的變異過濾結果。
+3. **對外服務**
+   - 以 API / 函式介面提供：
+     - 給定基因列表 → 回傳該個體在這些基因中的變異列表
+     - 支援疾病名稱/HPO → 基因 → 變異的查詢流程（初期可分步呼叫）
+
+### 3.2 模組設計
+
+#### 3.2.1 Variant Calling Pipeline
+
+- **輸入**：BAM（本人 + 父母）
+- **輸出**：個別 gVCF → joint VCF
+- **工具候選**：
+  - GATK（HaplotypeCaller + GenotypeGVCFs）
+  - 或 DeepVariant + joint genotyper
+- **自動化等級**：`Auto`
+- **需求**：
+  - 基本 QC（coverage、duplicate rate、on-target rate）
+  - 支援版本標記（如 reference genome 版本）
+
+#### 3.2.2 Annotation Pipeline
+
+- **輸入**：joint VCF
+- **輸出**：annotated VCF / 變異表
+- **工具候選**：
+  - VEP、ANNOVAR 或類似工具
+- **資料庫**：
+  - ClinVar
+  - gnomAD
+  - 基因功能與轉錄本資料庫
+- **自動化等級**：`Auto`
+
+#### 3.2.3 Genomic DB / Query API
+
+- **目的**：提供高效查詢，作為後續模組（疾病風險、PGx 等）的基底。
+- **形式**：
+  - 選項 A：基於 VCF + tabix，以封裝函式操作
+  - 選項 B：匯入 SQLite / PostgreSQL / 專用 genomic DB
+- **關鍵查詢**：
+  - `get_variants_by_gene(individual_id, gene_list, filters)`
+  - `get_variants_by_region(individual_id, chr, start, end, filters)`
+- **自動化等級**：`Auto`
+
+#### 3.2.4 疾病/表型 → 基因 → 變異流程
+
+- 初期可拆成三步：
+  1. 使用外部知識庫或手動 panel：疾病/表型 → 基因清單
+  2. 透過 Genomic DB 查詢個人變異
+  3. 以簡單規則（頻率、ClinVar 標註）做初步排序
+- **自動化等級**：`Auto+Review`
+
+### 3.3 ACMG 規則實作（初版）
+
+- **範圍**：僅實作部分機器可自動判定之 evidence（如 PVS1、PM2、BA1、BS1 等）。
+- **輸出**：
+  - 每個變異的 evidence tag 列表與建議分級（例如：`suggested_class = "VUS"`）
+- **人工介入點**：
+  - 變異最終分類（Pathogenic / Likely pathogenic / VUS / Likely benign / Benign） → `Human-only`
+  - 規則閾值（如頻率 cutoff）以 config 檔管理 → `Auto+Review`
+
+---
+
+## 4. Phase 2：基因藥物學（PGx）與藥–藥交互作用（DDI）
+
+### 4.1 功能需求
+
+1. 接收使用者目前用藥清單（處方藥、成藥）。
+2. 透過基因資料，判定與 PGx 相關的 genotype（例如 CYP2D6, CYP2C9, HLA 等）。
+3. 根據 CPIC / DPWG 等指南，給出：
+   - 適應症相關風險（如 HLA-B*58:01 與 allopurinol）
+   - 劑量調整建議 / 藥物替代建議（僅 decision-support 層級）
+4. 計算基礎藥–藥交互作用（DDI），例如：
+   - CYP 抑制 / 誘導疊加
+   - QT prolongation 疊加
+   - 出血風險疊加
+
+### 4.2 模組設計
+
+#### 4.2.1 用藥資料標準化
+
+- 使用 ATC / RxNorm / 自訂 ID。
+- **自動化等級**：`Auto`
+
+#### 4.2.2 PGx Engine
+
+- **輸入**：個人變異（Phase 1 DB）、藥物清單
+- **輸出**：每個藥物的 PGx 評估（genotype → phenotype → 建議）
+- **資料庫**：
+  - CPIC guidelines
+  - PharmGKB 關聯資料
+- **自動化等級**：
+  - genotype → phenotype：`Auto`
+  - phenotype → 臨床建議：`Auto+Review`
+
+#### 4.2.3 DDI Engine
+
+- **輸入**：藥物清單
+- **輸出**：已知 DDI 清單與嚴重程度分級
+- **資料來源**：公開或商用 DDI 資料庫（視可用性）
+- **自動化等級**：`Auto`
+
+---
+
+## 5. Phase 3：保健食品與中藥交互作用模組
+
+### 5.1 功能需求
+
+1. 接收使用者的保健食品與中藥使用資料。
+2. 將名稱解析為：
+   - 標準化有效成分（如 EPA/DHA mg、Vit D IU、銀杏葉萃取物 mg 等）
+   - 中藥材名稱（如 黃耆、當歸、川芎…）
+3. 評估：
+   - 成分與藥物、基因的交互作用風險
+   - 成分間的加乘作用（如抗凝、CNS 抑制等）
+4. 按證據等級給出：
+   - 高優先級警示（有較強臨床證據）
+   - 一般提醒（動物實驗 / case report 等）
+   - 資料不足，僅能提醒不確定性
+
+### 5.2 模組設計
+
+#### 5.2.1 成分標準化引擎
+
+- **輸入**：使用者輸入的品名 / 處方
+- **輸出**：
+  - 標準化成分列表
+  - 估計劑量範圍（若無精確資料）
+- **資料**：
+  - 保健食品常用成分資料表
+  - 中藥方與藥材對應表
+- **自動化等級**：`Auto+Review`
+
+#### 5.2.2 成分交互作用引擎
+
+- **輸入**：成分列表、藥物清單、基因資料
+- **輸出**：交互作用列表與風險層級
+- **邏輯**：
+  - 成分對 CYP / P-gp / OATP 等的影響
+  - 成分對凝血、血壓、中樞神經等系統的影響
+- **自動化等級**：
+  - 規則推論：`Auto`
+  - 最終臨床建議表述：`Human-only`
+
+---
+
+## 6. Phase 4：NLP/LLM 問答介面與報告生成
+
+### 6.1 功能需求
+
+1. 支援使用者以自然語言提問：
+   - 疾病/症狀相關風險
+   - 用藥安全性
+   - 保健食品、中藥併用風險
+2. LLM 負責：
+   - 問題解析 → 結構化查詢（疾病、HPO、藥物、成分等）
+   - 協調呼叫底層 API（Phase 1–3）
+   - 整合結果並生成報告草稿
+3. 報告形式：
+   - 機器可讀 JSON（便於後處理）
+   - 人類可讀 Markdown / PDF 報告
+
+### 6.2 Orchestration 設計
+
+- 可採用「LLM + Tool/Function Calling」模式：
+  - 工具包括：
+    - `query_variants_by_gene`
+    - `query_disease_gene_panel`
+    - `run_pgx_analysis`
+    - `run_ddi_analysis`
+    - `run_supplement_herb_interaction`
+- LLM 主要負責：
+  - 意圖辨識與拆解
+  - 工具呼叫順序規劃
+  - 結果解釋與用語調整（需符合安全與保守原則）
+- **自動化等級**：
+  - 工具呼叫：`Auto`
+  - 臨床敏感結論：`Auto+Review` / `Human-only`（視場景而定）
+
+---
+
+## 7. 安全性、隱私與版本管理
+
+### 7.1 資料安全與隱私
+
+- 所有基因資料、用藥清單、報告：
+  - 儲存於本地或受控環境
+  - 若需與外部服務（如雲端 LLM）互動，需：
+    - 做脫敏處理（移除個資）
+    - 或改用 local/私有 LLM
+
+### 7.2 版本管理
+
+- 對以下物件進行版本控制：
+  - 參考基因組版本
+  - variant calling pipeline 版本
+  - 資料庫版本（ClinVar、gnomAD 等）
+  - ACMG 規則 config 版本
+  - gene panel / PGx 規則版本
+- 每份分析報告需記錄所用版本，以利追蹤與重跑。
+
+### 7.3 人工介入紀錄
+
+- 每次人工 override 或審核需紀錄：
+  - 變異 ID / 分析項目
+  - 原自動建議
+  - 人工調整結果
+  - 理由與參考文獻（如有）
+  - 審核者與時間
+
+---
+
+## 8. 未來擴充方向（Optional）
+
+- 整合 polygenic risk score（PRS）模組
+- 整合 longitudinal data（實驗室數據、症狀日誌）做風險動態追蹤
+- 為特定疾病領域建立更深的 expert-curated knowledge base
+- 與可穿戴裝置／其他健康資料源整合
+
+---
+
+## 9. 第一階段實作建議路線（Actionable TODO）
+
+1. **規劃 Phase 1 的技術選型**
+   - 選擇 variant caller（如 GATK）與 reference genome 版本
+   - 選擇 annotation 工具（如 VEP 或 ANNOVAR）
+2. **建立基本 pipeline**
+   - BAM → gVCF → joint VCF（trio）
+   - 加上基本 QC 報表
+3. **建置簡單的 Genomic Query 介面**
+   - 先以 CLI/Notebook 函式為主（例如 Python 函式庫）
+4. **選一個你最關心的疾病領域**
+   - 建立第一個 gene panel（例如視覺/聽力相關）
+   - 實作 panel-based 查詢與變異列表輸出
+5. **撰寫第一版報告模板**
+   - 輸入：疾病名稱 + gene panel + 查詢結果
+   - 輸出：簡易 Markdown 報告（含變異表 + 限制說明）
+6. **逐步加入 ACMG 自動 evidence 標記與人工 review 流程**
+
+這個規格書預期會在實作過程中持續更新，可視此為 v0.1 的起點版本。