complexa-binder-design

Complexa Binder 设计（工作流）

从一个请求——“为 <target> 设计结合蛋白”——到经过排序且独立验证的结合蛋白。返回的每个结合蛋白都是一个共同设计的序列 + 预测的结合蛋白–靶标复合物，并且经过界面置信度、结合蛋白是否实际接触靶标热点，以及脱辅基／全息状态稳定性的筛选。

生成使用 Proteina-Complexa（共同设计结合蛋白序列和全原子结构——无需反向折叠步骤——并采用奖励引导的测试时搜索）。验证使用不同的模型系列（Boltz2 / OpenFold3），因此关键置信度指标是独立检查，而不是让生成模型给自己的作业打分。

上游模型 + 代码（由你提供）：

• 项目页面：https://research.nvidia.com/labs/genair/proteina-complexa/
• 代码：https://github.com/NVIDIA-Digital-Bio/Proteina-Complexa（complexa CLI）
• 权重（NGC）：nvidia/clara/proteina_complexa
• 论文：Didi 等，Scaling Atomistic Protein Binder Design…，ICLR 2026。

首次在主机上使用？→ references/setup.md——完整的独立设置指南，无需 NIM：安装 Proteina-Complexa + 下载权重、Python 依赖项（numpy biotite pyyaml）、AF2 配置或绕过、可选分析工具（foldseek/sc/dssp）、Boltz2/OF3 验证端点，以及所有环境变量。然后运行 bash scripts/check_setup.sh，一次性检查就绪状态。

Stage 1: Resolve target + hotspots            → target.pdb + hotspots.json   (no GPU)
        ┌──────────────────────────────────────────────────────────────────────┐
        │ repeat until ≥ N validated passers (or a stop cap):                    │
Stage 2 │   Generate (complexa design) → complex .pdb + AF2-reward-gated designs │
Stage 3 │   Validate (Boltz2 default; OF3 optional) → holo+apo + ipTM/ipSAE/     │
        │     pLDDT + apo↔holo RMSD + hotspot contact → passers                  │
        └──────────────────────────────────────────────────────────────────────┘
Stage 4: Report                               → REPORT_<target>_<run>.md (GO/NO-GO)

组合组件（按需阅读——不要内联）

步骤	工具	负责内容
靶标 + 热点	vendored science-skills（UniProt、AFDB）+ scripts/	结构解析、基于证据的热点、≤500 裁剪、预检
生成	Proteina-Complexa complexa CLI	共同设计结合蛋白序列 + 结构、AF2-reward 筛选 → references/complexa-cli.md
验证／评分	boltz2-nim（默认）或 openfold3-nim	独立的全息状态 + 脱辅基状态重新折叠、ipTM / pLDDT / PAE
MSA（靶标）	msa-search-nim 或 scripts/fetch_target_msa_colabfold.py	用于提高重新折叠置信度的靶标 A3M

如果你在 Proteina-Complexa 仓库内运行，其捆绑的 .claude/skills （complexa-setup、complexa-target、complexa-design）可驱动生成部分；此技能额外提供自动化的 Stage 1、独立验证、GO/NO-GO 判定以及清单文件。

阶段 1 — 确定目标和热点（无需 GPU）

用户通过名称、序列和／或结构文件给出目标。 按优先级顺序，准确解析出一个可用于设计的结构：(1) 实验PDB（RCSB），(2) AFDB 模型（UniProt → vendor/science-skills/.../fetch_structure.py）， (3) 用户提供的文件，(4) 从头折叠（MSA-Search + OpenFold3/Boltz2）。 scripts/pipeline.py:resolve_target_spec/resolve_target 可从 自由文本自动完成 (1)–(2)。

热点 = 结合剂应接触的目标残基，即紧凑、暴露于表面且结合剂可及的表位。按证据优先级确定（scripts/hotspot_strategy.py、scripts/pdb_interface.py）：

1. PDB 共复合物界面（金标准）——来自目标与蛋白质伙伴接触的结构中的界面残基。
2. UniProt 功能残基——Mutagenesis + 可及的 Active/Binding/Site， 筛选至细胞外／可及区域（催化／细胞质口袋不是结合剂要结合的表面，应予以剔除）。
3. 文献（Paperclip）——当 1–2 为空时进行全文挖掘 （prompts/hotspot_paperclip.md）；通过结构确认自动校正编号。
4. 无条件（[]）仅作为有记录的最后手段。

