{"id":17477,"plugin_id":"plugins_6a76572d8f8081918362aa7ff90947fb","kind":"skill","collection_source":null,"comparison_source":null,"observed_at":"2026-09-30T23:14:13.884Z","digest":"f4af783d3a53c7a1386bff987ac2108f91276990d01cf1a82f8e938361979ee6","against":null,"payload":{"name":"complexa-setup","description":"First-time setup, environment configuration, and model-weight installation for Proteina-Complexa. Reach for this skill whenever the user says \"set up complexa\", \"install complexa\", \"configure my .env\", \"first-time setup\", \"what models do I have installed\", \"what's in my .env\", \"download model weights\", \"download Complexa / AF2 / RF3 / ProteinMPNN / LigandMPNN / ESM2 / ESMFold checkpoints\", \"preflight my GPU\", \"verify environment\", \"complexa init\", \"complexa download\", \"complexa download --status\", \"complexa validate env\", or any time a fresh checkout needs to be made runnable. This is the first skill to run on a new clone — it drives `complexa init`, `complexa download`, and `complexa validate env` end-to-end, edits the required `.env` keys, picks the right runtime (UV vs Docker), and emits a replayable setup artifact.","included_files":[{"relative_path":"reference/downloads.md","size_in_bytes":7553},{"relative_path":"reference/env_keys.md","size_in_bytes":10157}],"skill_md_contents":"---\nname: complexa-setup\ndescription: >\n  First-time setup, environment configuration, and model-weight installation for\n  Proteina-Complexa. Reach for this skill whenever the user says \"set up complexa\",\n  \"install complexa\", \"configure my .env\", \"first-time setup\", \"what models do I\n  have installed\", \"what's in my .env\", \"download model weights\", \"download\n  Complexa / AF2 / RF3 / ProteinMPNN / LigandMPNN / ESM2 / ESMFold checkpoints\",\n  \"preflight my GPU\", \"verify environment\", \"complexa init\", \"complexa download\",\n  \"complexa download --status\", \"complexa validate env\", or any time a fresh\n  checkout needs to be made runnable. This is the first skill to run on a new\n  clone — it drives `complexa init`, `complexa download`, and `complexa validate\n  env` end-to-end, edits the required `.env` keys, picks the right runtime (UV\n  vs Docker), and emits a replayable setup artifact.\ncompatibility: \"complexa CLI installed (pip install -e .); bash 4+; nvidia-smi optional\"\nallowed-tools: Bash, Read, Write, AskUserQuestion\n---\n\n# Complexa Setup Skill\n\nDrive the three steps a fresh Proteina-Complexa checkout needs before any\ndesign run: create `.env`, fetch model weights, and sanity-check the env.\nProbe the host for GPU / disk / tool binaries first so the user does not\ndiscover a missing dependency mid-pipeline. End with a JSON setup artifact the\nuser (or a future agent) can re-read instead of re-deriving state.\n\n## CLI vs direct file-edit — pick the cheapest path per step\n\n| Step | Preferred path | Why |\n|---|---|---|\n| `.env` creation (Step 2) | **File edit** (`cp .env_example .env` + 3 line swaps) or `complexa init` | `complexa init` is a thin wrapper around `cp + 3 regex swaps` (`_swap_runtime_in_env` in `cli_runner.py`). Either path works; pick CLI for new humans, direct edit for agents. |\n| `.env` value edits (Step 3) | **File edit** (StrReplace `LOCAL_CODE_PATH=…` etc.) | No CLI for this — the values are user-specific paths. |\n| Download model weights (Step 4) | **CLI** (`complexa download --…`) | Dispatches to `env/download_startup.sh` (~1000 lines of bash with NGC URLs, retries, checksum-style skip-if-present). Don't try to replicate. |\n| Validate env (Step 5) | **CLI** (`complexa validate env`) or `test -f .env && test -d $DATA_PATH` | CLI prints a nicer report; the manual check is one-liner-safe. |\n| Validate full design config (after picking a pipeline) | **CLI** (`complexa validate design CONFIG`) | Non-trivial Hydra defaults traversal + ckpt + env-var checks; not worth replicating. |\n\n## What this skill enables\n\n- A correctly-shaped `.env` for either UV or Docker runtime.\n- Model checkpoints (Complexa protein/ligand/AME plus community models) downloaded to known paths.\n- A `preflight.json` snapshot of the host (GPU, disk, .env, ckpts, tool binaries).\n- A `run_manifest.json` capturing exactly which `complexa init` + `complexa download` invocations were used (replay-friendly).\n- A pass/fail report from `complexa validate env` with clear next-step hints.\n\n## Step 1: Pre-flight check\n\nAlways run the shared preflight before touching the environment. It does not\nrequire `.env` to exist — it falls back to defaults — and it tells you whether\nthe host can run Complexa at all.\n\n```bash\nbash .claude/skills/_shared/scripts/preflight.sh\n```\n\nThe script writes `./complexa_setup/preflight.json`. Read it and surface:\n\n- `gpu.available` — if `false`, design / evaluate steps will fail; warn the user.\n- `gpu.vram_gb` — Complexa needs ≥40 GB (A100/H100/L40S).\n- `disk.free_gb` at `CKPT_PATH` — minimum ~50 GB for the full Complexa + community model set.\n- `env.missing_required` — anything listed here must be edited in `.env` before validation passes.\n- `tools.{foldseek,mmseqs,dssp,hbplus,sc}.exists` — missing tools degrade evaluation but do not block generation.\n\n## Step 1b: Build the Python environment (only if `.venv/` is missing)\n\nThe `complexa` CLI is installed inside the project's Python environment, not on\nthe system path by default. On a **fresh clone**, the `.venv/` directory does\nnot yet exist and `complexa init` will fail with `command not found`. Build the\nUV venv before anything else:\n\n```bash\ntest -d .venv || ./env/build_uv_env.sh   # first-time UV build\nsource .venv/bin/activate\nwhich complexa                            # sanity check: should point inside .venv\n```\n\nSkip this step if `which complexa` already resolves — that means a previous\nbuild is still good. The Docker runtime skips it entirely; the venv lives\ninside the container image instead. If the user said \"I just cloned\" or you\nsee no `.venv/` next to `pyproject.toml`, run the build script — `complexa init`\nwithout a venv produces a confusing `command not found` rather than an obvious\n\"build the venv first\" error.\n\n## Step 2: Create `.env`\n\nPick the runtime. UV is the default and faster to start; Docker is required on\nUbuntu 20.04 or systems with GLIBC mismatches.\n\nUse AskUserQuestion if it is not obvious from context:\n\n> \"Which runtime do you want to configure? `uv` (recommended, faster) or `docker` (use if you do not have a UV venv built locally)?\"\n\n### Path A: file edit (preferred for agents)\n\n`complexa init` only does three things — copy `.env_example` → `.env` and\nswap the `COMPLEXA_RUNTIME=` line plus the `UV_*` ↔ `DOCKER_*` prefixes on the\ntool/data/cache path block. You can do the same with `cp` + StrReplace and skip\nthe CLI:\n\n```bash\ncp .env_example .env\n# Then StrReplace these lines in .env:\n#   COMPLEXA_RUNTIME=uv          → COMPLEXA_RUNTIME=<runtime>\n#   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)\n#   DATA_PATH=${LOCAL_DATA_PATH} → DATA_PATH=${DOCKER_DATA_PATH}                  (and same for CACHE_DIR, CKPT_PATH)\n```\n\nSkip the prefix swap entirely if you're staying on UV (the `.env_example`\nalready targets UV).\n\n### Path B: CLI\n\n```bash\ncomplexa init                    # UV runtime (default)\ncomplexa init --runtime docker   # Docker runtime\ncomplexa init --force            # Recreate .env from .env_example (drops any edits)\n```\n\nIf `.env` already exists and `--force` is not passed, only the runtime-dependent\nlines are swapped — user edits in Step 3 are preserved across runtime flips.\n\n### Verify either way\n\n```bash\ntest -f .env && echo \"OK: .env present\" || echo \"MISSING\"\ngrep -E '^COMPLEXA_RUNTIME=' .env\n```\n\n## Step 3: Edit .env\n\nNo CLI for this — Step 2 only set the runtime; you still need to write your\nmachine-specific paths into `.env` by hand (StrReplace or your editor). The two\nabsolutely-required edits are:\n\n```bash\nLOCAL_CODE_PATH=/absolute/path/to/protein-foundation-models\nLOCAL_DATA_PATH=/absolute/path/to/PFM_data\n```\n\nEverything else (cache, ckpts, community-model dirs, tool binaries) is derived\nfrom `LOCAL_CODE_PATH` by default and only needs editing if you have a\nnon-standard layout. For the full table — every key, what it controls, what\nfails if it is missing — see [reference/env_keys.md](reference/env_keys.md).\n\nQuick decision table for the four edits most users make:\n\n| Key | Default | Set this if |\n|-----|---------|-------------|\n| `LOCAL_CODE_PATH` | placeholder | Always — required |\n| `LOCAL_DATA_PATH` | `/path/to/PFM_data` | Always — required, points at target PDBs |\n| `HF_TOKEN` | placeholder | You need ESMFold or gated HF models |\n| `WANDB_API_KEY` | placeholder | You want training runs logged to W&B |\n\n## Step 4: Download checkpoints\n\n**Always use the CLI here.** `complexa download` dispatches to\n`env/download_startup.sh` (~1000 lines of bash with NGC URLs, retries, and\nskip-if-present logic across ~6 community-model families). Rolling your own\nwget loop is a recipe for partial downloads and wrong destination paths.\n\nAsk which models the user actually needs — downloading everything is ~100+ GB.\nPick from the three Complexa variants and the community-model set. Each\nComplexa variant unlocks exactly one `complexa design` pipeline; AF2 / RF3\ninside the community-model set are what `evaluate` (and reward-guided search)\nneed at run time.\n\n| Flag | What it downloads | Unlocks pipeline | Destination | Approx size |\n|------|-------------------|------------------|-------------|-------------|\n| `--complexa` | Complexa protein-binder model + AE (`complexa.ckpt`, `complexa_ae.ckpt`) | **Protein binder** (default) — `configs/search_binder_local_pipeline.yaml` | `./ckpts/` | ~3 GB |\n| `--complexa-ligand` | Ligand-binder model + AE (`complexa_ligand.ckpt`, `complexa_ligand_ae.ckpt`) | Ligand binder — `configs/search_ligand_binder_local_pipeline.yaml` | `./ckpts/` | ~3 GB |\n| `--complexa-ame` | AME motif-scaffolding model + AE (`complexa_ame.ckpt`, `complexa_ame_ae.ckpt`) | AME (enzyme) — `configs/search_ame_local_pipeline.yaml` | `./ckpts/` | ~3 GB |\n| `--complexa-all` | All three Complexa variants | All three pipelines | `./ckpts/` | ~9 GB |\n| `--all` | All community models (ProteinMPNN + LigandMPNN + AF2 + ESM2 + ESMFold + RF3) | Needed by **evaluate / reward**: AF2 (protein binder), RF3 (ligand binder + AME), MPNNs (inverse folding for every pipeline). | `./community_models/` | ~50 GB |\n| `--everything` | Complexa + community + optional (Boltz2 / Protenix) | Everything plus alternative refold backends | both | ~100+ GB |\n| `--status` | Show install state — does not download | (none) | (none) | n/a |\n\n**Minimum download per pipeline:**\n\n- Protein binder (default): `complexa download --complexa --all`\n- Ligand binder: `complexa download --complexa-ligand --all`\n- AME / enzyme: `complexa download --complexa-ame --all`\n- All three: `complexa download --everything`\n\nFor the full per-model destination breakdown and per-flag NGC sources, see\n[reference/downloads.md](reference/downloads.md).\n\nPick the smallest invocation that covers the user's goal, then run:\n\n```bash\ncomplexa download --complexa            # protein binder only\ncomplexa download --complexa-all        # all three Complexa variants\ncomplexa download --all                 # community models only\ncomplexa download --everything          # everything\n```\n\nWithout arguments, `complexa download` launches an interactive wizard — prefer\nexplicit flags in agent mode.\n\nVerify what landed:\n\n```bash\ncomplexa download --status\n```\n\nThe status output groups by family (Complexa / community / optional) and prints\n\"Installed\" or \"Missing\" per ckpt. Re-run the specific flag if a ckpt is\nflagged missing.\n\n## Step 5: Validate\n\nFinal check that `.env` is loadable and the required paths resolve:\n\n```bash\ncomplexa validate env\n```\n\n`validate env` checks: (1) `.env` exists, (2) `DATA_PATH` is set and points at\nan existing directory. It does not check ckpt files — those are checked by\n`complexa validate design <config>` once you have a pipeline config picked.\n\nCommon failures and fixes:\n\n| Symptom | Cause | Fix |\n|---------|-------|-----|\n| `.env file: No .env file found` | `complexa init` not run | Run `complexa init` first |\n| `DATA_PATH: Not set in .env` | Placeholder not edited | Edit `LOCAL_DATA_PATH` in `.env` |\n| `DATA_PATH: Directory not found` | Path edited but does not exist on disk | `mkdir -p $LOCAL_DATA_PATH` or copy target data there |\n| Hydra error `InterpolationKeyError: AF2_DIR` | Reward/eval config wants AF2 but `.env` does not define it | Download AF2 weights or remove AF2 from the config |\n\n## Step 6: Emit setup artifact\n\nDrop a JSON manifest in `./complexa_setup/` so the user has a single file\ndescribing the resulting state. The shared helper writes it for you:\n\n```bash\nmkdir -p ./complexa_setup\npython .claude/skills/_shared/scripts/write_manifest.py \\\n    --kind setup \\\n    --runtime \"$(grep -E '^COMPLEXA_RUNTIME=' .env | cut -d= -f2)\" \\\n    --preflight ./complexa_setup/preflight.json \\\n    --out ./complexa_setup/run_manifest.json\n```\n\nSurface the resulting files to the user:\n\n```bash\nls -la ./complexa_setup/\n```\n\nExpected contents:\n\n```\ncomplexa_setup/\n├── preflight.json      # GPU / disk / .env / ckpt / tool snapshot\n└── run_manifest.json   # init + download invocations + git SHA + runtime\n```\n\n## Hardware requirements\n\n| Resource | Minimum | Recommended |\n|----------|---------|-------------|\n| GPU | 1× CUDA GPU, ≥24 GB VRAM | A100 / H100 / L40S, 40–80 GB VRAM |\n| CUDA | 12.0 | 12.4+ |\n| Disk (CKPT_PATH) | 50 GB | 150 GB (covers `--everything`) |\n| RAM | 16 GB | 64 GB+ |\n| OS | Ubuntu 22.04+ (UV) | Ubuntu 22.04+ or Docker on any host |\n\nUbuntu 20.04 throws GLIBC errors with the UV runtime — use `complexa init\n--runtime docker` on those hosts. See `.claude/skills/_shared/reference/hardware.md`\nfor per-pipeline (binder vs ligand vs AME) requirements.\n\n## Troubleshooting\n\n| Symptom | Cause | Fix |\n|---------|-------|-----|\n| `complexa: command not found` | Package not installed in active env | `source .venv/bin/activate` then `pip install -e .` |\n| `complexa init` says `.env_example not found` | Running outside repo root | `cd` to the project root (where `.env_example` lives) |\n| `.env_example not found. Cannot initialize .env.` | Not in project root | `cd` into `protein-foundation-models/` and retry |\n| `complexa download` fails on NGC URL | Behind firewall / no internet | Configure a proxy for the download script, or download the model `.ckpt`s manually from the NGC pages linked in the main `README.md` and drop them into `./ckpts/` |\n| `complexa download --status` shows ckpts present but `validate` fails | `.env` `CKPT_PATH` points elsewhere | Either move ckpts or edit `LOCAL_CHECKPOINT_PATH` in `.env` |\n| GLIBC error on import | Ubuntu 20.04 with UV runtime | Re-run `complexa init --runtime docker` and use `./env/docker-ops.sh run` |\n\n---\n\nFor the full `.env` reference (every key, defaults, failure modes), see\n[reference/env_keys.md](reference/env_keys.md).\n\nFor the full download flag matrix, NGC URLs, and destination layout, see\n[reference/downloads.md](reference/downloads.md).\n"},"changes":[],"summary":"First saved snapshot. No earlier version is available for comparison.","summary_kind":"deterministic","summary_metadata":{}}