Unravel

<p align="center"> <img src="assets/unravel-logo.png" alt="Unravel — 基因组学 · 临床智能" width="560"> </p> # Unravel **关闭医学中长期悬而未决的诊断难题，为患者及其家人带来希望。** 由谷歌云快速代理黑客马拉松和Fivetran赛道驱动的五个Gemini 3.1代理组成的Agent Builder流程，监控通过 **Fivetran MCP** 同步的不断演变的变异证据，并在 **变异不确定性（VUS）** 被重新分类时，重新计算校准的ACMG后验概率，并草拟患者重新联系和家族级联测试的方案。这是目前尚无系统能够提供的功能。草案仅限，FHIR R4，人工干预。 为 **谷歌云快速代理黑客马拉松** · **Fivetran赛道** 构建。 - **实时演示（无需登录）：** https://unravel-ra.web.app · **API:** https://unravel-api-306681961993.us-central1.run.app - **3分钟视频：** _即将推出_ - **技术支持：** Gemini 3.1（Pro + Flash-Lite）· 谷歌ADK / 代理构建器 · Cloud Run · Fivetran MCP · BigQuery · Firestore（FHIR R4）· AlphaFold + AlphaMissense --- ## 问题 VUS意味着实验室无法确定变异是良性还是危险的，因此在临床上不会采取任何措施， *"如果有变化，我们会通知您。"* 但是证据在不断变化：很大一部分VUS在18个月到5年以上的时间里被重新分类，但目前尚无系统能够代表患者重新评估这些变异。当一个危险的变异被发现时，原始病例可能已经缓解或去世；由于生殖细胞变异是可遗传的，现在处于风险之中的生命是 **亲属** 的，家族级联测试从未提供。ACMG自己的话说，重新联系的义务是 *"理想但目前不可行。"* Unravel是关闭这一循环的主动层，**优先考虑家族级联测试** 和 **与疾病无关** 。 *(完整的故事和Diane的案例在 [使命页面](https://unravel-ra.web.app/mission) 上。)* --- ## 快速入门 > 需要谷歌云项目（Vertex AI，Cloud Run，BigQuery，Firestore，Secret Manager）和Fivetran账户。 ```bash # 后端：ADK代理 + API（Python 3.12） cd backend python3.12 -m venv .venv && source .venv/bin/activate pip install -r requirements.txt cp .env.example .env # 设置GOOGLE_CLOUD_PROJECT PYTHONPATH=. python scripts/seed_registry.py # 将FHIR队列播种到Firestore PYTHONPATH=. python -m pytest tests/ -q # 891个案例，全绿色 PYTHONPATH=. uvicorn server:app --reload --port 8000 # 前端：React + Vite SPA（代理/api到:8000） cd ../frontend && npm install && npm run dev ``` 打开 **http://localhost:5173/app**，选择一个标记的患者，运行监视循环。 `PYTHONPATH=.` 是必需的，以便 `unravel` 包导入。部署：将 `backend/` 容器化到Cloud Run； `npm run build` 到Firebase Hosting。 --- ## 架构 <p align="center"><img src="assets/architecture.png" alt="Unravel系统架构" width="100%"></p> 公共证据存储在GCS中，并通过Fivetran同步到一个精选的BigQuery视图。五代理系统（`SequentialAgent` 根：Watcher → Adjudicator → `ParallelAgent` 分支的Planner ‖ Cascade ‖ Steward，一个共享的Session）读取该视图，驱动Fivetran MCP以确保新鲜度，调用Vertex AI Gemini进行判断，拉取AlphaFold结构，并将草案FHIR写入Firestore。Firebase Hosting上的React SPA重写 `/api` 到Cloud Run（同源）。临床医生审批；不自动发送。 - **模型：** `gemini-3.1-flash-lite` （高频增量检测）； `gemini-3.1-pro-preview` （裁决，规划，草案）。 - **合作伙伴超能力（深度MCP）：** 循环将多个Fivetran MCP操作编织到其推理、鲜度检查和有针对性的重新同步中，此外还支持按需连接器创建，而不仅仅是一次令牌调用。 - **临床缝隙（FHIR R4）：** 当外部 **证据** 发生变化时（不是当EHR推送结果时），会触发该功能，读取FHIR患者注册表，并将 **草案** 写回 (`intent: proposal`)。HL7基因组学报告IG，无EHR修改。 - **控制台（React/Vite）：** 选项卡视图，监视列表，家谱，知识图，数据资源管理器（Fivetran控制面板），审批，审计跟踪，添加患者，以及一个扎根的“询问数据”助手和引导式游览。 --- ## 五个代理 五个真正的Gemini `LlmAgent` 在一个真正的ADK多代理流程中（`backend/unravel/agents.py`）。每个代理都读取前一个代理的输出，并调用确定性的 **FunctionTools** 进行可审计的工作，即大脑/手部分离。 | 代理 | 模型 | 工具 | 任务 | |---|---|---|---| | **1. 监视器** | Flash-Lite | `lookup_reclassification` ， `check_feed_freshness` | 分类检测到的变化；可以检查Fivetran的鲜度。 | | **2. 裁决者** | 3.1 Pro | `assemble_evidence` | 衡量引用的ACMG分类账 + 校准的后验概率与审查质量，并 **保留** 低置信度的翻转。 *护城河。* | | **3. 分辨率规划器** | 3.1 Pro | `rank_next_experiments` | 推荐单个最高收益的下一个实验，以ACMG货币表示。 | | **4. 级联协调器** | 3.1 Pro | `find_family` | 在可行的裁决下，为携带者 + 高风险亲属起草临床医生面对面的重新联系为草案FHIR。 | | **5. 管理者** | 3.1 Pro | `steward_assessment` | 将已故探针病例路由到伦理途径（从不一封信）；起草一个ClinVar归还。 | *为什么是代理系统，而不是cron作业：* 检测状态翻转是确定性的（一个工具）；判断是代理的，ClinVar带有不同星级水平的冲突提交，正确地 **保留** 一个1星翻转，同时对同一个分子后验概率下的3星翻转采取行动，这是真正的推理，阈值无法做到。 --- ## 黑客马拉松要求（快速代理 · Fivetran赛道） | 要求 | Unravel如何满足它 | |---|---| | **Fivetran目的地** | 三个 **GCS → BigQuery** 连接器登陆ClinVar，gnomAD和AlphaMissense；一个精选的视图（`backend/sql/variant_evidence.sql`）将它们建模为智能数据平面，代理查询。还部署了一个自定义的 **Connector SDK** 连接器。 | | **Fivetran MCP服务器** （硬要求） | 官方的 `fivetran-mcp` 服务器被编译到Cloud Run镜像中，并在实时运行：每次裁决前进行鲜度检查（`get_connection_state`），有针对性的重新同步（`sync_connection`），暂停/恢复（`modify_connection`），以及按需连接器 **创建** （`create_connection`）用于基因上线。 `backend/unravel/fivetran_mcp.py`。 | | **谷歌云AI** | Gemini 3.1 Pro + Flash-Lite（Vertex AI），作为一个五代理 **谷歌ADK（代理构建器）** 系统编排。 `backend/unravel/agents.py`。 | | **端到端** | Fivetran MCP → BigQuery → 五个ADK代理（鲜度检查）→ 草案FHIR临床行动，均在实时仪表板上。 | | **人工干预** | 每个临床输出都是一个 **草案** FHIR资源，由临床医生批准；每个Fivetran写入都由明确的应用程序内批准和记录。 | | **Fivetran上的代理CRUD** | 数据资源管理器是一个实时控制面板：列出，健康检查，暂停，恢复，同步，创建连接器。 | | **可复制性** | `backend/scripts/setup_fivetran.py` 通过MCP重新创建连接器； `sql/variant_evidence.sql` 重新创建视图。 | | **工作部署** | 在 **unravel-ra.web.app** （SPA）+ Cloud Run API上实时运行。 | --- ## 校准的贝叶斯模型 后验概率是ACMG/AMP指南（Tavtigian 2018/2020）的已发布、基于点的贝叶斯公式，在 `backend/unravel/acmg.py` 中，不是一个我们发明的置信度： ``` OddsPath = 350 ^ (points / 8) Posterior = (Prior x OddsPath) / (1 + Prior x (OddsPath - 1)) # Prior = 0.10 ``` 对ACMG点数进行求和并应用公式可以重现ClinGen锚点概率至 **0.0001** 以内（由 `backend/eval/calibration.py` 验证）： | ACMG点数 | 带 | 后验概率 | |---|---|---| | 0 | （先验） | 0.10 | | +6 | **可能致病** （可行的界限） | 0.90 | | +10 | **致病** | 0.994 | | −7 | **良性** | ~0.001 | **证据映射。** gnomAD等位基因频率 → `PM2` / `BS1` / `BA1` 。 AlphaMissense → `PP3` / `BP4` 在ClinGen推荐的校准强度（Pejaver 2022）下，上限为支持证据，绝不作为分类器，并 **降低一级** 以减轻预测偏差（Pathak 2024; Livesey & Marsh 2024）。 ClinVar断言故意 **不** 转换为积分（避免声誉不佳的PP5/BP6双重计算）；其审查状态作为上下文传递，即1星保留所在的位置。 家族证据（`PP1`，`PS3`）来自FHIR注册表。 > 参考：Richards 2015; Tavtigian 2018, 2020; Pejaver 2022, Bergquist 2025; Thompson 2014. 提交的完整参考文献列表。 --- ## 评估 真正的测试是AI的判断，而不是确定性的管道，所以这是头条。 - **代理护城河，实时模型** （`backend/eval/adjudicator_eval.py`）：在分子后验概率 **相同（0.81）** 的情况下，Gemini 3.1 Pro裁决者获得了 **12 / 12** ，跨越8个基因，对每个3星专家升级采取行动， **保留** 每个1星冲突的升级，缓和每个良性降级。 （根据临床原则，而不是每个案例的答案，因此衡量的是泛化判断。） - **校准：** 重现ClinGen锚点至 **0.0001** 。对 **31,432个真实的Lynch变异** 的检查显示，仅计算证据不足以分类（Brier 0.20），这就是为什么AlphaMissense被限制为支持。 - **规模 + 安全** （600患者合成FHIR队列携带具有真实ClinVar重新分类历史的变异，16个基因）： **0** 个假警报在 **48** 个硬负样本（文本变化，非类别）上，1星陷阱的保留召回 **1.0** ，无危险升级， **pytest套件74个函数/ 891个案例，全绿** 。 > 头条（实时裁决者的判断，在31,432个真实变异上的校准）是独立且非平凡的；确定性步骤作为正确性检查被验证。带有真实变异的合成患者：一个研究原型，经过严格评估，尚未经过临床验证。 --- ## 安全 - **仅草案，面向临床医生，从不面向患者，从不自主。** 界限是 *通知，不是行动* 。 - **设计为不对称：** 可行的升级大声疾呼，常见的VUS→良性降级作为安慰。出处是第一类（单一提交者断言不是ClinGen专家小组）。 - **设计为隐私保护：** 仅使用合成数据，因此不处理任何PHI；准备好合规，不声称合规（我们不声称的审计状态）。预测偏差被披露和控制，而不是声称已修复。 --- ## 数据源 - **证据（真实，公共）：** ClinVar（断言 + 审查星级），gnomAD v4（等位基因频率），AlphaMissense（硅基错义），AlphaFold（结构）。已注册的基因从Fivetran同步的仓库中提供；任何其他基因都从公共公共领域解析（Ensembl VEP + gnomAD + ClinVar），因此该系统与疾病无关。 - **患者（合成）：** 一个演示队列，包含五个具有真实家谱的携带者（Diane Marchetti，MLH1 c.114C>G，一个真实的重新分类； Mei Tanaka，相同的变异，祖先公平臂；一个1星“陷阱”；一个良性降级；一个已故探针伦理案例）。不使用真实的患者数据。 --- ## 仓库布局 ``` backend/ unravel/ 引擎：acmg（贝叶斯后验），证据（分类账）和实时证据 （与疾病无关的公共API备用），检测，注册表（FHIR + Firestore）， 裁决者（Gemini），规划器，级联，管理者，结构（AlphaFold）， fivetran_mcp，注册（基因推广），审计（持久日志）， 助手（只读基础解释器，闪存），监视（编排） connectors/ 一个自定义Fivetran Connector SDK连接器（gnomAD），实时部署 scripts/ 数据提取器，注册表播种器，Fivetran设置 + MCP烟雾测试 sql/ 统一的BigQuery证据视图 tests/ pytest套件（74个函数，891个案例，全绿） server.py FastAPI：/api/cohort，/run-loop（+stream），/pedigree，/graph，/patient， /structural，/freshness，/resync，/fivetran/pause，/warehouse， /onboard（+status），/audit，/approve，/assist frontend/ src/pages/ 目标页，技术页，使命页，应用仪表盘（监视列表，资源管理器， 审批，审计视图） src/dash/ 图形视图，家谱视图，结构查看器，添加患者表单， 助手小部件（询问数据），引导式游览 src/api.ts 类型化的API客户端 ``` --- ## 构建（合规） 根据黑客马拉松的产品需求规则，Unravel完全构建在 **谷歌云AI** （Gemini，谷歌ADK / 代理构建器，Vertex AI，Cloud Run，BigQuery，Firestore，Secret Manager，Firebase Hosting）和 **Fivetran** 合作伙伴的MCP服务器上。未使用竞争云或AI服务。 ## 许可证 [Apache-2.0](./LICENSE)。开源且免费用于商业用途。