metabolomics-workflow-router

Use when a user has a whole metabolomics analysis GOAL (e.g. "annotate my untargeted LC-MS/MS data", "find biomarkers", "where else has this molecule been seen") rather than a single step — select the

SKILL.md

GitHub

ASB Metabolomics — composite workflow router

This is the goal-level entry point for the ASB Metabolomics collection. Where the leaf router (metabolomics-collection-router) finds ONE atomic skill, this router selects an end-to-end composite workflow super-skill — an ordered pipeline of stages, each delegating to vetted leaf skills, with grounding and a declarative workflow.yaml.

Use it in three steps: select → run → ground.

1. Select — match the goal to a workflow

Prefer semantic retrieval (P2): run

python bin/semantic_search.py --query "<the user's goal>" \
  --collection . --target workflows [--technique LC-MS] --k 3

It uses meaning-based ranking (text-embedding-3-large — the same model Perspicacité uses) when an embedding backend is available, and falls back to a keyword index search automatically when it is not, so it always works offline. The result's mode field tells you which ran. The same tool works at the leaf level with --target skills (Step 2).

If you prefer manual lookup, load workflows_index.json (one row per composite workflow: slug, name, description, techniques, stages, member_tools) and match the goal, in order of precision:

  1. Technique — what platform is the data? LC-MS, GC-MS, MS-imaging, ion-mobility-MS, NMR. Filter techniques first.
  2. Goal phrasing — match the user's intent against each row's description.

Available workflows (published as outlines):

workflow technique what it does
untargeted-lcmsms-annotation LC-MS raw mzML → preprocess → network → library-match → SIRIUS → fuse → master table
lipidomics-lcms-annotation LC-MS class/species-level lipid annotation + stats
gcms-deconvolution-and-identification GC-MS EI deconvolution → library match → retention index → stats
ms-imaging-spatial-metabolomics MS-imaging imzML → spatial annotation (FDR) → segmentation → region stats
statistics-and-biomarker-discovery LC-MS normalize → multivariate → differential → pathway → biomarkers
sirius-denovo-structure-elucidation LC-MS formula → structure → class → confidence filter (no library needed)
masst-repository-scale-search LC-MS reverse metabolomics: where else does this molecule occur in public data
ion-mobility-4d-annotation ion-mobility-MS 4D feature extraction → CCS calibration → CCS-aware annotation
nmr-metabolomics-profiling NMR spectra → preprocess → identify (chemical shift) → quantify → stats
pathway-functional-analysis LC-MS m/z feature list → mummichog → pathway/enrichment → interpretation

If no workflow fits the goal, fall back to the leaf router (metabolomics-collection-router) and assemble steps from atomic skills.

2. Run — execute the workflow's stages

Read the chosen workflows/<slug>/SKILL.md and follow its Stages in order. Each stage carries: a goal, candidate leaf skills (primary first), the tools to install/invoke, and its typed inputs/outputs. The machine-readable workflows/<slug>/workflow.yaml is the DAG (after, inputs_from). Automatic grading of that DAG (asb solve-workflow) is not part of this release: no released ASB version loads these files, so run the stages yourself. Honor the I/O contract: each stage consumes the prior stage's declared outputs. Optional stages are marked.

For a stage's leaf skills, read each skills/<leaf-slug>/SKILL.md for the procedure, or use the leaf router to pick among the candidates for your exact data.

3. Ground — verify each stage against its source papers

Before trusting a parameter or default, ground the stage's leaves against the papers they were distilled from. Each stage's grounding.kb_slugs/dois (in workflow.yaml) point at the asb-paper-<doi> KBs. Use the collection's /ground command or bin/perspicacite_kb_bind.py (Perspicacité KB; serverless local-clone fallback).

These workflows are published as outlines: the stage structure is validated, the execution is not. Bindings were chosen by semantic retrieval (text-embedding-3-large) + deterministic selection. derived_from_workflows in each frontmatter is a provenance record; no ablation experiment consuming it is released.