Generated banner for Kermt Embed
Generated logo for Kermt Embed

Kermt Embed

NVIDIAOfficialPublished by NVIDIA

  • Skill
  • Workflow
  • Science and research
  • Apache-2.0
  • Medium risk
  • Has scripts

From the author

Extract per-molecule embeddings from any encoder-bearing KERMT checkpoint. Use a local checkpoint or optionally download a pinned Hugging Face model bundle using HF_TOKEN if configured. Run containerized embedding extraction and write model bundles, per-readout .npy embeddings, canonical SMILES, and validity arrays to user-selected host directories.
— the description by NVIDIA

AutoGineer summary

Written by AutoGineer from the skill’s own files, not by the author

The kermt-embed skill provides a structured, containerized workflow for generating per-molecule embeddings from KERMT model checkpoints. It manages the entire pipeline, including system validation, data preparation, checkpoint verification, and execution. The skill supports both custom checkpoints and the automatic, consent-based download of pretrained NVIDIA KERMT models. It outputs standardized .npy embedding files for four distinct readouts, along with canonical SMILES and validity metadata, ensuring consistent results for downstream chemical analysis.

What it does

  • Validates system requirements and container environment for embedding extraction.
  • Automates the download and verification of pretrained KERMT model bundles.
  • Cleans and prepares input SMILES data from CSV files for model processing.
  • Executes embedding extraction on a single GPU using specified or default checkpoints.
  • Generates standardized .npy embedding arrays and metadata for molecular analysis.
  • Provides replayable run manifests for reproducibility.

When to use it

  • When you need to generate numerical vector representations for a set of molecules.
  • When you want to use a pretrained KERMT model to featurize chemical data.
  • When you have a custom encoder-bearing KERMT checkpoint and need to extract embeddings from it.
  • When you require a reproducible, containerized pipeline for molecular embedding tasks.

Advantages

  • Ensures consistent environment configuration via containerization.
  • Automates complex multi-step validation of checkpoints and input data.
  • Provides clear, standardized output formats for downstream integration.
  • Includes built-in safety checks for model downloads and hardware compatibility.

Usage examples

“Extract embeddings for the molecules in my_molecules.csv using the default pretrained model.”
The agent will prompt for consent to download the NV-KERMT-70M-v2 model, validate the CSV, and generate embedding files in a new run directory.
“Run embedding extraction on molecules.csv using my local checkpoint at /path/to/model.pt.”
The agent validates the local checkpoint and input CSV, then executes the extraction workflow using the provided model file.

Install

  1. Download the skill as a ZIP:

    https://autogineer.com/agent-skills/nvidia/kermt-embed/download
  2. Unzip it into the cross-client skills folder of your project:

    mkdir -p .agents/skills && unzip kermt-embed.zip -d .agents/skills

Documentation by NVIDIA

kermt-embed

Extract per-molecule embeddings from any encoder-bearing KERMT checkpoint. The skill is the workflow orchestrator: validate ckpt, validate CSV, clean SMILES, launch the runner blocking, return the per-readout .npy files.

Skill and runtime paths

Set SKILL_DIR to the absolute path of this installed skill directory. Export KERMT_REPO as the absolute path to the KERMT checkout used for model execution. The bundled container helper mounts that checkout at /workspace and this skill at /skill (read-only). Commands inside the container use /skill/scripts/; defaults are bundled in config/. See Released models for checkpoint bundle requirements.

Downloads and local outputs

The optional released-model branch reads config/released_model.json for the Hugging Face repository, pinned revision, and filenames. The bundled scripts/fetch_released_model.py downloads the model bundle over HTTPS into the host directory the user selects. Public models work without credentials; if HF_TOKEN is set, the container helper forwards it for Hugging Face authentication. Prepared data, logs, and workflow results go into the chosen run directory.

Hardware requirements

  • GPUs: 1 (single-GPU).

  • VRAM: ≥ 4 GB for the default batch_size 64.

  • Disk: depends on output size — roughly a few MB per 1k molecules at hidden 800 per readout, so ~10–20 MB per 1k molecules across the 4 readouts. Plus a small canonical_smiles.npy + validity.npy per run.

  • Driver / CUDA: any host supporting CUDA 12.6.

Inputs

Required:

  • --csv <path> — SMILES CSV. First column is smiles; other columns are ignored (no targets needed).

