boltz-small-molecule-adme

name	boltz-small-molecule-adme
description	Predict Tier-1 ADME/ADMET for small molecules with Boltz from bare SMILES — no target, no docking. Use when the user wants solubility, permeability, or lipophilicity/logD for a molecule or list of molecules. Not for ranking molecules against a protein target (use boltz-small-molecule-screen, which already returns ADME free).

Workflow

If boltz-api reports missing or expired authentication, surface the error to the user. Do not attempt to re-authenticate; the host environment must provide BOLTZ_API_KEY.

Use this skill for standalone ADME triage on SMILES the user already has. No protein target is involved. If the user is also screening or docking those molecules against a target, prefer boltz-small-molecule-screen — it returns the same ADME block free as part of the screen.

1. Normalize the molecules from raw SMILES, a CSV (auto-detect the SMILES column), .smi, or .txt into the molecules list. Each entry is {smiles, id?}; the optional id is echoed back as external_id on each result so you can map results to inputs.
2. Hard cap: 128 molecules per request. If the list exceeds 128, split into batches of ≤128 and submit one request per batch (suffix the run name, for example -b1, -b2), then merge results. Never send more than 128 in one call — the API rejects it with VALIDATION_ERROR: input.molecules must contain at most 128 items.
3. Author the payload YAML or JSON.
4. run to submit and wait — ADME finishes in seconds, so it is synchronous and needs no background polling. run persists results locally under --root-dir/<run-name>/.
5. Report from <output-root>/<run-name>/run.json → output.molecules[]. For each molecule show external_id (or smiles), solubility, permeability, and lipophilicity. The three values live under each molecule's adme object. Call out any molecule with status: failed and its error (an object {code, message}, e.g. code adme_enumeration_failed, message Invalid SMILES) — adme is null there; one bad SMILES fails only that molecule, not the batch. Read references/results.md for the output layout and references/api.md for the payload and batching details.

ADME values are approximate estimates for triage and ranking, not absolute measurements.

Command Pattern

# Replace placeholders with concrete absolute paths before running.
# Use a short descriptive run name, for example: adme-<library>-v1

# `run` is synchronous (submit + wait + persist) and finishes in seconds — no background mode needed.
boltz-api predictions:adme run \
  --model adme-v1 \
  --idempotency-key "<run-name>" \
  --input @yaml:///absolute/path/payload.yaml \
  --name "<run-name>" \
  --root-dir "/absolute/path/boltz-experiments" \
  --poll-interval-seconds 5
# -> /absolute/path/boltz-experiments/<run-name>/run.json  (output.molecules[].adme)

Payload is just a molecules list — the API body field name, not the direct CLI flag. --model adme-v1 is required.

Always Do This

• Keep payload field names exactly as the API body names shown in references/api.md (molecules, each {smiles, id?}).
• Pass --model adme-v1 on every estimate-cost, run, and start.
• Enforce the 128-molecule-per-request cap. Chunk larger libraries into ≤128 batches and submit each as its own run; merge the per-batch run.json outputs when reporting.
• Use absolute paths for the output root and payload files. Do not cd into the run directory; pass the same --root-dir and use absolute paths so later relative paths do not drift.
• Prefer one merged top-level payload via --input @yaml:///absolute/path/payload.yaml or @json:///absolute/path/payload.json. Keep --model, --idempotency-key, and --workspace-id top-level. Never use @file:// or @./.
• Use the same slug as both --idempotency-key and --name so re-runs resume via .boltz-run.json.
• Keep each Boltz call as a top-level command that starts with boltz-api. Prefer concrete arguments over sh -c, inline environment assignments, aliases, wrapper scripts, loops, or pipelines unless the user already allowed that exact command form.
• ADME run is synchronous and finishes in seconds, so unlike the screen/design endpoints it needs no background/non-blocking mode.
• Do not require or accept a protein target — ADME is structure-free. If the user wants ADME and binding against a target, redirect to boltz-small-molecule-screen.

Escape Hatch

• Payload reference: https://api.boltz.bio/docs/api/resources/predictions/subresources/adme/methods/start/
• Guide: https://api.boltz.bio/docs/guides/small-molecule-adme/
• CLI flag names: boltz-api predictions:adme run --help

Read references/api.md for the molecules payload shape, the per-molecule output fields, the 128-molecule cap, and error handling.

Outputs

Read <output-root>/<run-name>/run.json and report output.molecules[]. There are no structure files — ADME returns scalar/categorical values only. Read references/results.md for the local layout and per-molecule output fields; references/api.md has the full request/response schema.