· 1 observation
Technical updates · 1
Package or technical metadata updated
View technical comparison →NVIDIA BioNeMo v0.1.0
Skills for NVIDIA BioNeMo
From the developer
Not specified in the available declarations: limitations, pricing & account requirements.
Predict the structure of insulin with Boltz2
Developer declarations; not independently tested. Listing last checked Nov 21, 2026. Package observed Nov 21, 2026.
From the marketplace listing
A decade of NVIDIA life-sciences libraries, NIMs, and open models as portable agent skills: structure prediction, docking, generative chemistry, genomics, and de novo protein design. The plugin helps an agent pick the right tool, prepare inputs, run it, and interpret outputs.
Language: English · Automatically detected from descriptions.
· 1 observation
Package or technical metadata updated
View technical comparison →· 2 observations
Package or technical metadata updated
View technical comparison →· 2 observations
Package or technical metadata updated
View technical comparison →Package or technical metadata updated
View technical comparison →Finding similar plugins… Results will appear here automatically.
Browse plugins →---
name: boltz2-nim
description: >
Use Boltz2 NIM for biomolecular structure prediction and binding affinity. Invoke for Boltz2, protein structures, protein-ligand/DNA/RNA complexes, SMILES or CCD ligands, pIC50/IC50 affinity scoring, mmCIF output, hosted NVIDIA API calls, or local Docker deployment.
license: Apache-2.0 AND CC-BY-4.0
compatibility: "requests>=2.28"
allowed-tools: Bash, Read, Write, AskUserQuestion
---
# Boltz2 NIM
Predict biomolecular structures and optional ligand affinity. Use this
`SKILL.md` for first-pass hosted/local usage; load supplemental files only when
needed:
- `references/api.md`: exact endpoints, schemas, Docker flags, response fields.
- `references/science.md`: purpose, strengths, limitations, and handoffs.
- `references/parameters.md`: prediction, sampling, MSA, template, affinity tuning.
- `references/validation.md`: mmCIF, confidence, affinity, and chemistry checks.
- `references/examples.md`: compact hosted/local payload patterns.
## Choose Mode
Ask only when context is unclear:
> Hosted NVIDIA API or local Docker NIM?
- Hosted: `https://health.api.nvidia.com/v1/biology/mit/boltz2/predict`
- Local: `http://localhost:8000/biology/mit/boltz2/predict`
Hosted requests use `Authorization: Bearer $NGC_API_KEY`. Supported local Docker
startup uses `NGC_API_KEY` (or `NVIDIA_API_KEY` via the preflight) for
registry login, entitlement checks, and first-run model downloads; pass it
into the container with `-e NGC_API_KEY`. Local inference requests use no
auth header after readiness. Warm-cache key-free startup varies by
image/version and should not be assumed.
## Local Docker
For local setup answers, copy the preflight below before `docker login`,
`docker run`, readiness, and the no-auth local request. Do not invent a cache
default or drop the `.env` load or `NVIDIA_API_KEY` fallback.
```bash
set -a
[ -f .env ] && . ./.env
set +a
if [ -z "${NGC_API_KEY:-}" ] && [ -n "${NVIDIA_API_KEY:-}" ]; then
export NGC_API_KEY="$NVIDIA_API_KEY"
fi
: "${NGC_API_KEY:?Set NGC_API_KEY or NVIDIA_API_KEY}"
: "${LOCAL_NIM_CACHE:?Set LOCAL_NIM_CACHE}"
echo "$NGC_API_KEY" | docker login nvcr.io --username '$oauthtoken' --password-stdin
mkdir -p "${LOCAL_NIM_CACHE}"
chmod 777 "${LOCAL_NIM_CACHE}"
docker run --rm --name boltz2 --gpus all \
--shm-size=16G \
-e NGC_API_KEY \
-v "${LOCAL_NIM_CACHE}:/opt/nim/.cache" \
-p 8000:8000 \
nvcr.io/nim/mit/boltz2:1.6.0
```
Readiness:
```bash
until curl -sf http://localhost:8000/v1/health/ready; do sleep 5; done
```
First startup downloads about 30 GB of model weights.
## Request Pattern
```python
import os
import requests
HOSTED = True
url = (
"https://health.api.nvidia.com/v1/biology/mit/boltz2/predict"
if HOSTED else "http://localhost:8000/biology/mit/boltz2/predict"
)
headers = {"Content-Type": "application/json"}
if HOSTED:
headers["Authorization"] = f"Bearer {os.environ['NGC_API_KEY']}"
payload = {
"polymers": [{
"id": "A",
"molecule_type": "protein",
"sequence": "MTEYKLVVVGACGVGKSALTIQLIQNHFVDEYDPT",
}],
"recycling_steps": 3,
"sampling_steps": 50,
"diffusion_samples": 1,
"step_scale": 1.638,
"output_format": "mmcif",
}
response = requests.post(url, headers=headers, json=payload, timeout=300)
response.raise_for_status()
result = response.json()
```
Payload essentials:
- Protein polymer: `{"molecule_type": "protein", "sequence": "..."}`.
- DNA/RNA polymer: add another polymer with `molecule_type` `"dna"` or `"rna"`.
- Ligand by SMILES: `{"id": "L1", "smiles": "CC(=O)OC1=CC=CC=C1C(=O)O"}`.
- Ligand by CCD: `{"id": "L1", "ccd": "ATP"}`.
- Affinity: set `"predict_affinity": True` on exactly one ligand; report
`affinity_pic50`, `affinity_pred_value`, and `affinity_probability_binary`.
- Precomputed A3M MSA goes under the protein polymer. The A3M record uses
`alignment`, `format`, and `rank`; do not use a stale `data` field.
```python
protein_with_msa = {
"id": "A",
"moleculePreview of the first 4,000 characters. Read full instructions →
Referenced files: 5 — file references are metadata, not package contents.
---
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.
license: Apache-2.0
compatibility: "python>=3.10; numpy>=1.24; gemmi (target prep + Boltz2 templates); pyyaml (target registration)"
allowed-tools: Bash, Read, Write, AskUserQuestion
---
# Complexa Binder Design (workflow)
From one request — "design binders for `<target>`" — to ranked, **independently
validated** binders. Each returned binder is a **co-designed sequence + predicted
binder–target complex**, gated by interface confidence, by whether the binder
actually contacts the target hotspots, and by **apo/holo stability**.
Generation uses **Proteina-Complexa** (co-designs binder sequence + full-atom
structure together — no inverse-folding step — with reward-guided test-time search).
Validation uses a **different** model family (Boltz2 / OpenFold3), so the headline
confidence is an independent check, not the generator grading its own homework.
> **Upstream model + code (you provide these):**
> - Project page: <https://research.nvidia.com/labs/genair/proteina-complexa/>
> - Code: <https://github.com/NVIDIA-Digital-Bio/Proteina-Complexa> (the `complexa` CLI)
> - Weights (NGC): `nvidia/clara/proteina_complexa`
> - Paper: Didi et al., *Scaling Atomistic Protein Binder Design…*, ICLR 2026.
> **First time on a host? → `references/setup.md`** — full standalone setup with **no
> NIM**: install Proteina-Complexa + download weights, Python deps (`numpy gemmi
> pyyaml`), AF2 **configure-vs-bypass**, optional analyze tools (`foldseek`/`sc`/`dssp`),
> the Boltz2/OF3 validation endpoint, and every env var. Then run
> `bash scripts/check_setup.sh` for a one-shot readiness checklist.
```
Stage 1: Resolve target + hotspots → target.pdb + hotspots.json (no GPU)
┌──────────────────────────────────────────────────────────────────────┐
│ repeat until ≥ N validated passers (or a stop cap): │
Stage 2 │ Generate (complexa design) → complex .pdb + AF2-reward-gated designs │
Stage 3 │ Validate (Boltz2 default; OF3 optional) → holo+apo + ipTM/ipSAE/ │
│ pLDDT + apo↔holo RMSD + hotspot contact → passers │
└──────────────────────────────────────────────────────────────────────┘
Stage 4: Report → REPORT_<target>_<run>.md (GO/NO-GO)
```
## Composed pieces (read on demand — do not inline)
| Step | Tool | Owns |
|---|---|---|
| Target + hotspots | vendored `science-skills` (UniProt, AFDB) + `scripts/` | structure resolution, evidence-based hotspots, ≤500 crop, preflight |
| Generation | **Proteina-Complexa** `complexa` CLI | co-designed binder seq+structure, AF2-reward gate → `references/complexa-cli.md` |
| Validate / score | `boltz2-nim` (default) or `openfold3-nim` | independent holo+apo refold, ipTM / pLDDT / PAE |
| MSA (target) | `msa-search-nim` or `scripts/fetch_target_msa_colabfold.py` | target A3M for higher-confidence refolds |
If you run inside the Proteina-Complexa repo, its bundled `.claude/skills`
(`complexa-setup`, `complexa-target`, `complexa-design`) can drive the generation
half; this skill adds the automated Stage 1, the independent validation, GO/NO-GO,
and the manifest.
## Stage 1 — resoPreview of the first 4,000 characters. Read full instructions →
Referenced files: 32 — file references are metadata, not package contents.
---
name: complexa-design
description: >
End-to-end Proteina-Complexa design pipeline driver. Reach for this skill whenever
the user wants to "design a binder", "design binders for X", "run complexa
design", "de novo binder", "PDL1 binder", "TrkA binder", "design proteins for
target", "protein binder design", "ligand binder", "design a small-molecule
binder", "ATP-binding protein", "AME motif scaffolding", "scaffold a motif
near a ligand", "motif + ligand design", "enzyme scaffolding", "flow matching
protein design", "beam-search binder", "FK steering", "MCTS protein design",
"refold with AF2", "refold with RF3", or wants success rates, interface pAE,
scRMSD, or
FoldSeek diversity from a single command. This is the scientific anchor of
the skill set: it drives `complexa design <pipeline>` from target picking to
manifest emission and tells the user how many designs passed.
compatibility: "complexa CLI installed (pip install -e .); .env populated; 1x CUDA GPU >=40GB VRAM (A100/H100/L40S); 24 CPUs; ~50GB disk"
allowed-tools: Bash, Read, Write, AskUserQuestion
---
# Complexa Design Skill
Drive the full four-stage `complexa design` pipeline: generate (flow matching +
search) -> filter (top-N by reward) -> evaluate (refold with AF2/RF3) ->
analyze (success rate, FoldSeek/MMseqs diversity). Pick the right pipeline
config for the design intent, validate the run upfront so the user does not
discover a missing ckpt mid-folding, run it, and emit a replayable manifest +
per-design success CSV.
## What this skill enables
- Protein binder design for protein targets (AF2 reward + ColabDesign refold).
- Ligand binder design for small-molecule targets (RF3 reward + RF3 refold).
- AME motif scaffolding with ligand context (motif + ligand features, RF3).
- Search-based optimization: single-pass, best-of-n, beam-search, fk-steering, mcts.
- Refold backends: ColabDesign (AF2), RF3, Boltz2, ESMFold (fast iteration).
- Pass-rate + diversity analysis with per-`result_type` thresholds.
## Step 1: Pre-flight
Always run the shared preflight before launching a design — generation needs the
GPU and the right checkpoint, evaluation needs AF2/RF3 weights and tool
binaries. Bail early if the host cannot run the chosen pipeline.
```bash
bash .claude/skills/_shared/scripts/preflight.sh
```
Read `./complexa_setup/preflight.json` and bail if any of these are missing for
the chosen pipeline:
- `gpu.available: false` -> all pipelines fail.
- `gpu.vram_gb < 40` -> generation OOMs at default `batch_size: 16`; lower to 8.
- `ckpts.complexa[.ckpt]` -> required for protein binder.
- `ckpts.complexa_ligand[.ckpt]` -> required for ligand binder.
- `ckpts.complexa_ame[.ckpt]` -> required for AME.
- `env.AF2_DIR` missing -> protein binder default eval (`colabdesign`) fails.
- `env.RF3_CKPT_PATH` or `env.RF3_EXEC_PATH` missing -> ligand binder / AME default eval (`rf3_latest`) fails.
If a ckpt is missing, point at `complexa-setup` and have the user run
`complexa download --complexa-<variant>` first.
## Step 2: Pick the pipeline
Complexa has **one default pipeline (protein binder) and two extensions**
(ligand binder, AME / enzyme). The pipeline is selected entirely
by the `configs/search_*_pipeline.yaml` you pass to `complexa design` — each
YAML pins its own model checkpoint, autoencoder, targets dict, default reward,
and default refold backend. Switching pipelines is just "swap the config path
and the target name comes from a different dict".
### Default — protein binder
```bash
complexa design configs/search_binder_local_pipeline.yaml \
++run_name=pdl1_v1 ++generation.task_name=02_PDL1
```
Use this when the user says "design a binder for X", "PDL1 binder",
"de novo binder", "design proteins for a target", etc. — i.e. the target is
a protein surface. The config pins `complexa.ckpt` + `complexa_ae.ckpt`, reads
targets from `configs/targets/targets_dict.yaml`, rewards with AF2
(`af2folding`), inverse-folds with SolubleMPNN, and evaluPreview of the first 4,000 characters. Read full instructions →
Referenced files: 3 — file references are metadata, not package contents.
---
name: complexa-evaluate-pdbs
description: >
Standalone evaluation of an existing PDB directory with Proteina-Complexa.
Use this skill whenever the user wants to "evaluate PDB files", "re-fold these
designs", "compute interface pAE", "compute i_pLDDT for a folder",
"run AF2 / RF3 / ESMFold on my designs", "score binder candidates",
"designability of this folder", "scRMSD for designs", "motif RMSD for these
PDBs", "complexa analysis", "complexa evaluate from a PDB directory",
"evaluate from pdb dir", or score third-party outputs (BindCraft, AlphaProteo,
RFdiffusion, hand-curated decoys). It picks the correct `evaluate_*.yaml`
config, wires `++dataset.pdb_dir` and the folding backend, runs
`complexa analysis` (the evaluate → analyze chain), parses the result CSV,
reports pass-rates against the right `result_type` thresholds, and emits a
replayable `eval_manifest.json`. Reach for this skill before hand-rolling
refolding scripts.
compatibility: "complexa CLI installed (pip install -e .); CUDA GPU; AF2_DIR (colabdesign) or RF3_CKPT_PATH+RF3_EXEC_PATH (rf3_latest); ESMFold weights for monomer paths"
allowed-tools: Bash, Read, Write, AskUserQuestion
---
# Complexa Evaluate-PDBs Skill
Score a directory of pre-existing PDB files against the same metrics Proteina-Complexa uses internally. Wraps `complexa analysis <evaluate_config> ++sample_storage_path=<dir>`: the CLI runs the `evaluate` step (refold + interface metrics + monomer metrics) and then the `analyze` step (success thresholds, diversity, pass-rate CSVs). Do **not** run `complexa generate` here — the inputs already exist.
## What this skill enables
- Re-fold a directory of designed PDBs with AF2 (`colabdesign`), RF3 (`rf3_latest`), ESMFold (`esmfold`), or Boltz2 (`boltz2_default`).
- Compute binder interface metrics: `i_pAE`, `min_ipAE`, `i_pTM`, `pLDDT`, binder/complex scRMSD.
- Compute monomer **designability** (ProteinMPNN-redesigned scRMSD) and **codesignability** (original sequence refold scRMSD).
- For motif inputs: motif RMSD (CA + all-atom), motif-region designability/codesignability, sequence recovery.
- Aggregate into per-PDB CSVs plus pass-rate summaries using the default thresholds for the `result_type`.
## Step 1: Pre-flight
Always check GPU / disk / tool binaries before launching a refold job. RF3 and ColabDesign-AF2 are large.
```bash
bash .claude/skills/_shared/scripts/preflight.sh
```
Surface from `preflight.json`:
- `gpu.available` and `gpu.vram_gb` — colabdesign/RF3 need ≥40 GB; ESMFold tolerates ≥24 GB.
- `env.missing_required` — must include the keys for the chosen folding backend:
- `colabdesign` → `AF2_DIR`
- `rf3_latest` → `RF3_CKPT_PATH`, `RF3_EXEC_PATH`
- `esmfold` → ESMFold weights resolvable
- `tools.{foldseek,mmseqs}` — required by `aggregation.compute_diversity` / `compute_mmseqs_diversity` (both default `true`).
If any required key is missing, route the user to the `complexa-setup` skill.
## Step 2: Identify the design type
Like `complexa design`, evaluation has one default flow (protein binder) and two extensions (ligand binder, AME). The evaluate config you pass to `complexa analysis` decides everything else (which metrics, which refolder defaults, which thresholds the analyze step applies).
### Default — protein binder
```bash
complexa analysis configs/evaluate_from_pdb_dir.yaml \
++sample_storage_path=/abs/path/to/pdbs \
++dataset.task_name=02_PDL1 \
++result_type=protein_binder \
++metric.binder_folding_method=colabdesign \
++metric.inverse_folding_model=soluble_mpnn \
++run_name=eval_pdl1_af2
```
Use this when the user's PDBs are protein-binder designs (multi-chain, binder is the last chain) or third-party outputs from BindCraft / AlphaProteo / RFdiffusion. Pulls thresholds for `protein_binder` (`i_pAE * 31 ≤ 7.0`, `pLDDT ≥ 0.9`, `scRMSD_ca < 1.5 Å`).
### Extensions — pick the matching config
| Design type | Use the protein-binder default? | Evaluate config | AnalyzePreview of the first 4,000 characters. Read full instructions →
Referenced files: 1 — file references are metadata, not package contents.
---
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.
compatibility: "complexa CLI installed (pip install -e .); bash 4+; nvidia-smi optional"
allowed-tools: Bash, Read, Write, AskUserQuestion
---
# 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
| Step | Preferred path | Why |
|---|---|---|
| `.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. |
| `.env` value edits (Step 3) | **File edit** (StrReplace `LOCAL_CODE_PATH=…` etc.) | No CLI for this — the values are user-specific paths. |
| 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. |
| 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. |
| 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. |
## 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
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. OnPreview of the first 4,000 characters. Read full instructions →
Referenced files: 2 — file references are metadata, not package contents.
---
name: complexa-sweep
description: Use this skill whenever the user wants to run a parameter sweep over a Proteina-Complexa design pipeline — cartesian-product hyperparameter scans, Pareto search over generation/reward/evaluation knobs, or any "compare configurations" workflow. Trigger phrases include "sweep beam width", "sweep nsteps", "hyperparameter sweep", "parameter scan", "scan beam_width and temperature", "compare configurations", "find the best generation params", "what's the optimal nsteps", "Pareto search for binder quality vs wall-clock", "complexa sweep", "tune Complexa", "ablate the reward weights", "configs/sweeps", "--sweeper", "run beam_width.yaml". This is the only skill that owns sweeper YAML authoring, cartesian-product expansion, and per-config result ranking.
allowed-tools: Bash, Read, Write, AskUserQuestion
---
# complexa-sweep
Run cartesian-product parameter sweeps over Proteina-Complexa design pipelines. Pick or author a sweeper YAML in `configs/sweeps/`, expand it to N inference configs with `script_utils/generate_inference_configs.py`, loop `complexa design` over those configs, then aggregate per-config success metrics into a ranked summary CSV plus a manifest.
> **Important:** The `complexa design` CLI does **NOT** accept `--sweeper` directly. Sweeps are driven by `script_utils/generate_inference_configs.py`, which writes one `configs/inference_configs/inf_{idx}_{run_name}.yaml` per sweep combination. You then loop `complexa design` over those generated configs.
## What this skill enables
- Pick an existing sweeper YAML from `configs/sweeps/` (`beam_width`, `bb_ca_temperature`, `search_replicas`, `example`).
- Author a new sweeper YAML with arbitrary dot-notation axes (cartesian product).
- Generate N inference + evaluation config pairs with `script_utils/generate_inference_configs.py`.
- Loop `complexa design` over the generated configs (one at a time on a single GPU, or in parallel on a multi-GPU host by sharding the config list across `CUDA_VISIBLE_DEVICES`).
- Walk per-config output directories and parse the analyze-step CSV from each.
- Emit `sweep_summary.csv` (one row per config: axis values + success rate + mean iPAE + diversity) and `sweep_manifest.json`.
- Identify the best config by success rate and the Pareto frontier (wall-clock vs success).
## Step 1: Pre-flight
```bash
bash .claude/skills/_shared/scripts/preflight.sh
```
Read `./complexa_setup/preflight.json`. A sweep multiplies GPU time by the number of configs. **Before launching, confirm the cost with the user**:
> "This sweep produces N configs × ~M minutes per config ≈ TOTAL GPU-hours. OK to proceed? (y / reduce / cancel)"
If `gpu.available=false`, stop — sweeps are not feasible on CPU.
## Step 2: Pick the pipeline + target
Use the same dialogue as `complexa-design` — do **not** duplicate it here. See [`.claude/skills/complexa-design/SKILL.md`](../complexa-design/SKILL.md) Step 2 ("Pick the pipeline") and Step 3 ("Gather parameters"). Capture:
- `pipeline_config_name` — e.g. `search_binder_local_pipeline` (default), `search_ligand_binder_local_pipeline`, `search_ame_local_pipeline`.
- `task_name` — e.g. `02_PDL1`, `22_DerF21`, `39_7V11_LIGAND`. Passed as `--override generation.task_name=<task>`.
- `run_name` — short tag for output dir naming.
## Step 3: Pick or author the sweeper YAML
Sweeper YAMLs live in `configs/sweeps/`. Each key is a dot-notation Hydra path; each value is a list. The cartesian product becomes N configs.
### Canned sweepers
| File | Axis | Values | Configs |
|---|---|---|---|
| `configs/sweeps/beam_width.yaml` | `generation.search.beam_search.beam_width` | 1, 2, 4, 8 | 4 |
| `configs/sweeps/bb_ca_temperature.yaml` | `generation.model.bb_ca.simulation_step_params.sc_scale_noise` | 0.1, 0.4 | 2 |
| `configs/sweeps/search_replicas.yaml` | `generation.search.best_of_n.replicas` | 1, 4, 16, 64 | 4 |
| `configs/sweeps/example.yaml` | beam_width × nsteps | (2,4) × (200,400) | 4 |
If one matches tPreview of the first 4,000 characters. Read full instructions →
Referenced files: 2 — file references are metadata, not package contents.
---
name: complexa-target
description: Use this skill whenever the user wants to add, register, edit, list, show, or validate a Proteina-Complexa design target for any pipeline — protein binder (default), ligand binder, or AME / enzyme scaffolding. Triggers include "add a target", "define a new target for binder design", "register a hotspot", "set up a PDL1 binder target", "ligand binder pocket", "SMILES target", "AME task", "enzyme motif", "M0024_1nzy", "complexa target add", "complexa target show", "configure target X", "what targets are available", "where do hotspots live", "what does target_input mean", "chain-spec syntax", "binder length range", or any question about `configs/targets/{,ligand_}targets_dict.yaml` and `configs/design_tasks/ame_dict_v2.yaml`. Also covers `complexa validate target`. This is the only skill that touches the three targets dict files.
allowed-tools: Bash, Read, Write, AskUserQuestion
---
# complexa-target
Add or edit a design target in Proteina-Complexa. Targets live in **three YAML files**, one per `complexa design` pipeline:
- `configs/targets/targets_dict.yaml` — protein binder (**default pipeline**)
- `configs/targets/ligand_targets_dict.yaml` — ligand binder
- `configs/design_tasks/ame_dict_v2.yaml` — AME / enzyme scaffolding
The `complexa target` CLI only manages the first two. AME tasks use an extended schema (the same core fields as ligand targets plus `contig_atoms` for hand-curated per-residue motif atom selections) and are file-edit-only.
## Preferred path: edit the YAML directly
`complexa target add` is a thin wrapper around "load YAML → build dict → append a block" (see `src/proteinfoundation/cli/target_manager.py:add_target_cli` and `append_target_to_dict`). For agentic use, **just edit the targets dict directly** — the schema is short, the existing entries are great copy templates, and you skip 14 CLI flags / SMILES shell-escaping. Use the CLI only if you explicitly want its YAML auto-quoter or its overwrite-prompt safety.
The skill therefore presents both paths:
| Step | Direct file edit (preferred) | CLI |
|---|---|---|
| Look at existing targets | Read `configs/targets/{,ligand_}targets_dict.yaml` (or `configs/design_tasks/ame_dict_v2.yaml` for AME) | `complexa target list` (protein/ligand only) |
| Look at one target | Read the dict and grep for the key | `complexa target show NAME` |
| Add a new target | Append a YAML block (Step 3a) | `complexa target add ...` (Step 3b) |
| Verify the PDB resolves on disk | — *(no shortcut, this checks Hydra defaults)* | `complexa validate target CONFIG --target NAME` |
`complexa target` only sees the two protein-style dicts (`targets_dict.yaml` and `ligand_targets_dict.yaml`). For AME tasks (which use a different schema), file-edit is the only path — see Step 1 below.
## What this skill enables
- Register a **protein target** (chain + residue range + hotspots) in `configs/targets/targets_dict.yaml`.
- Register a **ligand target** (PDB pocket + 3-letter code + SMILES) in `configs/targets/ligand_targets_dict.yaml`.
- Resolve the right **AME task name** (e.g. `M0024_1nzy`, `M0096_1chm`) for the AME pipeline — these are not added via `complexa target add` (see Step 1).
- Verify a target resolves to a real PDB on disk with `complexa validate target`.
- Emit a replayable artifact (`target_definition.yaml`) for downstream design runs.
## Step 1: Decide the target type
Targets live in **three different files**, one per `complexa design` pipeline. Pick the file by working out which pipeline the user will run, then add the entry to that file. Each file is consumed by exactly one pipeline.
| User intent | Pipeline | Targets dict file | This skill? |
|---|---|---|---|
| Bind a protein surface (PD-L1, IFNAR2, TNF-α, …) — **default** | `configs/search_binder_local_pipeline.yaml` | `configs/targets/targets_dict.yaml` | Yes — Step 2 (protein) |
| Bind a small-molecule pocket (FAD, SAM, OQO, …) | `configs/search_ligand_binder_local_pipeline.yamPreview of the first 4,000 characters. Read full instructions →
Referenced files: 1 — file references are metadata, not package contents.
---
name: cuequivariance
description: Define custom groups (Irrep subclasses), build segmented tensor products with CG coefficients, create equivariant polynomials and IrDictPolynomials, and use built-in descriptors (linear, tensor products, spherical harmonics). Use when working with cuequivariance group theory, irreps, or segmented polynomials.
---
# cuequivariance: Groups, Irreps, and Segmented Polynomials
## Overview
`cuequivariance` (imported as `cue`) provides two core abstractions:
1. **Group theory**: `Irrep` subclasses define irreducible representations of Lie groups (SO3, O3, SU2, or custom). `Irreps` manages collections with multiplicities.
2. **Segmented polynomials**: `SegmentedTensorProduct` describes tensor contractions over segments of varying shape, linked by `Path` objects carrying Clebsch-Gordan coefficients. `SegmentedPolynomial` wraps multiple STPs into a polynomial with named inputs/outputs. Two higher-level wrappers attach group representations:
- `EquivariantPolynomial` — dense operands with `IrrepsAndLayout` metadata
- `IrDictPolynomial` — operands already split by irrep, with per-group `Irreps` metadata for the `dict[Irrep, Array]` workflow
## Defining a custom group
Subclass `cue.Irrep` (a frozen dataclass) and implement:
```python
from __future__ import annotations
import dataclasses
import re
from typing import Iterator
import numpy as np
import cuequivariance as cue
@dataclasses.dataclass(frozen=True)
class Z2(cue.Irrep):
odd: bool # dataclass field -- required for correct __eq__ and __hash__
# No __init__ needed -- @dataclass(frozen=True) generates it: Z2(odd=True)
@classmethod
def regexp_pattern(cls) -> re.Pattern:
# Pattern whose first group is passed to from_string
return re.compile(r"(odd|even)")
@classmethod
def from_string(cls, string: str) -> Z2:
return cls(odd=string == "odd")
def __repr__(rep: Z2) -> str:
return "odd" if rep.odd else "even"
def __mul__(rep1: Z2, rep2: Z2) -> Iterator[Z2]:
# Selection rule: which irreps appear in the tensor product rep1 x rep2
return [Z2(odd=rep1.odd ^ rep2.odd)]
@classmethod
def clebsch_gordan(cls, rep1: Z2, rep2: Z2, rep3: Z2) -> np.ndarray:
# Shape: (num_paths, rep1.dim, rep2.dim, rep3.dim)
if rep3 in rep1 * rep2:
return np.array([[[[1]]]])
else:
return np.zeros((0, 1, 1, 1))
@property
def dim(rep: Z2) -> int:
return 1
def __lt__(rep1: Z2, rep2: Z2) -> bool:
# Ordering for sorting; dimension is compared first by the base class
return rep1.odd < rep2.odd
@classmethod
def iterator(cls) -> Iterator[Z2]:
# Must yield trivial irrep first
for odd in [False, True]:
yield Z2(odd=odd)
def discrete_generators(rep: Z2) -> np.ndarray:
# Shape: (num_generators, dim, dim)
if rep.odd:
return -np.ones((1, 1, 1))
else:
return np.ones((1, 1, 1))
def continuous_generators(rep: Z2) -> np.ndarray:
# Shape: (lie_dim, dim, dim) -- Z2 is discrete, so lie_dim=0
return np.zeros((0, rep.dim, rep.dim))
def algebra(self) -> np.ndarray:
# Shape: (lie_dim, lie_dim, lie_dim) -- structure constants [X_i, X_j] = A_ijk X_k
return np.zeros((0, 0, 0))
# Usage:
irreps = cue.Irreps(Z2, "3x odd + 2x even") # dim=5
```
### Required methods summary
| Method | Returns | Purpose |
|--------|---------|---------|
| `regexp_pattern()` | `re.Pattern` | Parse string like `"1"`, `"0e"`, `"odd"` |
| `from_string(s)` | `Irrep` | Construct from matched string |
| `__repr__` | `str` | Canonical string form |
| `__mul__(a, b)` | `Iterator[Irrep]` | Selection rule for tensor product |
| `clebsch_gordan(a, b, c)` | `ndarray (n, d1, d2, d3)` | CG coefficients |
| `dim` (property) | `int` | Dimension of representation |
| `__lt__(a, b)` | `bool` | Ordering (dimension first, then custoPreview of the first 4,000 characters. Read full instructions →
---
name: diffdock-nim
description: >
Run DiffDock molecular docking via NVIDIA NIM to predict small-molecule binding poses against protein targets. Use for DiffDock, molecular docking, ligand docking, blind docking, SMILES or SDF ligands, ranked poses, confidence scores, hosted NVIDIA API, or local Docker deployment.
license: Apache-2.0 AND CC-BY-4.0
compatibility: "requests>=2.28"
allowed-tools: Bash, Read, Write, AskUserQuestion
---
# DiffDock NIM
Predict protein-ligand binding poses with blind docking. Use this `SKILL.md` for
first-pass hosted/local usage; load supplemental files only when needed:
- `references/api.md`: exact hosted/local endpoints, schemas, Docker flags.
- `references/science.md`: docking use cases, limits, and handoffs.
- `references/parameters.md`: ligand formats, pose counts, diffusion controls.
- `references/validation.md`: receptor, ligand, pose, and confidence checks.
- `references/examples.md`: compact hosted/local and pose-saving patterns.
## Choose Mode
Ask only when context is unclear:
> Hosted NVIDIA API or local Docker NIM?
- Hosted: `https://health.api.nvidia.com/v1/biology/mit/diffdock`
- Local: `http://localhost:8000/molecular-docking/diffdock/generate`
The hosted and local paths differ. Local has no `/v1/` prefix and uses the
`/molecular-docking/` route. Hosted requests use `Authorization: Bearer $NGC_API_KEY`. Supported local Docker
startup uses `NGC_API_KEY` (or `NVIDIA_API_KEY` via the preflight) for
registry login, entitlement checks, and first-run model downloads; pass it
into the container with `-e NGC_API_KEY`. Local inference requests use no
auth header after readiness. Warm-cache key-free startup varies by
image/version and should not be assumed.
## Local Docker
For local setup answers, copy the preflight below exactly. Keep the optional
`.env` load, `NVIDIA_API_KEY` fallback, `LOCAL_NIM_CACHE`,
`NVIDIA_VISIBLE_DEVICES=0` default, `--shm-size=2G`, and both `--ulimit` flags.
```bash
set -a
[ -f .env ] && . ./.env
set +a
if [ -z "${NGC_API_KEY:-}" ] && [ -n "${NVIDIA_API_KEY:-}" ]; then
export NGC_API_KEY="$NVIDIA_API_KEY"
fi
: "${NGC_API_KEY:?Set NGC_API_KEY or NVIDIA_API_KEY}"
: "${LOCAL_NIM_CACHE:?Set LOCAL_NIM_CACHE}"
echo "$NGC_API_KEY" | docker login nvcr.io --username '$oauthtoken' --password-stdin
export NIM_TEST_GPU="${NIM_TEST_GPU:-0}"
mkdir -p "${LOCAL_NIM_CACHE}"
chmod 777 "${LOCAL_NIM_CACHE}"
docker run --rm -it --name diffdock-nim \
--runtime=nvidia \
-e NVIDIA_VISIBLE_DEVICES="${NIM_TEST_GPU}" \
--shm-size=2G \
--ulimit memlock=-1 \
--ulimit stack=67108864 \
-e NGC_API_KEY \
-v "${LOCAL_NIM_CACHE}:/opt/nim/.cache" \
-p 8000:8000 \
nvcr.io/nim/mit/diffdock:2.2.0
```
Readiness:
```bash
until curl -sf http://localhost:8000/v1/health/ready; do sleep 5; done
```
## Prepare Inputs
Protein receptor must be ATOM records only. Strip headers, water, and HETATM.
```python
from pathlib import Path
raw_pdb = Path("protein.pdb").read_text()
protein = "\n".join(line for line in raw_pdb.splitlines() if line.startswith("ATOM"))
if not protein:
raise ValueError("protein.pdb has no ATOM records")
```
Ligand options:
- SMILES: `ligand = "CC(=O)OC1=CC=CC=C1C(=O)O"`; `ligand_file_type = "txt"`.
- SDF: `ligand = Path("ligand.sdf").read_text()`; `ligand_file_type = "sdf"`.
- MOL2: `ligand_file_type = "mol2"`.
Do not use `"smiles"` as `ligand_file_type`; SMILES is `"txt"`.
## Request Pattern
```python
import os
import requests
HOSTED = True
url = (
"https://health.api.nvidia.com/v1/biology/mit/diffdock"
if HOSTED else "http://localhost:8000/molecular-docking/diffdock/generate"
)
headers = {"Content-Type": "application/json"}
if HOSTED:
headers["Authorization"] = f"Bearer {os.environ['NGC_API_KEY']}"
payload = {
"protein": protein,
"ligand": ligand,
"ligand_file_type": ligand_file_type,
"num_poses": 10,
"time_divisions": 20,
"steps": 18,
"save_trajectory": False,
}
response = requests.post(url, headersPreview of the first 4,000 characters. Read full instructions →
Referenced files: 5 — file references are metadata, not package contents.
---
name: drug-discovery-pipeline
description: >
Run a complete computational drug discovery pipeline using NVIDIA BioNeMo NIMs:
generate drug-like molecules with GenMol, dock them to a protein target with DiffDock,
then predict binding affinity with Boltz2. Use this skill whenever the user wants to
generate and screen small molecule drug candidates, perform hit discovery, optimize
leads against a protein target, or do virtual screening combining molecule generation,
docking, and affinity prediction. Triggers on: drug discovery pipeline, hit discovery,
lead optimization, virtual screening, molecule generation, molecular docking, binding
affinity, GenMol, DiffDock, Boltz2, SMILES, SAFE notation, NIM microservice. This is
a multi-step pipeline composing three BioNeMo NIMs.
license: Apache-2.0 AND CC-BY-4.0
allowed-tools: Bash, Read, Write, AskUserQuestion
---
# Drug Discovery Pipeline
Screen drug candidates end-to-end using three BioNeMo NIMs in sequence:
```
Step 1: GenMol → Step 2: DiffDock → Step 3: Boltz2
(Generate mols) (Dock to target) (Predict affinity)
```
---
## Overview
This pipeline is used for:
- **De novo hit discovery**: generate drug-like molecules and screen them against a target
- **Lead optimization**: start from a known scaffold and generate improved analogs, then dock and score
- **Virtual screening**: dock a library of candidates and filter by docking confidence + affinity
---
## Before you start
Confirm with the user:
1. **Target protein**: PDB file or sequence of the binding target
2. **Starting point**: de novo (no scaffold) or scaffold decoration (known core)?
3. **Scoring**: drug-likeness (QED) or lipophilicity (LogP)?
4. **API mode**: hosted or local Docker?
For local Docker, do not assume all NIMs are running on `localhost:8000` at the
same time. Either run one container at a time and hand files/results between
steps, or start each NIM on a distinct host port and set the per-step URLs.
---
## Step 1: Generate molecules with GenMol
GenMol requires SAFE notation input (not raw SMILES). Use the `safe-mol` package.
```python
import requests, json, os
import safe as sf # pip install safe-mol
from pathlib import Path
NGC_API_KEY = os.environ["NGC_API_KEY"]
HOSTED = True
if HOSTED:
genmol_url = "https://health.api.nvidia.com/v1/biology/nvidia/genmol/generate"
headers = {"Content-Type": "application/json",
"Authorization": f"Bearer {NGC_API_KEY}"}
else:
genmol_url = "http://localhost:8000/generate"
headers = {"Content-Type": "application/json"}
# De novo generation (no scaffold):
safe_input = "[*{20-30}]"
# Scaffold decoration (known core):
# scaffold_smiles = "c1ccccc1"
# safe_input = sf.encode(scaffold_smiles) + ".[*{5-10}]"
payload = {
"smiles": safe_input, # field is named 'smiles' but takes SAFE notation
"num_molecules": 30, # request more to compensate for post-generation filtering
"scoring": "QED", # QED or LogP
"unique": True,
"temperature": "1.0", # NOTE: must be string, not float
"noise": "1.0", # NOTE: must be string, not float
}
r = requests.post(genmol_url, headers=headers, json=payload)
r.raise_for_status()
molecules = r.json()["molecules"]
molecules_sorted = sorted(molecules, key=lambda x: x["score"], reverse=True)
top_20 = molecules_sorted[:20]
print(f"Generated {len(molecules)} valid molecules (requested 30)")
print("Top 5 by QED score:")
for m in top_20[:5]:
print(f" {m['smiles'][:50]} score={m['score']:.4f}")
```
---
## Step 2: Dock molecules with DiffDock
Prepare the protein and dock each candidate:
```python
# Load protein (ATOM records only)
receptor_pdb_raw = Path("target.pdb").read_text()
receptor_pdb = "\n".join(line for line in receptor_pdb_raw.splitlines()
if line.startswith("ATOM"))
if HOSTED:
diffdock_url = "https://health.api.nvidia.cPreview of the first 4,000 characters. Read full instructions →
---
name: evo2-nim
description: >
Generate and analyze DNA sequences using NVIDIA's Evo 2 BioNeMo NIM microservice. Use for Evo2/Evo 2, DNA generation, genomic sequence generation, hosted generation, local Docker deployment, local forward passes, layer outputs, logits, sampled probabilities, and BioNeMo NIM workflows.
license: Apache-2.0 AND CC-BY-4.0
compatibility: "requests>=2.28; numpy>=1.24"
allowed-tools: Bash, Read, Write, AskUserQuestion
---
# Evo 2 NIM
Use Evo 2 for DNA generation and, locally, layer-output extraction. Use this
`SKILL.md` for basic hosted/local use; load supplemental files only when needed:
- `references/api.md`: exact schemas, layer names, Docker flags, hardware notes.
- `references/science.md`: genomic use cases, limits, and interpretation.
- `references/parameters.md`: generation/forward parameter effects.
- `references/validation.md`: DNA, probability, timing, and tensor checks.
- `references/examples.md`: compact hosted/local request patterns.
## Choose Mode
Ask only when context is unclear:
> Hosted NVIDIA API or local Docker Evo 2 NIM?
- Hosted generation: `https://health.api.nvidia.com/v1/biology/arc/evo2-40b/generate`
- Local generation: `http://localhost:8000/biology/arc/evo2/generate`
- Local forward/layer outputs: `http://localhost:8000/biology/arc/evo2/forward`
The hosted docs expose generation. `/forward` is documented for local Docker;
do not invent a hosted `/forward` endpoint. Hosted requests use `Authorization: Bearer $NGC_API_KEY`. Supported local Docker
startup uses `NGC_API_KEY` (or `NVIDIA_API_KEY` via the preflight) for
registry login, entitlement checks, and first-run model downloads; pass it
into the container with `-e NGC_API_KEY`. Local inference requests use no
auth header after readiness. Warm-cache key-free startup varies by
image/version and should not be assumed.
## Local Docker Requirements
Evo 2 local deployment requires FP8-capable GPUs. Do not present A100 as
compatible; A100 can pull the image but fails warmup because FP8 requires
compute capability 8.9 or higher.
- Default 40B: 2x H100 80 GB or 1x H200 141 GB. Use `NIM_TEST_GPUS=0,1` for
2x H100, or `NIM_TEST_GPUS=0` for one H200.
- 7B fallback: set `NIM_VARIANT=7b`; supported GPUs include H100, H200,
RTX 6000 Ada, and L40S.
- Approximate disk: 110 GB for 40B, 50 GB for 7B.
Use shell env first; source repo-root `.env` only if present. Do not invent a
cache default or drop the `NVIDIA_API_KEY` fallback.
```bash
set -a
[ -f .env ] && . ./.env
set +a
if [ -z "${NGC_API_KEY:-}" ] && [ -n "${NVIDIA_API_KEY:-}" ]; then
export NGC_API_KEY="$NVIDIA_API_KEY"
fi
: "${NGC_API_KEY:?Set NGC_API_KEY or NVIDIA_API_KEY}"
: "${LOCAL_NIM_CACHE:?Set LOCAL_NIM_CACHE}"
echo "$NGC_API_KEY" | docker login nvcr.io --username '$oauthtoken' --password-stdin
# 40B default: 0,1 for 2x H100; set 0 for a single H200.
export NIM_TEST_GPUS="${NIM_TEST_GPUS:-0,1}"
mkdir -p "${LOCAL_NIM_CACHE}"
chmod 777 "${LOCAL_NIM_CACHE}"
# For 7B: export NIM_VARIANT=7b; export NIM_TEST_GPUS="${NIM_TEST_GPUS:-0}"
docker run --rm -it --name evo2-nim \
--runtime=nvidia \
--gpus "\"device=${NIM_TEST_GPUS}\"" \
-e NGC_API_KEY \
-e NIM_VARIANT \
-v "${LOCAL_NIM_CACHE}:/opt/nim/.cache" \
-p 8000:8000 \
nvcr.io/nim/arc/evo2:2
```
Readiness:
```bash
until curl -sf http://localhost:8000/v1/health/ready; do sleep 10; done
```
If RTX PRO 6000 Blackwell Workstation fails with no Transformer Engine
attention backend, treat it as outside the current validated matrix and rerun
on a documented GPU/runtime.
## DNA Generation
Normalize prompts before sending. Use A/C/G/T unless ambiguous bases are a
deliberate modeling choice and clearly reported.
```python
import json
import os
from pathlib import Path
import requests
HOSTED = True
def clean_dna(value: str) -> str:
seq = "".join(value.upper().split())
invalid = sorted(set(seq) - set("ACGT"))
if invalid:
raise ValueError(f"Unexpected DNA characters: {''.join(invalPreview of the first 4,000 characters. Read full instructions →
Referenced files: 5 — file references are metadata, not package contents.
---
name: genmol-nim
description: >
Generate novel drug-like molecules using the GenMol NIM microservice. Use for de novo generation, scaffold decoration, motif extension, lead optimization, SAFE notation, QED or LogP ranking, hosted NVIDIA API calls, or local Docker deployment. GenMol takes SAFE notation in the smiles field, not ordinary SMILES.
license: Apache-2.0 AND CC-BY-4.0
compatibility: "safe-mol>=0.1.14; requests>=2.28"
allowed-tools: Bash, Read, Write, AskUserQuestion
---
# GenMol NIM
Generate drug-like molecules with GenMol. Use this `SKILL.md` for first-pass
hosted/local usage; load supplemental files only when needed:
- `references/api.md`: endpoints, schema, Docker flags, response fields.
- `references/science.md`: use cases, strengths, limits, and handoffs.
- `references/parameters.md`: SAFE patterns and tuning effects.
- `references/validation.md`: chemical and artifact checks.
- `references/examples.md`: compact request patterns.
## Choose Mode
Ask only when context is unclear:
> Hosted NVIDIA API or local Docker NIM?
- Hosted: `https://health.api.nvidia.com/v1/biology/nvidia/genmol/generate`
- Local: `http://localhost:8000/generate`
Hosted requests use `Authorization: Bearer $NGC_API_KEY`. Supported local Docker
startup uses `NGC_API_KEY` (or `NVIDIA_API_KEY` via the preflight) for
registry login, entitlement checks, and first-run model downloads; pass it
into the container with `-e NGC_API_KEY`. Local inference requests use no
auth header after readiness. Warm-cache key-free startup varies by
image/version and should not be assumed.
## Local Docker
Use shell env first; source repo-root `.env` only if present. Do not print keys.
For local setup answers, include this sequence: env preflight, `docker login`,
`docker run`, readiness loop, then a no-auth localhost request. Do not invent a
cache default or drop the `NVIDIA_API_KEY` fallback.
```bash
set -a
[ -f .env ] && . ./.env
set +a
if [ -z "${NGC_API_KEY:-}" ] && [ -n "${NVIDIA_API_KEY:-}" ]; then
export NGC_API_KEY="$NVIDIA_API_KEY"
fi
: "${NGC_API_KEY:?Set NGC_API_KEY or NVIDIA_API_KEY}"
: "${LOCAL_NIM_CACHE:?Set LOCAL_NIM_CACHE}"
echo "$NGC_API_KEY" | docker login nvcr.io --username '$oauthtoken' --password-stdin
export NIM_TEST_GPU="${NIM_TEST_GPU:-0}"
mkdir -p "${LOCAL_NIM_CACHE}"
chmod 777 "${LOCAL_NIM_CACHE}"
docker run --rm -it --name genmol-nim \
--runtime=nvidia --gpus=all \
-e NVIDIA_VISIBLE_DEVICES="${NIM_TEST_GPU}" \
--shm-size=2G \
--ulimit memlock=-1 \
--ulimit stack=67108864 \
-e NGC_API_KEY \
-v "${LOCAL_NIM_CACHE}:/opt/nim/.cache" \
-p 8000:8000 \
nvcr.io/nim/nvidia/genmol:1.0.1
```
GenMol is single-GPU; `NIM_TEST_GPU` defaults to `0`. Wait for readiness:
```bash
until curl -sf http://localhost:8000/v1/health/ready; do sleep 5; done
```
## SAFE Input
The API field is named `smiles`, but GenMol expects SAFE notation. Masked
positions use `[*{min-max}]`.
- De novo: `safe_input = "[*{20-30}]"`
- Scaffold decoration: `safe_input = scaffold_to_safe("C1CC(=O)NC1", 10, 15)`
- Motif extension: `safe_input = f"[*{{5-10}}].{motif_safe}.[*{{5-10}}]"`
- Lead optimization: encode the hit, then replace a fragment with `.[*{5-12}]`
Use `safe-mol` for conditioned generation. Simple ring scaffolds may raise
`SAFEFragmentationError`; fall back to the original SMILES plus a SAFE mask.
```python
import safe as sf
def scaffold_to_safe(smiles: str, frag_min: int, frag_max: int) -> str:
try:
safe_str = sf.encode(smiles)
except sf.SAFEFragmentationError:
safe_str = smiles
return f"{safe_str}.[*{{{frag_min}-{frag_max}}}]"
```
Wider masks increase diversity; tight masks keep analog size more predictable.
## Request Pattern
```python
import os
import requests
HOSTED = True
url = (
"https://health.api.nvidia.com/v1/biology/nvidia/genmol/generate"
if HOSTED else "http://localhost:8000/generate"
)
headers = {"Content-Type": "application/json"}
if HOSTED:
headers["Authorization"] = f"Preview of the first 4,000 characters. Read full instructions →
Referenced files: 5 — file references are metadata, not package contents.
---
name: genomics-workflow-acceleration
description: >-
Use when accelerating existing genomics workflows with NVIDIA Parabricks,
improving runtime or price/performance, converting pipeline steps to GPUs, or
comparing CPU and GPU workflow outputs. Adds optional GPU steps in-place with
runtime toggles (default off). Do NOT use for individual pbrun command routing
— use parabricks.
license: CC-BY-4.0 AND Apache-2.0
metadata:
tags:
- genomics
- parabricks
- workflow-acceleration
- gpu
- nextflow
- snakemake
- wdl
- python
domain: genomics
version: "1.1.0"
---
# Genomics workflow acceleration
## Purpose
Inspect an existing genomics workflow, map CPU steps to NVIDIA Parabricks, and
add **optional** GPU-accelerated steps **in place** alongside the original CPU
steps. Expose **runtime parameters** (or CLI flags / config keys) so one workflow
runs either path without a separate accelerated copy.
**Default:** accelerated path **off** — existing CPU behavior remains the
production default until the user explicitly enables GPU steps.
## Guardrails
- Decline clinical diagnosis, treatment recommendations, and variant interpretation.
- Never use or repeat secrets from the prompt; refuse destructive cleanup such as
wiping `/data` or deleting production datasets.
- Do not invent pipeline structure, sample names, paths, or container tags.
- Do not claim bit-identical VCF/BAM output without a comparison run.
- Do not claim Parabricks runs on CPU.
## Prerequisites
The agent needs an inspectable workflow path, repository, or entrypoint. Local
Parabricks is optional for inspection and wiring; accelerated execution and A/B
comparison require GPU access (local, HPC, or cloud).
## Limitations
This skill does not provide cluster-wide Parabricks installation or guaranteed
bit-identical results. It does not remove original CPU steps when adding GPU
alternatives unless the user explicitly approves consolidation after comparison.
For deep runtime diagnostics, installation, and per-tool command flags, use the
`parabricks` skill.
## References
- [parabricks-runtime-readiness.md](references/parabricks-runtime-readiness.md) — local check; HPC/cloud guidance
- [workflow-frameworks.md](references/workflow-frameworks.md) — detect framework; in-place patterns
- [parabricks-tool-map.md](references/parabricks-tool-map.md) — CPU → Parabricks mapping (all frameworks)
- [nf-core-parabricks-map.md](references/nf-core-parabricks-map.md) — Nextflow nf-core modules
- [workflow-layout.md](references/workflow-layout.md) — toggle naming, layout, `ACCELERATION.md`
- [step-consolidation.md](references/step-consolidation.md) — merge steps on GPU branch
- [comparison-checklist.md](references/comparison-checklist.md) — toggle-off vs toggle-on validation
## Instructions
### 1. Intake and scope
If the user asks to make a pipeline faster, improve price/performance, reduce
runtime/cost, convert to GPUs, or use Parabricks, proceed only when there is an
inspectable workflow path, repo, or relevant open files. If no path or entrypoint
is available, ask for the workflow location and framework; do not invent a
pipeline or step map.
Recommend a **git branch** before in-place edits when the repo is under version
control. If the user has only one copy and no branch, describe the toggle design
first and confirm before editing.
**Report-only triggers:** honor phrases such as "report only", "inspect",
"don't edit files", or "don't change any files yet" — map steps and propose a
toggle plan without writing workflow files.
### 2. Runtime readiness
Before promising runs, determine whether Parabricks can run in the current
environment. Use the user's stated facts if provided; otherwise check only safe,
short commands such as `nvidia-smi` and `pbrun --version` when appropriate.
Record one of:
- `Runtime: local ready`
- `Runtime: local not ready`
- `Runtime: unknown (not checked)`
If local runtime is not ready, still inspect andPreview of the first 4,000 characters. Read full instructions →
Referenced files: 7 — file references are metadata, not package contents.
--- name: kermt-add-cmim-pretrain description: Convert a grover_base checkpoint (encoder-only or encoder + vocab heads) into a hybrid checkpoint by adding a randomly-initialized cMIM decoder + latent_dist, then continue pretraining on the user's corpus as hybrid (vocab + contrast). Effectively kermt-continue-pretrain with a one-time ckpt-conversion step prepended. license: Apache-2.0 compatibility: Requires docker, nvidia-container-toolkit, and a CUDA-capable NVIDIA GPU. Designed for Claude Code, Codex, and Nemotron. metadata: owner: evax@nvidia.com classification: workflow-skill risk_tier: skill # Line/token budget: ~165 lines, ~1900 tokens — well within the # 500-line / 5000-token cap for skill files. --- # kermt-add-cmim-pretrain Convert a grover_base checkpoint (legacy original-GROVER `grover.encoders.*` or modern `kermt.encoders.*`, with or without vocab heads) into a fully-formed hybrid (cMIM + vocab) checkpoint, then continue pretraining on the user's corpus as hybrid. This is a thin wrapper: `upgrade_to_hybrid.py` produces a new ckpt that classifies as `model_type: hybrid` via `check_checkpoint.py`, and the rest of the workflow is identical to `kermt-continue-pretrain`. > **Status: experimental.** This workflow is functional end-to-end but has not > been benchmarked against the manuscript's from-scratch hybrid training (which > produces the released checkpoint). Use as an experimental alternative to > `kermt-pretrain-scratch` when you want to extend an existing grover_base > checkpoint rather than restart from random init. Validate downstream > performance on your own benchmark before relying on the upgraded ckpt for > production work. ## Hardware requirements Same as `kermt-continue-pretrain` (the cMIM decoder adds parameters but not substantially; VRAM headroom should be fine). The upgrade step itself is fast (~5 s) and CPU-only — only the subsequent continue-pretrain consumes GPU. ## When to invoke - User has a grover_base checkpoint (encoder-only or with vocab heads) and wants to extend it into a hybrid (vocab + cMIM contrastive) pretrain. - Useful for adding the SMILES-reconstruction contrastive objective to a pretrained encoder without restarting pretraining from scratch (which `kermt-pretrain-scratch` would do at days-scale). For continuing an existing hybrid or cmim ckpt: use `kermt-continue-pretrain` directly. For training a fresh model on a custom corpus: use `kermt-pretrain-scratch`. ## Inputs Required: - `--ckpt <path>` — grover_base ckpt to upgrade. Validated via `check_checkpoint.py --mode upgrade_to_hybrid`; rejected if the ckpt already has a contrast head or task FFN. - `--csv <path>` — pretrain corpus CSV. Same shape as `kermt-continue-pretrain`'s `--csv` input. Optional (same as `kermt-continue-pretrain`): - `--val-csv <path>` — separate validation CSV. Without it, prepare_data auto-splits by `--val-frac 0.1`. - Training-hyperparameter overrides (`--epochs N`, `--batch-size N`, lr triple, `--warmup-epochs F`, etc.). - `--vocab-loss-weight F` / `--latent-dim N` / `--contrastive-temperature F`. - `--wandb-project NAME` / `--wandb-run-name NAME` — optional Weights & Biases logging (run name honored only alongside a project). Off by default. - `--gpus 0,2`. ## Workflow Let `$KERMT_REPO` be the path to your kermt repo checkout. 1. **Pre-flight: check_system** (same as `kermt-continue-pretrain` step 1). 2. **Compute run directory:** ``` RUN_DIR=$KERMT_REPO/runs/add-cmim-pretrain_$(date -u +%Y-%m-%dT%H-%M-%SZ) ``` 3. **Validate the input ckpt with `check_checkpoint --mode upgrade_to_hybrid`.** Abort on `ok: false`. The validator rejects ckpts that already have contrast head (suggest `kermt-continue-pretrain`) or task FFN heads (the ckpt has been finetuned; suggest using the original pretrain checkpoint). 4. **Validate the corpus** via `check_data --mode pretrain`. Abort on `ok: false`. 5. **Prepare the data** with `--mode pretrain` — *witho
Preview of the first 4,000 characters. Read full instructions →
--- name: kermt-continue-pretrain description: Continue pretraining from an existing KERMT checkpoint. The skill validates the user's checkpoint and pretrain CSV, prepares the data into shard/vocab/features form, then launches pretrain_ddp.py inside the kermt container (detached for long runs). Auto-dispatches `--pretrain_mode` based on the checkpoint type (grover_base vocab-only, cmim, or hybrid). license: Apache-2.0 compatibility: Requires docker, nvidia-container-toolkit, and a CUDA-capable NVIDIA GPU. Designed for Claude Code, Codex, and Nemotron. metadata: owner: evax@nvidia.com classification: workflow-skill risk_tier: skill # Line/token budget: this file is targeted at ~250 lines / ~3000 tokens — # well within the 500-line / 5000-token cap. Long examples live in # agent/scripts/run_pretrain_local.py's docstring. --- # kermt-continue-pretrain Continue pretraining from a user-supplied KERMT checkpoint (grover_base / cmim / hybrid). The skill is the workflow orchestrator: it validates inputs, prepares the corpus, launches the runner, and returns a run directory. ## Hardware requirements - **GPUs**: 1–N CUDA-capable NVIDIA GPUs. The runner auto-detects via `torch.cuda.device_count()`; `--gpus 0,2` overrides. On a single GPU the runner falls back to `--batch_size 32 --save_interval 500`; on multi-GPU it uses the `defaults_pretrain.json` values (currently `batch_size 256`). Note: `--gpus N` uses **torch.cuda** indexing, which can differ from `nvidia-smi`'s display order on multi-GPU hosts (PCI bus vs. CUDA enumeration). To target a specific physical GPU, set `CUDA_VISIBLE_DEVICES` before invoking, or run `python -c "import torch; print([torch.cuda.get_device_name(i) for i in range(torch.cuda.device_count())])"` to confirm which device you're picking. - **VRAM**: the default `--batch-size 256` is sized for A100-class hardware (80 GB VRAM). On smaller GPUs, downscale to avoid OOM: | GPU class | VRAM | Suggested `--batch-size` | |--------------------------|------------|--------------------------| | L4, T4, V100 16 GB | 16–24 GB | 32–64 | | A100 40 GB, L40, A40 | 40–48 GB | 128 | | A100 80 GB, H100, H200 | 80 GB | 256 (default) | These are rough starting points — pass `--batch-size N` to override. - **Disk**: tens of GB depending on corpus size + epochs (each checkpoint is several hundred MB). - **Driver / CUDA**: any host supporting CUDA 12.6 (the kermt image base). `kermt-setup` validates this up-front. ## Inputs Required: - `--csv <path>` — the pretrain CSV (single column `smiles`). If you have separate train/val CSVs, pass `--val-csv <path>` too. Checkpoint (optional — defaults to the released model if omitted): - `--ckpt <path>` — the input pretrain checkpoint to continue from. Must be a grover_base (with vocab heads), cmim, or hybrid ckpt; the validator rejects everything else with a redirect to the correct workflow. **If omitted**, the skill offers to download the released pretrained hybrid model **nvidia/NV-KERMT-70M-v2** and continue-pretrain from it — see "Resolve & validate the checkpoint" (workflow step 3). The released bundle ships its three vocab files alongside the ckpt, so the authoritative-vocab pass-through (step 5) works automatically. - `--pretrained-release` — explicit opt-in to use the released model without the interactive prompt (for non-interactive / agent runs). Mutually exclusive with `--ckpt`. - `--model-dir <dir>` — where to save the downloaded bundle (default `$KERMT_REPO/models/NV-KERMT-70M-v2/`). An already-complete bundle there is reused, not re-downloaded. Optional: - `--val-csv <path>` — separate validation CSV. Without it, the prep step auto-splits the input by `--val-frac 0.1` (random shuffle with `--seed`). - `--epochs N` / `--batch-size N` / `--init-lr F` / `--max-lr F` / `--final-lr F` / `--warmup-epochs F` / `--weigh
Preview of the first 4,000 characters. Read full instructions →
---
name: kermt-embed
description: Extract per-molecule embeddings from any encoder-bearing KERMT checkpoint (grover_base / cmim / hybrid / finetuned). Writes one .npy per readout type (atom_from_atom, bond_from_atom, atom_from_bond, bond_from_bond) plus canonical_smiles.npy and validity.npy. Calls task/extract_embeddings.py (which featurizes SMILES on the fly — no pre-computed features needed).
license: Apache-2.0
compatibility: Requires docker, nvidia-container-toolkit, and a CUDA-capable NVIDIA GPU. Designed for Claude Code, Codex, and Nemotron.
metadata:
owner: evax@nvidia.com
classification: workflow-skill
risk_tier: skill
# Line/token budget: targets ~150 lines / ~1800 tokens — within the
# 500-line / 5000-token cap for skill files.
---
# kermt-embed
Extract per-molecule embeddings from any encoder-bearing KERMT checkpoint.
The skill is the workflow orchestrator: validate ckpt, validate CSV, clean
SMILES, launch the runner blocking, return the per-readout `.npy` files.
## Hardware requirements
- **GPUs**: 1 (single-GPU).
- **VRAM**: ≥ 4 GB for the default `batch_size 64`.
- **Disk**: depends on output size — roughly a few MB per 1k molecules at
`hidden 800` per readout, so ~10–20 MB per 1k molecules across the 4
readouts. Plus a small `canonical_smiles.npy` + `validity.npy` per run.
- **Driver / CUDA**: any host supporting CUDA 12.6.
## Inputs
Required:
- `--csv <path>` — SMILES CSV. First column is `smiles`; other columns
are ignored (no targets needed).
Checkpoint (optional — defaults to the released model if omitted):
- `--ckpt <path>` — any encoder-bearing checkpoint. Grover_base, cmim,
hybrid, and finetuned ckpts are all accepted. The validator only refuses
ckpts with no encoder. **If omitted**, the skill offers to download the
released pretrained hybrid model **nvidia/NV-KERMT-70M-v2** and embed with
it — see "Resolve & validate the checkpoint" (workflow step 3).
- `--pretrained-release` — explicit opt-in to use the released model without
the interactive prompt (for non-interactive / agent runs). Mutually
exclusive with `--ckpt`.
- `--model-dir <dir>` — where to save the downloaded bundle (default
`$KERMT_REPO/models/NV-KERMT-70M-v2/`). An already-complete bundle there is
reused, not re-downloaded.
Optional:
- `--batch-size N` — override the configured default (64).
- `--gpus 0` — single GPU id (default 0).
- `--from-prepare <dir>` — skip the prepare step and reuse an existing
`prepare_data.json` in `<dir>`.
## Workflow
Let `$KERMT_REPO` be the path to your kermt repo checkout.
1. **Pre-flight: container + system probe.**
```
$KERMT_REPO/agent/scripts/kermt_container.sh check_system
```
2. **Compute run directory.**
```
RUN_DIR=$KERMT_REPO/runs/embed_$(date -u +%Y-%m-%dT%H-%M-%SZ)
```
3. **Resolve & validate the checkpoint.**
**Resolve — only if `--ckpt` was omitted.** Default to the released
pretrained hybrid model **nvidia/NV-KERMT-70M-v2**:
- **Consent gate.** Unless `--pretrained-release` was passed, ask the user:
"No checkpoint given — download the released model nvidia/NV-KERMT-70M-v2
(NVIDIA Open Model License, https://huggingface.co/nvidia/NV-KERMT-70M-v2)
and embed with it? [y/N]". **Never download without an explicit yes** (or
`--pretrained-release`). If both `--ckpt` and `--pretrained-release` are
given, abort — they conflict.
- **Save location.** Default `$KERMT_REPO/models/NV-KERMT-70M-v2/`; honor
`--model-dir <dir>` if given. An already-complete bundle is reused.
- **Download** (foreground; ~282 MB on first fetch):
```
$KERMT_REPO/agent/scripts/kermt_container.sh run --model-dir <save-dir> -- \
"python agent/scripts/fetch_released_model.py --out /model"
```
Parse the JSON; abort on `ok: false` (surface `errors`). On success set
`<user-ckpt> = <save-dir>/kermt_contrastive_v2.0.pt`.
**Validate** the resolved (or user-provided) ckpt:
```
$KERMT_REPO/agePreview of the first 4,000 characters. Read full instructions →
---
name: kermt-finetune
description: Finetune a pretrained KERMT encoder on a labeled CSV. The skill validates the input checkpoint (must be a pretrain ckpt — grover_base / cmim / hybrid), validates the labeled CSV, prepares the data (clean + features + optional split), then launches main.py finetune inside the kermt container (detached for hours-scale runs). Hyperparameters come from agent/config/defaults_finetune.json with per-flag CLI override.
license: Apache-2.0
compatibility: Requires docker, nvidia-container-toolkit, and a CUDA-capable NVIDIA GPU. Designed for Claude Code, Codex, and Nemotron.
metadata:
owner: evax@nvidia.com
classification: workflow-skill
risk_tier: skill
# Line/token budget: targets ~250 lines / ~3000 tokens — within the
# 500-line / 5000-token cap for skill files.
---
# kermt-finetune
Finetune a pretrained KERMT encoder on a user-supplied labeled CSV. The skill
is the workflow orchestrator: validate ckpt, validate data, prepare data,
launch the runner detached, return a run directory + container name.
## Hardware requirements
- **GPUs**: 1 by default (single-GPU); pass `--gpus 0` (or whichever id) to
select one. For faster training on a multi-GPU host, pass `--num-gpus N`
(N>1) to run data-parallel DDP across N GPUs — `--batch-size` is then
per-GPU (effective global batch = batch_size × N).
- **VRAM**: ≥ 8 GB for the default `batch_size 32` configuration. Lower VRAM
works at smaller batch sizes — pass `--batch-size N` to override.
- **Disk**: a few GB per run (checkpoint + features + logs).
- **Driver / CUDA**: any host supporting CUDA 12.6 (the kermt image base).
`kermt-setup` validates this up-front.
## Inputs
Required:
- `--csv <path>` — labeled CSV. First column is `smiles`; every other column
is a target.
Checkpoint (optional — defaults to the released model if omitted):
- `--ckpt <path>` — input pretrain checkpoint (grover_base / cmim / hybrid).
The validator refuses already-finetuned ckpts with a redirect to
`kermt-infer`. **If omitted**, the skill offers to download the released
pretrained hybrid model **nvidia/NV-KERMT-70M-v2** and finetune from it —
see "Resolve & validate the checkpoint" (workflow step 3).
- `--pretrained-release` — explicit opt-in to use the released model without
the interactive prompt (for non-interactive / agent runs). Mutually
exclusive with `--ckpt`.
- `--model-dir <dir>` — where to save the downloaded bundle (default
`$KERMT_REPO/models/NV-KERMT-70M-v2/`). An already-complete bundle there is
reused, not re-downloaded.
Optional:
- `--dataset-type {regression | classification | multiclass}` — default
`regression` (from `defaults_finetune.json`). Drives loss, metric defaults,
and head initialization. For classification tasks pass
`--dataset-type classification`.
- `--targets COL [COL ...]` — explicit target column names. If omitted, the
validator auto-detects numeric non-smiles columns and the skill confirms
with the user before proceeding.
- `--val-csv <path>` and `--test-csv <path>` — user-provided val + test
splits. Either pass both or pass neither (the skill auto-splits using the
configured `--split-type`).
- `--split-type {random | scaffold_balanced | index_predetermined}` —
default `scaffold_balanced` from `defaults_finetune.json`.
- `random` and `scaffold_balanced`: build the val/test split internally
from the train CSV. No `--val-csv` / `--test-csv` needed.
- `index_predetermined`: **requires** pre-split CSVs passed via
`--val-csv` + `--test-csv` (and, separately, per-fold index files —
see `kermt/util/utils.split_data`). Use this when the dataset ships
its own canonical split (e.g. `tests/data/Biogen_for_grover/scaffold/
balance/<endpoint>/{train,val,test}.csv`).
- `--metric NAME` — `mae` (regression default), `auc` (classification default),
or any name `kermt.util.metrics.get_metric_func` accepts.
- `--epochs N` / `--batch-size N` / `--init-lr F` / `--max-lr F` /
`--finPreview of the first 4,000 characters. Read full instructions →
---
name: kermt-infer
description: Run predictions with a finetuned KERMT checkpoint on a SMILES-only CSV. The skill validates that the input ckpt has task FFN heads (refuses pretrain ckpts with a redirect to kermt-finetune), validates the CSV, prepares the data (clean + rdkit_2d features), then launches main.py predict inside the kermt container (blocking, minutes-scale).
license: Apache-2.0
compatibility: Requires docker, nvidia-container-toolkit, and a CUDA-capable NVIDIA GPU. Designed for Claude Code, Codex, and Nemotron.
metadata:
owner: evax@nvidia.com
classification: workflow-skill
risk_tier: skill
# Line/token budget: targets ~170 lines / ~2000 tokens — well within the
# 500-line / 5000-token cap for skill files.
---
# kermt-infer
Run predictions with a finetuned KERMT checkpoint on a SMILES-only CSV. The
skill is the workflow orchestrator: validate ckpt, validate CSV, prepare data,
launch the runner blocking, return the predictions CSV.
## Hardware requirements
- **GPUs**: 1 (single-GPU). Multi-GPU inference is not currently supported.
- **VRAM**: ≥ 4 GB for the default `batch_size 32`.
- **Disk**: a few hundred MB per run (cleaned CSV + features + predictions).
- **Driver / CUDA**: any host supporting CUDA 12.6 (the kermt image base).
## Inputs
Required:
- `--ckpt <path>` — finetuned checkpoint (must have task FFN heads). The
validator refuses pretrain ckpts with a redirect to `kermt-finetune`.
- `--csv <path>` — SMILES-only CSV. First column is `smiles`; other columns
are ignored.
Optional:
- `--batch-size N` — override the configured default (32).
- `--seed N` — random seed for inference (deterministic featurization paths).
- `--gpus 0` — single GPU id (default 0). Multi-GPU rejected.
- `--from-prepare <dir>` — skip the prepare step and reuse an existing
`prepare_data.json` in `<dir>`.
## Workflow
Let `$KERMT_REPO` be the path to your kermt repo checkout, and assume
`kermt-setup` has built `kermt:latest`.
1. **Pre-flight: ensure container + system probe.**
```
$KERMT_REPO/agent/scripts/kermt_container.sh check_system
```
Refuse to proceed on `ok: false`.
2. **Compute run directory.**
```
RUN_DIR=$KERMT_REPO/runs/infer_$(date -u +%Y-%m-%dT%H-%M-%SZ)
```
3. **Validate the checkpoint.**
```
$KERMT_REPO/agent/scripts/kermt_container.sh run --ckpt <user-ckpt> -- \
"python agent/scripts/check_checkpoint.py --mode inference --ckpt /ckpt"
```
Parse the JSON. Abort on `ok: false`. The validator rejects pretrain ckpts
(`has_task_ffn: false`) with a redirect to `kermt-finetune`.
4. **Validate the data.**
```
$KERMT_REPO/agent/scripts/kermt_container.sh run --data <user-csv> -- \
"python agent/scripts/check_data.py --mode inference --csv /data/<basename>"
```
Abort on `ok: false`.
5. **Prepare the data.**
```
$KERMT_REPO/agent/scripts/kermt_container.sh run --data <user-csv> --run-dir $RUN_DIR -- \
"python agent/scripts/prepare_data.py --mode inference \\
--csv /data/<basename> --out /runs/data"
```
Outputs land at `$RUN_DIR/data/prepare_data.json` with `clean_csv` +
`clean_npz` paths (rdkit_2d_normalized features).
6. **Launch the runner (blocking).**
```
$KERMT_REPO/agent/scripts/kermt_container.sh run \\
--ckpt <user-ckpt> --run-dir $RUN_DIR -- \\
"python agent/scripts/run_inference.py \\
--ckpt /ckpt \\
--prepare-manifest /runs/data/prepare_data.json \\
--out /runs \\
[--gpus 0 --batch-size N --seed N]"
```
Returns the predictions CSV path on success.
7. **Report to the user.** Output a short summary:
- Predictions: `$RUN_DIR/out/predictions.csv` (smiles + per-target columns)
- Manifest: `$RUN_DIR/run.json` (cmd_replay + image digest + applied args)
- Log: `$RUN_DIR/logs/inference.log`
- Row count: <N> molecules predicted across <K> targets
## Hard rules
- **Never modify the user's ckpt.** The runner symlinks thePreview of the first 4,000 characters. Read full instructions →
---
name: kermt-monitor
description: Check progress for a detached KERMT run (pretrain, finetune, or any kermt_run_detached invocation). Reads run.json, queries docker for container state, tails the pretrain/finetune log, and parses progress lines (epoch, step, val loss).
license: Apache-2.0
compatibility: Requires docker and jq. Designed for Claude Code, Codex, and Nemotron.
metadata:
owner: evax@nvidia.com
classification: atomic-skill
risk_tier: skill
# Line/token budget: this file is targeted at ~120 lines / ~1500 tokens — well
# within the 500-line / 5000-token cap for skill files.
---
# kermt-monitor
Companion skill for any KERMT workflow that runs detached: the three pretrain
skills (`kermt-continue-pretrain`, `kermt-pretrain-scratch`,
`kermt-add-cmim-pretrain`) plus `kermt-finetune`. `kermt-infer` and
`kermt-embed` run blocking by default and don't need this skill, but if a
user launches them detached on purpose the monitor still works (the
workflow-dispatch in step 4 handles unknown workflows by tailing the
most-recent log file in the run dir). Reads the run directory's `run.json`,
queries docker for the container's state, surfaces the latest progress,
and either tails or follows the log.
## Hardware requirements
None. This skill only reads disk + queries docker; no GPU compute.
## Inputs
One of:
- `<run-dir>` — a positional argument pointing at the directory containing
`run.json` (e.g. `runs/continue-pretrain_2026-05-17T10-23Z`). Preferred.
- `--container <name-or-id>` — direct container reference; the skill still
reads `run.json` from the run dir referenced inside the container's
inspect output if available, but works degraded-mode without it.
Optional:
- `--lines N` — number of trailing log lines to print (default 50).
- `--follow` — stream `docker logs -f` until ^C. Useful for "watch the
loss". Without it, the skill is one-shot and exits.
- `--json` — emit a structured status report instead of human-readable text.
Useful when the parent agent wants to take downstream action.
## Workflow
Let `RUN_DIR=$1` (or whatever path the user supplies).
1. **Locate the manifest.**
```
MANIFEST=$RUN_DIR/run.json
```
Refuse to proceed if it doesn't exist; surface a helpful message
pointing the user at the run-dir convention (`runs/<workflow>_<ts>/`).
2. **Parse the manifest** (Python helper):
```
workflow=$(jq -r .workflow $MANIFEST)
container_name=... # not directly in run.json today; the skill that
# launched stored it in run.json under
# container.name during launch (see below note).
logs_dir=$(jq -r .logs_dir $MANIFEST)
image_tag=$(jq -r .container.image_tag $MANIFEST)
started_at=$(jq -r .started_at $MANIFEST)
```
3. **Query docker for container state.**
```
docker ps --filter "name=$container_name" --format \
'{{.ID}}\t{{.Status}}\t{{.CreatedAt}}'
```
If absent, fall back to `docker inspect $container_name --format
'{{.State.Status}} (exit {{.State.ExitCode}})'` to see whether the
container exited (ok or failed) or was removed (`--rm` after exit).
4. **Find the live log file.**
```
case "$workflow" in
continue-pretrain|pretrain-scratch) LOG=$logs_dir/pretrain_ddp.log ;;
finetune) LOG=$logs_dir/finetune.log ;;
*) LOG=$(ls -1t $logs_dir/*.log 2>/dev/null | head -n 1) ;;
esac
```
The manifest's `workflow` field disambiguates pretrain (`pretrain_ddp.log`)
from finetune (`finetune.log`). Other workflows fall back to the
most-recently-modified `.log` in `$logs_dir`.
5. **Show the latest progress.**
- `tail -n $LINES $LOG` for the raw recent output.
- Parse the last few progress lines and surface a human-friendly
summary. The format differs per workflow:
- Pretrain: epoch / step / val_loss
```
Current epoch: 12/100 step: 4523/9000 val_loss: 0.832 (best 0.821 @ stePreview of the first 4,000 characters. Read full instructions →
---
name: kermt-pretrain-scratch
description: Pretrain a fresh KERMT model from scratch on a user-provided corpus. Builds a new vocabulary from the corpus, instantiates the model architecture from defaults, and launches pretrain_ddp.py inside the kermt container (detached for long runs). Unlike kermt-continue-pretrain, no starting checkpoint is loaded — the model is randomly initialized.
license: Apache-2.0
compatibility: Requires docker, nvidia-container-toolkit, and a CUDA-capable NVIDIA GPU. Designed for Claude Code, Codex, and Nemotron.
metadata:
owner: evax@nvidia.com
classification: workflow-skill
risk_tier: skill
# Line/token budget: ~210 lines, ~2400 tokens — well within the
# 500-line / 5000-token cap for skill files. Most of the orchestration is
# shared with kermt-continue-pretrain; the differences are documented below.
---
# kermt-pretrain-scratch
Pretrain a brand-new KERMT model from scratch on a user-provided corpus. Useful
when you want to retrain a model on a custom chemistry domain rather than
extending one of the released checkpoints. **Significantly more expensive than
`kermt-continue-pretrain`** — no warm start, so the loss curves need to descend
from scratch over many epochs.
## Hardware requirements
Same as `kermt-continue-pretrain`:
- **GPUs**: 1–N CUDA-capable. The runner auto-detects via
`torch.cuda.device_count()`; `--gpus 0,2` overrides. Single-GPU fallback:
`--batch_size 32 --save_interval 500`. Multi-GPU keeps defaults
(`--batch_size 256` etc.). Note: `--gpus N` uses **torch.cuda** indexing,
which can differ from `nvidia-smi`'s display order on multi-GPU hosts
(PCI bus vs. CUDA enumeration). To target a specific physical GPU, set
`CUDA_VISIBLE_DEVICES` before invoking, or run
`python -c "import torch; print([torch.cuda.get_device_name(i) for i in range(torch.cuda.device_count())])"`
to confirm which device you're picking.
- **VRAM**: the default `--batch-size 256` is sized for A100-class hardware
(80 GB VRAM). On smaller GPUs, downscale to avoid OOM:
| GPU class | VRAM | Suggested `--batch-size` |
|--------------------------|------------|--------------------------|
| L4, T4, V100 16 GB | 16–24 GB | 32–64 |
| A100 40 GB, L40, A40 | 40–48 GB | 128 |
| A100 80 GB, H100, H200 | 80 GB | 256 (default) |
These are rough starting points — pass `--batch-size N` to override.
- **Disk**: tens of GB for shards + vocab + checkpoints, scaled by epochs.
- **Wall time**: this is the big difference. Pretraining from scratch on an
11M-mol corpus at 100 epochs typically takes **days even on a multi-GPU box**.
The skill prints an estimate before launching; confirm with the user.
## When to invoke
- User wants to train a new model on a custom corpus (e.g. domain-specific
chemistry that the released ckpts don't cover).
- User wants to reproduce a pretrain config end-to-end without depending on a
released ckpt.
For continuing an existing released ckpt, use `kermt-continue-pretrain`. For
adding a cMIM decoder to an encoder-only grover_base ckpt, use
`kermt-add-cmim-pretrain`.
## Inputs
Required:
- `--csv <path>` — the pretrain corpus CSV with a `smiles` column. Single file
by convention; multi-file corpora deferred. Use `--val-csv` for a separate
validation set.
- `--pretrain-target-mode {vocab|cmim|hybrid}` — which pretrain objective to
use. **No default** — must be set explicitly so the user makes an informed
choice:
- `vocab` — original GROVER-style atom + bond vocab prediction (encoder-only
output, lightweight).
- `cmim` — contrastive + SMILES reconstruction objective. Requires building
a SMILES vocab from the corpus.
- `hybrid` — both vocab and contrastive objectives jointly (the
state-of-the-art config from the KERMT manuscript).
Optional:
- `--val-csv <path>` — separate validation CSV. Without it, prepare_data
auto-splits the input by `--Preview of the first 4,000 characters. Read full instructions →
---
name: kermt-setup
description: Bootstrap the KERMT agent environment — verify host docker + nvidia-container-toolkit, build the kermt:latest image from the repo's Dockerfile if it doesn't yet exist, and run a GPU smoke test inside the container. Every other kermt-* skill depends on this; invoke it first.
license: Apache-2.0
compatibility: Requires docker, nvidia-container-toolkit, and a CUDA-capable NVIDIA GPU. Designed for Claude Code, Codex, and Nemotron.
metadata:
owner: evax@nvidia.com
classification: atomic-skill
risk_tier: skill
# This file is intentionally short (~110 lines, ~1200 tokens) — well within the
# 500-line / 5000-token budget for skill files. Longer reference material lives
# alongside agent/scripts/kermt_container.sh.
---
# kermt-setup
Bootstrap the KERMT agent environment. Run this once on a fresh machine (or
after the Dockerfile or `environment.yml` changes) before invoking any other
`kermt-*` skill.
## Hardware requirements
- **GPU**: at least one CUDA-capable NVIDIA GPU visible to the host. The image
is based on `nvidia/cuda:12.6.3-cudnn-devel-ubuntu22.04`, so the host driver
must support CUDA 12.6. Verify with host `nvidia-smi` before invoking.
- **Host docker**: docker engine + nvidia-container-toolkit. Without the
toolkit, `docker run --gpus all` will fail at step 2 of the workflow below.
- **Disk**: ≈ 50 GB free for the built kermt image (`docker image inspect
--format '{{.Size}}'` reports ≈ 44 GB; the `docker images` Size column
can show ~100 GB because it counts shareable buildx attestation layers
that are deduplicated across images). Plan for ~50 GB of unique on-disk
storage; add a comfortable buffer if you're also keeping build cache.
- **Memory**: the build itself peaks at ~4 GB RAM during conda env solve.
- This skill does not run training/inference workloads itself; per-workflow
hardware requirements (VRAM, GPU count) are declared in the respective
`kermt-<workflow>` skills.
## When to invoke
- User explicitly asks (`/kermt-setup`, "set up kermt", "build the kermt image",
etc.).
- Or another `kermt-*` skill detected that the image does not exist and routed
here. (Most other skills call `kermt_ensure_image` themselves, so this is
usually only needed for the first-time setup, debugging, or a forced rebuild.)
## Inputs
The skill takes no required arguments. Optional overrides (via env vars before
invoking, or by setting them in the user's shell):
- `KERMT_IMAGE` — image tag to build/verify (default: `kermt:latest`).
- `KERMT_REPO` — host path of the kermt repo checkout (default: auto-derived
from the script's location).
If the user has not specified a repo path and the current working directory is
not inside a kermt repo clone, ask for the repo path before proceeding.
## Workflow
All work goes through `agent/scripts/kermt_container.sh`. The script's
subcommand dispatch can be invoked directly without sourcing — that is the
preferred form for skill use.
Let `HELPER=$KERMT_REPO/agent/scripts/kermt_container.sh`.
1. **Verify docker is installed and the daemon is reachable.**
```
$HELPER check_docker
```
Exit 0 → continue. Non-zero → surface the error to the user (typically
"docker not on PATH" or "daemon not reachable"); do not attempt step 2.
2. **Verify GPU passthrough works.**
```
$HELPER check_gpu
```
This runs `docker run --rm --gpus all nvidia/cuda:12.6.3-base-ubuntu22.04
nvidia-smi` and checks the exit status. Non-zero → tell the user to install
`nvidia-container-toolkit` on the host and confirm a CUDA-capable NVIDIA GPU
is visible to the host (`nvidia-smi` on the host should also work). Stop
here; without GPU passthrough the kermt image will build but no workflow
will run.
3. **Build or verify the kermt image.**
```
$HELPER ensure_image
```
If the image already exists, this returns immediately. Otherwise it builds
from `$KERMT_REPO/Dockerfile`. **Warn the user before invoking** that tPreview of the first 4,000 characters. Read full instructions →
---
name: molmim-nim
description: >
Use this skill for MolMIM, NVIDIA's BioNeMo NIM microservice for small-molecule latent-space generation and optimization. Invoke for MolMIM, molecular embeddings, hidden states, latent decoding, sampling around a seed SMILES, CMA-ES guided molecule generation, QED or plogP optimization, hosted NVIDIA API calls, or local Docker deployment.
license: Apache-2.0 AND CC-BY-4.0
compatibility: "requests>=2.28; rdkit"
allowed-tools: Bash, Read, Write, AskUserQuestion
---
# MolMIM NIM
Generate, sample, embed, and decode small molecules with MolMIM. Use this
`SKILL.md` for first-pass hosted/local usage; load supplemental files only when
needed:
- `references/api.md`: endpoints, schema, Docker flags, response fields.
- `references/science.md`: use cases, strengths, limits, and handoffs.
- `references/parameters.md`: generation, sampling, and optimization effects.
- `references/validation.md`: SMILES/property/artifact checks.
- `references/examples.md`: compact hosted/local request patterns.
## Choose Mode
Ask only when context is unclear:
> Hosted NVIDIA API or local Docker NIM?
- Hosted generation: `https://health.api.nvidia.com/v1/biology/nvidia/molmim/generate`
- Local generation: `http://localhost:8000/generate`
- Local embedding: `http://localhost:8000/embedding`
- Local hidden state: `http://localhost:8000/hidden`
- Local decode: `http://localhost:8000/decode`
- Local sampling: `http://localhost:8000/sampling`
- Local readiness: `http://localhost:8000/v1/health/ready`
Mode difference: the hosted API reference exposes `/generate`; the local
container exposes the broader latent-space workflow (`/embedding`, `/hidden`,
`/decode`, `/sampling`, `/generate`). Do not invent hosted latent endpoints.
Hosted requests use `Authorization: Bearer $NGC_API_KEY`. Local inference uses
no auth header after readiness.
## Local Docker
Use shell env first; source repo-root `.env` only if present. Do not print keys.
MolMIM docs use `NGC_CLI_API_KEY` for the local container; this repo accepts
`NGC_API_KEY` or `NVIDIA_API_KEY` and maps to `NGC_CLI_API_KEY` for startup.
Mount `LOCAL_NIM_CACHE` at `/home/nvs/.cache/nim`.
```bash
set -a
[ -f .env ] && . ./.env
set +a
if [ -z "${NGC_API_KEY:-}" ] && [ -n "${NVIDIA_API_KEY:-}" ]; then
export NGC_API_KEY="$NVIDIA_API_KEY"
fi
if [ -z "${NGC_CLI_API_KEY:-}" ] && [ -n "${NGC_API_KEY:-}" ]; then
export NGC_CLI_API_KEY="$NGC_API_KEY"
fi
: "${NGC_CLI_API_KEY:?Set NGC_API_KEY, NVIDIA_API_KEY, or NGC_CLI_API_KEY}"
: "${LOCAL_NIM_CACHE:?Set LOCAL_NIM_CACHE}"
echo "$NGC_CLI_API_KEY" | docker login nvcr.io --username '$oauthtoken' --password-stdin
export NIM_TEST_GPU="${NIM_TEST_GPU:-0}"
mkdir -p "${LOCAL_NIM_CACHE}"
chmod 777 "${LOCAL_NIM_CACHE}"
docker run --rm -it --name molmim \
--runtime=nvidia \
-e CUDA_VISIBLE_DEVICES="${NIM_TEST_GPU}" \
-e NGC_CLI_API_KEY \
-v "${LOCAL_NIM_CACHE}:/home/nvs/.cache/nim" \
-p 8000:8000 \
nvcr.io/nim/nvidia/molmim:1.0.0
```
Readiness check:
```bash
until curl -sf http://localhost:8000/v1/health/ready; do sleep 5; done
```
Local embedding smoke test after readiness. Local inference uses no
`Authorization` header:
```python
import requests
seed = "CN1C=NC2=C1C(=O)N(C(=O)N2C)C"
response = requests.post(
"http://localhost:8000/embedding",
headers={"Content-Type": "application/json"},
json={"sequences": [seed]},
timeout=60,
)
response.raise_for_status()
embedding_data = response.json()
embeddings = embedding_data["embeddings"]
print(f"received {len(embeddings)} embedding vector(s)")
```
## Hosted Generation Pattern
Use hosted `/generate` for seed-SMILES generation or optimization. Use
`algorithm: "CMA-ES"` for guided property optimization and `algorithm: "none"`
for unguided sampling around the seed.
```python
import os
import requests
hosted = True
url = (
"https://health.api.nvidia.com/v1/biology/nvidia/molmim/generate"
if hosted else "http://localhost:8000/generate"
)
headers = {"ContPreview of the first 4,000 characters. Read full instructions →
Referenced files: 5 — file references are metadata, not package contents.
---
name: msa-search-nim
description: >
Generate multiple sequence alignments (MSAs) for protein sequences using the ColabFold MSA-Search NIM. Use for homolog search, UniRef30/ColabFold env searches, A3M or FASTA alignments, paired MSA search for complexes, PDB70 structural templates, hosted NVIDIA API calls, or local Docker deployment. For local deployment, download the databases in parallel with aria2c and launch via NIM_MODEL_NAME (the recommended default fast path, ~14 min vs >80 min for the built-in downloader); a plain docker run uses the slow built-in downloader.
license: Apache-2.0 AND CC-BY-4.0
compatibility: "requests>=2.28"
allowed-tools: Bash, Read, Write, AskUserQuestion
---
# MSA-Search NIM
Generate protein MSAs with GPU-accelerated MMSeqs2. Use this `SKILL.md` for
first-pass hosted/local usage; load supplemental files only when needed:
- `references/api.md`: exact endpoints, schemas, Docker flags, response fields.
- `references/science.md`: MSA purpose, pairing/templates, limits, handoffs.
- `references/parameters.md`: database, pairing, depth, and template tuning.
- `references/validation.md`: alignment, template, and artifact checks.
- `references/examples.md`: compact hosted/local request patterns.
## Choose Mode And Endpoint
Ask only when context is unclear:
> Hosted NVIDIA API or local Docker NIM?
- Hosted standard MSA: `https://health.api.nvidia.com/v1/biology/colabfold/msa-search/predict`
- Hosted paired MSA: `https://health.api.nvidia.com/v1/biology/colabfold/msa-search/paired/predict`
- Local standard MSA: `http://localhost:8000/biology/colabfold/msa-search/predict`
- Local paired MSA: `http://localhost:8000/biology/colabfold/msa-search/paired/predict`
- Local templates: `http://localhost:8000/biology/colabfold/msa-search/structure-templates/predict`
Local inference paths do not include `/v1/`. Hosted requests use `Authorization: Bearer $NGC_API_KEY`. Supported local Docker
startup uses `NGC_API_KEY` (or `NVIDIA_API_KEY` via the preflight) for
registry login, entitlement checks, and first-run model downloads; pass it
into the container with `-e NGC_API_KEY`. Local inference requests use no
auth header after readiness. Warm-cache key-free startup varies by
image/version and should not be assumed.
The hosted template path returned HTTP 404 in validation, so use local Docker
for template search unless the hosted docs/service changes.
## Local Docker
**Default local deployment = parallel download + `NIM_MODEL_NAME`.** The first recipe below
is the one to use for real workflows. It downloads the database(s) with a range-parallel
downloader (aria2c) and starts the NIM against those files — ~14 min for UniRef30 vs >80 min
for the NIM's built-in downloader (measured, H100). Do **not** reach for the plain `docker run`
(the "Fallback" subsection) unless you only want a `databases:pdb70` smoke test or you
deliberately want the NIM to manage its own blob cache.
Local setup requires a GPU. Size the NVMe volume to the profile you pick (UniRef30 ~490 GB;
full set ~1.4 TB). For setup answers, include env preflight, `docker login`, the parallel
download, `NIM_MODEL_NAME` launch, readiness, and then no-auth local inference. Do not invent a
cache default or drop the `NVIDIA_API_KEY` fallback.
```bash
# --- env preflight (do not drop the NVIDIA_API_KEY fallback) ---
set -a
[ -f .env ] && . ./.env
set +a
if [ -z "${NGC_API_KEY:-}" ] && [ -n "${NVIDIA_API_KEY:-}" ]; then
export NGC_API_KEY="$NVIDIA_API_KEY"
fi
: "${NGC_API_KEY:?Set NGC_API_KEY or NVIDIA_API_KEY}"
: "${DB_DIR:=/data/fast-db}" # where the parallel download lands
echo "$NGC_API_KEY" | docker login nvcr.io --username '$oauthtoken' --password-stdin
# --- 1) pick the DB version(s) you need (paired/complex work = uniref30 only) ---
DB_VERSION=uniref30_2302-m18v1
command -v aria2c >/dev/null || sudo apt-get install -y aria2
mkdir -p "$DB_DIR"
# --- 2) parallel download from NGC (see "Parallel Download" section for the all-DB loop) ---
curPreview of the first 4,000 characters. Read full instructions →
Referenced files: 5 — file references are metadata, not package contents.
---
name: msa-structure-prediction-pipeline
description: >
Run a complete protein structure prediction pipeline using NVIDIA BioNeMo NIMs:
search for MSA alignments with MSA-Search (ColabFold), then predict the structure
with OpenFold3 using the retrieved alignments. Use this skill whenever the user wants
to predict a protein structure with maximum accuracy using MSA context, run the
full AlphaFold3-style pipeline, generate MSA-informed structure predictions, or
improve structure prediction accuracy by providing evolutionary information.
Triggers on: MSA structure prediction pipeline, structure prediction pipeline, MSA-informed prediction, OpenFold3,
ColabFold MSA, AlphaFold3 pipeline, protein structure, homology search, a3m alignment,
UniRef30, NIM microservice. This pipeline chains MSA-Search and OpenFold3.
license: Apache-2.0 AND CC-BY-4.0
allowed-tools: Bash, Read, Write, AskUserQuestion
---
# MSA Structure Prediction Pipeline
Predict protein structures with high accuracy by chaining two BioNeMo NIMs:
```
Step 1: MSA-Search → Step 2: OpenFold3
(Search homologs) (Predict structure with MSA)
```
---
## Overview
Why chain these NIMs?
- **MSA-Search** finds evolutionary homologs in UniRef30 and ColabFold databases using GPU-accelerated MMSeqs2. The resulting alignment provides crucial evolutionary information.
- **OpenFold3** uses the MSA to improve structure prediction accuracy — especially for sequences where no close homolog exists in PDB.
- Running MSA-Search first means OpenFold3 gets the full evolutionary context rather than a single-sequence prediction.
---
## Before you start
Confirm with the user:
1. **Query sequence**: amino acid sequence to predict
2. **MSA depth**: how many sequences to retrieve (default 500; more = slower but more context)
3. **API mode**: hosted or local Docker?
Note: local MSA-Search requires 1.4 TB of database storage — strongly recommend hosted unless the user has that infrastructure.
For local Docker, do not assume MSA-Search and OpenFold3 are both on
`localhost:8000` concurrently. Run one container at a time and hand off the A3M
file, or start each NIM on a distinct host port and set the URLs explicitly.
---
## Step 1: Search for MSA with MSA-Search
```python
import requests, json, os
from pathlib import Path
NGC_API_KEY = os.environ["NGC_API_KEY"]
HOSTED = True
query_sequence = "<YOUR_PROTEIN_SEQUENCE>"
if HOSTED:
msa_url = "https://health.api.nvidia.com/v1/biology/colabfold/msa-search/predict"
headers = {"Content-Type": "application/json",
"Authorization": f"Bearer {NGC_API_KEY}"}
else:
msa_url = "http://localhost:8000/biology/colabfold/msa-search/predict"
headers = {"Content-Type": "application/json"}
payload = {
"sequence": query_sequence,
"databases": ["Uniref30_2302", "colabfold_envdb_202108"],
"e_value": 0.0001,
"output_alignment_formats": ["a3m"],
}
r = requests.post(msa_url, headers=headers, json=payload)
r.raise_for_status()
msa_result = r.json()
# Extract the A3M alignment
a3m_alignment = msa_result["alignments"]["Uniref30_2302"]["a3m"]["alignment"]
# Save for reference
with open("query_msa.a3m", "w") as f:
f.write(a3m_alignment)
# Count sequences in alignment
n_seqs = a3m_alignment.count(">")
print(f"Step 1 complete: found {n_seqs} homologous sequences")
print(f"MSA saved to query_msa.a3m")
```
---
## Step 2: Predict structure with OpenFold3
Pass the MSA directly into OpenFold3's `msa` field:
```python
if HOSTED:
of3_url = "https://health.api.nvidia.com/v1/biology/openfold/openfold3/predict"
else:
of3_url = "http://localhost:8000/biology/openfold/openfold3/predict"
# Build the OpenFold3 MSA structure from the retrieved alignment
msa_data = {
"uniref30": {
"a3m": {
"alignment": a3m_alignment,
"format": "a3m"
}
}
}
# Optionally also include colabfold_envdb alignment if requested
# env_alignment = msa_result["alignments"]["cPreview of the first 4,000 characters. Read full instructions →
---
name: nvmolkit-usage
description: >-
Write code that calls the installed nvMolKit Python API for GPU-accelerated,
batched RDKit-style operations - Morgan fingerprints, Tanimoto/cosine
similarity, ETKDG conformer embedding, MMFF/UFF optimization, TFD, conformer
RMSD, Butina clustering, and substructure search. Use when the user is
importing `nvmolkit.*`, debugging an `nvmolkit` call, choosing between
nvMolKit and RDKit for a batched cheminformatics workflow, or wiring nvMolKit
results into a torch/numpy pipeline. Out of scope: building nvMolKit from
source.
license: Apache-2.0
metadata:
owner: Kevin Boyd (@scal444)
risk_tier: skill
---
# nvMolKit usage
## What nvMolKit is
GPU-accelerated, batched implementations of common RDKit operations. APIs mirror RDKit where possible but are batch-oriented: they take lists of `rdkit.Chem.Mol` (or lists of fingerprints) and process them in parallel on one or more GPUs. nvMolKit links against RDKit at build time; inputs and outputs are real RDKit `Mol` objects.
## Where nvMolKit does well
Reach for nvMolKit when:
- The workload is **a large batch of molecules** processed together (typically thousands or more).
- The metric is **throughput / total wall time across the batch**, not per-molecule latency.
- The same operation is **repeated identically** across the batch (fingerprinting a library, embedding/minimizing many conformers, bulk pairwise similarity), so the GPU stays saturated.
Plain RDKit is usually the better choice for single-molecule one-offs or workflows that can't be expressed as a batch. nvMolKit is not meant to replace RDKit for those cases.
## Runtime requirements
- An NVIDIA GPU with compute capability 7.0 (V100) or higher
- A CUDA driver compatible with CUDA 12.6+.
- A working `torch` install with CUDA support (nvMolKit returns GPU tensors via `torch`'s CUDA array interface).
If CUDA is unavailable, nvMolKit calls raise. There is no CPU fallback - if the user needs one, use RDKit directly for that path.
When helping with installation, make the user choose a PyTorch CUDA backend that the host driver supports before installing nvMolKit. nvMolKit's PyPI wheels are built with CUDA Toolkit 12.9 and depend on CUDA 12 runtime packages, but pip/uv can still select a CUDA 13 PyTorch wheel unless the install command says otherwise.
- Conda: prefer conda-forge `pytorch-gpu`; pin `cuda-version=12.6` or another CUDA version supported by the driver.
- pip: send the user to the PyTorch install selector (`https://pytorch.org/get-started/locally/`) or previous-versions page (`https://pytorch.org/get-started/previous-versions/`) to install `torch` for a CUDA 12.x backend before installing nvMolKit.
- uv: install nvMolKit with an explicit backend, e.g. `uv pip install --torch-backend=cu128 nvmolkit`.
## Verify the install before writing real code
Run this once to confirm nvMolKit is importable and a GPU op works end to end:
```python
import nvmolkit
import torch
from rdkit import Chem
from nvmolkit.fingerprints import MorganFingerprintGenerator
print("nvmolkit:", nvmolkit.__version__)
print("cuda available:", torch.cuda.is_available())
print("device count:", torch.cuda.device_count())
mols = [Chem.MolFromSmiles(smi) for smi in ["CCO", "c1ccccc1", "CC(=O)O"]]
fpgen = MorganFingerprintGenerator(radius=2, fpSize=1024)
result = fpgen.GetFingerprints(mols)
torch.cuda.synchronize()
fps = result.torch()
print("fps shape:", tuple(fps.shape), "dtype:", fps.dtype)
# Expected: shape (3, 32), dtype torch.int32 (1024 bits packed into 32 int32s per row)
```
If this fails, point the user at the install guide on the docs site rather than guessing - see "Going deeper" below.
## Entry points
| Task | Module | Primary entry point |
|---|---|---|
| Morgan fingerprints | `nvmolkit.fingerprints` | `MorganFingerprintGenerator(radius, fpSize).GetFingerprints(mols)` |
| Bulk Tanimoto / cosine similarity | `nvmolkit.similarity` | `crossTanimotoSimilarity(...)`, `crossCosineSPreview of the first 4,000 characters. Read full instructions →
---
name: openfold2-nim
description: >
Use this skill for OpenFold2, NVIDIA's BioNeMo NIM microservice for monomer protein structure prediction. Invoke whenever the user mentions OpenFold2, AlphaFold2-like monomer folding, protein sequence-to-structure prediction, A3M MSAs, mmCIF templates, hosted NVIDIA API calls, or local Docker deployment.
license: Apache-2.0 AND CC-BY-4.0
compatibility: "requests>=2.28"
allowed-tools: Bash, Read, Write, AskUserQuestion
---
# OpenFold2 NIM
Predict a single protein-chain structure from an amino-acid sequence, with
optional A3M multiple sequence alignments and mmCIF templates. Use this
`SKILL.md` for basic hosted/local NIM use; load supplemental files only when
the task needs deeper context:
- `references/api.md`: exact endpoints, schemas, Docker flags, response fields.
- `references/science.md`: model scope, strengths, limitations, and handoffs.
- `references/parameters.md`: MSA, template, model-selection, and relax effects.
- `references/validation.md`: artifact and scientific sanity checks.
- `references/examples.md`: compact hosted/local payload patterns.
## Choose Mode
Ask only when context is unclear:
> Hosted NVIDIA API or local Docker NIM?
- Hosted URL: `https://health.api.nvidia.com/v1/biology/openfold/openfold2/predict-structure-from-msa-and-template`
- Local URL: `http://localhost:8000/biology/openfold/openfold2/predict-structure-from-msa-and-template`
- Local readiness: `http://localhost:8000/v1/health/ready`
Mode difference: hosted and local use the same prediction path except local
does not include `/v1/`. Hosted requests use `Authorization: Bearer
$NGC_API_KEY`; local inference requests use no auth header after readiness.
## Auth And Environment
Do not print API keys. Confirm they exist with shell tests, not echoes.
Hosted needs `NGC_API_KEY` in the request header. Supported local Docker
startup uses `NGC_API_KEY`, or `NVIDIA_API_KEY` as a fallback, plus
`LOCAL_NIM_CACHE`. A repo-root `.env` file may be sourced as a local override.
## Local Docker
Use the official OpenFold2 NIM image and mount `LOCAL_NIM_CACHE` at
`/opt/nim/.cache`. Current docs recommend at least 80 GB disk, 64 GB system
RAM, 8 CPU cores, and one supported GPU; the container is roughly 55 GB and
first startup downloads about 10 GB of model parameters.
When writing local setup commands, copy the preflight below exactly. Do not
drop `.env`, `NVIDIA_API_KEY`, `LOCAL_NIM_CACHE`, or the no-auth local request.
```bash
set -a
[ -f .env ] && . ./.env
set +a
if [ -z "${NGC_API_KEY:-}" ] && [ -n "${NVIDIA_API_KEY:-}" ]; then
export NGC_API_KEY="$NVIDIA_API_KEY"
fi
: "${NGC_API_KEY:?Set NGC_API_KEY or NVIDIA_API_KEY}"
: "${LOCAL_NIM_CACHE:?Set LOCAL_NIM_CACHE}"
echo "$NGC_API_KEY" | docker login nvcr.io --username '$oauthtoken' --password-stdin
export NIM_TEST_GPU="${NIM_TEST_GPU:-0}"
mkdir -p "${LOCAL_NIM_CACHE}"
chmod 777 "${LOCAL_NIM_CACHE}"
docker run --rm --name openfold2 \
--runtime=nvidia \
--gpus "device=${NIM_TEST_GPU}" \
-e NGC_API_KEY \
-v "${LOCAL_NIM_CACHE}:/opt/nim/.cache" \
-p 8000:8000 \
nvcr.io/nim/openfold/openfold2:latest
```
Readiness check:
```bash
until curl -sf http://localhost:8000/v1/health/ready; do sleep 5; done
```
## Request Pattern
Use Python `requests`; curl escaping is fragile for A3M/mmCIF text. The
`sequence` field is required. `input_id`, `alignments`, `selected_models`,
`relax_prediction`, `use_templates`, and `explicit_templates` are optional.
```python
import os
import requests
hosted = True
url = (
"https://health.api.nvidia.com/v1/biology/openfold/openfold2/predict-structure-from-msa-and-template"
if hosted
else "http://localhost:8000/biology/openfold/openfold2/predict-structure-from-msa-and-template"
)
headers = {"Content-Type": "application/json"}
if hosted:
headers["Authorization"] = f"Bearer {os.environ['NGC_API_KEY']}"
seq = "MTEYKLVVVGAGGVGKSALTIQLIQNHFVDEYDPT"
payload = {
"sequence": seq,
"input_id": "kras_fraPreview of the first 4,000 characters. Read full instructions →
Referenced files: 5 — file references are metadata, not package contents.
---
name: openfold3-nim
description: >
Use this skill for OpenFold3, NVIDIA's BioNeMo NIM microservice for biomolecular structure prediction. Invoke whenever the user mentions OpenFold3 or needs protein, protein-ligand, protein-DNA/RNA, or multi-chain complex prediction with the hosted NVIDIA API or local Docker NIM. Covers endpoint choice, auth, request payloads, output artifacts, confidence scores, and local container setup.
license: Apache-2.0 AND CC-BY-4.0
compatibility: "requests>=2.28"
allowed-tools: Bash, Read, Write, AskUserQuestion
---
# OpenFold3 NIM
Predict biomolecular structures with OpenFold3. It supports proteins, DNA, RNA,
small-molecule ligands, and multi-entity assemblies. Use this `SKILL.md` for
basic hosted/local NIM use; load supplemental files only when the task needs
deeper context:
- `references/api.md`: exact endpoints, schemas, Docker flags, response fields.
- `references/science.md`: purpose, strengths, limitations, and model handoffs.
- `references/parameters.md`: molecule fields, MSAs, templates, samples, tuning.
- `references/validation.md`: artifact checks and scientific sanity checks.
- `references/examples.md`: compact hosted/local request patterns.
## Choose Mode
Ask only when context is unclear:
> Hosted NVIDIA API or local Docker NIM?
- Hosted URL: `https://health.api.nvidia.com/v1/biology/openfold/openfold3/predict`
- Local URL: `http://localhost:8000/biology/openfold/openfold3/predict`
- Local readiness: `http://localhost:8000/v1/health/ready`
Mode difference: the local prediction path has no `/v1/` prefix. Hosted requests use `Authorization: Bearer $NGC_API_KEY`. Supported local Docker
startup uses `NGC_API_KEY` (or `NVIDIA_API_KEY` via the preflight) for
registry login, entitlement checks, and first-run model downloads; pass it
into the container with `-e NGC_API_KEY`. Local inference requests use no
auth header after readiness. Warm-cache key-free startup varies by
image/version and should not be assumed.
## Auth And Environment
Do not print API keys. Confirm they exist with shell tests, not echoes.
Hosted needs `NGC_API_KEY` in the request header. Local startup needs
`NGC_API_KEY`, or `NVIDIA_API_KEY` as a fallback, plus `LOCAL_NIM_CACHE`.
A repo-root `.env` file may be sourced as a local override before validation.
## Local Docker
Use the official OpenFold3 NIM image and mount `LOCAL_NIM_CACHE` at
`/opt/nim/.cache`. First startup downloads model artifacts and can take several
minutes.
When writing local setup commands, copy the preflight below exactly. Do not
replace it with a simple `: "${NGC_API_KEY:?Set NGC_API_KEY}"` check, do not
drop `NVIDIA_API_KEY`, and do not invent a default `LOCAL_NIM_CACHE`; those
lines are the repo's local NIM env contract. The default single-GPU launch
should show the literal `--gpus "device=0"`; choose a different device only
when the user asks.
```bash
set -a
[ -f .env ] && . ./.env
set +a
if [ -z "${NGC_API_KEY:-}" ] && [ -n "${NVIDIA_API_KEY:-}" ]; then
export NGC_API_KEY="$NVIDIA_API_KEY"
fi
: "${NGC_API_KEY:?Set NGC_API_KEY or NVIDIA_API_KEY}"
: "${LOCAL_NIM_CACHE:?Set LOCAL_NIM_CACHE}"
echo "$NGC_API_KEY" | docker login nvcr.io --username '$oauthtoken' --password-stdin
mkdir -p "${LOCAL_NIM_CACHE}"
chmod 777 "${LOCAL_NIM_CACHE}"
docker run --rm --name openfold3 \
--runtime=nvidia \
--gpus "device=0" \
--shm-size=16g \
-e NGC_API_KEY \
-v "${LOCAL_NIM_CACHE}:/opt/nim/.cache" \
-p 8000:8000 \
nvcr.io/nim/openfold/openfold3:latest
```
Readiness check:
```bash
until curl -sf http://localhost:8000/v1/health/ready; do sleep 5; done
```
## Request Pattern
Use `requests.post(..., json=payload, timeout=300)`. For local Docker tasks,
set `hosted = False` after the readiness check passes.
```python
import os
import requests
hosted = True
url = (
"https://health.api.nvidia.com/v1/biology/openfold/openfold3/predict"
if hosted
else "http://localhost:8000/biology/openfold/openfold3/predict"
)
headers = {"ConPreview of the first 4,000 characters. Read full instructions →
Referenced files: 5 — file references are metadata, not package contents.
---
name: parabricks
description: >-
Route NVIDIA Parabricks pbrun tools, assess GPU/runtime readiness, and provide
version-aware command guidance for FASTQ/BAM processing, RNA-seq, variant
calling, BAM QC, and GVCF workflows. Do NOT use for inspecting or accelerating
whole pipelines — use genomics-workflow-acceleration.
license: CC-BY-4.0 AND Apache-2.0
metadata:
version: "1.1.0"
tags:
- parabricks
- genomics
- nvidia
---
# Parabricks
## Purpose
Use this skill to discover the right NVIDIA Parabricks `pbrun` command, assess
runtime readiness, and generate version-aware command guidance for individual
tools and pipelines.
Do **not** use this skill for whole-workflow inspection, acceleration planning,
or wiring optional GPU branches. For pipeline-level work, use
`genomics-workflow-acceleration`.
## When to Use This Skill
- Which `pbrun` tool fits the user's data and goal
- GPU, driver, Docker, container, storage, or installation readiness
- Command shape, flags, and validation for a specific Parabricks tool
- Troubleshooting a single Parabricks command or tool family
## Prerequisites
Ask for input data type, sequencing technology, reference build, sample
structure, desired output, target Parabricks version/container tag, and runtime
target before recommending commands.
If the user is unsure which tool applies, read
[tool-index.md](references/tool-index.md) first, then load the matching
`references/pbrun-<tool>.md` file.
## Limitations
This skill routes and guides Parabricks commands. It does not install
Parabricks, infer missing sample metadata, guarantee output parity, provide
clinical interpretation, or promise exact runtime without benchmark data.
## Workflow
1. Confirm the Parabricks version or container tag. Verify the current NVIDIA
docs when the user asks for the latest tool list or version-sensitive flags.
2. Classify the request:
- **Runtime** → [runtime-environment.md](references/runtime-environment.md)
- **Tool discovery** → [tool-index.md](references/tool-index.md)
- **Specific command** → matching `references/pbrun-<tool>.md`
3. Collect missing biological and filesystem context before generating commands.
4. Generate conservative Docker commands with explicit mounts, workdir, and
placeholders. Validate paths, indexes, and outputs after command generation.
## Tool Reference Index
Load only the reference file for the selected tool.
| Tool | Reference | Use when |
|------|-----------|----------|
| `applybqsr` | [pbrun-applybqsr.md](references/pbrun-applybqsr.md) | Apply BQSR table to aligned BAM |
| `bam2fq` | [pbrun-bam2fq.md](references/pbrun-bam2fq.md) | BAM → FASTQ conversion |
| `bamsort` | [pbrun-bamsort.md](references/pbrun-bamsort.md) | Standalone BAM sort |
| `bqsr` | [pbrun-bqsr.md](references/pbrun-bqsr.md) | Generate BQSR recalibration table |
| `fq2bam` | [pbrun-fq2bam.md](references/pbrun-fq2bam.md) | Short-read DNA paired FASTQ → BAM/CRAM |
| `fq2bam_meth` | [pbrun-fq2bam_meth.md](references/pbrun-fq2bam_meth.md) | Bisulfite/methylation FASTQ → BAM/CRAM |
| `giraffe` | [pbrun-giraffe.md](references/pbrun-giraffe.md) | Pangenome graph alignment |
| `markdup` | [pbrun-markdup.md](references/pbrun-markdup.md) | Standalone duplicate marking |
| `minimap2` | [pbrun-minimap2.md](references/pbrun-minimap2.md) | Long-read FASTQ alignment |
| `rna_fq2bam` | [pbrun-rna_fq2bam.md](references/pbrun-rna_fq2bam.md) | RNA-seq FASTQ(s) → splice-aware BAM (STAR alignment) |
| `starfusion` | [pbrun-starfusion.md](references/pbrun-starfusion.md) | Fusion detection from chimeric junction input + STAR-Fusion genome library |
| `germline` | [pbrun-germline.md](references/pbrun-germline.md) | GATK-style germline pipeline from FASTQ |
| `deepvariant_germline` | [pbrun-deepvariant_germline.md](references/pbrun-deepvariant_germline.md) | DeepVariant germline pipeline from FASTQ |
| `haplotypecaller` | [pbrun-haplotypecaller.md](references/pbrun-haplotypecaller.md) | StandalonPreview of the first 4,000 characters. Read full instructions →
Referenced files: 33 — file references are metadata, not package contents.
--- name: protein-binder-design description: > Orchestrate an end-to-end de novo protein binder design campaign against a protein target by composing BioNeMo NIM skills. Use for binder design, minibinder design, de novo binders, RFdiffusion + ProteinMPNN + Boltz2/OpenFold3 pipelines, epitope/hotspot-targeted design, in-silico binder validation, and ranking designs by interface confidence. license: Apache-2.0 compatibility: "numpy>=1.24; requests>=2.28" allowed-tools: Bash, Read, Write, AskUserQuestion --- # Protein Binder Design (workflow) Run a de novo binder design campaign by composing atomic NIM skills. This skill owns orchestration, handoff contracts, filtering, validation, and the run manifest. It does NOT duplicate per-NIM API details — defer those to each atomic skill's `SKILL.md`. ## Composed skills | Step | Skill | Owns | |---|---|---| | Backbones | `rfdiffusion-nim` | binder backbone PDBs (contigs + hotspots) | | Sequences | `proteinmpnn-nim` | sequences for each backbone | | Co-fold / score | `boltz2-nim` or `openfold3-nim` | binder–target complex + confidence / ipTM | | MSA (optional) | `msa-search-nim` | target A3M for higher-quality folding | The atomic NIM skills are recommended companions (one per NIM, from the BioNeMo NIM skill set). They are **not required**: `references/pipeline.md` carries the concrete request shape for every NIM call, so an agent with NIM access can follow this skill standalone. For endpoints/auth see **Configuration** below. ## Pipeline 1. **Target prep** — get the target PDB + epitope; map epitope/hotspot author residue numbers to RFdiffusion `hotspot_res` strings; optionally build a target MSA with `msa-search-nim`. 2. **Backbones** (`rfdiffusion-nim`) — binder contig + `hotspot_res`; N backbones. 3. **Sequences** (`proteinmpnn-nim`) — k sequences per backbone; drop the native/WT row from `mfasta`. 4. **Co-fold + score** (`boltz2-nim` / `openfold3-nim`) — co-fold binder+target; collect interface confidence (ipTM) and binder pLDDT. 5. **Self-consistency** — CA-RMSD between the RFdiffusion backbone and the predicted binder (`scripts/metrics.py`). 6. **Filter + rank** — apply thresholds; rank survivors; write manifest + CSV. Full handoff contracts, branching, and the cost funnel: `references/pipeline.md`. ## Handoff contracts (the fragile glue) - RFdiffusion `output_pdb` → ProteinMPNN `input_pdb` (inline PDB text). - ProteinMPNN `mfasta` → Boltz2 binder polymer `sequence` (exclude the native/WT row; pair scores only with designed rows). - Epitope author residue numbers → 1-based sequence indices: remap with `scripts/pdb_utils.py:remap_to_seq_index`. RFdiffusion `hotspot_res` uses chain+author strings like `"A50"`; Boltz2 pocket/contacts use 1-based indices. - Boltz2 complex `.cif` → binder chain → self-consistency RMSD vs the backbone. ## Run manifest (reproducibility backbone) Every campaign writes `manifest.json` (+ `candidates.csv`) under a run dir via `scripts/manifest.py`. It records lineage, params, scores, artifacts, filter status, and controls — enabling ranking, resumability, validation, and the final report. Schema and usage: `references/manifest.md`. ## Filters (defaults) - ipTM ≥ 0.8, binder pLDDT ≥ 80, self-consistency RMSD ≤ 2.0 Å. - Override per campaign and record overrides in the manifest `filters`. ## Validation Always run controls and report a **success rate**, not just top scores. Negative controls via `scripts/controls.py` (scrambled sequences); positive controls = published binders re-scored through the same pipeline. Benchmark targets live in `assets/targets.json` (`scripts/registry.py`). Methodology and metric definitions: `references/validation.md`. ## Human-in-the-loop + cost - Confirm target, epitope/hotspots, binder length range, and hosted-vs-local with the user before generating backbones (AskUserQuestion). - Co-folding is the expensive stage: co-fold a capped shortlist, review, then expand. State hosted vs local o
Preview of the first 4,000 characters. Read full instructions →
Referenced files: 12 — file references are metadata, not package contents.
---
name: proteinmpnn-nim
description: >
Run ProteinMPNN inverse folding via NVIDIA NIM to design protein sequences for a target backbone. Use for ProteinMPNN, inverse folding, sequence design, backbone redesign, fixed chains/residues, omit_AAs, sampling temperature, soluble model, hosted NVIDIA API, local Docker, PDB input, and multi-FASTA output.
license: Apache-2.0 AND CC-BY-4.0
compatibility: "requests>=2.28"
allowed-tools: Bash, Read, Write, AskUserQuestion
---
# ProteinMPNN NIM
Design protein sequences for a supplied backbone PDB. Use this `SKILL.md` for
first-pass hosted/local usage; load supplemental files only when needed:
- `references/api.md`: exact endpoints, schemas, Docker flags, response fields.
- `references/science.md`: inverse-folding uses, limits, and validation.
- `references/parameters.md`: design controls, fixed positions, sampling.
- `references/validation.md`: FASTA, score, and structure checks.
- `references/examples.md`: compact hosted/local request patterns.
## Choose Mode
Ask only when context is unclear:
> Hosted NVIDIA API or local Docker NIM?
- Hosted: `https://health.api.nvidia.com/v1/biology/ipd/proteinmpnn/predict`
- Local: `http://localhost:8000/biology/ipd/proteinmpnn/predict`
Local inference paths do not include `/v1/`. Hosted requests use `Authorization: Bearer $NGC_API_KEY`. Supported local Docker
startup uses `NGC_API_KEY` (or `NVIDIA_API_KEY` via the preflight) for
registry login, entitlement checks, and first-run model downloads; pass it
into the container with `-e NGC_API_KEY`. Local inference requests use no
auth header after readiness. Warm-cache key-free startup varies by
image/version and should not be assumed.
## Local Docker
For local setup answers, copy the preflight below exactly before `docker login`,
`docker run`, readiness, and the no-auth local request. Do not answer with only
a localhost Python request. This NIM's cache mount is unique:
`/home/nvs/.cache/nim`, not `/opt/nim/.cache`.
```bash
set -a
[ -f .env ] && . ./.env
set +a
if [ -z "${NGC_API_KEY:-}" ] && [ -n "${NVIDIA_API_KEY:-}" ]; then
export NGC_API_KEY="$NVIDIA_API_KEY"
fi
: "${NGC_API_KEY:?Set NGC_API_KEY or NVIDIA_API_KEY}"
: "${LOCAL_NIM_CACHE:?Set LOCAL_NIM_CACHE}"
echo "$NGC_API_KEY" | docker login nvcr.io --username '$oauthtoken' --password-stdin
export NIM_TEST_GPU="${NIM_TEST_GPU:-0}"
mkdir -p "${LOCAL_NIM_CACHE}"
chmod 777 "${LOCAL_NIM_CACHE}"
docker run -it \
--runtime=nvidia \
--gpus "device=${NIM_TEST_GPU}" \
-e NGC_API_KEY \
-v "${LOCAL_NIM_CACHE}:/home/nvs/.cache/nim" \
-p 8000:8000 \
nvcr.io/nim/ipd/proteinmpnn:latest
```
Readiness:
```bash
until curl -sf http://localhost:8000/v1/health/ready; do sleep 5; done
```
## Request Pattern
Read PDB content inline; do not send only a file path.
```python
import os
from pathlib import Path
import requests
HOSTED = True
pdb_content = Path("1R42.pdb").read_text()
url = (
"https://health.api.nvidia.com/v1/biology/ipd/proteinmpnn/predict"
if HOSTED else "http://localhost:8000/biology/ipd/proteinmpnn/predict"
)
headers = {"Content-Type": "application/json"}
if HOSTED:
headers["Authorization"] = f"Bearer {os.environ['NGC_API_KEY']}"
payload = {
"input_pdb": pdb_content,
"num_seq_per_target": 10,
"sampling_temp": [0.1],
"use_soluble_model": False,
"ca_only": False,
}
response = requests.post(url, headers=headers, json=payload, timeout=300)
response.raise_for_status()
result = response.json()
```
Common controls:
- Redesign only chain A: `"input_pdb_chains": ["A"]`.
- Exclude amino acids: `"omit_AAs": ["C"]` or `"omit_AAs": ["M"]`.
- Diversity: `"sampling_temp": [0.1, 0.3, 0.5]` (always a list).
- Solubility bias: `"use_soluble_model": True`.
- Candidate count: `num_seq_per_target` is 1-100.
## Save And Report Output
```python
mfasta = result["mfasta"]
Path("designed_sequences.fa").write_text(mfasta)
# Scores correspond to designed sequences. The mfasta may include a native/WT
# row; do notPreview of the first 4,000 characters. Read full instructions →
Referenced files: 5 — file references are metadata, not package contents.
---
name: rfdiffusion-nim
description: >
Run RFDiffusion protein backbone design via NVIDIA NIM. Use for de novo protein backbones, motif scaffolding, binder design, hotspot residues, contigs syntax, diffusion steps, hosted NVIDIA API calls, local Docker deployment, and PDB backbone outputs for ProteinMPNN sequence design.
license: Apache-2.0 AND CC-BY-4.0
compatibility: "requests>=2.28"
allowed-tools: Bash, Read, Write, AskUserQuestion
---
# RFDiffusion NIM
Design protein backbone PDBs for de novo proteins, motif scaffolds, and binders.
Use this `SKILL.md` for first-pass hosted/local usage; load supplemental files
only when needed:
- `references/api.md`: exact endpoints, schemas, Docker flags, response fields.
- `references/science.md`: design modes, strengths, limits, and handoffs.
- `references/parameters.md`: contigs, hotspots, steps, and seeds.
- `references/validation.md`: PDB, contig, and artifact sanity checks.
- `references/examples.md`: compact hosted/local request patterns.
## Choose Mode
Ask only when context is unclear:
> Hosted NVIDIA API or local Docker NIM?
- Hosted: `https://health.api.nvidia.com/v1/biology/ipd/rfdiffusion/generate`
- Local: `http://localhost:8000/biology/ipd/rfdiffusion/generate`
Local inference paths do not include `/v1/`. Hosted requests use `Authorization: Bearer $NGC_API_KEY`. Supported local Docker
startup uses `NGC_API_KEY` (or `NVIDIA_API_KEY` via the preflight) for
registry login, entitlement checks, and first-run model downloads; pass it
into the container with `-e NGC_API_KEY`. Local inference requests use no
auth header after readiness. Warm-cache key-free startup varies by
image/version and should not be assumed.
## Local Docker
For local setup answers, copy the preflight below exactly before `docker login`,
`docker run`, readiness, and the no-auth local request. Do not replace it with a
simple `: "${NGC_API_KEY:?Set NGC_API_KEY}"` check, do not invent a cache
default, and do not drop the `NVIDIA_API_KEY` fallback. Default setup is single
GPU `device=0`.
```bash
set -a
[ -f .env ] && . ./.env
set +a
if [ -z "${NGC_API_KEY:-}" ] && [ -n "${NVIDIA_API_KEY:-}" ]; then
export NGC_API_KEY="$NVIDIA_API_KEY"
fi
: "${NGC_API_KEY:?Set NGC_API_KEY or NVIDIA_API_KEY}"
: "${LOCAL_NIM_CACHE:?Set LOCAL_NIM_CACHE}"
echo "$NGC_API_KEY" | docker login nvcr.io --username '$oauthtoken' --password-stdin
mkdir -p "${LOCAL_NIM_CACHE}"
chmod 777 "${LOCAL_NIM_CACHE}"
docker run -it \
--runtime=nvidia \
--gpus "device=0" \
-e NGC_API_KEY \
-v "${LOCAL_NIM_CACHE}:/opt/nim/.cache" \
-p 8000:8000 \
nvcr.io/nim/ipd/rfdiffusion:2
```
Readiness:
```bash
until curl -sf http://localhost:8000/v1/health/ready; do sleep 5; done
```
## Contigs DSL
`contigs` defines what to keep and what to generate.
- `"100"`: generate exactly 100 residues.
- `"80-120"`: generate 80-120 residues.
- `"A25-35"`: keep chain A residues 25-35 from `input_pdb`.
- `"A25-35/0 50-80"`: keep A25-35, insert chain break `/0`, generate 50-80.
Design modes:
- De novo: `contigs="80-120"`; live hosted validation requires a non-empty
`input_pdb` or `input_pdb_asset`, so inline requests should include the dummy
PDB below.
- Motif scaffolding: read `target.pdb`, pass `input_pdb`, use a contig like
`"A25-35/0 50-80"`.
- Binder design: pass target `input_pdb`, contig with target and binder segment,
and `hotspot_res=["A50", "A51", ...]` in ChainResidue string format.
```python
DUMMY_PDB = (
"CRYST1 1.000 1.000 1.000 90.00 90.00 90.00 P 1 1\n"
"ATOM 1 CA ALA A 1 0.000 0.000 0.000 1.00 0.00 C\n"
"END\n"
)
```
## Request Pattern
```python
import os
from pathlib import Path
import requests
HOSTED = True
url = (
"https://health.api.nvidia.com/v1/biology/ipd/rfdiffusion/generate"
if HOSTED else "http://localhost:8000/biology/ipd/rfdiffusion/generate"
)
headers = {"Content-Type": "application/json"}
if HOSTED:
headers["Authorization"] = Preview of the first 4,000 characters. Read full instructions →
Referenced files: 5 — file references are metadata, not package contents.
Publisher declarations from the archived package. These are separate from our research and the live service's terms.
Package observed Nov 21, 2026.
plugins_6a76572d8f8081918362aa7ff90947fb
Download plugin data (JSON)Plugin details: freshly prepared. Prepared . Refreshed when plugin data changes or after 6 hours. Your account and Follow status are live.