complexa-binder-design

Complexa Binder Design（ワークフロー）

1 つのリクエスト「<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 et al., 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)

構成要素（必要に応じて参照 — インラインに展開しないでください）

ステップ	ツール	担当内容
標的とホットスポット	ベンダー提供の science-skills（UniProt、AFDB）+ scripts/	構造の解決、根拠に基づくホットスポット、≤500 のクロップ、事前チェック
生成	Proteina-Complexa complexa CLI	バインダーの配列と構造の共同設計、AF2 報酬ゲート → 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）を使って生成部分を進められます。このスキルでは、自動化されたステージ 1、独立した検証、GO／NO-GO 判定、およびマニフェストが追加されます。

ステージ 1 — 標的とホットスポットの解決（GPU 不要）

ユーザーが標的を名前、配列、および／または構造ファイルで指定します。 優先順位に従って、設計に使用できる構造を正確に 1 つ解決します：（1）実験で得られた PDB（RCSB）、（2）AFDB モデル（UniProt → vendor/science-skills/.../fetch_structure.py）、 （3）ユーザー提供ファイル、（4）de novo 折りたたみ（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） — 座標ファイルに存在しない残基を除外し、実際の 3 文字表記のアミノ酸名を読み戻します（UniProt と PDB の番号のずれを検出します。インデックスが同じ、またはチェーンが A だと決めつけないでください）。
• エピトープの妥当性確認（_prune_hotspots） — コンパクトなパッチを 1 つにします。クラスター重心から 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 報酬（AF2 パラメーターは setup_af2_params.sh + AF2_DIR で設定）を使うと、探索中に 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 では多くの候補が生成されます。フォールディングするのは、生成時／AF2 の報酬スコア上位から、要求された N の約 2 倍だけにしてください。プール全体を検証すると GPU と時間を浪費し、ホスト型 Boltz2 ではレート制限にもかかります。利用可能な場合は、$BOLTZ2_URL（--endpoint local）を使ってローカルの Boltz2 NIM を指定してください。

各バインダーについて、1 つのリフォルダー（デフォルトは Boltz2）で 2 回予測を実行します。ホロ（バインダー＋ターゲット。ターゲット MSA、バインダーは単一配列、write_full_pae）と、アポ（バインダー単独）です。1 つのコマンドで実行できます。scripts/boltz2_refold.py がホロ予測を呼び出し（レート制限に対するリトライ／バックオフを実施）、続けて scripts/validate_binders.py を実行します。このスクリプトはアポ予測を実行し、メトリクスを計算してゲートを適用し、順位付けを行います。チェーンごとの条件付けとメトリクスの定義については、references/validation.md を参照してください。

ゲート（デフォルト — すべての条件を満たす必要があります）： ipTM ≥ 0.65、複合体の pLDDT ≥ 0.70、バインダーの pLDDT ≥ 0.70、アポ状態のバインダーの pLDDT ≥ 0.70、ipSAE_min ≥ 0.45、アポ↔ホロ間のバインダー RMSD ≤ 2.5 Å、条件付けされたホットスポットのうち ≥ 20% に接触（CB–CB < 13 Å）。すべてのデザインについて、合格・不合格を問わず、failure_reason とともに記録してください。タンパク質バインダーは、界面の信頼度（ipTM/ipSAE）＋ pLDDT ＋安定性で順位付けしてください。Boltz2 の affinity_pic50（リガンド専用）は使わないでください。

予算を限定したループ＋レポート

成果物は、界面の信頼度で順位付けされた上位 N 件のバインダー（デフォルト 10 件）です。完全なゲートに合格する N 件を目指しますが、コストには上限を設けてください。生成ラウンドは 最大 2 回までとし、厳格なゲートを通過する候補が N 件未満でも、スコア（ipTM、次いで ipSAE_min）の上位 N 件を必ず提出してください。各デザインの pass／failure_reason フラグは維持し、品質が分かるようにします。厳格な合格件数を N 件まで増やすためだけに、生成を続けてはいけません（時間を最も浪費する要因です）。N 件合格／2 ラウンド／予算上限／合格ゼロのラウンドのいずれかで停止します。キャンペーンごとに実行ディレクトリを 1 つ用意します。manifest.json には、ターゲット、Complexa の実行設定とシード、デザインごとの系譜／スコア／成果物、ゲートの状態を記録します。レポートには GO／NO-GO、要求件数と達成件数（合格件数および提出件数）、順位付けされたバインダー、発動した停止条件を記載します。ディレクトリ構成、ループ、レポートのセクションについては、references/pipeline.md を参照してください。

設定

• COMPLEXA_REPO — ローカルの Proteina-Complexa チェックアウトへのパス（complexa CLI はその場所で実行されます）。チェックポイントはパイプライン 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 のパラメーターをダウンロード（公開、認証不要）し、 報酬誘導型検索（best-of-n など）用に params/ の構成を作成します。
• 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 を使用してください）。

責任ある利用

de novo バインダー設計にはデュアルユースの側面があります。病原体の適応度、毒素の効力、または生物兵器としての機能の強化を目的とする依頼には応じず、正当な研究および治療を目的とする設計に限定してください。

関連項目

• protein-binder-design — RFdiffusion + ProteinMPNN（BioNeMo NIMs）を用いて同じ目標を達成します。
• Proteina-Complexa のドキュメント：README.md、docs/INFERENCE.md、docs/CONFIGURATION_GUIDE.md、 docs/EVALUATION_METRICS.md、および上記リポジトリに同梱されている .claude/skills/。