genmol-nim

GenMol NIM

Generate drug-like molecules with GenMol. Use this guide for first-pass hosted and 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: SAFE patterns and tuning effects.
• references/validation.md: chemical and artifact checks.
• references/examples.md: compact request patterns.

Choose Mode

Ask only when context is unclear:

Hosted NVIDIA API or local Docker NIM?

• Hosted: https://health.api.nvidia.com/v1/biology/nvidia/genmol/generate
• Local: http://localhost:8000/generate

Hosted requests use Authorization: Bearer $NGC_API_KEY. For local Docker, authenticate image pulls with docker login nvcr.io using NGC_API_KEY (or NVIDIA_API_KEY via the preflight). Pass -e NGC_API_KEY into the container for entitlement checks and first-run model downloads. Local inference requests use no auth header after readiness, so bind the published port to loopback with -p 127.0.0.1:8000:8000. Warm-cache key-free startup varies by image version and should not be assumed.

Local Docker

Use credentials already supplied in the shell environment or injected by a secret manager. Do not load credential files, print keys, or enable shell tracing. For local setup answers, include this sequence: env preflight, docker login with --password-stdin, docker run, readiness loop, then a no-auth localhost request. Do not invent a cache default or drop the NVIDIA_API_KEY fallback.

Before executing local setup, explain that registry authentication sends the key to the NVIDIA registry at https://nvcr.io and first-run model downloads use about 20 GB in LOCAL_NIM_CACHE. Execute deployment only when the user requests it; for a setup guide, provide the commands without running them.

For the exact startup preflight (environment checks, NVIDIA_API_KEY fallback, --shm-size=2G, both --ulimit flags, docker login, and the docker run for nvcr.io/nim/nvidia/genmol:1.0.1), copy the command block in references/api.md under Local container startup verbatim.

GenMol is single-GPU; NIM_TEST_GPU defaults to 0. Wait for readiness:

until curl -sf http://localhost:8000/v1/health/ready; do sleep 5; done

SAFE Input

The API field is named smiles, but GenMol expects SAFE notation. Masked positions use [*{min-max}].

• De novo: safe_input = "[*{20-30}]"
• Scaffold decoration: safe_input = scaffold_to_safe("C1CC(=O)NC1", 10, 15)
• Motif extension: safe_input = f"[*{{5-10}}].{motif_safe}.[*{{5-10}}]"
• Lead optimization: encode the hit, then replace a fragment with .[*{5-12}]

Use safe-mol for conditioned generation. Simple ring scaffolds may raise SAFEFragmentationError; fall back to the original SMILES plus a SAFE mask.

See the scaffold_to_safe helper in references/examples.md under Scaffold Decoration.

Wider masks increase diversity; tight masks keep analog size more predictable.

Request Pattern

import os
import requests

HOSTED = True
url = (
    "https://health.api.nvidia.com/v1/biology/nvidia/genmol/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 = {
    "smiles": "[*{20-30}]",  # SAFE notation
    "num_molecules": 30,
    "temperature": "1",      # string, not float
    "noise": "1",            # string, not float
    "step_size": 1,
    "scoring": "QED",        # or "LogP"
    "unique": False,
}

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

Gotchas:

• temperature and noise are strings.
• num_molecules is 1-1000; invalid/duplicate molecules may be filtered, so request extra when the user needs a minimum count.
• scoring is "QED" for drug-likeness or "LogP" for lipophilicity.
• Set unique=True for deduplicated analog lists.

Save And Report Output

Sort molecules by score, print the top ranks, and write a .smi file as shown in references/examples.md under Save Ranked Results. For chemical validity, uniqueness, PAINS/alerts, and visualization with RDKit, read references/validation.md.

Limits And Troubleshooting

• Fewer molecules than requested is expected after filtering.
• Invalid SAFE strings cause status: "failed" or validation errors.
• Install safe-mol only for scaffold, motif, or lead-optimization workflows; de novo masks work without conversion.
• Local startup downloads about 20 GB into LOCAL_NIM_CACHE.
• Container issues: confirm nvidia-smi, NVIDIA Container Toolkit, and --runtime=nvidia; use NIM_TEST_GPU to choose the single visible GPU.