complexa-setup

Complexa セットアップスキル

新しい Proteina-Complexa のチェックアウトで設計を実行する前に必要な3つの手順、.env の作成、モデルウェイトの取得、環境の健全性チェックを行います。まずホストの GPU、ディスク、ツールバイナリを調べ、パイプラインの途中で依存関係の不足が判明するのを防ぎます。最後に JSON セットアップ成果物を作成し、ユーザー（または将来のエージェント）が状態を再確認できるようにします。

CLI とファイルの直接編集 — 手順ごとに最も手軽な方法を選ぶ

手順	推奨方法	理由
.env の作成（手順 2）	ファイル編集（cp .env_example .env + 3つの行の置換）または complexa init	complexa init は cp + 3 regex swaps（cli_runner.py の _swap_runtime_in_env）を行う薄いラッパーです。どちらの方法でも問題ありません。初めて使う人には CLI、エージェントには直接編集を選びます。
.env の値の編集（手順 3）	ファイル編集（LOCAL_CODE_PATH=… などを StrReplace）	これには CLI がありません。値はユーザーごとに異なるパスだからです。
モデルウェイトのダウンロード（手順 4）	CLI（complexa download --…）	env/download_startup.sh（NGC URL、再試行、チェックサム形式の存在確認を含む約1000行の bash）を実行します。これを再現しようとしないでください。
環境の検証（手順 5）	CLI（complexa validate env）または test -f .env && test -d $DATA_PATH	CLI のほうが読みやすいレポートを出力します。手動チェックは1行で実行できます。
設計設定全体の検証（パイプラインの選択後）	CLI（complexa validate design CONFIG）	Hydra のデフォルト設定の複雑な走査に加え、ckpt と環境変数もチェックするため、再現する価値はありません。

このスキルでできること

• UV または Docker ランタイム用の正しい形式の .env を作成します。
• Complexa のタンパク質／リガンド／AME モデルとコミュニティモデルのチェックポイントを、既知のパスにダウンロードします。
• ホスト（GPU、ディスク、.env、ckpt、ツールバイナリ）のスナップショットである preflight.json を作成します。
• 使用した complexa init と complexa download の呼び出しを正確に記録した run_manifest.json を作成します（再実行しやすい形式です）。
• complexa validate env の合否レポートと、次の手順に関する明確なヒントを出力します。

手順 1：事前チェック

環境に手を加える前に、必ず共通の事前チェックを実行してください。.env がなくても実行でき、デフォルト値にフォールバックします。また、ホストで Complexa を実行できるかどうかを確認できます。

bash .claude/skills/_shared/scripts/preflight.sh

スクリプトは ./complexa_setup/preflight.json に書き込みます。これを読み取り、次の情報を提示してください。

• gpu.available — false の場合、設計／評価の手順は失敗するため、ユーザーに警告します。
• gpu.vram_gb — Complexa には 40 GB 以上（A100/H100/L40S）が必要です。
• CKPT_PATH にある disk.free_gb — Complexa とコミュニティモデル一式には、約50 GB以上の空き容量が必要です。
• env.missing_required — ここに記載された項目は、検証に合格する前に .env で編集する必要があります。
• tools.{foldseek,mmseqs,dssp,hbplus,sc}.exists — ツールが不足すると評価の品質は低下しますが、生成は妨げられません。

手順 1b：Python 環境を構築する（.venv/ がない場合のみ）

complexa CLI は、デフォルトではシステムの PATH 上ではなく、プロジェクトの Python 環境内にインストールされます。新しくクローンした直後は .venv/ ディレクトリがまだ存在せず、complexa init は command not found で失敗します。まず UV の venv を構築してください。

test -d .venv || ./env/build_uv_env.sh   # first-time UV build
source .venv/bin/activate
which complexa                            # sanity check: should point inside .venv

which complexa で見つかる場合は、この手順をスキップしてください。以前に構築した環境がまだ使えるということです。Docker ランタイムでは、venv はコンテナイメージ内にあるため、この手順全体をスキップします。ユーザーが「今クローンしたばかり」と言った場合、または pyproject.toml の隣に .venv/ がない場合は、ビルドスクリプトを実行してください。venv がない状態で complexa init を実行すると、「先に venv を構築してください」という明確なエラーではなく、わかりにくい command not found が表示されます。

手順 2：.env を作成する

ランタイムを選択します。UV はデフォルトで、起動も速くなります。Ubuntu 20.04 または GLIBC の不一致があるシステムでは Docker が必要です。

文脈から判断できない場合は AskUserQuestion を使用します。

"どのランタイムを設定しますか？ uv（推奨、より高速）または docker（ローカルで UV venv を構築していない場合に使用）"

パス A：ファイルを編集する（エージェントに推奨）

