complexa-target

complexa-target

Proteina-Complexa の設計ターゲットを追加または編集します。ターゲットは、complexa design パイプラインごとに 1 つずつ、3 つの YAML ファイルに格納されています。

• configs/targets/targets_dict.yaml — タンパク質バインダー（デフォルトのパイプライン）
• configs/targets/ligand_targets_dict.yaml — リガンドバインダー
• configs/design_tasks/ame_dict_v2.yaml — AME／酵素のスキャフォールディング

complexa target CLI で管理できるのは最初の 2 つだけです。AME タスクでは拡張スキーマ（リガンドターゲットと同じ基本フィールドに、残基ごとに手動でキュレーションしたモチーフ原子選択を指定する contig_atoms を追加したもの）を使用するため、ファイルを直接編集する必要があります。

推奨方法：YAML を直接編集する

complexa target add は、「YAML を読み込む → 辞書を作成する → ブロックを追加する」という処理を行う薄いラッパーです（src/proteinfoundation/cli/target_manager.py:add_target_cli と append_target_to_dict を参照）。エージェントから使用する場合は、ターゲット辞書を直接編集するだけで十分です。スキーマは短く、既存のエントリは優れたテンプレートとして使えるうえ、14 個の CLI フラグや SMILES のシェルエスケープを省略できます。CLI は、YAML の自動引用符付与機能や上書き確認による安全性を明示的に利用したい場合にのみ使ってください。

そのため、このスキルでは両方の方法を示します。

手順	ファイルを直接編集（推奨）	CLI
既存のターゲットを確認する	configs/targets/{,ligand_}targets_dict.yaml を読む（AME の場合は configs/design_tasks/ame_dict_v2.yaml）	complexa target list（タンパク質／リガンドのみ）
1 つのターゲットを確認する	辞書を読み、キーを grep する	complexa target show NAME
新しいターゲットを追加する	YAML ブロックを追加する（手順 3a）	complexa target add ...（手順 3b）
PDB がディスク上で解決されることを確認する	— (ショートカットなし。Hydra のデフォルト設定を確認します)	complexa validate target CONFIG --target NAME

complexa target で参照できるのは、タンパク質スタイルの 2 つの辞書（targets_dict.yaml と ligand_targets_dict.yaml）だけです。スキーマが異なる AME タスクでは、ファイル編集だけが可能な方法です。下記の手順 1 を参照してください。

このスキルでできること

• configs/targets/targets_dict.yaml に、タンパク質ターゲット（チェーン＋残基範囲＋ホットスポット）を登録します。
• configs/targets/ligand_targets_dict.yaml に、リガンドターゲット（PDB ポケット＋3 文字コード＋SMILES）を登録します。
• AME パイプライン用の適切な AME タスク名（例：M0024_1nzy、M0096_1chm）を特定します。これらは complexa target add では追加しません（手順 1 を参照）。
• complexa validate target で、ターゲットがディスク上の実在する PDB に解決されることを確認します。
• 下流の設計実行用に、再実行可能な成果物（target_definition.yaml）を生成します。

手順 1：ターゲットの種類を決める

ターゲットは、complexa design の各パイプラインに 1 つずつ、3 つの異なるファイルに格納されています。ユーザーが実行するパイプラインを特定してファイルを選び、そのファイルにエントリを追加してください。各ファイルは、それぞれ 1 つのパイプラインだけで使用されます。

ユーザーの目的	パイプライン	ターゲット辞書ファイル	このスキルの対象？
タンパク質表面に結合する（PD-L1、IFNAR2、TNF-α、…）— デフォルト	configs/search_binder_local_pipeline.yaml	configs/targets/targets_dict.yaml	はい — 手順 2（タンパク質）
小分子ポケットに結合する（FAD、SAM、OQO、…）	configs/search_ligand_binder_local_pipeline.yaml	configs/targets/ligand_targets_dict.yaml	はい — 手順 2（リガンド）
AME／酵素のスキャフォールディング（モチーフ＋リガンド、M####_<pdb> 形式の名前）	configs/search_ame_local_pipeline.yaml	configs/design_tasks/ame_dict_v2.yaml	一部対象 — 下記の「AME タスク」を参照

AME タスク（酵素パイプライン）