然后按确定性规则执行：

• 结构比对（align_hotspots_to_structure）——剔除坐标文件中不存在的残基；读取实际的三字母标识（可发现 UniProt↔PDB 编号偏移——绝不假定索引相同或链为 A）。
• 表位合理性检查（_prune_hotspots）——保留一个紧凑区域：剔除距离簇中心 > 30 Å 的离群点，最多保留 15 个残基，优先保留 ≥ 2 个。
• 大小预算 ≤ 500 个残基（_crop_target_to_epitope）——Complexa 会针对整个复合物构建 O(n²) 对特征映射，因此要将大型目标裁剪到表位窗口（保留原始编号）。

预检（无需 GPU）： python3 scripts/preflight_design.py <name|accession> … 会报告条件化长度、重新比对后的热点及其来源、紧凑性、≤500 的预算，以及 READY / NEEDS-ATTENTION 判定。使用 GPU 前请先检查。

阶段 2 — 生成（Proteina-Complexa，开放 CLI）

注册目标（热点 + 结合剂长度由目标字典驱动），然后使用精简快速路径 complexa generate（而非完整的 complexa design）：

python scripts/complexa_design.py run --task-name <name> --run-name <run> \
    --algorithm best-of-n --num-samples <N> --seed 0 --out <run-dir>

complexa_design.py run 默认使用 generate 动词。搭配 best-of-n 和 AF2 奖励（通过 setup_af2_params.sh + AF2_DIR 配置 AF2 参数），搜索会在生成过程中通过 AF2 选择最佳候选，并将联合设计的序列 + 结构 PDB 写入 inference/——直接使用该序列，不要用 MPNN 重新设计。搜索算法：best-of-n（默认）· beam-search · fk-steering · mcts。覆盖选项 + 输出：references/complexa-cli.md。

此工作流中不要运行完整的 complexa design。 其 evaluate 阶段会用 AF2/RF3/ESMFold 重新折叠每个设计（多余操作——best-of-n 已在搜索期间通过 AF2 完成选择**）**，而其 analyze 阶段需要 foldseek/sc（通常未安装）。这会显著拖慢流程，并增加一种失败模式。精简的 generate → 独立 Boltz2 验证（阶段 3）才是预期路径。

没有 AF2 参数？使用 --af2-bypass（single-pass + 移除 AF2 奖励）；之后将完全由独立的 Boltz2 关卡（阶段 3）进行筛选。低复杂度（poly-X）序列会在运行 Boltz2 前剔除。

阶段 3 — 验证（独立重新折叠）+ 门控

验证经过限制的候选名单，而不是整个候选池。 Best-of-n 会生成大量候选；只折叠约为所需 N 的 2 倍（按生成奖励/AF2 奖励排名靠前的候选）——验证整个候选池会浪费 GPU/时间，而且（使用托管 Boltz2 时）会触发速率限制。如果条件允许，请通过 $BOLTZ2_URL 指向本地 Boltz2 NIM（--endpoint local）。

对每个 binder 使用同一个折叠器（默认 Boltz2）运行 两次预测：holo（binder + target；target MSA、binder 单序列、write_full_pae）和 apo（仅 binder）。一条命令即可完成：scripts/boltz2_refold.py 执行 holo 调用（针对速率限制进行重试/退避），然后调用 scripts/validate_binders.py，后者运行 apo、计算指标、应用门控并排名。关于链条件设置和指标定义，请参阅：references/validation.md。

门控（默认值——所有条件都必须满足）： ipTM ≥ 0.65、complex pLDDT ≥ 0.70、binder pLDDT ≥ 0.70、apo binder pLDDT ≥ 0.70、ipSAE_min ≥ 0.45、apo↔holo binder RMSD ≤ 2.5 Å、至少 20% 的条件化热点与之接触（CB–CB < 13 Å）。为每个设计（通过和未通过）记录 failure_reason。按界面置信度（ipTM/ipSAE）+ pLDDT + 稳定性对蛋白 binder 排名——不要使用 Boltz2 affinity_pic50（仅适用于配体）。

