Update to NVIDIA BioNeMo Agent Toolkit

{
  "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.",
  "included_files": [
    {
      "relative_path": "references/api.md",
      "size_in_bytes": 5399
    },
    {
      "relative_path": "references/examples.md",
      "size_in_bytes": 2303
    },
    {
      "relative_path": "references/parameters.md",
      "size_in_bytes": 2819
    },
    {
      "relative_path": "references/science.md",
      "size_in_bytes": 2642
    },
    {
      "relative_path": "references/validation.md",
      "size_in_bytes": 2543
    }
  ],
  "skill_md_contents": "---\nname: openfold3-nim\ndescription: >\n  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.\nlicense: Apache-2.0 AND CC-BY-4.0\ncompatibility: \"requests>=2.28\"\nallowed-tools: Bash, Read, Write, AskUserQuestion\n---\n\n# OpenFold3 NIM\n\nPredict biomolecular structures with OpenFold3. It supports proteins, DNA, RNA,\nsmall-molecule ligands, and multi-entity assemblies. Use this `SKILL.md` for\nbasic hosted/local NIM use; load supplemental files only when the task needs\ndeeper context:\n\n- `references/api.md`: exact endpoints, schemas, Docker flags, response fields.\n- `references/science.md`: purpose, strengths, limitations, and model handoffs.\n- `references/parameters.md`: molecule fields, MSAs, templates, samples, tuning.\n- `references/validation.md`: artifact checks and scientific sanity checks.\n- `references/examples.md`: compact hosted/local request patterns.\n\n## Choose Mode\n\nAsk only when context is unclear:\n\n> Hosted NVIDIA API or local Docker NIM?\n\n- Hosted URL: `https://health.api.nvidia.com/v1/biology/openfold/openfold3/predict`\n- Local URL: `http://localhost:8000/biology/openfold/openfold3/predict`\n- Local readiness: `http://localhost:8000/v1/health/ready`\n\nMode difference: the local prediction path has no `/v1/` prefix. Hosted requests use `Authorization: Bearer $NGC_API_KEY`. Supported local Docker\nstartup uses `NGC_API_KEY` (or `NVIDIA_API_KEY` via the preflight) for\nregistry login, entitlement checks, and first-run model downloads; pass it\ninto the container with `-e NGC_API_KEY`. Local inference requests use no\nauth header after readiness. Warm-cache key-free startup varies by\nimage/version and should not be assumed.\n\n## Auth And Environment\n\nDo not print API keys. Confirm they exist with shell tests, not echoes.\n\nHosted needs `NGC_API_KEY` in the request header. Local startup needs\n`NGC_API_KEY`, or `NVIDIA_API_KEY` as a fallback, plus `LOCAL_NIM_CACHE`.\nA repo-root `.env` file may be sourced as a local override before validation.\n\n## Local Docker\n\nUse the official OpenFold3 NIM image and mount `LOCAL_NIM_CACHE` at\n`/opt/nim/.cache`. First startup downloads model artifacts and can take several\nminutes.\n\nWhen writing local setup commands, copy the preflight below exactly. Do not\nreplace it with a simple `: \"${NGC_API_KEY:?Set NGC_API_KEY}\"` check, do not\ndrop `NVIDIA_API_KEY`, and do not invent a default `LOCAL_NIM_CACHE`; those\nlines are the repo's local NIM env contract. The default single-GPU launch\nshould show the literal `--gpus \"device=0\"`; choose a different device only\nwhen the user asks.\n\n```bash\nset -a\n[ -f .env ] && . ./.env\nset +a\n\nif [ -z \"${NGC_API_KEY:-}\" ] && [ -n \"${NVIDIA_API_KEY:-}\" ]; then\n  export NGC_API_KEY=\"$NVIDIA_API_KEY\"\nfi\n: \"${NGC_API_KEY:?Set NGC_API_KEY or NVIDIA_API_KEY}\"\n: \"${LOCAL_NIM_CACHE:?Set LOCAL_NIM_CACHE}\"\n\necho \"$NGC_API_KEY\" | docker login nvcr.io --username '$oauthtoken' --password-stdin\n\nmkdir -p \"${LOCAL_NIM_CACHE}\"\nchmod 777 \"${LOCAL_NIM_CACHE}\"\n\ndocker run --rm --name openfold3 \\\n  --runtime=nvidia \\\n  --gpus \"device=0\" \\\n  --shm-size=16g \\\n  -e NGC_API_KEY \\\n  -v \"${LOCAL_NIM_CACHE}:/opt/nim/.cache\" \\\n  -p 8000:8000 \\\n  nvcr.io/nim/openfold/openfold3:latest\n```\n\nReadiness check:\n\n```bash\nuntil curl -sf http://localhost:8000/v1/health/ready; do sleep 5; done\n```\n\n## Request Pattern\n\nUse `requests.post(..., json=payload, timeout=300)`. For local Docker tasks,\nset `hosted = False` after the readiness check passes.\n\n```python\nimport os\nimport requests\n\nhosted = True\nurl = (\n    \"https://health.api.nvidia.com/v1/biology/openfold/openfold3/predict\"\n    if hosted\n    else \"http://localhost:8000/biology/openfold/openfold3/predict\"\n)\nheaders = {\"Content-Type\": \"application/json\"}\nif hosted:\n    headers[\"Authorization\"] = f\"Bearer {os.environ['NGC_API_KEY']}\"\n\nseq = \"MKTVRQERLKSIVR\"\npayload = {\n    \"inputs\": [{\n        \"input_id\": \"prediction_1\",\n        \"output_format\": \"pdb\",\n        \"molecules\": [{\n            \"type\": \"protein\",\n            \"id\": \"A\",\n            \"sequence\": seq,\n            \"diffusion_samples\": 1,\n            \"msa\": {\n                \"main\": {\n                    \"a3m\": {\n                        \"alignment\": f\">query\\n{seq}\",\n                        \"format\": \"a3m\"\n                    }\n                }\n            }\n        }]\n    }]\n}\n\nresponse = requests.post(url, headers=headers, json=payload, timeout=300)\nresponse.raise_for_status()\nresult = response.json()\n```\n\nPayload gotchas:\n\n- Top level is `{\"inputs\": [...]}` and OpenFold3 accepts exactly one input.\n- `molecules` can contain 1-32 objects with `type`: `protein`, `dna`, `rna`,\n  or `ligand`.\n- Protein/RNA MSAs are optional but, when supplied, `alignment` must start with\n  a FASTA header such as `>query\\nSEQUENCE`.\n- Ligands use either `smiles` or `ccd_codes`, for example\n  `{\"type\": \"ligand\", \"id\": \"L\", \"ccd_codes\": \"ATP\"}`.\n- DNA/RNA entities use `sequence`, for example\n  `{\"type\": \"dna\", \"id\": \"B\", \"sequence\": \"ATCGATCG\"}`.\n- `diffusion_samples` is 1-5. `output_format` is `pdb` or `cif`.\n\n## Save And Interpret Output\n\nSave every returned structure as a scientific artifact. Main response path:\n`result[\"outputs\"][0][\"structures_with_scores\"]`.\n\n```python\noutput = result[\"outputs\"][0]\nfor i, sample in enumerate(output[\"structures_with_scores\"], start=1):\n    fmt = sample[\"format\"]\n    with open(f\"openfold3_structure_{i}.{fmt}\", \"w\", encoding=\"utf-8\") as fh:\n        fh.write(sample[\"structure\"])\n    print(\"confidence_score\", sample.get(\"confidence_score\"))\n    print(\"complex_plddt_score\", sample.get(\"complex_plddt_score\"))\n    print(\"ptm_score\", sample.get(\"ptm_score\"))\n    print(\"iptm_score\", sample.get(\"iptm_score\"))\n    print(\"complex_pde_score\", sample.get(\"complex_pde_score\"))\n```\n\nHigher `confidence_score`, `complex_plddt_score`, `ptm_score`, and `iptm_score`\nare generally better; lower `complex_pde_score` is generally better. Treat toy\nor very short sequences as API smoke tests, not meaningful structural biology.\nFor why and when OpenFold3 is scientifically appropriate, read\n`references/science.md`.\n\n## Common Limits\n\n- Inputs per request: 1.\n- Molecules per input: 1-32.\n- Diffusion samples: 1-5.\n- TensorRT path supports shorter sequences; PyTorch path can support longer\n  sequences, but long inputs need much more GPU memory.\n- Sequences over roughly 1800 residues require at least 80 GB GPU memory.\n- Local NIM is single-GPU only; choose the target device in the Docker flag.\n\n## Troubleshooting\n\n- `401`: missing, expired, or unauthorized NGC API key.\n- `422`: invalid molecule type, invalid sequence characters, bad MSA shape, or\n  `diffusion_samples` outside 1-5.\n- MSA errors: ensure the alignment starts with `>query\\n`.\n- Local `404`: remove `/v1/` from the prediction URL.\n- Local startup stalls: first run may be downloading 10-15 GB of model weights\n  into `LOCAL_NIM_CACHE`.\n- Memory errors: shorten the sequence, reduce samples, or use a larger GPU.\n"
}