complexa init が行うのは 3 つだけです。.env_example→.envをコピーし、COMPLEXA_RUNTIME=の行と、ツール／データ／キャッシュのパスブロックにあるUV_↔DOCKER_ のプレフィックスを入れ替えます。cp` と StrReplace を使えば 同じことができ、CLI を省略できます。

cp .env_example .env
# Then StrReplace these lines in .env:
#   COMPLEXA_RUNTIME=uv          → COMPLEXA_RUNTIME=<runtime>
#   FOLDSEEK_EXEC=${UV_FOLDSEEK_EXEC}  → FOLDSEEK_EXEC=${DOCKER_FOLDSEEK_EXEC}   (and same for RF3_EXEC_PATH, SC_EXEC, HBPLUS_EXEC, MMSEQS_EXEC, DSSP_EXEC, TMOL_PATH)
#   DATA_PATH=${LOCAL_DATA_PATH} → DATA_PATH=${DOCKER_DATA_PATH}                  (and same for CACHE_DIR, CKPT_PATH)

UV を使い続ける場合は、プレフィックスの入れ替えを丸ごと省略できます（.env_example はすでに UV を対象にしています）。

パス B：CLI

complexa init                    # UV runtime (default)
complexa init --runtime docker   # Docker runtime
complexa init --force            # Recreate .env from .env_example (drops any edits)

.env がすでに存在し、--force が渡されていない場合は、ランタイムに依存する行だけが 入れ替わります。ステップ 3 でのユーザー編集は、ランタイムを切り替えても保持されます。

どちらの方法でも確認

test -f .env && echo "OK: .env present" || echo "MISSING"
grep -E '^COMPLEXA_RUNTIME=' .env

ステップ 3：.env を編集する

この手順には CLI はありません。ステップ 2 で設定されるのはランタイムだけです。.env に マシン固有のパスを手動で記述する必要があります（StrReplace またはエディターを使用）。 必ず編集しなければならない項目は次の 2 つです。

LOCAL_CODE_PATH=/absolute/path/to/protein-foundation-models
LOCAL_DATA_PATH=/absolute/path/to/PFM_data

それ以外の項目（キャッシュ、ckpts、community-model ディレクトリ、ツールのバイナリ）は、 デフォルトで LOCAL_CODE_PATH から導出されるため、標準的でないレイアウトの場合にのみ 編集が必要です。すべてのキー、制御対象、値がない場合に起きる問題を網羅した表は、 reference/env_keys.md を参照してください。

多くのユーザーが設定する 4 項目のクイック判断表：

キー	デフォルト	次の場合に設定
LOCAL_CODE_PATH	placeholder	常に必要
LOCAL_DATA_PATH	/path/to/PFM_data	常に必要。対象の PDB を指定します
HF_TOKEN	placeholder	ESMFold またはアクセス制限付き HF モデルを使う場合
WANDB_API_KEY	placeholder	トレーニング実行を W&B に記録する場合

ステップ 4：チェックポイントをダウンロードする

ここでは必ず CLI を使用してください。 complexa download は env/download_startup.sh（NGC の URL、再試行、約 6 種類のコミュニティモデルにわたる ダウンロード済みファイルのスキップ処理を含む、約 1000 行の bash スクリプト）を実行します。 独自に wget のループを組むと、不完全なダウンロードや保存先パスの誤りを招きます。

ユーザーが実際に必要としているモデルを確認してください。すべてダウンロードすると約 100 GB 以上になります。 3 種類の Complexa バリアントとコミュニティモデルのセットから選びます。各 Complexa バリアントで利用できる complexa design パイプラインは 1 つだけです。コミュニティモデルのセットに含まれる AF2／RF3 は、実行時に evaluate（および報酬ガイド付き検索）で必要になります。

フラグ	ダウンロードするもの	利用可能になるパイプライン	保存先	概算サイズ
--complexa	Complexa タンパク質結合モデル + AE（complexa.ckpt、complexa_ae.ckpt）	タンパク質結合剤（デフォルト） — configs/search_binder_local_pipeline.yaml	./ckpts/	約 3 GB
--complexa-ligand	リガンド結合モデル + AE（complexa_ligand.ckpt、complexa_ligand_ae.ckpt）	リガンド結合剤 — configs/search_ligand_binder_local_pipeline.yaml	./ckpts/	約 3 GB
--complexa-ame	AME モチーフ足場形成モデル + AE（complexa_ame.ckpt、complexa_ame_ae.ckpt）	AME（酵素） — configs/search_ame_local_pipeline.yaml	./ckpts/	約 3 GB
--complexa-all	3 種類すべての Complexa バリアント	3 種類すべてのパイプライン	./ckpts/	約 9 GB
--all	すべてのコミュニティモデル（ProteinMPNN + LigandMPNN + AF2 + ESM2 + ESMFold + RF3）	evaluate／reward で必要：AF2（タンパク質結合剤）、RF3（リガンド結合剤 + AME）、MPNN（すべてのパイプラインで逆フォールディングに使用）。	./community_models/	約 50 GB
--everything	Complexa + コミュニティモデル + オプションモデル（Boltz2 / Protenix）	代替リフォールドバックエンドを含むすべて	両方	約 100 GB 以上
--status	インストール状態を表示 — ダウンロードはしません	（なし）	（なし）	該当なし

パイプラインごとの最小ダウンロード：

• タンパク質結合剤（デフォルト）：complexa download --complexa --all
• リガンド結合剤：complexa download --complexa-ligand --all
• AME／酵素：complexa download --complexa-ame --all
• 3 種類すべて：complexa download --everything

モデルごとの保存先の詳細とフラグごとの NGC ソースについては、 reference/downloads.md を参照してください。

ユーザーの目的を満たす最小限のコマンドを選び、次を実行します。

complexa download --complexa            # protein binder only
complexa download --complexa-all        # all three Complexa variants
complexa download --all                 # community models only
complexa download --everything          # everything

引数なしで complexa download を実行すると、対話型ウィザードが起動します。エージェントモードでは、 明示的なフラグの使用を推奨します。

ダウンロードされた内容を確認します。

complexa download --status

ステータス出力では、ファミリー（Complexa／コミュニティ／オプション）ごとに分類され、各チェックポイントについて 「Installed」または「Missing」と表示されます。チェックポイントが「Missing」と表示された場合は、該当するフラグを再実行してください。

ステップ 5：検証する

.env を読み込めることと、必要なパスが解決されることを最終確認します。

complexa validate env

validate env は次の項目を確認します：（1）.env が存在すること、（2）DATA_PATH が設定され、 既存のディレクトリを指していること。チェックポイントファイルは確認しません。パイプライン設定を選択した後、 complexa validate design <config> で確認します。

よくある問題と解決方法：

症状	原因	解決方法
.env file: No .env file found	complexa init が未実行	まず complexa init を実行します
DATA_PATH: Not set in .env	プレースホルダーが編集されていない	.env の LOCAL_DATA_PATH を編集します
DATA_PATH: Directory not found	パスは編集されたものの、ディスク上に存在しない	mkdir -p $LOCAL_DATA_PATH を実行するか、対象データをそこにコピーします
Hydra エラー InterpolationKeyError: AF2_DIR	報酬／評価設定で AF2 が必要ですが、.env に定義されていない	AF2 の重みをダウンロードするか、設定から AF2 を削除します

ステップ 6：セットアップ成果物を生成する

ユーザーが現在の状態を 1 つのファイルで確認できるよう、./complexa_setup/ に JSON マニフェストを配置します。 共有ヘルパーが作成します。

mkdir -p ./complexa_setup
python .claude/skills/_shared/scripts/write_manifest.py \
    --kind setup \
    --runtime "$(grep -E '^COMPLEXA_RUNTIME=' .env | cut -d= -f2)" \
    --preflight ./complexa_setup/preflight.json \
    --out ./complexa_setup/run_manifest.json

生成されたファイルをユーザーに提示します。

ls -la ./complexa_setup/

想定される内容：

complexa_setup/
├── preflight.json      # GPU / disk / .env / ckpt / tool snapshot
└── run_manifest.json   # init + download invocations + git SHA + runtime

ハードウェア要件

リソース	最小構成	推奨構成
GPU	1× CUDA GPU、≥24 GB VRAM	A100 / H100 / L40S、40–80 GB VRAM
CUDA	12.0	12.4+
ディスク（CKPT_PATH）	50 GB	150 GB（--everything をカバー）
RAM	16 GB	64 GB+
OS	Ubuntu 22.04+（UV）	Ubuntu 22.04+、または任意のホスト上の Docker

Ubuntu 20.04 では UV ランタイムで GLIBC エラーが発生します。そのようなホストでは complexa init --runtime docker を使用してください。パイプライン別（binder、ligand、AME）の要件については、.claude/skills/_shared/reference/hardware.md を参照してください。

トラブルシューティング

症状	原因	対処方法
complexa: command not found	アクティブな環境にパッケージがインストールされていない	source .venv/bin/activate を実行してから pip install -e . を実行します
complexa init で .env_example not found と表示される	リポジトリのルート以外で実行している	プロジェクトのルート（.env_example がある場所）に cd します
.env_example not found. Cannot initialize .env.	プロジェクトのルートにいない	protein-foundation-models/ に cd して、もう一度実行します
complexa download が NGC URL で失敗する	ファイアウォールの背後にいる／インターネットに接続できない	ダウンロードスクリプト用にプロキシを設定するか、メインの README.md にリンクされている NGC ページからモデルの .ckpt を手動でダウンロードし、./ckpts/ に配置します
complexa download --status では ckpts が存在すると表示されるが、validate が失敗する	.env の CKPT_PATH が別の場所を指している	ckpts を移動するか、.env の LOCAL_CHECKPOINT_PATH を編集します
インポート時に GLIBC エラーが発生する	UV ランタイムを使用している Ubuntu 20.04	complexa init --runtime docker を再実行し、./env/docker-ops.sh run を使用します

---

.env の全項目、デフォルト値、障害発生時の動作については、完全版リファレンスの reference/env_keys.md を参照してください。

ダウンロードフラグの全組み合わせ、NGC URL、保存先の構成については、 reference/downloads.md を参照してください。