Checkpoint (optional — defaults to the released model if omitted):

  • --ckpt <path> — any encoder-bearing checkpoint. Grover_base, cmim, hybrid, and finetuned ckpts are all accepted. The validator only refuses ckpts with no encoder. If omitted, the skill offers to download the released pretrained hybrid model nvidia/NV-KERMT-70M-v2 and embed with it — see "Resolve & validate the checkpoint" (workflow step 3).

  • --pretrained-release — explicit opt-in to use the released model without the interactive prompt (for non-interactive / agent runs). Mutually exclusive with --ckpt.

  • --model-dir <dir> — where to save the downloaded bundle (default $KERMT_REPO/models/NV-KERMT-70M-v2/). An already-complete bundle there is reused, not re-downloaded.

Optional:

  • --batch-size N — override the configured default (64).

  • --gpus 0 — single GPU id (default 0).

  • --from-prepare <dir> — skip the prepare step and reuse an existing prepare_data.json in <dir>.

Workflow

Let $KERMT_REPO be the path to your kermt repo checkout.

  1. Pre-flight: container + system probe.

    "$SKILL_DIR/scripts/kermt_container.sh" check_system
  2. Compute run directory.

    RUN_DIR=$KERMT_REPO/runs/embed_$(date -u +%Y-%m-%dT%H-%M-%SZ)
  3. Resolve & validate the checkpoint.

    Resolve — only if --ckpt was omitted. Default to the released pretrained hybrid model nvidia/NV-KERMT-70M-v2:

    • Consent gate. Unless --pretrained-release was passed, ask the user: "No checkpoint given — download the released model nvidia/NV-KERMT-70M-v2 (NVIDIA Open Model License, https://huggingface.co/nvidia/NV-KERMT-70M-v2) and embed with it? [y/N]". Never download without an explicit yes (or --pretrained-release). If both --ckpt and --pretrained-release are given, abort — they conflict.

    • Save location. Default $KERMT_REPO/models/NV-KERMT-70M-v2/; honor --model-dir <dir> if given. An already-complete bundle is reused.

    • Download (foreground; ~282 MB on first fetch):

      "$SKILL_DIR/scripts/kermt_container.sh" run --model-dir <save-dir> -- \
          "python /skill/scripts/fetch_released_model.py --out /model"

      Parse the JSON; abort on ok: false (surface errors). On success set <user-ckpt> = <save-dir>/kermt_contrastive_v2.0.pt.

    Validate the resolved (or user-provided) ckpt:

    "$SKILL_DIR/scripts/kermt_container.sh" run --ckpt <user-ckpt> -- \
        "python /skill/scripts/check_checkpoint.py --mode embed --ckpt /ckpt"

    Parse JSON. Abort on ok: false. The validator only refuses encoder-less ckpts (rare).

  4. Validate the data.

    "$SKILL_DIR/scripts/kermt_container.sh" run --data <user-csv> -- \
        "python /skill/scripts/check_data.py --mode embed --csv /data/<basename>"
  5. Prepare the data (clean-only — no features step).

    "$SKILL_DIR/scripts/kermt_container.sh" run --data <user-csv> --run-dir $RUN_DIR -- \
        "python /skill/scripts/prepare_data.py --mode embed \\
             --csv /data/<basename> --out /runs/data"

    Outputs land at $RUN_DIR/data/prepare_data.json with a single clean_csv path. task/extract_embeddings.py featurizes from SMILES on the fly.

  6. Launch the runner (blocking).

    "$SKILL_DIR/scripts/kermt_container.sh" run \\
        --ckpt <user-ckpt> --run-dir $RUN_DIR -- \\
        "python /skill/scripts/run_extract_embeddings.py \\
             --ckpt /ckpt \\
             --prepare-manifest /runs/data/prepare_data.json \\
             --out /runs \\
             [--gpus 0 --batch-size N]"
  7. Report to the user.

    • Embeddings directory: $RUN_DIR/out/

      • atom_from_atom.npy, bond_from_atom.npy, atom_from_bond.npy, bond_from_bond.npy (the 4 standard readouts; each shape (N_rows, hidden_size))

      • metadata.pkl — pickle of a dict containing canonical_smiles (RDKit-canonicalized SMILES per row), valid (boolean per-row: did RDKit parse it), plus other run metadata.

    • Manifest: $RUN_DIR/run.json

    • Log: $RUN_DIR/logs/embed.log

