Update to NVIDIA BioNeMo Agent Toolkit

{
  "name": "complexa-binder-design",
  "description": "Run a complete protein binder design campaign with NVIDIA Proteina-Complexa: resolve a target structure and hotspots from a name/sequence/PDB, co-design binder sequence+structure with reward-guided test-time search (best-of-n, beam search, FK steering, MCTS), select with the internal AF2 reward gate, then INDEPENDENTLY validate each binder by refolding the complex with Boltz2 (default) or OpenFold3 and rank on interface confidence, pLDDT, ipSAE, apo/holo stability, and hotspot contact. Use whenever the user wants de novo binders against a named target, sequence, or PDB, hotspot/epitope-targeted design, Proteina-Complexa / Complexa, or ranked validated binders from one request. Sibling of protein-binder-design (RFdiffusion + ProteinMPNN); this skill uses Proteina-Complexa.",
  "included_files": [
    {
      "relative_path": "LICENSE",
      "size_in_bytes": 11357
    },
    {
      "relative_path": "NOTICE",
      "size_in_bytes": 1377
    },
    {
      "relative_path": "README.md",
      "size_in_bytes": 4552
    },
    {
      "relative_path": "assets/targets.json",
      "size_in_bytes": 721
    },
    {
      "relative_path": "prompts/hotspot_paperclip.md",
      "size_in_bytes": 5951
    },
    {
      "relative_path": "references/complexa-cli.md",
      "size_in_bytes": 5317
    },
    {
      "relative_path": "references/pipeline.md",
      "size_in_bytes": 6129
    },
    {
      "relative_path": "references/setup.md",
      "size_in_bytes": 8564
    },
    {
      "relative_path": "references/target-and-hotspots.md",
      "size_in_bytes": 5005
    },
    {
      "relative_path": "references/validation.md",
      "size_in_bytes": 4553
    },
    {
      "relative_path": "scripts/boltz2_refold.py",
      "size_in_bytes": 7399
    },
    {
      "relative_path": "scripts/check_setup.sh",
      "size_in_bytes": 3353
    },
    {
      "relative_path": "scripts/complexa_design.py",
      "size_in_bytes": 6675
    },
    {
      "relative_path": "scripts/fetch_ipsae.sh",
      "size_in_bytes": 1184
    },
    {
      "relative_path": "scripts/fetch_target_msa_colabfold.py",
      "size_in_bytes": 5921
    },
    {
      "relative_path": "scripts/hotspot_strategy.py",
      "size_in_bytes": 9082
    },
    {
      "relative_path": "scripts/pdb_interface.py",
      "size_in_bytes": 7064
    },
    {
      "relative_path": "scripts/pdb_to_boltz_template_cif.py",
      "size_in_bytes": 3370
    },
    {
      "relative_path": "scripts/pipeline.py",
      "size_in_bytes": 65860
    },
    {
      "relative_path": "scripts/preflight_design.py",
      "size_in_bytes": 10482
    },
    {
      "relative_path": "scripts/setup_af2_params.sh",
      "size_in_bytes": 1976
    },
    {
      "relative_path": "scripts/validate_binders.py",
      "size_in_bytes": 21664
    },
    {
      "relative_path": "vendor/ipsae/README.md",
      "size_in_bytes": 956
    },
    {
      "relative_path": "vendor/ipsae/VENDOR.md",
      "size_in_bytes": 1827
    },
    {
      "relative_path": "vendor/science-skills/LICENSE",
      "size_in_bytes": 11358
    },
    {
      "relative_path": "vendor/science-skills/VENDOR.md",
      "size_in_bytes": 2663
    },
    {
      "relative_path": "vendor/science-skills/alphafold_database_fetch_and_analyze/SKILL.md",
      "size_in_bytes": 4714
    },
    {
      "relative_path": "vendor/science-skills/alphafold_database_fetch_and_analyze/scripts/analyze_pae.py",
      "size_in_bytes": 6223
    },
    {
      "relative_path": "vendor/science-skills/alphafold_database_fetch_and_analyze/scripts/analyze_plddt.py",
      "size_in_bytes": 3940
    },
    {
      "relative_path": "vendor/science-skills/alphafold_database_fetch_and_analyze/scripts/fetch_structure.py",
      "size_in_bytes": 6351
    },
    {
      "relative_path": "vendor/science-skills/uniprot_database/SKILL.md",
      "size_in_bytes": 12307
    },
    {
      "relative_path": "vendor/science-skills/uniprot_database/scripts/uniprot_tools.py",
      "size_in_bytes": 16804
    }
  ],
  "skill_md_contents": "---\nname: complexa-binder-design\ndescription: >\n  Run a complete protein binder design campaign with NVIDIA Proteina-Complexa: resolve a target structure and hotspots from a name/sequence/PDB, co-design binder sequence+structure with reward-guided test-time search (best-of-n, beam search, FK steering, MCTS), select with the internal AF2 reward gate, then INDEPENDENTLY validate each binder by refolding the complex with Boltz2 (default) or OpenFold3 and rank on interface confidence, pLDDT, ipSAE, apo/holo stability, and hotspot contact. Use whenever the user wants de novo binders against a named target, sequence, or PDB, hotspot/epitope-targeted design, Proteina-Complexa / Complexa, or ranked validated binders from one request. Sibling of protein-binder-design (RFdiffusion + ProteinMPNN); this skill uses Proteina-Complexa.\nlicense: Apache-2.0\ncompatibility: \"python>=3.10; numpy>=1.24; gemmi (target prep + Boltz2 templates); pyyaml (target registration)\"\nallowed-tools: Bash, Read, Write, AskUserQuestion\n---\n\n# Complexa Binder Design (workflow)\n\nFrom one request — \"design binders for `<target>`\" — to ranked, **independently\nvalidated** binders. Each returned binder is a **co-designed sequence + predicted\nbinder–target complex**, gated by interface confidence, by whether the binder\nactually contacts the target hotspots, and by **apo/holo stability**.\n\nGeneration uses **Proteina-Complexa** (co-designs binder sequence + full-atom\nstructure together — no inverse-folding step — with reward-guided test-time search).\nValidation uses a **different** model family (Boltz2 / OpenFold3), so the headline\nconfidence is an independent check, not the generator grading its own homework.\n\n> **Upstream model + code (you provide these):**\n> - Project page: <https://research.nvidia.com/labs/genair/proteina-complexa/>\n> - Code: <https://github.com/NVIDIA-Digital-Bio/Proteina-Complexa> (the `complexa` CLI)\n> - Weights (NGC): `nvidia/clara/proteina_complexa`\n> - Paper: Didi et al., *Scaling Atomistic Protein Binder Design…*, ICLR 2026.\n\n> **First time on a host? → `references/setup.md`** — full standalone setup with **no\n> NIM**: install Proteina-Complexa + download weights, Python deps (`numpy gemmi\n> pyyaml`), AF2 **configure-vs-bypass**, optional analyze tools (`foldseek`/`sc`/`dssp`),\n> the Boltz2/OF3 validation endpoint, and every env var. Then run\n> `bash scripts/check_setup.sh` for a one-shot readiness checklist.\n\n```\nStage 1: Resolve target + hotspots            → target.pdb + hotspots.json   (no GPU)\n        ┌──────────────────────────────────────────────────────────────────────┐\n        │ repeat until ≥ N validated passers (or a stop cap):                    │\nStage 2 │   Generate (complexa design) → complex .pdb + AF2-reward-gated designs │\nStage 3 │   Validate (Boltz2 default; OF3 optional) → holo+apo + ipTM/ipSAE/     │\n        │     pLDDT + apo↔holo RMSD + hotspot contact → passers                  │\n        └──────────────────────────────────────────────────────────────────────┘\nStage 4: Report                               → REPORT_<target>_<run>.md (GO/NO-GO)\n```\n\n## Composed pieces (read on demand — do not inline)\n\n| Step | Tool | Owns |\n|---|---|---|\n| Target + hotspots | vendored `science-skills` (UniProt, AFDB) + `scripts/` | structure resolution, evidence-based hotspots, ≤500 crop, preflight |\n| Generation | **Proteina-Complexa** `complexa` CLI | co-designed binder seq+structure, AF2-reward gate → `references/complexa-cli.md` |\n| Validate / score | `boltz2-nim` (default) or `openfold3-nim` | independent holo+apo refold, ipTM / pLDDT / PAE |\n| MSA (target) | `msa-search-nim` or `scripts/fetch_target_msa_colabfold.py` | target A3M for higher-confidence refolds |\n\nIf you run inside the Proteina-Complexa repo, its bundled `.claude/skills`\n(`complexa-setup`, `complexa-target`, `complexa-design`) can drive the generation\nhalf; this skill adds the automated Stage 1, the independent validation, GO/NO-GO,\nand the manifest.\n\n## Stage 1 — resolve target and hotspots (no GPU)\n\nThe user gives a target as a **name**, **sequence**, and/or **structure file**.\nResolve exactly **one design-ready structure**, in priority order: (1) experimental\n**PDB** (RCSB), (2) **AFDB** model (UniProt → `vendor/science-skills/.../fetch_structure.py`),\n(3) **user-provided** file, (4) **fold de novo** (MSA-Search + OpenFold3/Boltz2).\n`scripts/pipeline.py:resolve_target_spec`/`resolve_target` automate (1)–(2) from\nfree text.\n\n**Hotspots** = the target residues the binder should contact — a compact,\nsurface-exposed, binder-accessible epitope. Resolve in evidence order\n(`scripts/hotspot_strategy.py`, `scripts/pdb_interface.py`):\n\n1. **PDB co-complex interface** (gold standard) — interface residues from a structure\n   where the target contacts a protein partner.\n2. **UniProt functional residues** — `Mutagenesis` + accessible `Active/Binding/Site`,\n   **filtered to the extracellular/accessible range** (catalytic/cytoplasmic pockets\n   are the wrong surface for a binder and are dropped).\n3. **Literature (Paperclip)** — full-text mining when 1–2 are empty\n   (`prompts/hotspot_paperclip.md`); structure-confirmed to auto-correct numbering.\n4. **Unconditioned** (`[]`) only as a documented last resort.\n\nThen enforce, deterministically:\n- **Structure alignment** (`align_hotspots_to_structure`) — drop residues absent from\n  the coordinate file; read back the real 3-letter identity (catches UniProt↔PDB\n  numbering offsets — never assume equal indices or chain `A`).\n- **Epitope sanity** (`_prune_hotspots`) — one compact patch: drop outliers > 30 Å\n  from the cluster centroid, cap at 15 residues, prefer ≥ 2.\n- **Size budget ≤ 500 residues** (`_crop_target_to_epitope`) — Complexa builds an\n  O(n²) pair-feature map over the whole complex, so crop large targets to an epitope\n  window (original numbering preserved).\n\n**Preflight (no GPU):** `python3 scripts/preflight_design.py <name|accession> …`\nreports the conditioned length, re-aligned hotspots + source, compactness, the ≤500\nbudget, and a READY / NEEDS-ATTENTION verdict. Review before spending GPU.\n\n## Stage 2 — generate (Proteina-Complexa, open CLI)\n\nRegister the target (hotspots + binder length are target-dict-driven), then **use\n`complexa generate` (NOT the full `complexa design`)** for the lean, fast path:\n\n```bash\npython scripts/complexa_design.py run --task-name <name> --run-name <run> \\\n    --algorithm best-of-n --num-samples <N> --seed 0 --out <run-dir>\n```\n\n`complexa_design.py run` defaults to the **`generate`** verb. With **`best-of-n` + the\nAF2 reward** (AF2 params configured via `setup_af2_params.sh` + `AF2_DIR`), the search\n**AF2-selects the best candidates during generation** and writes co-designed\n**sequence + structure** PDBs to `inference/` — **use the sequence directly, do not\nMPNN-redesign it**. Search algorithms: `best-of-n` (default) · `beam-search` ·\n`fk-steering` · `mcts`. Overrides + outputs: `references/complexa-cli.md`.\n\n> **Do NOT run the full `complexa design` for this workflow.** Its `evaluate` stage\n> **re-folds every design with AF2/RF3/ESMFold (redundant** — best-of-n already\n> AF2-selected during search**)** and its `analyze` stage needs `foldseek`/`sc`\n> (usually not installed). It is much slower and adds a failure mode. The lean\n> `generate` → independent **Boltz2** validation (Stage 3) is the intended path.\n>\n> No AF2 params? use `--af2-bypass` (`single-pass` + drop the AF2 reward); selection\n> then falls entirely to the independent Boltz2 gate (Stage 3). Low-complexity\n> (poly-X) sequences are dropped before spending Boltz2.\n\n## Stage 3 — validate (independent refold) + gate\n\n**Validate a capped shortlist, not the whole pool.** Best-of-n produces many\ncandidates; fold only ~**2× the requested N** (the top ones by the generation/AF2\nreward) — validating the entire pool wastes GPU/time and (on hosted Boltz2) trips rate\nlimits. Point at a local Boltz2 NIM via `$BOLTZ2_URL` (`--endpoint local`) when available.\n\nPer binder run **two** predictions with one refolder (Boltz2 default): **holo**\n(binder + target; target MSA, binder single-sequence, `write_full_pae`) and **apo**\n(binder alone). One command does it: **`scripts/boltz2_refold.py`** makes the holo\ncalls (with retry/backoff for rate limits) and chains **`scripts/validate_binders.py`**,\nwhich runs apo + computes the metrics + applies the gate + ranks. Per-chain\nconditioning + metric definitions: `references/validation.md`.\n\n**Gate (defaults — every gate must hold):** ipTM ≥ 0.65, complex pLDDT ≥ 0.70, binder\npLDDT ≥ 0.70, apo binder pLDDT ≥ 0.70, **ipSAE_min ≥ 0.45**, apo↔holo binder RMSD\n≤ 2.5 Å, ≥ 20% of conditioned hotspots contacted (CB–CB < 13 Å). Record **every**\ndesign (pass *and* fail) with a `failure_reason`. Rank protein binders by interface\nconfidence (ipTM/ipSAE) + pLDDT + stability — **not** Boltz2 `affinity_pic50`\n(ligand-only).\n\n## Bounded-budget loop + report\n\nThe deliverable is **the top-N binders ranked by interface confidence** (default 10).\nAim for N that pass the full gate, but **bound the cost**: run **at most 2 generation\nrounds**, then **deliver the top-N by score (ipTM, then ipSAE_min) even if fewer than N\nclear the strict gate** — keep each design's `pass`/`failure_reason` flag so quality is\nstill visible. Do **not** keep generating just to chase N strict passes (that is the\nsingle biggest time sink). Stop on N-passed / 2 rounds / budget / a zero-passer round.\nOne run dir per campaign; `manifest.json` records target, Complexa run config + seeds,\nper-design lineage/scores/artifacts, gate status. The report states GO/NO-GO,\nrequested-vs-achieved N (passed and delivered), ranked binders, and which stop\ncondition fired. Layout, loop, and report sections: `references/pipeline.md`.\n\n## Configuration\n\n- `COMPLEXA_REPO` — path to your local Proteina-Complexa checkout (the `complexa`\n  CLI runs there). Checkpoints via the pipeline YAML or `++ckpt_path=…`. Reward\n  weights (`AF2_DIR`, `RF3_CKPT_PATH`/`RF3_EXEC_PATH`) via the repo's `.env`.\n- Boltz2 / OpenFold3 endpoints + auth: hosted (`https://health.api.nvidia.com/v1/…`\n  + `NVIDIA_API_KEY`) or local (`http://localhost:8000/…`, no auth). The validator\n  takes `--endpoint hosted|local`; the key is read from `NVIDIA_API_KEY`/`NGC_API_KEY`\n  (or `--env-file`). Never hardcode hosts/keys.\n- `COMPLEXA_OUTPUTS` — run-output root (default `./outputs`).\n\n## Scripts & assets\n\n- `references/setup.md` + `scripts/check_setup.sh` — standalone (no-NIM) install guide\n  and a one-shot environment readiness check.\n- `scripts/pipeline.py` — orchestrator (Stage-1 resolution + open-CLI generation +\n  AF2 gate + scoring); `score_existing` and `full` modes.\n- `scripts/preflight_design.py` — no-GPU target/hotspot/size planner.\n- `scripts/hotspot_strategy.py`, `scripts/pdb_interface.py` — evidence-based hotspots.\n- `scripts/complexa_design.py` — thin `complexa design` driver + output extraction.\n- `scripts/setup_af2_params.sh` — download AF2-Multimer params (public, no auth) +\n  create the `params/` layout, for reward-guided search (`best-of-n`, etc.).\n- `scripts/boltz2_refold.py` — Stage-3 **holo** Boltz2 refolds (retry/backoff + throttle)\n  → `validation/raw/`, then chains `validate_binders.py`.\n- `scripts/validate_binders.py` — apo Boltz2 + scoring, ipSAE, apo↔holo RMSD,\n  hotspot contact, gating, ranking → `ranked_binders.json`. Needs the Dunbrack **ipSAE**\n  script: `bash scripts/fetch_ipsae.sh` (MIT; fetched, not bundled — see `vendor/ipsae/`).\n- `scripts/fetch_target_msa_colabfold.py`, `scripts/pdb_to_boltz_template_cif.py` —\n  target MSA / structural-template helpers for validation.\n- `vendor/science-skills/` — DeepMind UniProt + AFDB tooling (Apache-2.0) for Stage 1.\n- `prompts/hotspot_paperclip.md` — literature-mining hotspot fallback.\n- `assets/targets.json` — example registered targets (use `complexa target add` for your own).\n\n## Responsible use\n\nDe novo binder design is dual-use. Decline requests aimed at enhancing pathogen\nfitness, toxin potency, or bioweapon function; keep designs to legitimate research\nand therapeutic intent.\n\n## See also\n\n- `protein-binder-design` — same goal via RFdiffusion + ProteinMPNN (BioNeMo NIMs).\n- Proteina-Complexa docs: `README.md`, `docs/INFERENCE.md`, `docs/CONFIGURATION_GUIDE.md`,\n  `docs/EVALUATION_METRICS.md`, and its bundled `.claude/skills/` in the repo above.\n"
}