Onboard bionemo-agent-toolkit to nv-skills

.gitignore

@@ -4,3 +4,7 @@
 # nv-aces generated eval results (regenerate locally / via CI; never committed)
 **/evals/results/
 .nv-aces-verify/
+
+# Python bytecode / caches
+__pycache__/
+*.py[cod]

README.md

@@ -40,7 +40,7 @@ flow as well. Skills are also discoverable by partner harnesses directly from th
 
 | Product | Description | Skills |
 |---------|-------------|--------|
-| **Protein Binder Design** | End-to-end de novo binder design workflows — a NIM route and a Proteina-Complexa route. | [`protein-binder-design`](workflows/generative_protein_binder_design/protein-binder-design), [`complexa-binder-design`](workflows/generative_protein_binder_design/complexa-binder-design) |
+| **Protein Binder Design** | End-to-end de novo binder design workflows — a NIM route and a Proteina-Complexa route. | [`protein-binder-design`](workflows/generative-protein-binder-design/protein-binder-design), [`complexa-binder-design`](workflows/generative-protein-binder-design/complexa-binder-design) |
 | **Generative Virtual Screening workflow** | Generate candidate molecules, dock them to a target, and score binding affinity (GenMol → DiffDock → Boltz-2). | [`drug-discovery-pipeline`](nim-skills/meta-skills/drug-discovery-pipeline) |
 | **MSA-enabled protein structure prediction workflow** | Build a multiple sequence alignment, then predict structure (MSA-Search → OpenFold3). | [`msa-structure-prediction-pipeline`](nim-skills/meta-skills/msa-structure-prediction-pipeline) |
 | **Boltz-2** | Biomolecular structure prediction + binding affinity (NIM). | [`boltz2-nim`](nim-skills/boltz2-nim) |
@@ -53,11 +53,11 @@ flow as well. Skills are also discoverable by partner harnesses directly from th
 | **OpenFold3** | Biomolecular complex structure prediction (NIM). | [`openfold3-nim`](nim-skills/openfold3-nim) |
 | **ProteinMPNN** | Inverse folding / sequence design for a target backbone (NIM). | [`proteinmpnn-nim`](nim-skills/proteinmpnn-nim) |
 | **RFdiffusion** | De novo protein backbone and binder design (NIM). | [`rfdiffusion-nim`](nim-skills/rfdiffusion-nim) |
-| **Proteina-Complexa** | Protein binder design for protein and small molecule targets. Combines a pretrained flow-based generative model (built on La-Proteina) with inference-time optimization for high-quality binder generation. | [`complexa-setup`](open-models-skills/proteina-complexa/complexa-setup), [`complexa-target`](open-models-skills/proteina-complexa/complexa-target), [`complexa-design`](open-models-skills/proteina-complexa/complexa-design), [`complexa-sweep`](open-models-skills/proteina-complexa/complexa-sweep), [`complexa-evaluate-pdbs`](open-models-skills/proteina-complexa/complexa-evaluate-pdbs), [`complexa-slurm`](open-models-skills/proteina-complexa/complexa-slurm) |
+| **Proteina-Complexa** | Protein binder design for protein and small molecule targets. Combines a pretrained flow-based generative model (built on La-Proteina) with inference-time optimization for high-quality binder generation. | [`complexa-setup`](open-models-skills/proteina-complexa/complexa-setup), [`complexa-target`](open-models-skills/proteina-complexa/complexa-target), [`complexa-design`](open-models-skills/proteina-complexa/complexa-design), [`complexa-sweep`](open-models-skills/proteina-complexa/complexa-sweep), [`complexa-evaluate-pdbs`](open-models-skills/proteina-complexa/complexa-evaluate-pdbs) |
 | **KERMT** | Pretrained graph neural network for molecular property prediction (ADMET). Multi-task extension of GROVER with accelerated data loading via cuik-molmaker. SOTA on real-world ADMET data. | [`kermt-setup`](open-models-skills/kermt/skills/kermt-setup), [`kermt-infer`](open-models-skills/kermt/skills/kermt-infer), [`kermt-embed`](open-models-skills/kermt/skills/kermt-embed), [`kermt-finetune`](open-models-skills/kermt/skills/kermt-finetune), [`kermt-continue-pretrain`](open-models-skills/kermt/skills/kermt-continue-pretrain), [`kermt-pretrain-scratch`](open-models-skills/kermt/skills/kermt-pretrain-scratch), [`kermt-add-cmim-pretrain`](open-models-skills/kermt/skills/kermt-add-cmim-pretrain), [`kermt-monitor`](open-models-skills/kermt/skills/kermt-monitor) |
 | **Parabricks** | Agent-ready skills built on Parabricks for accelerated genomic analysis and workflows. | [`parabricks`](library-skills/parabricks), [`genomics-workflow-acceleration`](library-skills/genomics-workflow-acceleration) |
 | **nvMolKit** | GPU-accelerated cheminformatics library for molecular fingerprinting, Tanimoto/cosine similarity, Butina clustering, conformer generation (ETKDGv3), MMFF geometry optimization, and substructure search. | [`nvmolkit-usage`](library-skills/nvMolKit) |
