/bionemo-molmim-nim

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 guide 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?

See [`references/api.md`](references/api.md) under **Endpoints** for the full hosted/local endpoint list.

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`.

For the exact startup preflight (the `NGC_API_KEY`/`NVIDIA_API_KEY` → `NGC_CLI_API_KEY` mapping, `docker login`, and the `docker run` for `nvcr.io/nim/nvidia/molmim:1.0.0`), copy the command block in [`references/api.md`](references/api.md) under **Local Docker** verbatim.

Readiness check:

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:

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.

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 = {"Content-Type": "application/json"}
if hosted:
    headers["Authorization"] = f"Bearer {os.getenv('NGC_API_KEY')}"

payload = {
    "smi": "CN1C=NC2=C1C(=O)N(C(=O)N2C)C",
    "algorithm": "CMA-ES",
    "num_molecules": 10,
    "property_name": "QED",
    "minimize": False,
    "min_similarity": 0.4,
    "particles": 8,
    "iterations": 3,
}

response = requests.post(url, headers=headers, json=payload, timeout=180)
response.raise_for_status()
result = response.json()

Generation gotchas:

• Field name is `smi`, not `smiles`.
• `algorithm` is `"CMA-ES"` or `"none"`.
• `property_name` is `"QED"` or `"plogP"`.
• `num_molecules` is 1-100. `iterations` is 1-1000. `particles` is 2-1000.
• `min_similarity` is 0-1 in the hosted API reference; local docs emphasize

common values up to 0.7 for constrained optimization.

• `scaled_radius` is 0-2 and is mainly used with `algorithm: "none"` or local

`/sampling`.

Local Latent Workflow

Use local-only endpoints for embedding, hidden-state manipulation, and decode. This is also the surface used by the guided optimization example package. For local latent workflows, state explicitly that the hosted API reference exposes `/generate`; `/embedding`, `/hidden`, `/decode`, and `/sampling` are local-only in the current docs.

seed = "CC(Cc1ccc(cc1)C(C(=O)O)C)C"
base = "http://localhost:8000"
headers = {"Content-Type": "application/json"}

embedding = requests.post(
    f"{base}/embedding",
    headers=headers,
    json={"sequences": [seed]},
    timeout=60,
)
embedding.raise_for_status()
embedding_data = embedding.json()
embeddings = embedding_data["embeddings"]
print(f"received {len(embeddings)} embedding vector(s)")

hidden = requests.post(
    f"{base}/hidden",
    headers=headers,
    json={"sequences": [seed]},
    timeout=60,
)
hidden.raise_for_status()
hidden_data = hidden.json()
hiddens = hidden_data["hiddens"]
mask = hidden_data["mask"]

decoded = requests.post(
    f"{base}/decode",
    headers=headers,
    json={"hiddens": hiddens, "mask": mask},
    timeout=60,
)
decoded.raise_for_status()

sampled = requests.post(
    f"{base}/sampling",
    headers=headers,
    json={"sequences": [seed], "num_molecules": 10, "scaled_radius": 0.7},
    timeout=60,
)
sampled.raise_for_status()

Save And Validate Output

Save generated SMILES and validate before using them downstream.

from pathlib import Path
import json

def molmim_smiles(result):
    values = []
    if isinstance(result.get("generated"), list):
        for item in result["generated"]:
            if isinstance(item, str):
                values.append(item)
            elif isinstance(item, list):
                values.extend(x for x in item if isinstance(x, str))
    molecules = result.get("molecules")
    if isinstance(molecules, str):
        molecules = json.lo