Kermt Embed
NVIDIAOfficialPublished by NVIDIA
- Skill
- Workflow
- Science and research
- Apache-2.0
- Medium risk
- Has scripts
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
Download the skill as a ZIP:
https://autogineer.com/agent-skills/nvidia/kermt-embed/downloadUnzip 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 800per readout, so ~10–20 MB per 1k molecules across the 4 readouts. Plus a smallcanonical_smiles.npy+validity.npyper run.Driver / CUDA: any host supporting CUDA 12.6.
Inputs
Required:
--csv <path>— SMILES CSV. First column issmiles; 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 existingprepare_data.jsonin<dir>.
Workflow
Let $KERMT_REPO be the path to your kermt repo checkout.
Pre-flight: container + system probe.
"$SKILL_DIR/scripts/kermt_container.sh" check_systemCompute run directory.
RUN_DIR=$KERMT_REPO/runs/embed_$(date -u +%Y-%m-%dT%H-%M-%SZ)Resolve & validate the checkpoint.
Resolve — only if
--ckptwas omitted. Default to the released pretrained hybrid model nvidia/NV-KERMT-70M-v2:Consent gate. Unless
--pretrained-releasewas 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--ckptand--pretrained-releaseare 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(surfaceerrors). 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).Validate the data.
"$SKILL_DIR/scripts/kermt_container.sh" run --data <user-csv> -- \ "python /skill/scripts/check_data.py --mode embed --csv /data/<basename>"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.jsonwith a singleclean_csvpath.task/extract_embeddings.pyfeaturizes from SMILES on the fly.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]"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 containingcanonical_smiles(RDKit-canonicalized SMILES per row),valid(boolean per-row: did RDKit parse it), plus other run metadata.
Manifest:
$RUN_DIR/run.jsonLog:
$RUN_DIR/logs/embed.log
Hard rules
Never download the released model without consent. When
--ckptis omitted, downloadnvidia/NV-KERMT-70M-v2only after an explicit user "yes" or an explicit--pretrained-releaseflag.--ckptand--pretrained-releaseare 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-sizeflag etc. on this runner;task/extract_embeddings.pyreads arch from the ckpt's saved_args.
Common errors
prepare_data manifest is missing required output 'clean_csv'→ prepare ran with--skip-cleanbut 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
- ATTRIBUTION.mdAdded by AutoGineer829 B
- BENCHMARK.md7.6 KiB
- LICENSELicence file added by AutoGineer11.2 KiB
- SKILL.md7.5 KiB
- config/defaults_embed.json718 B
- config/released_model.json398 B
- evals/evals.json6.8 KiB
- references/released-models.md1.6 KiB
- scripts/_utils.pyScript14.1 KiB
- scripts/check_checkpoint.pyScript20.1 KiB
- scripts/check_data.pyScript11.9 KiB
- scripts/fetch_released_model.pyScript7.9 KiB
- scripts/kermt_container.shScript18.9 KiB
- scripts/prepare_data.pyScript36.5 KiB
- scripts/run_extract_embeddings.pyScript8.8 KiB
- skill-card.md4.2 KiB
- skill.oms.sig6.8 KiB
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