-| **cuEquivariance** | Build equivariant neural-network primitives (segmented tensor products, CG coefficients). | [`cuequivariance`](library-skills/cuEquivariance) |
+| **cuEquivariance** | Build equivariant neural-network primitives (segmented tensor products, CG coefficients). | [`cuequivariance`](library-skills/cuequivariance) |
 
 ## Evaluating NIM Skill Lift
 

catalog-exceptions.yml

@@ -14,7 +14,7 @@ exceptions:
     owner: trvachov
     component: BioNeMo NIMs
   - dir: workflows
-    reason: Native meta-skill workflows (generative_protein_binder_design, virtual_screening, ai_q) authored in-repo.
+    reason: Native meta-skill workflows (generative-protein-binder-design, virtual_screening, ai_q) authored in-repo.
     owner: trvachov
     component: Workflows
 
@@ -27,7 +27,7 @@ exceptions:
     reason: No public GitHub source yet (was gitlab apizarro); native until a public repo exists.
     owner: trvachov
     component: Genomics
-  - dir: library-skills/cuEquivariance
+  - dir: library-skills/cuequivariance
     reason: Upstream (NVIDIA/cuEquivariance) exposes only an embedded SKILL.md inside a package dir, no clean skill folder to rsync; native until upstream ships a skill dir.
     owner: trvachov
     component: cuEquivariance

library-skills/genomics-workflow-acceleration/references/workflow-layout.md

@@ -12,12 +12,8 @@
 
 ## Toggle naming (prefer consistency)
 
-| Framework | Recommended | Default |
-|-----------|-------------|---------|
-| Nextflow | `params.use_parabricks` or `params.accelerated` | `false` |
-| Snakemake | `config["use_parabricks"]` | `false` |
-| WDL | input `Boolean use_parabricks` | `false` |
-| Python | `--use-parabricks` / `USE_PARABRICKS` | off |
+See the **Toggle contract** table in `SKILL.md` for the recommended toggle
+name and default per framework.
 
 Document example commands for toggle off (CPU) and toggle on (GPU) in
 `ACCELERATION.md`.

library-skills/parabricks/references/pbrun-fq2bam.md

@@ -49,16 +49,8 @@ For multiple FASTQ pairs from the same sample, repeat `--in-fq`. If read groups
 
 ## Performance Guidance
 
-Prefer the documented automatic stream selection for general commands: leave
-`--bwa-nstreams` unset, or set `--bwa-nstreams auto` only when making the
-default explicit. Current NVIDIA Parabricks documentation says Parabricks
-automatically chooses an optimal number of BWA streams from the GPU device
-memory specification.
-
-Use integer `--bwa-nstreams` values only for benchmark-driven tuning or
-memory-pressure troubleshooting after confirming the selected Parabricks
-version's docs. More streams increase device memory use, so fixed stream counts
-should not be part of conservative default command templates.
+BWA-stream tuning (`--bwa-nstreams`) is shared with `fq2bam_meth`; see
+[performance.md](performance.md).
 
 ## BWA-MEM/GATK Option Mapping
 

library-skills/parabricks/references/pbrun-fq2bam_meth.md

@@ -37,16 +37,8 @@ options against the selected version before finalizing.
 
 ## Performance Guidance
 
