Orchidea Science

抗体研发科学算法引擎 —— Orchidea 平台的「科学计算层」。

把仪器产出的原始数据（NGS FASTQ、流式 FCS、SPR/BLI 传感图、质谱谱图）与 科研序列数据，转化为可被管理闭环消费的结构化结论（CDR 序列、效价、KD、 Tm、表位风险、群体比例、二级结构……）。

定位：LLM 是「调度者」，本引擎是「计算者」。凡涉及蛋白质折叠、结合动力学、 序列注释、群体门控等确定性计算，均由本引擎完成，而非交给语言模型。

2026-11 能力更新（v1.1.0）

• 结构预测：ESMFold（单序列端到端、逐残基 pLDDT）与 IgFold 真实适配
• 分子对接：DiffDock / AutoDock Vina 真实姿态搜索
• 免疫原性与注释：NetMHCpan 真实 CLI 调用、IgBLAST（AIRR）序列注释
• 存储：新增 S3 存储后端与测试
• 诚实降级：后端缺失或失败时如实回落并写入 warnings，绝不伪造

一、设计原则

二、引擎清单

统一契约：run(payload: dict) -> EngineResult。

二·补、原始数据存储层

方案要求「原始数据接入与存储」。io 层负责解析，storage 层负责落盘与检索， 二者共同构成原始数据闭环：

仪器原始文件 ──io 解析──▶ 结构化对象 ──storage 落盘──▶ 内容寻址 blob + SQLite 索引
                                          │
                                    path_for() ──▶ 交回 io/引擎 再解析（闭环）

• 内容寻址：payload 按 sha256 存入 blobs/<前2位>/<sha256>，相同内容自动去重。
• 记录独立：每次 put 生成独立 dataset_id（同内容不同样本互不覆盖）。
• 索引：index.sqlite3（纯标准库 sqlite3），记录种类/名称/大小/记录数/创建时间/自定义元数据。
• 完整性：verify 重算 sha256 比对，可检出落盘篡改。
• 默认根目录：$ORCHIDEA_SCIENCE_STORE 或 ~/.orchidea/science。

from orchidea_science.storage import RawDataStore
from orchidea_science.io.fcs import read_fcs

store = RawDataStore()
meta = store.put_fcs("sample.fcs", meta={"project": "SAIYEE-01"})
fcs = read_fcs(store.path_for(meta.dataset_id))   # 存储 → 分析 闭环

三、安装

# 核心（离线可用，仅 numpy + scipy）
uv pip install -e .

# REST 网关
uv pip install -e ".[api]"

# 重型后端（按需，隔离区用内网源离线安装）
uv pip install -e ".[bio]"         # Biopython
uv pip install -e ".[structure]"   # torch（IgFold / ESMFold 依赖）
uv pip install -e ".[spectra]"     # pyopenms
uv pip install -e ".[cytometry]"   # flowkit

# 开发
uv pip install -e ".[dev]"

要求 Python ≥ 3.9。

四、快速开始

4.1 命令行

# 列出全部引擎
orchidea-science-cli engines

# 查看某引擎能力
orchidea-science-cli describe curve_fit

# 运行引擎（ELISA 效价）
orchidea-science-cli run curve_fit --payload '{"model":"elisa_4pl","points":[[0.1,0.06],[0.5,0.9],[1,2.1],[5,2.95]]}'

# 序列分析
orchidea-science-cli run sequence_analyze --payload '{"sequence":"EVQLVESGGGLVQPGGSLRLSCAASGFNIKDTYIHWVRQAPGKGLEWVARIYPTNGYTRYADSVKGRFTISADTSKNTAYLQMNSLRAEDTAVYYCSRWGGDGFYAMDYWGQGTLVTVSS"}'

# 可选后端可用性
orchidea-science-cli backends

# 人源 germline 参考库运维（离线优先）：预联网预热缓存 / 导出便携 JSON
orchidea-science-cli germline fetch  --source ogrdb:human            # 下载并缓存（人类 IGH/IGK/IGL V 基因）
orchidea-science-cli germline list   --cache ~/.cache/orchidea-science/germline
orchidea-science-cli germline export --source ogrdb:human:IGH --out germline_igh.json

# 启动 REST 网关
orchidea-science-cli serve --host 0.0.0.0 --port 8100

4.2 REST API

curl -s localhost:8100/health
curl -s localhost:8100/api/v1/engines
curl -s -X POST localhost:8100/api/v1/engines/curve_fit/run \
  -H 'Content-Type: application/json' \
  -d '{"payload":{"model":"elisa_4pl","points":[[0.1,0.06],[0.5,0.9],[1,2.1],[5,2.95]]}}'

4.3 Python

from orchidea_science import registry

result = registry.run("curve_fit", {
    "model": "elisa_4pl",
    "points": [[0.1, 0.06], [0.5, 0.9], [1, 2.1], [5, 2.95]],
})
print(result.ok, result.backend, result.data.get("ec50"))

