Update to NVIDIA BioNeMo Agent Toolkit

{
  "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.",
  "included_files": [
    {
      "relative_path": "references/api.md",
      "size_in_bytes": 8865
    },
    {
      "relative_path": "references/examples.md",
      "size_in_bytes": 1054
    },
    {
      "relative_path": "references/parameters.md",
      "size_in_bytes": 1392
    },
    {
      "relative_path": "references/science.md",
      "size_in_bytes": 1387
    },
    {
      "relative_path": "references/validation.md",
      "size_in_bytes": 1308
    }
  ],
  "name": "evo2-nim",
  "skill_md_contents": "---\nname: evo2-nim\ndescription: >\n  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.\nlicense: Apache-2.0 AND CC-BY-4.0\ncompatibility: \"requests>=2.28; numpy>=1.24\"\nallowed-tools: Bash, Read, Write, AskUserQuestion\n---\n\n# Evo 2 NIM\n\nUse Evo 2 for DNA generation and, locally, layer-output extraction. Use this\n`SKILL.md` for basic hosted/local use; load supplemental files only when needed:\n\n- `references/api.md`: exact schemas, layer names, Docker flags, hardware notes.\n- `references/science.md`: genomic use cases, limits, and interpretation.\n- `references/parameters.md`: generation/forward parameter effects.\n- `references/validation.md`: DNA, probability, timing, and tensor 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 Evo 2 NIM?\n\n- Hosted generation: `https://health.api.nvidia.com/v1/biology/arc/evo2-40b/generate`\n- Local generation: `http://localhost:8000/biology/arc/evo2/generate`\n- Local forward/layer outputs: `http://localhost:8000/biology/arc/evo2/forward`\n\nThe hosted docs expose generation. `/forward` is documented for local Docker;\ndo not invent a hosted `/forward` endpoint. 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## Local Docker Requirements\n\nEvo 2 local deployment requires FP8-capable GPUs. Do not present A100 as\ncompatible; A100 can pull the image but fails warmup because FP8 requires\ncompute capability 8.9 or higher.\n\n- Default 40B: 2x H100 80 GB or 1x H200 141 GB. Use `NIM_TEST_GPUS=0,1` for\n  2x H100, or `NIM_TEST_GPUS=0` for one H200.\n- 7B fallback: set `NIM_VARIANT=7b`; supported GPUs include H100, H200,\n  RTX 6000 Ada, and L40S.\n- Approximate disk: 110 GB for 40B, 50 GB for 7B.\n\nUse shell env first; source repo-root `.env` only if present. Do not invent a\ncache default or drop the `NVIDIA_API_KEY` fallback.\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\n# 40B default: 0,1 for 2x H100; set 0 for a single H200.\nexport NIM_TEST_GPUS=\"${NIM_TEST_GPUS:-0,1}\"\nmkdir -p \"${LOCAL_NIM_CACHE}\"\nchmod 777 \"${LOCAL_NIM_CACHE}\"\n\n# For 7B: export NIM_VARIANT=7b; export NIM_TEST_GPUS=\"${NIM_TEST_GPUS:-0}\"\ndocker run --rm -it --name evo2-nim \\\n  --runtime=nvidia \\\n  --gpus \"\\\"device=${NIM_TEST_GPUS}\\\"\" \\\n  -e NGC_API_KEY \\\n  -e NIM_VARIANT \\\n  -v \"${LOCAL_NIM_CACHE}:/opt/nim/.cache\" \\\n  -p 8000:8000 \\\n  nvcr.io/nim/arc/evo2:2\n```\n\nReadiness:\n\n```bash\nuntil curl -sf http://localhost:8000/v1/health/ready; do sleep 10; done\n```\n\nIf RTX PRO 6000 Blackwell Workstation fails with no Transformer Engine\nattention backend, treat it as outside the current validated matrix and rerun\non a documented GPU/runtime.\n\n## DNA Generation\n\nNormalize prompts before sending. Use A/C/G/T unless ambiguous bases are a\ndeliberate modeling choice and clearly reported.\n\n```python\nimport json\nimport os\nfrom pathlib import Path\nimport requests\n\nHOSTED = True\n\ndef clean_dna(value: str) -> str:\n    seq = \"\".join(value.upper().split())\n    invalid = sorted(set(seq) - set(\"ACGT\"))\n    if invalid:\n        raise ValueError(f\"Unexpected DNA characters: {''.join(invalid)}\")\n    return seq\n\nprompt = clean_dna(\"ACTGACTGACTGACTG\")\nurl = (\n    \"https://health.api.nvidia.com/v1/biology/arc/evo2-40b/generate\"\n    if HOSTED else \"http://localhost:8000/biology/arc/evo2/generate\"\n)\nheaders = {\"Content-Type\": \"application/json\"}\nif HOSTED:\n    headers[\"Authorization\"] = f\"Bearer {os.environ['NGC_API_KEY']}\"\n\npayload = {\n    \"sequence\": prompt,\n    \"num_tokens\": 64,\n    \"temperature\": 0.7,\n    \"top_k\": 3,\n    \"top_p\": 0.0,\n    \"random_seed\": 1,\n    \"enable_sampled_probs\": True,\n    \"enable_elapsed_ms_per_token\": True,\n}\nresponse = requests.post(url, headers=headers, json=payload, timeout=180)\nresponse.raise_for_status()\nresult = response.json()\nseq = result[\"sequence\"]\nif sorted(set(seq.upper()) - set(\"ACGT\")):\n    raise ValueError(\"Generated sequence contains unexpected non-ACGT bases\")\n\nPath(\"evo2_generation.json\").write_text(json.dumps(result, indent=2) + \"\\n\")\nPath(\"evo2_generated.fa\").write_text(f\">evo2_generated\\n{seq}\\n\")\nprint(f\"Generated {len(seq)} bases in {result.get('elapsed_ms')} ms\")\n```\n\nOnly request `enable_logits` when needed; logits can make responses large.\n`random_seed` supports development reproducibility, not biological certainty.\n\n## Local Forward Pass\n\nForward returns base64-encoded NPZ tensors.\n\n```python\nimport base64\nimport io\nimport numpy as np\nimport requests\n\npayload = {\n    \"sequence\": clean_dna(\"ACTGACTGACTG\"),\n    \"output_layers\": [\"output_layer\", \"decoder.layers.3.self_attention\"],\n}\nresponse = requests.post(\n    \"http://localhost:8000/biology/arc/evo2/forward\",\n    headers={\"Content-Type\": \"application/json\"},\n    json=payload,\n    timeout=300,\n)\nresponse.raise_for_status()\nnpz_bytes = base64.b64decode(response.json()[\"data\"])\nwith open(\"evo2_forward_outputs.npz\", \"wb\") as handle:\n    handle.write(npz_bytes)\narrays = np.load(io.BytesIO(npz_bytes), allow_pickle=False)\nfor name in arrays.files:\n    arr = arrays[name]\n    print(name, arr.shape, arr.dtype, bool(np.isfinite(arr).all()), float(arr.mean()))\n```\n\n## Validate And Report\n\nSave request/response JSON, generated FASTA, and a metrics JSON with sequence\nlength, GC fraction, ambiguous-base fraction, homopolymer length, sampled-prob\nchecks, and elapsed timing. Treat invalid schema or alphabet as hard failures;\ntreat extreme GC, low complexity, duplicates, and missing motifs as warnings.\nFor deeper checks, read `references/validation.md`.\n\nKey fields: `sequence`, `num_tokens`, `temperature`, `top_k` (0-6), `top_p`\n(0-1), `random_seed`, `enable_sampled_probs`, `enable_elapsed_ms_per_token`,\nand optional `enable_logits`.\n\n## Troubleshooting\n\n- `401/403`: hosted key missing/expired or not sent as Bearer token.\n- `422`: wrong field names such as `max_tokens` instead of `num_tokens`.\n- Local auth confusion: do not send `Authorization` to localhost.\n- Local startup: first run downloads model assets; wait on `/v1/health/ready`.\n- FP8 failure: use hosted, 7B on a supported FP8 GPU, or documented 40B GPUs.\n"
}