PathwaySeeker checks each step of a metabolic pathway proposed by an AI assistant against a reaction graph built from an organism's proteomics and metabolomics data.
Language models can propose plausible metabolic pathways, but they cannot tell which steps are consistent with measurements from a particular organism. PathwaySeeker builds a graph of KEGG reactions linked to the enzymes and metabolites detected in the data, and labels each step of the routes an assistant proposes:
- Solid green steps match a reaction in the graph that is linked to a detected enzyme (through its KEGG Orthology annotation) or to a detected metabolite. This is consistent with the data; it does not show that the reaction occurs.
- Orange dashed steps were not found in the graph. They are not ruled out and are candidates for experimental testing.
In the output, a found step is labeled GRAPH_PATH when every step of its route was found,
and GRAPH_FACT when the route is a single step or also contains steps not found. Steps not
found are labeled HYPOTHESIS.
Graphs are stored and queried locally. Building a graph, and naming compounds that are not in the graph, uses the KEGG REST API. Questions and results are sent to the assistant you use and count toward your usage of that service. PathwaySeeker provides a skill for Claude Code and Codex and an MCP server. The command line and MCP tools are tested; end-to-end use inside Claude Code and Codex has not yet been tested.
To have an assistant install it, paste this into Claude Code or Codex (assistant-driven setup has not yet been tested end to end):
Set up PathwaySeeker from https://github.com/pnnl/PathwaySeeker by following its AGENTS.md, then run the demo.
Or do it yourself:
pip install "pathwayseeker[mcp] @ git+https://github.com/pnnl/PathwaySeeker"
pathwayseeker setup # installs the skill for Claude Code and Codex
pathwayseeker demo # labels an example answer on the included graph and opens itStart a new Claude Code or Codex session and ask, for example:
Using the tversicolor graph, what connects phenylalanine and 4-hydroxybenzoate? Show me the pathway.
tversicolor is the Trametes versicolor graph from the paper, included for testing.
| Location | |
|---|---|
| Training data (16,422 examples) | data/training/training_v3.jsonl.gz, with a readable sample and its composition |
| Evaluation queries (64) | evals/queries/: 60 sampled compound pairs and 4 case studies |
| Grader (LLM judge prompt and rubric) | evals/grader/judge_prompt_and_rubric.md |
| Results and logs | evals/results/; python evals/table1.py recomputes Table 1 without API calls |
| Graph used for training and evaluation | src/pathwayseeker/data/tversicolor/ |
Details are in evals/README.md.
| Folder | Contents |
|---|---|
src/pathwayseeker/ |
Python package: graph builder, graph queries, command line, MCP server |
skills/pathwayseeker/ |
Skill for Claude Code and Codex |
data/ |
T. versicolor input tables (raw/), pipeline outputs (output/) and training data (training/) |
evals/ |
Evaluation queries, grader, results and the Table 1 script |
analysis/ |
Original analysis code, unchanged: graph-construction scripts, notebooks and their outputs, thermodynamic analyses (MDF/), and the Rhodosporidium toruloides graph (not evaluated) |
pathway_viz/ |
PathwayViz, an interactive pathway map with per-condition abundance charts |
docs/, examples/, tests/ |
Documentation and images, a Python example, and tests |
pathwayseeker build is a packaged version of the analysis/multiomics_graph/ pipeline;
docs/PROVENANCE.md maps each original script to its package module.
Tell your assistant where your files are:
Build a PathwaySeeker graph called myorg from proteins.xlsx, ko.txt and metabolites.xlsx.
| File | What it contains |
|---|---|
Proteomics table (.xlsx or .csv) |
One row per protein, with a proteinID column |
KO annotation (.txt) |
Tab-separated protein ID, KEGG Orthology (KO) number and description, no header. Make it with KAAS, GhostKOALA or eggNOG-mapper. |
Metabolomics table (.xlsx or .csv) |
Metabolite names in the first column, or KEGG compound IDs in a KEGG_C_number column |
The first build downloads reaction data from KEGG; it took about 20 minutes in our tests and
can take a few hours for larger datasets or when KEGG responds slowly. Later builds reuse the
downloads. Metabolite names are matched to KEGG by taking the first search result, so some
matches will be wrong and some names will not match (they are listed in
unmatched_metabolites.txt). The published graph used manually curated matches; review the
matches before using the results.
Graphs are stored in ~/.pathwayseeker/graphs/<name>/. Saved answers are written to the
graph's answers/ folder (for the built-in graph, ~/.pathwayseeker/answers/tversicolor/) as
a JSON record and a pathway picture. pathwayseeker show opens the
latest one and pathwayseeker show --network opens the whole graph. Saved answers are a
record only; they are not fed back into later conversations.
The graph is built in eight steps. Each step writes a table, so the pipeline can be inspected or resumed at any point.
| Step | What it does | Output |
|---|---|---|
| 1 | Attach KEGG Orthology (KO) numbers to the proteomics table | proteomics_with_ko.csv |
| 2 | Retrieve the KEGG reactions of each KO | ko_to_reactions.csv |
| 3 | Record the first substrate and first product of each reaction | reaction_to_compounds_no_cofactors.csv |
| 4 | Match metabolite names to KEGG compound IDs | metabolomics_with_C_numbers.xlsx |
Manual curation: correct the matches and save the file as metabolomics_with_C_numbers_curated.xlsx |
||
| 5 | Retrieve the KEGG reactions of each detected metabolite, with its role (substrate or product) | reaction_to_compounds_from_metabolomics.csv |
| 6 | Merge the proteomics and metabolomics reactions, recording the evidence for each | matched_metabolites_reactions_all.csv |
| 7 | Add the balanced KEGG equation of each reaction | matched_metabolites_reactions_all.csv |
| 8 | Build the graph and an interactive view | graph_all.html, graph_all.json |
Manual curation between steps 4 and 5 is recommended: automatic matching takes the first KEGG search result. The pipeline can be run in two ways.
From the command line (script mode). pathwayseeker build runs all eight steps; it is the
packaged version of the scripts in analysis/multiomics_graph/. To curate,
stop after step 4, edit the table, and resume:
pathwayseeker build --name myorg --proteomics proteins.xlsx --ko-definitions ko.txt \
--metabolomics metabolites.xlsx --stage before
# correct ~/.pathwayseeker/graphs/myorg/metabolomics_with_C_numbers.xlsx and save it as
# metabolomics_with_C_numbers_curated.xlsx in the same folder, then:
pathwayseeker build --name myorg --proteomics proteins.xlsx --ko-definitions ko.txt \
--metabolomics metabolites.xlsx --stage afterWith the original notebooks (exploratory mode), in analysis/notebooks/:
conda create -n pathseeker python=3.11
conda activate pathseeker
pip install -r analysis/requirements.txt
python -m ipykernel install --user --name=pathseeker --display-name "Python (pathseeker)"
jupyter labFor proteomics and metabolomics data, open
analysis/notebooks/multiomics_graph_proteomics&metabolomics.ipynb; for proteomics (or
transcriptomics) data only, open analysis/notebooks/multiomics_graph_only_proteomics.ipynb.
Run the cells in order. The first notebook reads the T. versicolor tables in data/raw/;
the second expects your files at data/proteomics.xlsx and data/user_ko_definition.txt.
Both write their outputs to analysis/output/.
The graph can be viewed in a web browser or embedded in Jupyter, and the JSON file can be loaded into
PathwayViz (pathway_viz/) for interactive pathway maps with abundance charts
per condition. Thermodynamic feasibility of selected pathways (Max-min Driving Force with
eQuilibrator) is analyzed in analysis/MDF/; install its dependencies with
pip install -e ".[thermo]".
from pathwayseeker import Oracle, resolve_graph
graph = Oracle.from_dir(resolve_graph("tversicolor"))
graph.find_compound("ferulate") # names to KEGG IDs
graph.path_search("C00079", "C01494") # routes in the graph
graph.label_pathway(["C00079", "C00423", "C00811", "C00156"]) # label each step- pathway_viz/: PathwayViz, an interactive pathway map with abundance bar charts per condition.
pathwayseeker --helplists every command, includingask, which sends questions directly to an OpenAI, Azure or Anthropic model (requires an API key; not yet tested against live models in this release).
- Only the T. versicolor graph has been evaluated.
- The graph pools all experimental conditions; it is not specific to any one condition.
- A KEGG Orthology annotation indicates enzymatic capability, not activity or substrate specificity. Reactions linked to a detected metabolite are included whether or not the catalyzing enzyme was detected.
- For reactions added through proteomics, only the first compound on each side of the KEGG equation is linked, so some conversions catalyzed by detected enzymes are not found (for example, D-glucose to D-glucose 6-phosphate, R01786).
- Step direction follows the order in which KEGG writes each equation, not the direction in the cell; a step can be found in one direction and not in the reverse.
- Automatic metabolite-to-KEGG matching is error-prone and should be reviewed.
- The fine-tuned model described in the paper is not distributed.
- End-to-end use inside Claude Code and Codex has not yet been tested.
- Building a graph queries the KEGG REST API, which KEGG provides for academic use; other users should review the KEGG terms. Third-party components are listed in THIRD_PARTY_NOTICES.md.
If you use PathwaySeeker, please cite:
Monteiro, L.M.O., Chowdhury, N.B., Oostrom, M.T., McDermott, J.E., Stratton, K.G., Choudhury, S. and Bardhan, J.P. (2026). PathwaySeeker: Evidence-Grounded AI Reasoning over Organism-Specific Metabolic Networks. bioRxiv. https://doi.org/10.64898/2026.04.14.718256
@article{monteiro2026pathwayseeker,
title={PathwaySeeker: Evidence-Grounded AI Reasoning over Organism-Specific Metabolic Networks},
author={Monteiro, Lummy MO and Chowdhury, Niaz B and Oostrom, Marjolein T and McDermott, Jason E and Stratton, Kelly G and Choudhury, Sutanay and Bardhan, Jaydeep P},
journal={bioRxiv},
year={2026},
doi={10.64898/2026.04.14.718256},
publisher={Cold Spring Harbor Laboratory},
url={https://www.biorxiv.org/content/10.64898/2026.04.14.718256v1}
}- Lummy M. O. Monteiro - multi-omics and graph construction
- Marjolein T. Oostrom - metabolomics validation
- Niaz Bahar Chowdhury - thermodynamic validation
- Sutanay Choudhury - AI methods
This research was supported by the Environmental Molecular Sciences Laboratory, a DOE Office of Science User Facility sponsored by the Biological and Environmental Research program under Contract No. DE-AC05-76RL01830.
This material was prepared as an account of work sponsored by an agency of the United States Government. Neither the United States Government nor the United States Department of Energy, nor Battelle, nor any of their employees, nor any jurisdiction or organization that has cooperated in the development of these materials, makes any warranty, express or implied, or assumes any legal liability or responsibility for the accuracy, completeness, or usefulness or any information, apparatus, product, software, or process disclosed, or represents that its use would not infringe privately owned rights.
Reference herein to any specific commercial product, process, or service by trade name, trademark, manufacturer, or otherwise does not necessarily constitute or imply its endorsement, recommendation, or favoring by the United States Government or any agency thereof, or Battelle Memorial Institute. The views and opinions of authors expressed herein do not necessarily state or reflect those of the United States Government or any agency thereof.
PACIFIC NORTHWEST NATIONAL LABORATORY
operated by
BATTELLE
for the
UNITED STATES DEPARTMENT OF ENERGY
under Contract DE-AC05-76RL01830
BSD 2-Clause (Battelle Memorial Institute)
Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:
-
Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
-
Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.
THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.