4.4 MCP（供 Agent 调用）

python3 -m orchidea_science.mcp.server

暴露工具：science_list_engines / science_describe_engine / science_run_engine / science_backends。在 orchidea-director 中登记后， 工具名形如 mcp__science__science_run_engine。

五、离线 / 隔离区部署

隔离区（离线内网 GPU 服务器）
  ├── orchidea-science（本包）—— 纯 CPU 引擎 + 结构预测（GPU 可选）
  ├── 内网 PyPI/conda 镜像（devpi / Nexus）
  └── 模型权重 + 参考数据库（经「交换区」下载杀毒后摆渡）

要点：

1. 一次性离线导入：依赖包与模型权重在交换区下载、杀毒后摆渡进隔离区，之后永久断网。
2. 内网私有源：隔离区内以 pip install --index-url http://<内网源> 安装。
3. 分级启用：一期只启用纯 Python 引擎（曲线拟合、序列分析）；二期上轻量结构后端（IgFold / ESMFold）；三期上 AlphaFold2 全量与分子设计。

六、目录结构

orchidea-science/
├── orchidea_science/
│   ├── core/           核心框架（引擎抽象、注册表、后端探测、异常、执行护栏 guard）
│   ├── io/             原始数据接入（FASTQ / FCS / FASTA）
│   ├── storage/        原始数据存储（内容寻址 blob + SQLite 索引）
│   ├── engines/        12 个科学算法引擎
│   ├── viz/            可视化视图层 + 内置演示页（Chart.js / 3Dmol.js）
│   ├── utils/          配置中心（config）与结构化日志（logging）
│   ├── api/            REST 网关 + 认证 + 限流 + 指标 + 中间件 + 生命周期
│   ├── mcp/            stdio MCP Server
│   ├── cli/            命令行工具
│   ├── service.py      服务层：护栏 + 日志 + 统一错误契约（唯一调用入口）
│   └── registry.py     默认引擎装配（12 引擎）
├── tests/              单元与集成测试
├── docs/               部署指南 / 运维手册
├── deploy/             K8s 清单与部署说明
├── Dockerfile          多阶段镜像（非 root + 健康检查）
├── docker-compose.yml
├── .env.example
├── .github/workflows/  CI（多版本矩阵 + 部署工件校验）
├── SPEC.md             引擎接口规范
└── pyproject.toml

七、平台集成（Orchidea Director）

科学引擎以 stdio MCP Server 形式接入 Orchidea Director，工具名形如 mcp__science__science_run_engine。已作为内置默认上游端点登记在 orchidea-director/bridge/gateway/src/upstream-mcp.ts：

可用 ORCHIDEA_MCP_ENDPOINTS 覆盖或禁用；端点不可达时仅不贡献工具，不影响其余服务。

八、生产运行

网关已具备生产级防护与可观测性（详见 docs/deployment.md 与 docs/operations.md）。

生产就绪状态、能力边界与上线前检查表见 PRODUCTION_READINESS.md； 版本演进记录见 CHANGELOG.md。

8.1 环境变量

前缀统一为 ORCHIDEA_SCIENCE_：

8.2 安全与限流

• 认证：仅当设置 API_KEY 时启用；比较使用常量时间算法。
• 限流：按客户端（API Key 优先，否则 IP）令牌桶；限流先于认证，未认证洪泛同样受限。
• 护栏：请求体上限（413）+ 引擎执行超时（线程池受控，避免耗尽）。

8.3 可观测性

8.4 部署

# 本地
orchidea-science-cli serve --port 8100

# Docker
docker build -t orchidea-science:1.0.0 .
docker run -p 8100:8100 -e ORCHIDEA_SCIENCE_API_KEY=$(openssl rand -hex 24) orchidea-science:1.0.0

# Kubernetes
kubectl apply -f deploy/k8s/

生产务必设置 API_KEY（启动日志会在未设置时告警），并按 docs/operations.md 配置告警规则。

8.5 可视化与三维结构

内置可视化演示页：启动服务后打开 http://127.0.0.1:8100/viz。页面用 Chart.js 渲染曲线/散点/棒状谱/区段轨道，用 3Dmol.js 渲染三维分子。

三维分子结构：结构预测已接入 IgFold（权重随包内置、离线可跑，CPU 约 1s/条）与 ESMFold（fair-esm + openfold，单序列端到端，CPU 约 20s/条·120aa，自动兼容新版 openfold 的 Linear 命名）。当 structure_predict 返回真实 PDB 时，演示页的 3D 查看器会渲染 cartoon 结构（spectrum 着色）；无后端时 pdb=null 并显示明确提示（绝不伪造坐标）。

深链：orchidea_science.viz.deeplink(engine, payload) 可生成 /viz#engine=<e>&payload=<base64url>，让桌面端把「本次真实结果」（含 IgFold PDB） 直接带到演示页渲染。

九、测试

python3 -m pytest -q