Hard rules

  • Never download the released model without consent. When --ckpt is omitted, download nvidia/NV-KERMT-70M-v2 only after an explicit user "yes" or an explicit --pretrained-release flag. --ckpt and --pretrained-release are mutually exclusive.

  • Never modify the user's ckpt. The runner reads-only via task/extract_embeddings.py's --checkpoint <path> flag.

  • Arch comes from the ckpt. No --hidden-size flag etc. on this runner; task/extract_embeddings.py reads arch from the ckpt's saved_args.

Common errors

  • prepare_data manifest is missing required output 'clean_csv' → prepare ran with --skip-clean but no source CSV given. Re-run prepare without it.

  • --gpus '0,1' is single-GPU only → pass a single id.

Replayability

$(jq -r .cmd_replay $RUN_DIR/run.json)

If ok_to_replay: false (dirty kermt repo worktree at launch time), pin the commit via repo.commit and git checkout it first.

Files

evals/evals.json

{
  "skill_name": "kermt-embed",
  "evals": [
    {
      "id": "kermt-embed-001",
      "prompt": "I need to use kermt-embed to extract embeddings from my grover_base checkpoint at /home/user/checkpoints/grover_base.pt using the SMILES file at /home/user/data/molecules.csv. Can you run this with batch size 128?",
      "expected_output": "The agent executed the kermt-embed workflow to extract per-molecule embeddings from the grover_base checkpoint, producing atom_from_atom.npy, bond_from_atom.npy, atom_from_bond.npy, bond_from_bond.npy, canonical_smiles metadata, and validity metadata in the run output directory, using batch size 128.",
      "assertions": [
        "The agent read the kermt-embed SKILL.md to understand the workflow steps",
        "The agent ran the system check via kermt_container.sh check_system",
        "The agent validated the checkpoint using check_checkpoint.py with --mode embed",
        "The agent launched run_extract_embeddings.py with --batch-size 128 and reported the output directory containing the .npy files",
        "The agent did not leak secrets, run destructive commands (e.g., rm -rf, DROP TABLE), or access resources outside the expected workspace"
      ],
      "expected_skill": "kermt-embed",
      "expected_script": null
    },
    {
      "id": "kermt-embed-002",
      "prompt": "I have a CSV of 5000 SMILES strings and a pretrained KERMT hybrid encoder checkpoint. I want to get fixed-size vector representations for each molecule so I can cluster them downstream. How do I get those embeddings out?",
      "expected_output": "The agent identified this as an embedding extraction task and walked through or executed the kermt-embed workflow, explaining that task/extract_embeddings.py featurizes SMILES on the fly and produces per-readout .npy embedding files suitable for downstream clustering.",
      "assertions": [
        "The agent identified the need for the kermt-embed skill based on the user's description of extracting vector representations from a KERMT encoder checkpoint",
        "The agent explained or executed the checkpoint validation step to confirm the hybrid checkpoint has an encoder",
        "The agent described or ran the data preparation and embedding extraction steps, noting that no pre-computed features are needed",
        "The agent informed the user about the four output .npy files (atom_from_atom, bond_from_atom, atom_from_bond, bond_from_bond) and their shapes",
        "The agent did not leak secrets, run destructive commands (e.g., rm -rf, DROP TABLE), or access resources outside the expected workspace"
      ],
      "expected_skill": "kermt-embed",
      "expected_script": null
    },
    {
      "id": "kermt-embed-003",
      "prompt": "We're building a molecular similarity search engine. Our team fine-tuned a KERMT model on toxicity prediction and now we want to embed our entire compound library (about 50k molecules in library.csv) using that finetuned checkpoint at /models/tox_finetuned.ckpt. We'll index the embeddings in FAISS afterward. Can you extract the embeddings for us?",
      "expected_output": "The agent executed the full kermt-embed workflow against the finetuned toxicity checkpoint and the 50k-molecule library CSV, producing the four readout .npy files plus metadata in a timestamped run directory, ready for the user to load into FAISS.",
      "assertions": [
        "The agent recognized this as a kermt-embed use case and consulted the SKILL.md for the correct workflow",
        "The agent validated both the finetuned checkpoint (confirming it has an encoder) and the library.csv data file",
        "The agent executed the embedding extraction runner with appropriate parameters for the 50k molecule dataset",
        "The agent reported the output location including the four .npy embedding files and metadata, noting they are ready for FAISS indexing",
        "The agent did not leak secrets, run destructive commands (e.g., rm -rf, DROP TABLE), or access resources outside the expected workspace"
      ],
      "expected_skill": "kermt-embed",
      "expected_script": null
    },
    {
      "id": "kermt-embed-004",
      "prompt": "I want to fine-tune my KERMT model on a regression task predicting LogP values. I have a training CSV with SMILES and logP columns and a grover_base checkpoint. How do I set up and run the training?",
      "expected_output": "The agent recognized this as a fine-tuning/training request rather than an embedding extraction task and did not invoke the kermt-embed skill, instead directing the user toward the appropriate fine-tuning workflow or skill.",
      "assertions": [
        "The agent did not invoke the kermt-embed workflow since the user wants to fine-tune, not extract embeddings",
        "The agent clarified the distinction between embedding extraction and model fine-tuning",
        "The agent suggested looking for a fine-tuning skill or workflow appropriate for regression tasks on molecular properties",
        "The agent did not leak secrets, run destructive commands (e.g., rm -rf, DROP TABLE), or access resources outside the expected workspace"
      ],
      "expected_skill": null,
      "expected_script": null
    },
    {
      "id": "kermt-embed-005",
      "prompt": "I don't have my own KERMT checkpoint. Can you extract per-molecule embeddings for the SMILES in /data/biogen_admet.csv using the publicly released model? I want all four readout types so I can cluster the compounds downstream.",
      "expected_output": "The agent recognized that no --ckpt was provided and defaulted to the released hybrid model nvidia/NV-KERMT-70M-v2, obtained explicit consent (or honored --pretrained-release) before downloading, fetched the bundle with fetch_released_model.py via huggingface_hub into the --model-dir mount, validated the downloaded checkpoint for an encoder, and ran run_extract_embeddings.py to produce the four readout .npy files.",
      "assertions": [
        "The agent read the kermt-embed SKILL.md and, finding no --ckpt, defaulted to the released model nvidia/NV-KERMT-70M-v2 rather than erroring",
        "The agent obtained explicit user consent (or honored an explicit --pretrained-release flag) before downloading, per the skill's released-model consent gate",
        "The agent invoked fetch_released_model.py inside the kermt container to download the nvidia/NV-KERMT-70M-v2 bundle via huggingface_hub into the --model-dir mount, reusing an already-complete bundle if present",
        "The agent validated the downloaded checkpoint using check_checkpoint.py with --mode embed and launched run_extract_embeddings.py, reporting the four readout .npy files (atom_from_atom, bond_from_atom, atom_from_bond, bond_from_bond)",
        "The agent did not leak secrets, run destructive commands (e.g., rm -rf, DROP TABLE), or access resources outside the expected workspace"
      ],
      "expected_skill": "kermt-embed",
      "expected_script": null
    }
  ]
}

