Complexa Setup

Complexa Setup Skill

Drive the three steps a fresh Proteina-Complexa checkout needs before any design run: create .env, fetch model weights, and sanity-check the env. Probe the host for GPU / disk / tool binaries first so the user does not discover a missing dependency mid-pipeline. End with a JSON setup artifact the user (or a future agent) can re-read instead of re-deriving state.

CLI vs direct file-edit — pick the cheapest path per step

What this skill enables

• A correctly-shaped .env for either UV or Docker runtime.
• Model checkpoints (Complexa protein/ligand/AME plus community models) downloaded to known paths.
• A preflight.json snapshot of the host (GPU, disk, .env, ckpts, tool binaries).
• A run_manifest.json capturing exactly which complexa init + complexa download invocations were used (replay-friendly).
• A pass/fail report from complexa validate env with clear next-step hints.

Step 1: Pre-flight check

Always run the shared preflight before touching the environment. It does not require .env to exist — it falls back to defaults — and it tells you whether the host can run Complexa at all.

Prerequisite: the _shared/ bundle is not vendored in this flat vault. Install open-models-skills/proteina-complexa/_shared/ from NVIDIA-BioNeMo/bionemo-agent-toolkit to .claude/skills/_shared/ (scripts/preflight.sh, scripts/write_manifest.py, reference/hardware.md), or substitute an inline nvidia-smi / df -h probe.

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

The script writes ./complexa_setup/preflight.json. Read it and surface:

• gpu.available — if false, design / evaluate steps will fail; warn the user.
• gpu.vram_gb — Complexa needs ≥40 GB (A100/H100/L40S).
• disk.free_gb at CKPT_PATH — minimum ~50 GB for the full Complexa + community model set.
• env.missing_required — anything listed here must be edited in .env before validation passes.
• tools.{foldseek,mmseqs,dssp,hbplus,sc}.exists — missing tools degrade evaluation but do not block generation.

Step 1b: Build the Python environment (only if .venv/ is missing)

The complexa CLI is installed inside the project's Python environment, not on the system path by default. On a fresh clone, the .venv/ directory does not yet exist and complexa init will fail with command not found. Build the UV venv before anything else:

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

Skip this step if which complexa already resolves — that means a previous build is still good. The Docker runtime skips it entirely; the venv lives inside the container image instead. If the user said "I just cloned" or you see no .venv/ next to pyproject.toml, run the build script — complexa init without a venv produces a confusing command not found rather than an obvious "build the venv first" error.

Step 2: Create .env

Pick the runtime. UV is the default and faster to start; Docker is required on Ubuntu 20.04 or systems with GLIBC mismatches.

Use AskUserQuestion if it is not obvious from context:

"Which runtime do you want to configure? uv (recommended, faster) or docker (use if you do not have a UV venv built locally)?"

Path A: file edit (preferred for agents)

complexa init only does three things — copy .env_example → .env and swap the COMPLEXA_RUNTIME= line plus the UV_* ↔ DOCKER_* prefixes on the tool/data/cache path block. You can do the same with cp + StrReplace and skip the 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)

Skip the prefix swap entirely if you're staying on UV (the .env_example already targets UV).

Path B: CLI

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

If .env already exists and --force is not passed, only the runtime-dependent lines are swapped — user edits in Step 3 are preserved across runtime flips.

Verify either way

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

Step 3: Edit .env

No CLI for this — Step 2 only set the runtime; you still need to write your machine-specific paths into .env by hand (StrReplace or your editor). The two absolutely-required edits are:

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

Everything else (cache, ckpts, community-model dirs, tool binaries) is derived from LOCAL_CODE_PATH by default and only needs editing if you have a non-standard layout. For the full table — every key, what it controls, what fails if it is missing — see reference/env_keys.md.

Quick decision table for the four edits most users make:

Step 4: Download checkpoints

Always use the CLI here. complexa download dispatches to env/download_startup.sh (~1000 lines of bash with NGC URLs, retries, and skip-if-present logic across ~6 community-model families). Rolling your own wget loop is a recipe for partial downloads and wrong destination paths.

Ask which models the user actually needs — downloading everything is ~100+ GB. Pick from the three Complexa variants and the community-model set. Each Complexa variant unlocks exactly one complexa design pipeline; AF2 / RF3 inside the community-model set are what evaluate (and reward-guided search) need at run time.

Minimum download per pipeline:

• Protein binder (default): complexa download --complexa --all
• Ligand binder: complexa download --complexa-ligand --all
• AME / enzyme: complexa download --complexa-ame --all
• All three: complexa download --everything

For the full per-model destination breakdown and per-flag NGC sources, see reference/downloads.md.

Pick the smallest invocation that covers the user's goal, then run:

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

Without arguments, complexa download launches an interactive wizard — prefer explicit flags in agent mode.

Verify what landed:

complexa download --status

The status output groups by family (Complexa / community / optional) and prints "Installed" or "Missing" per ckpt. Re-run the specific flag if a ckpt is flagged missing.

Step 5: Validate

Final check that .env is loadable and the required paths resolve:

complexa validate env

validate env checks: (1) .env exists, (2) DATA_PATH is set and points at an existing directory. It does not check ckpt files — those are checked by complexa validate design <config> once you have a pipeline config picked.

Common failures and fixes:

Step 6: Emit setup artifact

Drop a JSON manifest in ./complexa_setup/ so the user has a single file describing the resulting state. The shared helper writes it for you:

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

Surface the resulting files to the user:

ls -la ./complexa_setup/

Expected contents:

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

Hardware requirements

Ubuntu 20.04 throws GLIBC errors with the UV runtime — use complexa init --runtime docker on those hosts. See .claude/skills/_shared/reference/hardware.md for per-pipeline (binder vs ligand vs AME) requirements.

Troubleshooting

For the full .env reference (every key, defaults, failure modes), see reference/env_keys.md.

For the full download flag matrix, NGC URLs, and destination layout, see reference/downloads.md.