-Prefer the documented automatic stream selection for general commands: leave
-`--bwa-nstreams` unset, or set `--bwa-nstreams auto` only when making the
-default explicit. Current NVIDIA Parabricks documentation says Parabricks
-automatically chooses an optimal number of BWA streams from the GPU device
-memory specification.
-
-Use integer `--bwa-nstreams` values only for benchmark-driven tuning or
-memory-pressure troubleshooting after confirming the selected Parabricks
-version's docs. More streams increase device memory use, so fixed stream counts
-should not be part of conservative default command templates.
+BWA-stream tuning (`--bwa-nstreams`) is shared with `fq2bam`; see
+[performance.md](performance.md).
 
 ## BWA-Meth/GATK Option Mapping
 

library-skills/parabricks/references/performance.md

@@ -0,0 +1,17 @@
+# Parabricks Alignment Performance Guidance
+
+Shared BWA-stream tuning guidance for the `fq2bam` and `fq2bam_meth` commands.
+(Giraffe uses `--nstreams`; see `pbrun-giraffe.md`.)
+
+## BWA Streams
+
+Prefer the documented automatic stream selection for general commands: leave
+`--bwa-nstreams` unset, or set `--bwa-nstreams auto` only when making the
+default explicit. Current NVIDIA Parabricks documentation says Parabricks
+automatically chooses an optimal number of BWA streams from the GPU device
+memory specification.
+
+Use integer `--bwa-nstreams` values only for benchmark-driven tuning or
+memory-pressure troubleshooting after confirming the selected Parabricks
+version's docs. More streams increase device memory use, so fixed stream counts
+should not be part of conservative default command templates.

library-skills/parabricks/references/tool-index.md

@@ -4,55 +4,11 @@ Use this reference for tool discovery, category comparison, and routing heuristi
 when the user's data type or analysis goal is not yet mapped to a specific
 `pbrun` command.
 
-## Current Tool Categories
+## Tool Categories
 
-For NVIDIA Parabricks v4.7.0, the official Tool Reference lists these command
-categories.
-
-### FASTQ/BAM Processing
-
-- `applybqsr`: apply base quality score recalibration to aligned reads.
-- `bam2fq`: convert BAM input to FASTQ output.
-- `bamsort`: sort BAM input.
-- `bqsr`: generate base quality score recalibration data.
-- `fq2bam`: align FASTQ reads and produce BAM/CRAM with common preprocessing.
-- `fq2bam_meth`: methylation-oriented FASTQ-to-BAM workflow.
-- `giraffe`: pangenome graph alignment using vg giraffe with GATK-style steps.
-- `markdup`: mark duplicate reads in aligned data.
-- `minimap2`: long-read alignment.
-
-### Variant Calling
-
-- `deepsomatic`: DeepSomatic-based somatic variant calling.
-- `deepvariant`: DeepVariant variant calling.
-- `deepvariant_germline`: germline pipeline using DeepVariant.
-- `germline`: GATK-style germline short variant pipeline.
-- `haplotypecaller`: GATK HaplotypeCaller-compatible calling.
-- `mutectcaller`: Mutect2-compatible somatic calling.
-- `ont_germline`: Oxford Nanopore germline workflow.
-- `pacbio_germline`: PacBio germline workflow.
-- `pangenome_aware_deepvariant`: pangenome-aware DeepVariant workflow listed
-  in the alphabetical tool index.
-- `pangenome_germline`: pangenome-aware germline workflow.
-- `postpon`: post-processing for pangenome-aware workflows.
-- `prepon`: pre-processing for pangenome-aware workflows.
-- `somatic`: somatic variant calling pipeline.
-
-### RNA
-
-- `rna_fq2bam`: RNA-seq FASTQ-to-BAM workflow.
-- `starfusion`: fusion detection with STAR-Fusion.
-
-### Quality Control
-
-- `bammetrics`: BAM metrics and QC.
-- `collectmultiplemetrics`: collect multiple alignment metrics.
-
-### Variant and GVCF Processing
-
-- `dbsnp`: dbSNP annotation or processing support.
-- `genotypegvcf`: genotype GVCF input.
-- `indexgvcf`: index GVCF input.
+The per-tool descriptions and their reference links live in the
+**Tool Reference Index** table in the skill's `SKILL.md`. This file focuses on
+routing rather than restating that table.
 
 ## Routing Heuristics
 

