gbanyan/genomic-consultant

Fork 0

Files

gbanyan f74dc351f7 Initial commit

2025-11-28 11:52:04 +08:00

12 KiB

Raw Blame History

個人基因風險與用藥交互作用決策支援系統 – 系統規格書

版本：v0.1-draft
作者：Gbanyan + 助理規劃
狀態：草案，預期隨實作迭代
目的：提供給 LLM（如 Claude、Codex 等）與開發者閱讀，作為系統設計與實作的基礎規格。

0. 系統目標與範圍

0.1 目標

建立一套「個人化、基因驅動」的決策支援系統，核心功能：

從個人與父母的外顯子定序資料（BAM）出發，產生可查詢的變異資料庫。
針對特定疾病、症狀或表型，自動查詢相關基因與已知致病變異，並在個人資料中搜尋對應變異。
依據 ACMG/AMP 等準則 與公開資料庫，給出 機器輔助、具人工介入點的變異詮釋。
進一步整合：
- 基因藥物學（Pharmacogenomics, PGx）
- 藥–藥交互作用（DDI）
- 保健食品、中藥等成分的潛在交互作用與風險
提供一個自然語言問答介面，使用者可直接問：
- 「我有沒有 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）

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 功能需求

輸入
- 本人與雙親外顯子定序 BAM 檔。
輸出
- 高品質 joint VCF（含 trio）
- 每個變異的註解資訊：
  - 基因、轉錄本、蛋白改變
  - 族群頻率（gnomAD 等）
  - ClinVar 註解
  - 功能預測（SIFT/PolyPhen/CADD 等）
- 對特定疾病/基因清單的變異過濾結果。
對外服務
- 以 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 功能需求

接收使用者目前用藥清單（處方藥、成藥）。
透過基因資料，判定與 PGx 相關的 genotype（例如 CYP2D6, CYP2C9, HLA 等）。
根據 CPIC / DPWG 等指南，給出：
- 適應症相關風險（如 HLA-B*58:01 與 allopurinol）
- 劑量調整建議 / 藥物替代建議（僅 decision-support 層級）
計算基礎藥–藥交互作用（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 功能需求

接收使用者的保健食品與中藥使用資料。
將名稱解析為：
- 標準化有效成分（如 EPA/DHA mg、Vit D IU、銀杏葉萃取物 mg 等）
- 中藥材名稱（如黃耆、當歸、川芎…）
評估：
- 成分與藥物、基因的交互作用風險
- 成分間的加乘作用（如抗凝、CNS 抑制等）
按證據等級給出：
- 高優先級警示（有較強臨床證據）
- 一般提醒（動物實驗 / 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 功能需求

支援使用者以自然語言提問：
- 疾病/症狀相關風險
- 用藥安全性
- 保健食品、中藥併用風險
LLM 負責：
- 問題解析 → 結構化查詢（疾病、HPO、藥物、成分等）
- 協調呼叫底層 API（Phase 1–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）

規劃 Phase 1 的技術選型
- 選擇 variant caller（如 GATK）與 reference genome 版本
- 選擇 annotation 工具（如 VEP 或 ANNOVAR）
建立基本 pipeline
- BAM → gVCF → joint VCF（trio）
- 加上基本 QC 報表
建置簡單的 Genomic Query 介面
- 先以 CLI/Notebook 函式為主（例如 Python 函式庫）
選一個你最關心的疾病領域
- 建立第一個 gene panel（例如視覺/聽力相關）
- 實作 panel-based 查詢與變異列表輸出
撰寫第一版報告模板
- 輸入：疾病名稱 + gene panel + 查詢結果
- 輸出：簡易 Markdown 報告（含變異表 + 限制說明）
逐步加入 ACMG 自動 evidence 標記與人工 review 流程

這個規格書預期會在實作過程中持續更新，可視此為 v0.1 的起點版本。

12 KiB Raw Blame History Unescape Escape

個人基因風險與用藥交互作用決策支援系統 – 系統規格書

0. 系統目標與範圍

0.1 目標

0.2 核心設計哲學

1. 發展階段與整體架構

1.1 發展階段總覽

1.2 高階架構圖（Mermaid）

2. 通用設計：人機分工標記

3. Phase 1：基因本體與變異詮釋基礎

3.1 功能需求

3.2 模組設計

3.2.1 Variant Calling Pipeline

3.2.2 Annotation Pipeline

3.2.3 Genomic DB / Query API

3.2.4 疾病/表型 → 基因 → 變異流程

3.3 ACMG 規則實作（初版）

4. Phase 2：基因藥物學（PGx）與藥–藥交互作用（DDI）

4.1 功能需求

4.2 模組設計

4.2.1 用藥資料標準化

4.2.2 PGx Engine

4.2.3 DDI Engine

5. Phase 3：保健食品與中藥交互作用模組

5.1 功能需求

5.2 模組設計

5.2.1 成分標準化引擎

5.2.2 成分交互作用引擎

6. Phase 4：NLP/LLM 問答介面與報告生成

6.1 功能需求

6.2 Orchestration 設計

7. 安全性、隱私與版本管理

7.1 資料安全與隱私

7.2 版本管理

7.3 人工介入紀錄

8. 未來擴充方向（Optional）

9. 第一階段實作建議路線（Actionable TODO）

12 KiB

Raw Blame History