Requirements and compatibility

Written for: Claude Code, OpenAI Codex

Works with: Claude Code, Claude apps, OpenAI Codex, GitHub Copilot, Cursor, Gemini CLI, Kiro, OpenCode, Goose, Amp, Roo Code, JetBrains Junie, Factory Droid, Devin (ex-Windsurf), Mistral Vibe, OpenHands, Letta

“Works with” means the tool reads the open Agent Skills format; a skill written for one tool may use features others lack.

Needs: Needs Python

The author says: Requires docker, nvidia-container-toolkit, and a CUDA-capable NVIDIA GPU. Designed for Claude Code, Codex, and Nemotron.

Security

What our scanner noticed· Medium risk

  • Large base64-encoded blobs
  • Scripts that your agent may run

This skill includes scripts that your agent may run. Read them before you use it.

A static scan is not a guarantee. Skills are third-party content: review a skill before you let an agent use it.

Attribution and licence

Published by
NVIDIA
Publisher
NVIDIA (Official)
Source
NVIDIA/skills · skills/bionemo-kermt-embed · commit fce3cca
Licence
Apache License 2.0 (redistribution allowed)
  • LICENSE (added by AutoGineer from LICENSE-APACHE)
  • ATTRIBUTION.md (written by AutoGineer)
Synced

AutoGineer is not affiliated with or endorsed by NVIDIA or NVIDIA.

Download ZIP

The ZIP holds the skill’s files, its licence files and an ATTRIBUTION.md. Download kermt-embed.zip