Molmim Nim
Apps & Automationmolmim-nimMolmim Nim is an Agent Skill for apps & automation published in the NVIDIA-BioNeMo/bionemo-agent-toolkit repository on GitHub: a SKILL.md instruction file an AI agent can load to do this task.
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.
How to use this skill
Bring this guide into your coding agent with a prompt tailored to the tool you use.
- Open your project in Codex.
- Copy and paste the prompt below.
- Review files and risks before approving any action.
Inspect the Agent Skill at https://github.com/NVIDIA-BioNeMo/bionemo-agent-toolkit/blob/HEAD/plugins/bionemo-agent-toolkit/skills/molmim-nim/SKILL.md and all supporting files. Report provenance, permissions, scripts, dependencies, and security risks. Propose an exact installation into .agents/skills/molmim-nim, but wait for my approval before writing files or running scripts.
Copying this prompt does not install or run the skill. Review third-party files before use.
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.
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:
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.environ['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, notsmiles. algorithmis"CMA-ES"or"none".property_nameis"QED"or"plogP".num_moleculesis 1-100.iterationsis 1-1000.particlesis 2-1000.min_similarityis 0-1 in the hosted API reference; local docs emphasize common values up to 0.7 for constrained optimization.scaled_radiusis 0-2 and is mainly used withalgorithm: "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.loads(molecules)
if isinstance(molecules, list):
for item in molecules:
if isinstance(item, dict) and isinstance(item.get("sample"), str):
values.append(item["sample"])
return values
generated = molmim_smiles(result)
if not generated:
raise RuntimeError(f"MolMIM returned no generated molecules: {result}")
Path("molmim_response.json").write_text(json.dumps(result, indent=2))
Path("molmim_generated.smi").write_text("\n".join(generated) + "\n")
for i, smiles in enumerate(generated, start=1):
print(i, smiles)
Use RDKit when available to check parseability, uniqueness, simple property ranges, and whether seed similarity constraints are plausible. Generated molecules are candidates, not validated hits; use downstream property, docking, affinity, toxicity, and synthetic-feasibility checks before prioritization.
Troubleshooting
- Hosted
404on/embedding,/hidden,/decode, or/sampling: those endpoints are local-only in the docs. 401: missing or unauthorized NGC key for hosted requests.- Hosted response parsing: live hosted
/generatemay returnmoleculesas a JSON string of{sample, score}objects, while local endpoints may returngenerated; parse both. 422: invalid SMILES, unsupportedalgorithm, invalidproperty_name, or parameter outside documented ranges.- Local startup auth: set
NGC_CLI_API_KEY, or setNGC_API_KEY/NVIDIA_API_KEYand map it as shown above. - Local startup cache misses: mount
LOCAL_NIM_CACHEto/home/nvs/.cache/nim, not/opt/nim/.cache.