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.

bash 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)?"

Preferred: CLI

test -f .env || complexa init    # Phase 1: copy .env_example to .env

If the CLI is not yet available but the checkout is trusted, cp .env_example .env is equivalent to phase 1 only. Runtime selection happens later through env.sh; do not rewrite the active path expressions in .env.

To deliberately discard an existing dotenv and recreate it from the template:

complexa init --force            # Recreate .env from .env_example (drops any edits)

Verify either way

test -f .env && echo "OK: .env present" || echo "MISSING"

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/Proteina-Complexa
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 references/env_keys.md.

Quick decision table for the four edits most users make:

After editing the paths, generate and activate the runtime environment. The runtime is a positional argument:

complexa init uv                 # or: complexa init docker
source env.sh

env.sh sources the edited .env, maps the active tool/data/checkpoint paths for the selected runtime, and exports COMPLEXA_INIT=uv or docker.

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 references/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 scripts/write_manifest.py \
    --output-dir ./complexa_setup \
    --command "complexa init ${COMPLEXA_INIT}; complexa download <selected flags>; complexa validate env" \
    --skill complexa-setup \
    --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 docker on those hosts. See references/hardware.md for per-pipeline (binder vs ligand vs AME) requirements.

Troubleshooting

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

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