openfold2-nim

OpenFold2 NIM

Predict a single protein-chain structure from an amino-acid sequence, with optional A3M multiple sequence alignments and mmCIF templates. Use this SKILL.md for basic hosted/local NIM use; load supplemental files only when the task needs deeper context:

• references/api.md: exact endpoints, schemas, Docker flags, response fields.
• references/science.md: model scope, strengths, limitations, and handoffs.
• references/parameters.md: MSA, template, model-selection, and relax effects.
• references/validation.md: artifact and scientific sanity checks.
• references/examples.md: compact hosted/local payload patterns.

Choose Mode

Ask only when context is unclear:

Hosted NVIDIA API or local Docker NIM?

• Hosted URL: https://health.api.nvidia.com/v1/biology/openfold/openfold2/predict-structure-from-msa-and-template
• Local URL: http://localhost:8000/biology/openfold/openfold2/predict-structure-from-msa-and-template
• Local readiness: http://localhost:8000/v1/health/ready

Mode difference: hosted and local use the same prediction path except local does not include /v1/. Hosted requests use Authorization: Bearer $NGC_API_KEY; local inference requests use no auth header after readiness.

Auth And Environment

Do not print API keys. Confirm they exist with shell tests, not echoes.

Hosted needs NGC_API_KEY in the request header. Supported local Docker startup uses NGC_API_KEY, or NVIDIA_API_KEY as a fallback, plus LOCAL_NIM_CACHE. A repo-root .env file may be sourced as a local override.

Local Docker

Use the official OpenFold2 NIM image and mount LOCAL_NIM_CACHE at /opt/nim/.cache. Current docs recommend at least 80 GB disk, 64 GB system RAM, 8 CPU cores, and one supported GPU; the container is roughly 55 GB and first startup downloads about 10 GB of model parameters.

When writing local setup commands, copy the preflight below exactly. Do not drop .env, NVIDIA_API_KEY, LOCAL_NIM_CACHE, or the no-auth local request.

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
: "${NGC_API_KEY:?Set NGC_API_KEY or NVIDIA_API_KEY}"
: "${LOCAL_NIM_CACHE:?Set LOCAL_NIM_CACHE}"

echo "$NGC_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 --name openfold2 \
  --runtime=nvidia \
  --gpus "device=${NIM_TEST_GPU}" \
  -e NGC_API_KEY \
  -v "${LOCAL_NIM_CACHE}:/opt/nim/.cache" \
  -p 8000:8000 \
  nvcr.io/nim/openfold/openfold2:latest

Readiness check:

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

Request Pattern

Use Python requests; curl escaping is fragile for A3M/mmCIF text. The sequence field is required. input_id, alignments, selected_models, relax_prediction, use_templates, and explicit_templates are optional.

import os
import requests

hosted = True
url = (
    "https://health.api.nvidia.com/v1/biology/openfold/openfold2/predict-structure-from-msa-and-template"
    if hosted
    else "http://localhost:8000/biology/openfold/openfold2/predict-structure-from-msa-and-template"
)
headers = {"Content-Type": "application/json"}
if hosted:
    headers["Authorization"] = f"Bearer {os.environ['NGC_API_KEY']}"

seq = "MTEYKLVVVGAGGVGKSALTIQLIQNHFVDEYDPT"
payload = {
    "sequence": seq,
    "input_id": "kras_fragment",
    "selected_models": [1],
    "relax_prediction": False,
    "alignments": {
        "uniref90": {
            "a3m": {
                "alignment": f">query\n{seq}",
                "format": "a3m",
            }
        }
    },
}

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

Payload gotchas:

• OpenFold2 is monomer-only. For protein-ligand, protein-DNA/RNA, or multi-chain complexes, use OpenFold3 or Boltz2 instead.
• sequence must use valid amino-acid IUPAC symbols.
• Hosted API docs list sequence length 1-1000; local docs say current NIM supports sequences up to 2048 residues on supported hardware.
• A3M alignments go under alignments by database name, then a3m with alignment and format. When the user needs to create or deepen an MSA, hand off to msa-search-nim / MSA Search and map its A3M output into this alignments shape.
• Starting with OpenFold2 2.0.0, use explicit_templates with mmCIF content; do not write new HHR-template examples.
• selected_models chooses AlphaFold2/OpenFold parameter sets 1-5. Select one or two models for smoke tests; use all five for stronger production runs.

Save And Interpret Output

The response includes one prediction per selected model, ordered by confidence. Save every returned structure-like text field and the full JSON response so field-shape differences are auditable. Production answers should explicitly write .pdb or .cif artifacts, preserve the response JSON, and print any confidence/ranking fields the service returns.

from pathlib import Path
import json

Path("openfold2_response.json").write_text(json.dumps(result, indent=2))

def save_strings(obj, prefix="openfold2"):
    i = 0
    if isinstance(obj, dict):
        for key, value in obj.items():
            if isinstance(value, str) and ("ATOM" in value or value.lstrip().startswith("data_")):
                i += 1
                ext = "cif" if value.lstrip().startswith("data_") else "pdb"
                Path(f"{prefix}_{key}_{i}.{ext}").write_text(value)
            elif isinstance(value, (dict, list)):
                i += save_strings(value, f"{prefix}_{key}")
    elif isinstance(obj, list):
        for idx, value in enumerate(obj, start=1):
            if isinstance(value, (dict, list)):
                i += save_strings(value, f"{prefix}_{idx}")
    return i

saved = save_strings(result)
print(f"saved {saved} structure artifact(s)")

For production monomer runs:

• Use selected_models: [1, 2, 3, 4, 5] unless the user requests a smoke test.
• Use relax_prediction: True in Python payloads when relaxation is desired; JSON examples may show true.
• State the sequence length caveat: hosted API docs list 1-1000 residues, while local support-matrix docs list up to 2048 residues on supported hardware.
• If the task is a complex rather than a monomer, redirect to OpenFold3 or Boltz2.

Treat tiny toy sequences and single-sequence MSAs as API smoke tests, not quality evidence. For scientific interpretation and validation, read references/science.md and references/validation.md.

Troubleshooting

• 401: missing, expired, or unauthorized NGC API key.
• 422: invalid amino-acid characters, sequence too long, malformed A3M, bad selected_models, or malformed mmCIF template object.
• Local 404: remove /v1/ from the prediction URL.
• Weak structures: use MSA Search to generate deeper A3M alignments and add biologically relevant mmCIF templates when appropriate.
• Local startup stalls: first run downloads parameters into LOCAL_NIM_CACHE.