kermt-embed
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, c
Install
npx skills add https://github.com/NVIDIA/skills/tree/main/skills/bionemo-kermt-embed
claude plugin marketplace add https://llmmart.ai/marketplace.json && claude plugin install nvidia-skills@llmmart
git clone https://github.com/NVIDIA/skills.git
The skills CLI installs just this skill, for any of its supported agents. Claude Code installs the whole nvidia/skills collection as a plugin from our marketplace. Git is the plain clone.
Skill manifest
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):
Parse the JSON; abort on"$SKILL_DIR/scripts/kermt_container.sh" run --model-dir <save-dir> -- \ "python /skill/scripts/fetch_released_model.py --out /model"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).- Consent gate. Unless
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.json - Log:
$RUN_DIR/logs/embed.log
- Embeddings directory:
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 (skills)
-
config
-
defaults_embed.json 718 B
Loading… -
released_model.json 398 B
Loading…
-
-
evals
-
evals.json 6.8 KB
Loading…
-
-
references
-
released-models.md 1.6 KB
Loading…
-
-
scripts
-
check_checkpoint.py 20.1 KB
Loading… -
check_data.py 11.9 KB
Loading… -
fetch_released_model.py 7.9 KB
Loading… -
kermt_container.sh 18.9 KB
Loading… -
prepare_data.py 36.5 KB
Loading… -
run_extract_embeddings.py 8.8 KB
Loading… -
_utils.py 14.1 KB
Loading…
-
-
BENCHMARK.md 7.6 KB
Loading… -
skill-card.md 4.2 KB
Loading… -
SKILL.md 7.5 KB
--- name: kermt-embed description: 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. license: Apache-2.0 compatibility: Requires docker, nvidia-container-toolkit, and a CUDA-capable NVIDIA GPU. Designed for Claude Code, Codex, and Nemotron. metadata: owner: evax@nvidia.com classification: workflow-skill risk_tier: skill # Line/token budget: targets ~150 lines / ~1800 tokens — within the # 500-line / 5000-token cap for skill files. --- # 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](references/released-models.md) 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 ```bash $(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. -
skill.oms.sig 6.8 KB · in bundle
Comments (0)
Sign in to join the conversation.
Reviews (0)
No reviews yet.
No comments yet.