Return the canonical workflow + operating rules. Call once at the start.

Report what is mapped vs pending and suggest the next tool(s).

Load raw names (list OR an xlsx column), normalize, and seed the ledger.

Flags entries the LLM should look at: parenthetical abbreviations, combined names, and isomer-sensitive digit locants (never auto-substitute those).

MetaboAnalyst batch name->ID. Exact DB-name matches are a lookup, not a judgement: with auto_accept_exact they are committed at confidence M1 (KEGG/HMDB/structure by what resolves); everything non-exact stays pending for the LLM.

PubChem: name -> CID / InChIKey / formula / monoisotopic mass. Attaches evidence.

Search KEGG / PubChem / ChEBI for LLM-proposed query strings (abbrev expansions, typo fixes, synonyms). Returns candidates; the LLM picks + verifies. Never auto-accepts.

Promote ids across systems via BridgeDb (batch; DB loads once).

Each query: {id, source, targets:[...], feature_id?}. source/target in {kegg,hmdb,chebi,pubchem,inchikey}. If feature_id + workdir are given, bridged ids are attached to that entry as a 'bridgedb' candidate.

Deterministic formula/mass consistency gate (molmass). Passing this is required before accepting any fuzzy/synonym/mass-only candidate. Optionally logs to the ledger.

m/z + adduct -> neutral monoisotopic mass windows (weak evidence). Hand the window to search_synonym / a DB search; never accept a mass-only hit as primary.

Deterministic NON-biological (xenobiotic) screen: LC-MS additives / surfactants / plasticizers / industrial reagents. EMITS evidence only. This lexicon detects the xenobiotic → xenobiotic-excluded classes; it deliberately does NOT flag biologically exogenous compounds (diet/drug/microbial/plant → the KEPT 'exogenous' class) because those require reasoning-layer judgement. Surfaces xenobiotic-class names that are still kept in the analysable set so the driver can reclassify them as xenobiotic-excluded.

Commit the LLM's identity CALL for one entry — the ONLY tool that sets final_class/confidence/origin. origin is the compound's PROVENANCE and, for non- endogenous compounds, decides the class:

• BIOLOGICAL but from outside the host -> origin in {diet, drug, microbial, plant}; final_class='exogenous' (KEPT + tagged; it is a real signal, may carry KEGG/HMDB IDs).

• NON-biological / technical -> origin in {contaminant, industrial, additive, surfactant, plasticizer, reagent}; final_class='xenobiotic-excluded' (dropped from analysis).

• host-produced -> origin='endogenous' (default for KEGG/HMDB/structure-only mappings).

For an exclusion pass final_class='xenobiotic-excluded' (or 'unmapped') with accepted={}; origin is auto-suggested from the contaminant lexicon when omitted.

Bridge missing HMDB for every non-excluded entry lacking an accepted HMDB, using its available ids (InChIKey/KEGG/ChEBI/PubChem) via BridgeDb in ONE batched call, then accept.

Reflects the run-2 finding that HMDB rides along with KEGG matching and is under-counted; this maximizes HMDB coverage. Does not touch KEGG assignments or the final_class/origin of KEGG-mapped or exogenous entries (HMDB is added as an extra xref); a structure-only entry that gains HMDB → HMDB-mapped. xenobiotic-excluded entries are skipped.

Map accepted KEGG/HMDB/ChEBI ids to Mouse-GEM MAM species (flux input). Sets gem_mam + gem_cause ('id-gap' when it has ids but the GEM lacks the xref).

Recovery provenance for the report: what was mapped to KEGG / HMDB BEYOND the MetaboAnalyst 1st pass and by which logic, plus the unmapped (harmonized-name-tried, reason) and the two origin buckets. Writes kegg_recovered.tsv, hmdb_recovered.tsv, unmapped_harmonization.tsv, exogenous_kept.tsv (biological outside-host, KEPT + origin), and xenobiotic_excluded.tsv (non-biological contaminant, EXCLUDED + origin).

Append the final ID-result columns to the ORIGINAL data file — the intensity matrix keeps all its columns and gains ID_final_class / ID_confidence / ID_kegg / ID_hmdb / ID_chebi / ID_pubchem / ID_inchikey / ID_gem_mam per compound (matched by name).

Uses the source recorded by ingest_names if source is omitted. header is the 0-based header row (some vendor sheets have a preamble row, e.g. header=1). Writes _annotated .xlsx + .tsv into the workdir.

Always-on DB-matching figures: figures/db_matching_upset.png (5-DB UpSet + enriched_xref.tsv) and figures/db_matching_improvement.png (MetaboAnalyst baseline vs current logic).

Write standalone reproduction code that reproduces the run using the ORIGINAL library APIs (MetaboAnalystR/BridgeDbR/KEGGREST via Rscript, PubChem PUG-REST, molmass, COBRApy, matplotlib) — NOT the tool wrappers. Emits both code/reproduce_mapping.py (flow-based, reads the saved ledger) and code/reproduce_mapping.ipynb (same flow unrolled into linear cells, no def, with detailed input/output/reuse comments per cell).

Build a PPTX report from the run's outputs + figures (Title · Coverage KPI · Methods · Pipeline · UpSet · Improvement · Recovery cause→fix · KEGG/HMDB recovered · Unmapped · Exogenous · Outputs). Reads coverage_summary.tsv + provenance tsvs + figures; run coverage_summary first. Requires python-pptx + pillow.

Compute class/confidence coverage and (optionally) write the master ledger tsv, coverage tsv, and provenance tsv. With figures=True (default) ALWAYS emits the db_matching_upset + db_matching_improvement figures + enriched_xref.tsv.

GOVERNANCE / process-completeness auditor (read-only, no identity judgement): reads the session ledger + workdir artifacts and checks that the reasoning layer actually HONORED metabo-idmapper's OWN contract — no fabricated ID, no mass-only (W) candidate used as primary, final_class↔confidence coherent, fuzzy (M2/M3) accepts carry formula/mass verification, locant/anomer-sensitive names re-checked, xenobiotic-exclusion applied consistently, origin↔class coherent (exogenous kept vs xenobiotic excluded), flagged auto-accepts reviewed, id-gap KEGG re-tried, every CALL has a rationale, no entry left pending, gem_crosswalk ran, and the stage-7 always-emit artifacts exist. Emits a per-check pass/warn/fail scorecard so 'rules defined but not followed' is caught. Changes nothing. Run LAST (after coverage_summary).