同様に、AME タスクは configs/design_tasks/ame_dict_v2.yaml の motif_target_dict_cfg: の下にあり、独自のスキーマ（source、target_filename、ligand、contig_atoms、binder_length、use_bonds_from_file）を使用します。contig_atoms 文字列には、"A64: [O, C]; A86: [CB, CA, N, C]; ..." のように、残基ごとのモチーフ原子の選択が記述されています。これらは手動でキュレーションされているため、新しい AME タスクの追加には CLI の実行ではなくファイル編集が必要です。ファイルを確認し、似たエントリをテンプレートとしてコピーしてから、++generation.task_name=<NAME> を complexa design configs/search_ame_local_pipeline.yaml に渡してください。

ステップ 2：必要な情報を集める

AskUserQuestion を使用して収集してください。推測してはいけません。必須フィールドは、タンパク質かリガンドかによって異なります。

タンパク質ターゲット

フィールド	質問	例	必須
name	「ターゲット名（dict のキーおよび task_name として使用）？」	02_PDL1、MyTarget_v1	はい
source	「$DATA_PATH/target_data/ 配下のソースディレクトリは？」	bindcraft_targets、custom_targets	はい（または target_path）
target_filename	「PDB ファイル名（.pdb 拡張子なし）？」	PD-L1、IFNAR2	はい（または target_path）
target_input	「チェーン＋残基範囲 — 書式についてはリファレンスを参照してください。」	A1-115、A1-50,B1-50	はい
hotspot_residues	「ホットスポット残基（界面の接触残基）は？」	["A33", "A95", "A102"]	任意、推奨
binder_length	「バインダーの長さの範囲 [min, max]、または単一の [length] は？」	[80, 150]、[100]	任意（デフォルトは [60, 120]）
pdb_id	「参照 PDB ID（任意、メタデータのみ）？」	"2lag"	任意

リガンドターゲット — 上記のタンパク質フィールド（target_input を除く）に加えて：

フィールド	質問	例	必須
ligand	「3 文字の PDB リガンド残基コードは？」	FAD、OQO、SAM	はい（指定するとターゲットがリガンドとして扱われます）
smiles	「リガンドの SMILES 文字列は？」	"O=C2C3=Nc1cc(c(...)..."	推奨
ligand_only	「リガンドの周囲にのみポケットを生成しますか（タンパク質間界面なし）？」	true / false	任意（デフォルトは true）
use_bonds_from_file	「入力 PDB/CIF の結合情報を使用しますか？」	true / false	任意（デフォルトは true）
target_input	リガンドターゲットでは不要	—	いいえ

dict を読み取る（rg '^ NEW_NAME:' configs/targets/targets_dict.yaml）か、complexa target list -v --ligand / --protein を実行して、名前が重複していないか確認してください。

ステップ 3a：YAML ブロックを直接追加する（推奨）

configs/targets/targets_dict.yaml（リガンドターゲットの場合は ligand_targets_dict.yaml）を開き、スタイルのテンプレートとして既存の類似エントリを探して、新しいブロックを target_dict_cfg: の下に追加します。インデントは 2 つのスペースとし、エントリ間には空行を 1 行入れます。

タンパク質テンプレート

  02_PDL1:
    source: bindcraft_targets
    target_filename: PD-L1
    target_input: "A1-115"
    hotspot_residues: ["A37", "A39", "A49", "A98"]
    binder_length: [64, 155]
    pdb_id: "4z18"

既存ファイルのスタイルに合わせるためのルール（complexa target add が出力する内容と同様）：

• チェーン／残基範囲（"A1-115"、"A33"）と SMILES は引用符で囲みます。囲まないと、フロースタイルの文字列で : や角括弧が問題を引き起こします。
• フロースタイルのリスト（["A33", "A95"]、[64, 155]）を使用します。ディスク上のダンプでもこの形式が出力されます。
• タンパク質では target_input、source、target_filename が必須です。PDB が $DATA_PATH/target_data/ の外部にある場合は、target_path（絶対パス）を使って source と target_filename を置き換えられます。