有限预算循环 + 报告

交付内容是按界面置信度排名的前 N 个 binder（默认 10）。目标是让 N 个 binder 通过完整门控，但要控制成本：最多运行 2 轮生成，然后按分数（先 ipTM，再 ipSAE_min）交付前 N 个，即使通过严格门控的数量少于 N 也一样——保留每个设计的 pass/failure_reason 标记，以便仍能看出质量。不要为了凑够 N 个严格通过的结果而持续生成（这是最耗时的一项）。在达到 N 个通过、运行 2 轮、预算耗尽或某一轮没有任何通过结果时停止。每个 campaign 使用一个运行目录；manifest.json 记录 target、Complexa 运行配置与种子、每个设计的 lineage/分数/产物及门控状态。报告说明 GO/NO-GO、请求与实际达到的 N（通过数和交付数）、排名靠前的 binder，以及触发了哪项停止条件。目录布局、循环和报告章节：references/pipeline.md。

配置

• COMPLEXA_REPO — 本地 Proteina-Complexa 检出目录的路径（complexa CLI 在此运行）。通过 pipeline YAML 或 ++ckpt_path=… 指定检查点。奖励 权重（AF2_DIR、RF3_CKPT_PATH/RF3_EXEC_PATH）通过仓库的 .env 配置。
• Boltz2 / OpenFold3 端点 + 身份验证：托管端点（https://health.api.nvidia.com/v1/…
  • NVIDIA_API_KEY）或本地端点（http://localhost:8000/…，无需身份验证）。验证器 接受 --endpoint hosted|local；密钥从 NVIDIA_API_KEY/NGC_API_KEY 读取 （或通过 --env-file 指定）。不要硬编码主机地址/密钥。
• COMPLEXA_OUTPUTS — 运行输出根目录（默认 ./outputs）。

脚本与资源

• references/setup.md + scripts/check_setup.sh — 独立安装指南（无需 NIM） 和一次性环境就绪检查。
• scripts/pipeline.py — 编排器（Stage-1 解析 + open-CLI 生成 + AF2 门控 + 评分）；支持 score_existing 和 full 模式。
• scripts/preflight_design.py — 无 GPU 的靶点／热点／尺寸规划器。
• scripts/hotspot_strategy.py、scripts/pdb_interface.py — 基于证据的热点。
• scripts/complexa_design.py — 轻量级 complexa design 驱动程序 + 输出提取。
• scripts/setup_af2_params.sh — 下载 AF2-Multimer 参数（公开，无需认证）+ 创建 params/ 目录结构，用于奖励引导搜索（best-of-n 等）。
• scripts/boltz2_refold.py — Stage-3 holo Boltz2 重折叠（重试／退避 + 限流） → validation/raw/，随后调用 validate_binders.py。
• scripts/validate_binders.py — apo Boltz2 + 评分、ipSAE、apo↔holo RMSD、 热点接触、门控、排序 → ranked_binders.json。需要 Dunbrack ipSAE 脚本：bash scripts/fetch_ipsae.sh（MIT；下载而非随包提供 — 参见 vendor/ipsae/）。
• scripts/fetch_target_msa_colabfold.py、scripts/pdb_to_boltz_template_cif.py — 用于验证的靶点 MSA／结构模板辅助工具。
• vendor/science-skills/ — 用于 Stage 1 的 DeepMind UniProt + AFDB 工具（Apache-2.0）。
• prompts/hotspot_paperclip.md — 文献挖掘热点的备用方案。
• assets/targets.json — 示例已注册靶点（可用 complexa target add 添加自己的靶点）。

负责任地使用

从头设计结合剂具有双重用途。对于旨在增强病原体适应性、毒素效力或生物武器功能的请求，应予以拒绝；设计应仅用于正当研究和治疗目的。

另请参阅

• protein-binder-design — 通过 RFdiffusion + ProteinMPNN（BioNeMo NIMs）实现相同目标。
• Proteina-Complexa 文档：README.md、docs/INFERENCE.md、docs/CONFIGURATION_GUIDE.md、 docs/EVALUATION_METRICS.md，以及上述仓库中随附的 .claude/skills/。