nim-skills/boltz2-nim/SKILL.md

@@ -86,7 +86,7 @@ url = (
 )
 headers = {"Content-Type": "application/json"}
 if HOSTED:
-    headers["Authorization"] = f"Bearer {os.environ['NGC_API_KEY']}"
+    headers["Authorization"] = f"Bearer {os.getenv('NGC_API_KEY')}"
 
 payload = {
     "polymers": [{
@@ -131,18 +131,9 @@ protein_with_msa = {
 
 ## Save And Report Output
 
-```python
-for i, structure in enumerate(result["structures"], start=1):
-    with open(f"structure_{i}.cif", "w", encoding="utf-8") as handle:
-        handle.write(structure["structure"])
-for i, score in enumerate(result.get("confidence_scores", []), start=1):
-    print(f"structure {i} confidence {score:.4f}")
-if "affinities" in result:
-    for ligand_id, aff in result["affinities"].items():
-        print(ligand_id, aff["affinity_pic50"][0], aff["affinity_pred_value"][0], aff["affinity_probability_binary"][0])
-```
-
-Save every `.cif` artifact. Visualize in PyMOL, ChimeraX, or UCSF Chimera. For
+Save every `.cif` artifact and read the confidence/affinity fields using the
+snippet in [`references/examples.md`](references/examples.md) under **Save
+Structures And Affinity**. Visualize in PyMOL, ChimeraX, or UCSF Chimera. For
 confidence/affinity sanity checks, read `references/validation.md`.
 
 ## Limits And Troubleshooting

nim-skills/diffdock-nim/SKILL.md

@@ -37,38 +37,11 @@ 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
-```
+For the exact local preflight (`.env` load, `NVIDIA_API_KEY` fallback,
+`LOCAL_NIM_CACHE`, `NVIDIA_VISIBLE_DEVICES=0`, `--shm-size=2G`, both `--ulimit`
+flags, `docker login`, and the `docker run` for `nvcr.io/nim/mit/diffdock:2.2.0`),
+copy the command block in [`references/api.md`](references/api.md) under
+**Docker Reference** verbatim.
 
 Readiness:
 
@@ -109,7 +82,7 @@ url = (
 )
 headers = {"Content-Type": "application/json"}
 if HOSTED:
-    headers["Authorization"] = f"Bearer {os.environ['NGC_API_KEY']}"
+    headers["Authorization"] = f"Bearer {os.getenv('NGC_API_KEY')}"
 
 payload = {
     "protein": protein,
@@ -130,16 +103,8 @@ result = response.json()
 `ligand_positions` and `position_confidence` are parallel ranked lists.
 `position_confidence[0]` is the rank-1 pose confidence.
 
-```python
-poses = result["ligand_positions"]
-scores = result["position_confidence"]
-for rank, (pose_sdf, score) in enumerate(zip(poses, scores), start=1):
-    filename = f"pose_{rank}_conf{score:.3f}.sdf"
-    with open(filename, "w", encoding="utf-8") as handle:
-        handle.write(pose_sdf)
-    print(f"pose {rank}: confidence={score:.4f} saved={filename}")
-print(f"best pose confidence: {scores[0]:.4f}")
-```
+Save the ranked pose SDFs using the snippet in
+[`references/examples.md`](references/examples.md) under **Save Ranked Poses**.
 
 View pose SDF files with the receptor in PyMOL, ChimeraX, or UCSF Chimera. For
 pose sanity checks and confidence caveats, read `references/validation.md`.

nim-skills/diffdock-nim/references/examples.md

@@ -26,7 +26,7 @@ payload = {
 }
 headers = {
     "Content-Type": "application/json",
-    "Authorization": f"Bearer {os.environ['NGC_API_KEY']}",
+    "Authorization": f"Bearer {os.getenv('NGC_API_KEY')}",
 }
 r = requests.post(
     "https://health.api.nvidia.com/v1/biology/mit/diffdock",

nim-skills/diffdock-nim/references/parameters.md

@@ -1,22 +1,8 @@
 # DiffDock Parameter Guidance
 
-## Core Fields
-
-- `protein`: required receptor PDB content. Use non-empty ATOM records only.
-- `ligand`: required ligand content. For SMILES, pass one SMILES per line.
-- `ligand_file_type`: required. Use `"txt"` for SMILES, `"sdf"` for SDF, or
-  `"mol2"` for MOL2. Do not use `"smiles"`.
-- `num_poses`: optional integer, up to `100`. Use `5-20` for quick exploration
-  and more poses when screening a difficult target.
-- `time_divisions`: optional integer, maximum `20`. Higher values are slower
-  and more thorough.
-- `steps`: optional integer, maximum `18`. Higher values are slower and more
-  thorough.
-- `save_trajectory`: optional boolean. Keep `false` for normal pose generation;
-  use `true` only when trajectory frames are needed.
-- `skip_gen_conformer`: optional boolean. Use with care when ligand input already
-  encodes a suitable conformation.
-- `is_staged`: optional boolean staging flag.
+Field types, required flags, and limits live in the canonical schema table in
+[`api.md`](api.md) under **Request Body Schema**. This file is usage guidance
+only.
 
 ## Ligand Format Choices
 

nim-skills/evo2-nim/SKILL.md

@@ -67,7 +67,7 @@ echo "$NGC_API_KEY" | docker login nvcr.io --username '$oauthtoken' --password-s
 # 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}"
+chmod 700 "${LOCAL_NIM_CACHE}"   # owner-only; if the NIM runs as a different UID, add -u "$(id -u)" to docker run
 
 # For 7B: export NIM_VARIANT=7b; export NIM_TEST_GPUS="${NIM_TEST_GPUS:-0}"
 docker run --rm -it --name evo2-nim \
@@ -111,13 +111,15 @@ def clean_dna(value: str) -> str:
     return seq
 
 prompt = clean_dna("ACTGACTGACTGACTG")
+nim_url = os.getenv("EVO2_NIM_URL", "http://localhost:8000")
 url = (
     "https://health.api.nvidia.com/v1/biology/arc/evo2-40b/generate"
-    if HOSTED else "http://localhost:8000/biology/arc/evo2/generate"
+    if HOSTED else f"{nim_url}/biology/arc/evo2/generate"
 )
 headers = {"Content-Type": "application/json"}
 if HOSTED:
-    headers["Authorization"] = f"Bearer {os.environ['NGC_API_KEY']}"
+    api_key = os.getenv("NGC_API_KEY")
+    headers["Authorization"] = f"Bearer {api_key}"
 
 payload = {
     "sequence": prompt,
@@ -151,15 +153,17 @@ Forward returns base64-encoded NPZ tensors.
 ```python
 import base64
 import io
+import os
 import numpy as np
 import requests
 
+nim_url = os.getenv("EVO2_NIM_URL", "http://localhost:8000")
 payload = {
     "sequence": clean_dna("ACTGACTGACTG"),
     "output_layers": ["output_layer", "decoder.layers.3.self_attention"],
 }
 response = requests.post(
-    "http://localhost:8000/biology/arc/evo2/forward",
+    f"{nim_url}/biology/arc/evo2/forward",
     headers={"Content-Type": "application/json"},
     json=payload,
     timeout=300,

nim-skills/evo2-nim/references/api.md

@@ -169,7 +169,7 @@ echo "$NGC_API_KEY" | docker login nvcr.io --username '$oauthtoken' --password-s
 # 40B default: use 0,1 for 2x H100 80 GB; set NIM_TEST_GPUS=0 for a single H200.
 export NIM_TEST_GPUS="${NIM_TEST_GPUS:-0,1}"
 mkdir -p "${LOCAL_NIM_CACHE}"
-chmod 777 "${LOCAL_NIM_CACHE}"
+chmod 700 "${LOCAL_NIM_CACHE}"   # owner-only; if the NIM runs as a different UID, add -u "$(id -u)" to docker run
 
 # Optional: export NIM_VARIANT=7b and add `-e NIM_VARIANT` for the 7B model.
 docker run --rm -it --name evo2-nim \