リガンドテンプレート

  41_7BKC_LIGAND:
    source: ligand_targets
    target_filename: 7BKC_ligand_centered
    hotspot_residues: [null]
    binder_length: [100]
    pdb_id: 7BKC
    ligand: 'FAD'
    ligand_only: True
    SMILES: "O=C2C3=Nc1cc(c(cc1N(C3=NC(=O)N2)CC(O)C(O)C(O)COP(=O)(O)OP(=O)(O)OCC6OC(n5cnc4c(ncnc45)N)C(O)C6O)C)C"
    use_bonds_from_file: True

ligand: キーが存在すると、ターゲットはリガンドモードになります。別個の is_ligand フラグはありません。リガンドでは target_input は不要です。

保存したら、ステップ 4 に進んで確認してください。

ステップ 3b：CLI を使用する方法（complexa target add）

チェーン／残基の引用符付けを自動化したい場合、上書き確認のプロンプトを利用したい場合、または Python 以外のスクリプトにターゲット作成を組み込みたい場合は、CLI を使用します。エージェントによる使用では、非対話モードを推奨します（-i / --editor はエディターを開き、処理をブロックします）。

確認済みのフラグ（src/proteinfoundation/cli/target_cli.pyから）

フラグ	型	対象	備考
name（位置引数）	str	両方	dict のキー
--dict PATH	path	両方	ターゲット dict のパスを上書きします
-i, --interactive	flag	両方	$EDITORを開きます
-e, --editor NAME	str	両方	code、nano、vim、cursor、...
--source NAME	str	両方	$DATA_PATH/target_data/配下のディレクトリ
--target-filename NAME	str	両方	PDB のステム（.pdbなし）
--target-path PATH	str	両方	フルパス。sourceとfilenameを上書きします
--target-input SPEC	str	タンパク質	チェーン／残基範囲。例：A1-115
--hotspot-residues R [R ...]	list	両方	例：A33 A95
--binder-length N [N ...]	int list	両方	[min, max]または[length]
--pdb-id ID	str	両方	メタデータのみ
--ligand CODE	str	リガンド	指定するとリガンドターゲットとして扱われます
--ligand-only	flag	リガンド	ポケットのみのモード
--smiles STR	str	リガンド	リガンドの SMILES
--use-bonds-from-file	flag	リガンド	PDB の結合を使用します
-f, --force	flag	両方	確認なしで既存の内容を上書きします

タンパク質の例

complexa target add 02_PDL1 \
  --source bindcraft_targets \
  --target-filename PD-L1 \
  --target-input A1-115 \
  --hotspot-residues A37 A39 A49 A98 \
  --binder-length 64 155 \
  --pdb-id 4z18

リガンドの例

complexa target add 41_7BKC_LIGAND \
  --source ligand_targets \
  --target-filename 7BKC_ligand_centered \
  --pdb-id 7BKC \
  --ligand FAD \
  --ligand-only \
  --use-bonds-from-file \
  --smiles "O=C2C3=Nc1cc(c(cc1N(C3=NC(=O)N2)CC(O)C(O)C(O)COP(=O)(O)OP(=O)(O)OCC6OC(n5cnc4c(ncnc45)N)C(O)C6O)C)C" \
  --binder-length 100

これらのデフォルト値を使用する理由：--sourceのデフォルトは、タンパク質の場合はcustom_targets、リガンドの場合はligand_targetsであり、--target-filenameのデフォルトはnameです。そのため、PDB のステムがターゲット名と異なる場合は、明示的に指定してください。リガンドターゲットでは、デフォルトで dict にligand_only: trueとuse_bonds_from_file: trueが設定されます。明示する場合はフラグを渡し、デフォルトを受け入れる場合は省略してください。

ステップ 4：検証

2つのチェックを順番に実行します。最初のチェックに失敗したら、そこで止めて修正してください。

# 1. Confirm the entry landed and looks right.
#    Direct read works just as well: `rg -A 7 '^  02_PDL1:' configs/targets/targets_dict.yaml`
complexa target show 02_PDL1

# 2. Resolve the PDB path and validate it exists on disk.
#    No shortcut for this — it traverses Hydra defaults to find the target dict.
complexa validate target configs/search_protein_local_pipeline.yaml --target 02_PDL1

complexa validate target（src/proteinfoundation/cli/validate.py::validate_targetから）は、以下をチェックします。

• DATA_PATHが設定され、target_data/が存在すること。
• ターゲット名がtarget_dict_cfgで解決されること。
• target_pathが存在するか、$DATA_PATH/target_data/<source>/<target_filename>.pdbが存在すること。
• target_input、hotspot_residues、binder_lengthが出力され、人が妥当性を確認できること。

リガンドターゲットの場合は、--targetにリガンドパイプライン設定（例：リガンド結合体の検索設定）を指定してください。

ステップ 5：成果物を出力

再実行可能な記録を./target_<name>/に保存します。

mkdir -p target_02_PDL1
complexa target show 02_PDL1 > target_02_PDL1/target_show.txt

次に、追記された YAML スニペット（complexa target addがtarget_dict_cfg:の下に書き込んだ行）を、Write ツールを使ってtarget_02_PDL1/target_definition.yamlに書き込みます。この成果物を使えば、実行ごとのターゲット定義を比較し、別のチェックアウトでcomplexa target add ... --forceを実行してエントリーを再作成できます。

ハードウェア要件

ターゲット定義には必要ありません。これは YAML の編集であり、トレーニング／推論のステップではありません。ディスク使用量は、ターゲット dict に追記される数 KB 分です（さらに、save_targets_dictによって.yaml.bakバックアップが自動的に作成されます）。

ターゲットを使用する後続の設計／評価の実行については、complexa-designおよび_shared/reference/hardware.mdを参照してください。

トラブルシューティング

症状	原因	解決方法
validate target で Target PDB file: File not found と表示される	$DATA_PATH/target_data/ に <source>/<target_filename>.pdb が存在しません	PDB の名前の部分と source ディレクトリを確認します。ファイルが target_data/ の外にある場合は、--target-path /full/path.pdb を使用します。
「Target 'X' already exists! Overwrite? (y/N)」と表示される	dict 内で名前が重複しています	別の名前を選ぶか、-f / --force を指定して上書きします。
ホットスポット残基が PDB にありません	chain または残基番号が正しくありません	PDB を開き、chain の文字（大文字と小文字を区別します）と残基インデックスを再確認します。ホットスポットは <CHAIN><RESNUM> 形式を使用します。リファレンスを参照してください。
Chain が見つかりません	target_input が、PDB に存在しない chain を参照しています	grep "^ATOM" target.pdb | awk '{print $5}' | sort -u で PDB を確認します。
リガンドコードが PDB にありません	3 文字の ligand コードが、ファイル内の HETATM 残基名として存在しません	PDB を開き、HETATM 行を確認します。PDB の _ligand_centered バリアントが必要な場合があります。
後続処理で SMILES の解析に失敗します	SMILES 文字列が正しくありません	追加する前に rdkit.Chem.MolFromSmiles(smiles) で検証します。ブラケットや括弧をエスケープするため、シェルでは SMILES を引用符で囲みます。
先頭が数字のターゲット名で Hydra の補間に失敗します	YAML では 02_PDL1 は問題なく文字列として扱われますが、一部のオーバーライド構文では引用符が必要です	++generation.task_name=02_PDL1 を使用します。シェルによって文字が取り除かれる場合は、引用符で囲みます。
リガンドターゲットで target_input が無視されるように見えます	仕様です。リガンドターゲットでは target_input を使用せず、リガンドによってポケットを定義します	リガンドターゲットでは設定しないでください。

リファレンス

• reference/target_schema.md — 各フィールド、chain 指定の文法、AME タスク名の文法、3 つの詳細な例。
• configs/targets/targets_dict.yaml — 現在のタンパク質エントリ（テンプレートとして、正常に動作する既知のエントリをコピーしてください）。
• configs/targets/ligand_targets_dict.yaml — 現在のリガンドエントリ。
• configs/design_tasks/ame_dict_v2.yaml — AME タスク定義（ファイル編集のみ。complexa target CLI では公開されていません）。
• src/proteinfoundation/cli/target_cli.py — argparse の信頼できる情報源。
• src/proteinfoundation/cli/target_manager.py — add_target_cli、list_targets、show_target、TARGET_FIELDS 内のスキーマ。
• src/proteinfoundation/cli/validate.py — validate_target の実装。