MetaboT: an LLM-based multi-agent framework for interactive analysis of mass spectrometry metabolomics knowledge graphs

Abstract

Mass spectrometry-based metabolomics generates complex, high-dimensional data that holds vast potential for biological discovery but remains difficult to integrate and interpret. Knowledge graphs (KGs) unify this heterogeneous information by representing spectra, annotations, taxa, chemical classes, and biological activities as a single interoperable network; however, their practical use is limited by the steep learning curve of corresponding specialized representation and query languages. Here we introduce MetaboT, an open-source multi-agent Large Language Model (LLM) framework that translates natural-language questions into executable SPARQL queries over metabolomics knowledge graphs. MetaboT is designed to mitigate the hallucination and schema-compliance limitations of single-model approaches through a modular architecture in which specialised agents handle scope validation, entity resolution against authoritative resources, schema-aware query generation, iterative refinement, and result interpretation. We validated MetaboT on the Experimental Natural Products Knowledge Graph (ENPKG), using an expert-authored benchmark of natural-language questions paired with reference SPARQL queries, and demonstrate its ability to answer complex questions about plant–metabolite relationships and biological activities, achieving 83.67% accuracy versus 8.16% for a single-shot baseline and reducing schema-mismatch errors to a single residual case in our benchmark. MetaboT lowers the technical barrier for metabolomics researchers and enables semantic data mining without specialised programming expertise.

Scientific contribution

MetaboT introduces a multi-agent LLM architecture that grounds each step of natural-language-to-SPARQL translation in authoritative identifier resolution and schema-aware validation, substantially reducing the hallucinations observed with single-model baselines. The framework couples orchestrated agents with domain-specific tools for chemical, taxonomic, and biological target resolution, and with an iterative refinement loop that distinguishes query-construction errors from genuine data absence. Released as open-source software with an archived evaluated version, a reusable benchmark, and a public web demonstrator, MetaboT provides a reproducible reference implementation for knowledge-graph-driven exploration of mass spectrometry metabolomics data.

Graphical abstract

Supplementary Information

The online version contains supplementary material available at https://doi.org/10.1186/s13321-026-01257-8.

Introduction

Contemporary mass spectrometry-based metabolomics generates unprecedented volumes of spectral data, with a single untargeted experiment routinely producing thousands of fragmentation spectra [1]. While these raw data contain vast potential for discovery, they remain uninformative without extensive computational processing [1]. Over the past decade, the community has developed a rich ecosystem of open-source frameworks that streamline spectral data processing and annotation, including MZmine [2], SIRIUS [3], GNPS [4], and OpenMS [5]. Yet the complexity and volume of metabolomics data continue to demand advanced expertise in statistical analysis, programming, data engineering, and visualisation, ultimately constraining researchers’ ability to extract deeper biological insights [6].

Untargeted metabolomics of natural products typically relies on liquid chromatography coupled to tandem mass spectrometry (LC-MS/MS) [6]. Liquid chromatography first separates the complex mixture of metabolites in an extract; as compounds elute, electrospray ionisation transfers them to the gas phase and a first stage of mass analysis (MS1) records their intact precursor masses. Selected precursor ions are then fragmented, and a second stage of analysis (MS2) records the resulting fragment spectra—the tandem-MS (MS/MS) step. These fragmentation spectra act as structural fingerprints that enable putative compound annotation through spectral library matching and in silico tools, and they are the primary evidence that, together with taxonomic and bioactivity data, is integrated into metabolomics knowledge graphs such as ENPKG [7] and MetaboKG [8]. MetaboT operates on this integrated graph rather than on the raw spectra themselves.

Over the past decade, molecular networking has democratised mass spectra exploration by enabling researchers from diverse backgrounds to intuitively map structural relationships among metabolites through graph-based comparison of fragmentation spectra [4]. More recently, knowledge graphs have emerged as the next frontier in the field, semantically integrating metabolites, pathways, taxa, and biological activities into an interoperable framework [7, 9, 10]. These graphs rely on domain-specific ontologies that provide standardised vocabularies, including concepts and relation hierarchies, essential for consistent data integration across different experimental platforms. Despite their potential, knowledge graphs and their underlying ontologies remain underutilised, because of the steep learning curve associated with representation languages such as RDF and query languages such as SPARQL, as well as the complexity of mastering domain-specific ontological frameworks. These technical barriers require in-depth understanding of the data graph model, its query syntax, and the underlying schema that defines its structure, constraints, and semantics—significantly limiting accessibility for many researchers [11, 12].

Recent advances in generative AI using Large Language Models (LLMs) have shown promising results in automating SPARQL query generation [11, 13–15] and in enabling knowledge-graph construction through tools such as BioCypher [16]. However, LLMs still suffer from critical limitations. In particular, they are prone to hallucinations, generating incorrect identifiers or properties and thereby corrupting query construction [15]. Their performance is also heavily dependent on access to detailed schema information and precise entity identifiers, which has so far limited their standalone applicability in complex metabolomics contexts. Supplementing LLMs with tools such as retrieval-augmented generation (RAG) pipelines, schema parsers, specialised entity-resolution modules, or integrated frameworks such as BioChatter and ExpasyGPT [14, 17] can reduce dependency on schema memorisation, yet these approaches still demand complex, schema-specific integration and may hallucinate identifiers because of limited orchestration. Emerging evidence shows that SPARQL generation improves markedly with chain-of-thought prompting [18] and role-based specialised-agent orchestration [19].

To overcome these hurdles—and to harness the power of chain-of-thought prompting and role-based agent orchestration—we developed MetaboT, a multi-agent LLM framework that decomposes complex metabolomics knowledge-graph queries into discrete subtasks, routes each to a specialist agent, and thereby delivers precise entity resolution, schema-aware SPARQL generation, and fewer hallucinations than a single-LLM baseline, quantified in our error analysis (Section Query-construction error analysis). MetaboT enables researchers to query a metabolomics knowledge graph through an intuitive conversational interface (Fig. 1a). It resolves entity identifiers through orchestrated resolution steps to prevent hallucinations, leverages knowledge-graph schemas, and translates natural-language questions into SPARQL queries adapted to the specific schema of the targeted graph. MetaboT is released as open-source software under the Apache 2.0 license, with an archived evaluated version, a reusable benchmark, and a public web demonstrator, and constitutes the founding proof-of-concept prototype of the MetaboLinkAI programme (https://www.metabolinkai.net) for open AI-assisted metabolomics.

Fig. 1.

MetaboT overview. a A user’s natural-language question is translated into a SPARQL query and executed against the mass spectrometry knowledge graph, returning the final answer. b Detailed schematic of the multi-agent architecture, highlighting specialised agents and tools for entity resolution, query validation, and result interpretation. The “SPARQL Agent” in the figure corresponds to the SPARQL Query Runner Agent described in the main text

Implementation

MetaboT is implemented as a modular, multi-agent pipeline designed to manage the complexities of natural-language-to-SPARQL translation (Fig. 1b). The system orchestrates tasks through a hierarchy of specialised agents and supporting tools, built on top of LangChain [20] (v0.3.27) and LangGraph [21] (v0.3.34). LangChain provides a flexible framework for developing LLM-based applications, with standard components for LLM calls, prompts, chains, and tool-using agents. LangGraph structures the workflow as a stateful directed graph, where nodes represent discrete computational steps and edges represent message passing between agents. This stateful graph enables dynamic state evolution as each agent completes its task, allowing for adaptive interactions throughout the query-processing pipeline. Formally, each agent in the workflow is represented as a tuple $A_i=(L_i,P_i,T_i)$ [22], where $L_i$ is the language model guiding decision-making, $P_i$ is the prompt customised for the agent’s role, and $T_i$ is the set of tools the agent can invoke. The system was initially developed and evaluated using GPT-4o and GPT-4o-mini. At the time the framework was designed and evaluated, the GPT-4 family represented the state of the art for the capabilities MetaboT depends on most—complex tool use, schema-aware reasoning, and reliable generation of structured queries such as SPARQL—and exploratory tests with other contemporaneous APIs yielded less consistent structured output for our multi-agent routing and query-generation needs; GPT-4o was therefore adopted as the core reasoning engine and GPT-4o mini as a lower-capacity contrast within the same architecture. This reflects a design-time choice rather than a claim of permanent superiority. Because the architecture is model-agnostic, the LLM backend is configurable; the current implementation updates this default to GPT−5.5 while maintaining support for other models.

Schema and identifier provision

To accurately generate SPARQL queries from natural-language inputs, the LLM must be supplied with the specific ontology schema and Internationalized Resource Identifiers (IRIs) pertinent to the target knowledge graph: the schema defines the relationships between nodes [23] and IRIs uniquely identify the entities and properties used in queries [24]. LLMs are trained on broad datasets that may not include these specific IRIs [13, 15], and even when relevant IRIs are present in the training data, LLMs are not guaranteed to retrieve them correctly or to incorporate them appropriately into SPARQL queries, limiting their effectiveness for precise identifier-based tasks. Consequently, these IRIs must be supplied externally to the LLM alongside the ontology schema to ensure correct SPARQL construction. Prior work by Meyer et al. [13] and Avila et al. [25] confirms that providing LLMs with explicit schema information and IRIs significantly enhances the accuracy and reliability of SPARQL query generation. MetaboT therefore integrates dedicated tools and agents that resolve entities against authoritative resources and supply IRIs together with the relevant Turtle-serialised schema before query generation.

Workflow and agent orchestration

MetaboT processes user inputs through a flexible pipeline that manages context, entity resolution, query generation, and iterative refinement (Fig. 1b). The execution lifecycle proceeds as follows:

1. Context management and validation. When a user submits a natural-language question (e.g., “What bioactive compounds are found in Tabernaemontana coffeoides?”), the Entry Agent first determines whether the question is new or a follow-up to previous interactions. New questions are forwarded to the Validator Agent, a single LLM prompted with relevant details of the knowledge-graph schema, which checks the question’s scope to ensure relevance (e.g., confirming that bioactive compounds and plant species are valid entity types in the schema). For plant-specific questions, the PlantDatabaseChecker tool confirms the presence of the plant in a curated database (e.g., verifying that Tabernaemontana coffeoides exists in the plant database). Upon successful validation, the question is passed to the Supervisor Agent.

2. Supervisor delegation and entity resolution. The Supervisor Agent acts as the central coordinator for verified queries and routes them to appropriate agents based on content analysis. In our demonstration we use the Experimental Natural Products Knowledge Graph (ENPKG) [7], a comprehensive semantic graph that integrates mass spectrometry data with taxonomic information, chemical structures, and biological activities of natural products from plant sources. MetaboT does not import or annotate raw LC-MS/MS data: it queries the pre-computed annotations already integrated into the graph, so its compatibility is defined by the graph schema rather than by raw-file formats. The structural and chemical-class annotations that MetaboT can query in ENPKG are produced by SIRIUS (CSI:FingerID and CANOPUS) [3] and by the in silico ISDB-LOTUS spectral library [26, 27], both materialised as searchable annotation records. GNPS molecular networking and spectral-library matching were also performed when the ENPKG instance was built [4]; their results are stored on each feature as GNPS fast-search (FASST) links, which MetaboT can retrieve—for example, to flag the features carrying a GNPS library match—but which resolve to the match on the GNPS side rather than to structures materialised for querying within ENPKG. MetaboT queries these pre-computed annotations rather than recomputing them; its only live GNPS API call is the SMILESResolver (SMILES to InChIKey). When entity resolution is required, the Supervisor Agent delegates to the KG Agent, which extracts entities mentioned in the user’s question and resolves them to their IRIs via specialised tools:

   • When “Tabernaemontana coffeoides” is mentioned, the KG Agent calls the TaxonResolver to retrieve its Wikidata IRI.
   • For chemical classes such as “flavonoids”, the ChemicalResolver tool retrieves the appropriate NPClassifier (NPCClass) IRI.
   • When a SMILES string is provided (e.g., “C1=CC=C2C(=C1)C=CN2”), the SMILESResolver converts it to a standardised InChIKey.
   • When a biological target such as “acetylcholinesterase” is referenced, the TargetResolver obtains its ChEMBL target IRI.

   Once entities are resolved, the KG Agent verifies the returned matches against contextual information and returns precise identifiers to the Supervisor.

3. Query generation and execution. With entities resolved and schema details collated, the Supervisor Agent routes the request to the SPARQL Query Runner Agent. This agent contextualises the user’s question with the aligned identifiers and a Turtle-formatted schema to build a structured prompt for the GraphSparqlQAChain tool, which generates a SPARQL SELECT query, executes it on the KG endpoint, and retrieves the answer.

4. Interpretation. If the SPARQL output is large or the user explicitly requests a visualisation (e.g., “Plot the distribution”), the Interpreter Agent is invoked, which delegates the task to the Interpreter tool. This tool dynamically generates and executes Python code within a secure, locally hosted subprocess sandbox to produce textual summaries and, on demand, Plotly-based visualisations (e.g., bar charts, scatter plots) as JSON specifications. These visualisations are rendered automatically in the Streamlit web application; when running locally, the JSON specifications are returned without automatic rendering.

To manage computational costs and context-window limits, the system monitors token usage and systematically generates a CSV file containing the complete results. If the combined tokens of the query context and KG output exceed 6000, the system suppresses the direct text output in the interface and instead provides the user solely with the file path to the generated CSV.

Agent framework

MetaboT implements six primary agents, each with a distinct role in processing user queries.

Entry Agent. Purpose: gateway to the MetaboT system; determines whether a query is new or related to prior interactions. Key functions: processes user-provided files via the FileAnalyzer tool; forwards new queries to the Validator Agent; retrieves context for follow-up questions from the conversation history. Processing approach: classifies queries as new knowledge questions (requiring new database information) or help me understand questions (seeking clarification on previous answers), preventing redundant processing and maintaining conversation context.

Validator Agent. Purpose: ensures that user questions are appropriate for querying the knowledge graph before further processing. Key functions: confirms query validity and alignment with the schema and available data; uses the PlantDatabaseChecker tool to verify the presence of mentioned plant or taxon names; routes valid questions to the Supervisor Agent and returns specific feedback for invalid ones. Processing approach: employs in-context learning [28] and few-shot examples by embedding a compact form of the knowledge-graph schema directly in its prompt, enabling schema compliance through comparison with valid and invalid example questions.

Supervisor Agent. Purpose: central coordinator; routes user queries to appropriate agents based on content analysis. Key functions: identifies key entities (taxon names, chemical names, biological targets, etc.); delegates entity resolution to the KG Agent when needed; passes processed outputs to the SPARQL Query Runner Agent. Processing approach: follows explicit guidelines for task delegation, entity-specific processing, and multi-step query workflows, with worked examples covering proper task routing and error handling.

KG Agent. Purpose: resolves entities mentioned in user queries to provide precise identifiers for knowledge-graph elements. Key functions: retrieves standardised identifiers through specialised resolver tools—ChemicalResolver (RAG over a reference file), SMILESResolver (GNPS API), TargetResolver (ChEMBL API), and TaxonResolver (SPARQL over the Wikidata endpoint). Processing approach: uses external APIs, RAG on local files, or SPARQL queries to resolve each entity against authoritative sources rather than relying on the LLM’s parametric knowledge, substantially reducing hallucinations.

SPARQL Query Runner Agent. Purpose: prepares inputs for SPARQL generation and coordinates query execution. Key functions: if a question requires Wikidata comparison, extracts the Wikidata-related part (using WikidataStructureSearch) and sends only the non-Wikidata component with resolved entities to the GraphSparqlQAChain tool; otherwise, selects GraphSparqlQAChain and provides the complete question with resolved entities; ensures all required information (user question, resolved entities, schema details) is properly structured; manages query execution and result formatting; when applicable, calls OutputMerger to combine GraphSparqlQAChain and WikidataStructureSearch outputs and returns the merged result to the Supervisor. Processing approach: emphasises structured input preparation rather than direct query generation, ensuring precise SPARQL construction through comprehensive context provision.

Interpreter Agent. Purpose: bridges the gap between raw query results and user-friendly insights. Key functions: analyses outputs from the SPARQL Query Runner Agent or user-submitted files; produces clear summaries of query results; generates visualisations (bar charts, diagrams, mass-spectrum plots) when required. Processing approach: invokes the Interpreter tool with structured inputs; follows detailed guidelines for presenting data in an accessible, query-appropriate format.

Tool integration

MetaboT employs eleven specialised tools that support the agents and integrate external resources. The resolver tools—ChemicalResolver, SMILESResolver, TargetResolver, and TaxonResolver—map free-text entities from the user’s question to standardised identifiers (URIs/IRIs), whether through a local FAISS index (NPClassifier classes) or external services (the GNPS API, ChEMBL, and the Wikidata endpoint). These resources are used exclusively for entity resolution: they return identifiers, not biological or chemical content. Bioactivity values, spectral annotations, and taxonomic hierarchies are retrieved from the knowledge graph itself via the resolved identifiers.

1. PlantDatabaseChecker. Verifies the presence of plant names within a pre-existing database to filter queries based on data availability. Input: plant name string. Process: loads a CSV file containing plant names considered in the ENPKG analysis and searches for exact matches. Output: confirmation of the plant’s presence or absence, with error handling for file access issues.

2. ChemicalResolver. Resolves chemical names to standardised NPClassifier class identifiers (NPCClass URIs). Input: chemical name extracted from the user query. Process: matches chemical names to NPCClass URIs using a FAISS [29] vector store with OpenAI embeddings [30], built from a precompiled CSV file of NPCClass data extracted from the knowledge graph. Output: NPCClass URI with type information.

3. SMILESResolver. Converts SMILES [31] molecular representations to standardised InChIKeys [32] for chemical interoperability. Input: SMILES string. Process: sends the SMILES to the GNPS API  [4] to retrieve the corresponding InChIKey. Output: standardised InChIKey with process logging. Error handling: robust logging for API request issues and exception handling.

4. TargetResolver. Maps biological target names to standardised ChEMBL target IRIs [33]. Input: biological target name. Process: queries the ChEMBL API to locate matches based on target names, parsing XML responses to extract and format ChEMBL target IDs as IRIs. Output: formatted ChEMBL target IRI. Error handling: logs successful and unsuccessful API calls and suggests refinement when no matches are found.

5. TaxonResolver. Resolves taxonomic names to their corresponding Wikidata IRIs. Input: taxonomic name. Process: constructs and executes SPARQL queries on the Wikidata endpoint [34] to retrieve unique IRIs associated with taxon names. Output: Wikidata IRI for the taxonomic entity. Error handling: robust handling of unexpected formats and connectivity issues with clear logging.

6. FileAnalyzer. Analyses user-provided files and generates content summaries. Input: uploaded files and session identifier. Process: initialises session-specific directories, identifies file types, and applies tailored analysis methods—row/column/header extraction via pandas for spreadsheets, spectrum counts for Mascot Generic Format (MGF) files, and line counts for text files. Output: structured summaries with file paths, sizes, and content-specific details for downstream processing.

7. GraphSparqlQAChain. Generates and executes SPARQL queries aligned with the knowledge graph’s schema. Input: user question, schema information in Turtle format, and resolved entity identifiers. Process—query generation: uses the LLM with structured prompts combining in-context learning, chain-of-thought reasoning [18], and one-shot examples to create schema-compliant queries. Process—query refinement: when initial queries yield no results, identifies schema nodes related to the original query and leverages a FAISS store of similar queries to regenerate a more accurate command. Process—result processing: executes queries on the KG endpoint and saves outputs to temporary CSV files. Error handling: removes extraneous elements from generated queries, ensures schema compliance, and manages token limits by truncating outputs for the LLM context window when necessary.

8. WikidataStructureSearch. Retrieves compound annotations associated with a taxon (e.g., plant genus) using its Wikidata identifier. Input: Wikidata identifier string. Process: constructs and executes a SPARQL query on the Wikidata endpoint to retrieve Wikidata IRIs of chemical compounds annotated to species within the genus of the given taxon; results are saved to a temporary CSV file. Output: path to a CSV file containing the list of compound Wikidata IRIs, or None if no results are found.

9. OutputMerger. Identifies overlapping Wikidata compound annotations between results from two different SPARQL endpoints. Input: two CSV paths containing Wikidata IDs—one from the ENPKG endpoint (GraphSparqlQAChain) and one from the Wikidata endpoint (WikidataStructureSearch). Process: standardises identifier formatting, identifies common IDs, removes duplicates, and saves the final list to a temporary CSV file. Output: path to the merged CSV.

10. Interpreter. Contextualises query results through summaries and visualisations. Input: SPARQL query results, file paths, and the original user question. Process: parses agent inputs to extract questions, file paths, and contextual information; delegates execution to the Interpreter tool, which dynamically generates and runs Python code within a secure, custom-built local subprocess sandbox (restricted to user-specific session directories) to produce interpretations of query results and Plotly [35] JSON graph specifications on request. Output: textual summaries and, when visualisations are requested, JSON files containing Plotly graph code. Output management: logs processing steps and provides accessible file paths to users.

11. SpectrumPlotter. Provides a URL that displays a plot of a spectrum based on a given Universal Spectrum Identifier (USI) [36]. Input: a USI value that uniquely identifies the spectrum, or a CSV file path with a column named usi. Process: constructs a URL of the form https://metabolomics-usi.gnps2.org/dashinterface/?usi1={usi} that points to the Metabolomics Spectrum Resolver dashboard [37]. Output: the constructed URL.

SPARQL query generation and execution

The GraphSparqlQAChain tool implements a three-stage process for translating natural-language questions into executable SPARQL queries.

Initial query generation. The tool combines the user’s question with schema information (in Turtle format) and the resolved entity identifiers to generate a SPARQL SELECT query. For example, a user question about “bioactive compounds in Tabernaemontana coffeoides” is combined with the Wikidata IRI for Tabernaemontana coffeoides (Q15376858) and the relevant schema properties. The generation prompt enforces content clarity, proper prefix usage, schema alignment, and validation requirements, and combines in-context learning, chain-of-thought prompting [18], and one-shot examples to guide the LLM toward well-structured, syntactically correct queries.

Query execution and result analysis. Generated queries are executed on the knowledge-graph endpoint, with results analysed for completeness and relevance. If a query yields no results or errors, the tool initiates a refinement process.

Query refinement. For unsuccessful queries, the tool identifies schema nodes related to the initial query and retrieves one similar query from a FAISS store of prior queries. Using these insights, it prompts the LLM to regenerate a more accurate, schema-compliant query. This refinement is performed only once, guided by concise schema information, step-by-step reasoning, and validation criteria. An important component of the refinement workflow is the tool’s ability to distinguish between errors in query construction and the actual absence of relevant data in the knowledge graph. For example, if a query about “terpenes in Tabernaemontana coffeoides” returns no results, the system first assesses whether the query might be improperly constructed and attempts to regenerate it. If the regenerated query returns results, the initial failure is attributed to construction errors. If the regenerated query still fails, this either indicates that the knowledge graph truly lacks data on the topic or that errors persist in the query formulation. The distinction enables targeted refinement strategies that enhance system reliability and user confidence.

Result processing. Successfully executed query results are saved to a temporary CSV file for downstream analysis. Token usage is monitored to ensure compatibility with the LLM’s context window; if the combined tokens from the generated SPARQL query, the user’s question, and the KG output exceed 6000 tokens, the full results are not passed to the LLM and users retrieve the complete output from the generated CSV file.

Interaction between agents

Agent interaction is orchestrated through a directed graph, with messages passing along edges from one agent to the next (Fig. 1b; Additional file 1, Fig. S1). The output of each agent becomes the input for subsequent agents, enabling seamless information flow and decision-making throughout the system. For instance, after the Entry Agent determines a query’s nature, it passes relevant data to the Validator Agent via their connecting edge; valid questions proceed to the Supervisor Agent, where an initial entity analysis determines whether to invoke the KG Agent or proceed directly to SPARQL query generation. The structured directed-graph communication ensures that each agent operates with the most current and relevant information, enhancing efficiency and accuracy. During development and evaluation, agent interactions were monitored and analysed using LangSmith [38] (v0.3.45), which we used to systematically evaluate agent performance, track interactions, and identify refinement opportunities.

Web application

MetaboT is accessible via a web application (https://metabot.holobiomicslab.eu) designed to prioritise usability for researchers (Fig. 2). It captures natural-language questions and displays results, while the processing is managed by the backend LLM multi-agent framework. Current features—file uploads, visualisations, and the SpectrumPlotter module that integrates Metabolomics USIs [36] to render spectrum plots [37]—are implemented as proofs of concept that demonstrate the system’s extensibility. Outputs are presented as concise summaries, optionally supplemented with plots for visual interpretation of complex datasets. MetaboT’s design ensures accessibility for researchers without extensive computer-science expertise while providing robust data-querying capabilities through an interactive query interface, automated SPARQL generation, and built-in error handling. A step-by-step visual guide to the interface is provided in Additional file 1 (Fig. S4).

Fig. 2.

Representative interactions with MetaboT. a Annotation query. From Tabernaemontana coffeoides, MetaboT retrieves 728 metabolites annotated by SIRIUS (ZODIAC $>0.9$, COSMIC $>0.3$) and displays the generated SPARQL. b Cross-sample comparison. MetaboT ranks extracts by counts of aspidosperma alkaloids, plots the distribution, and repeats the analysis for tetraketide meroterpenoids. Green panels are MetaboT responses; brown panels are researcher prompts

Results

Validation dataset

To evaluate MetaboT’s performance, we constructed a synthetic dataset of 50 natural-language questions paired with manually verified reference SPARQL queries, designed to span multiple ontology classes within ENPKG. The questions were drafted with domain experts, considering the classes and properties present in the schema of the knowledge graph. Each question was submitted to MetaboT to generate an initial SPARQL query, which was manually reviewed and corrected against the ENPKG schema to ensure semantic correctness and full alignment with the intent of the question. Questions were categorised by complexity:

• Low complexity (11 questions): simple entity retrieval (e.g., “List all compounds found in Lovoa trichilioides”).

• Medium complexity (19 questions): multi-step operations with filtering (e.g., “Find all plant species containing flavonoids with molecular $weight>300$”).

• High complexity (20 questions): complex relationships and filtering (e.g., “Which compounds in Acer species have been reported to interact with human kinase targets and show molecular similarity (cosine score) $>0.7$ to known anti-inflammatory compounds?”).

The complete dataset is available in the project repository (app/data/evaluation_dataset.csv) and archived on Zenodo (DOI 10.5281/zenodo.20748535).

Evaluation procedure

We implemented an automated evaluation process in November 2024 using the LangSmith evaluation workflow [38], with LLM-based evaluators assessing outputs against criteria including correctness, accuracy, and SPARQL query similarity to the reference. To mitigate the known tendency of LLMs to hallucinate during evaluation [39], we complemented the automated scores with manual review.

A baseline evaluation established whether GPT-4o alone—without the multi-agent system—could produce accurate SPARQL. In this single-shot setting, each question was submitted to GPT-4o in a single conversational turn, together with the schema in Turtle format and a prompt analogous to that of the query-generation step of GraphSparqlQAChain, but without any pre-resolved entity identifiers and without the iterative refinement loop; the model was asked to generate the SPARQL query directly and was not prompted to reformulate it. Results showed that standalone GPT-4o produced inaccurate queries with property mismatches and incorrect entity identifiers, motivating the structured multi-agent approach.

Building on this baseline, we compared three configurations:

1. GPT-4o in single-shot mode without orchestration.

2. MetaboT using GPT-4o mini as the underlying LLM.

3. MetaboT using GPT-4o within the full multi-agent framework.

Each configuration processed identical queries under controlled conditions (consistent hardware and network). The evaluation was performed up to the point of SPARQL query generation and did not include the Interpreter Agent; the goal was to ensure that all components leading to SPARQL generation functioned correctly.

Across the 50 questions, the refinement chain of GraphSparqlQAChain regenerated three queries using formulations identical to the correct reference queries. This refinement was beneficial for only one of the three questions, which was therefore excluded from the overall accuracy computation to avoid crediting the framework with a coincidentally matching reformulation. In the two other cases, the underlying issue was that the Supervisor Agent had not invoked the KG Agent to retrieve the necessary entities. Accuracy reported below is therefore computed over 49 questions, while the full 50-question dataset is preserved and released for future evaluations. Because the excluded question is a high-complexity one, the high-complexity tier comprises 19 of its 20 questions in the accuracy tables (Table 1).

Table 1.

Accuracy of the three evaluated configurations across complexity levels

System	Overall (%)	Low (%)	Medium (%)	High (%)
GPT-4o (single-shot)	8.16	18.18 (T2)	10.53 (T2)	0.00 (T2)
MetaboT – GPT-4o mini	12.24	0.00 (T1)	15.79 (T1–2)	15.79 (T1–4)
MetaboT – GPT-4o	83.67	81.82 (T1)	89.47 (T2–3)	78.95 (T2)

T1–T4: error type codes defined in Section Error analysis

Accuracy is reported as the percentage of correctly generated SPARQL queries over 49 evaluation questions (Low: 11; Medium: 19; High: 19). Dominant error types are indicated in parentheses (see Section Error analysis)

Overall and per-complexity accuracy

MetaboT using GPT-4o within the multi-agent framework achieved 83.67% overall accuracy on the 49-question evaluation set, compared with 8.16% for single-shot GPT-4o and 12.24% for MetaboT using GPT-4o mini (Table 1). The gap between the standalone and multi-agent GPT-4o configurations was most pronounced for high-complexity queries, where the multi-agent GPT-4o configuration maintained 78.95% accuracy while standalone GPT-4o failed completely (0%). The GPT-4o mini-based MetaboT system performed better on high-complexity questions than on low-complexity ones; this counterintuitive pattern is explained by the fact that low-complexity questions often omit explicit entity mentions, making them harder for the Validator Agent—powered by a weaker LLM—to accept.

Error analysis

Manual review of failures revealed four primary error types, which informed subsequent prompt refinements:

• Type 1 – Validator misclassification: valid questions incorrectly rejected as out of scope (e.g., legitimate queries about plant metabolites).

• Type 2 – Incorrect SPARQL: queries with incompatible properties or malformed syntax.

• Type 3 – Missing KG Agent invocation: the Supervisor failed to call the KG Agent for queries requiring entity resolution.

• Type 4 – Inappropriate tool selection in the KG Agent: e.g., using TaxonResolver for chemical entities.

Type 1 and Type 2 errors dominated for the weaker model (GPT-4o mini), whereas the GPT-4o multi-agent configuration was left almost exclusively with Type 2 errors on the hardest questions.

Query-construction error analysis

Whereas the taxonomy above classifies where in the pipeline a failure occurs, we now zoom into the Incorrect SPARQL failures (Type 2) to characterise how a produced query is wrong. A failing question falls into one of two broad situations: either (a) the framework does not produce a usable query because upstream processing fails—for example, the question is rejected by the Validator Agent, or entities are incorrectly resolved, leaving insufficient information for SPARQL generation—or (b) the framework produces a SPARQL query that is itself incorrect despite sufficient information being available. To characterise the second situation, we reviewed every produced-but-incorrect query across the three evaluated configurations and categorised the query-construction errors into four types:

• Syntax error—a malformed query that fails to parse or execute.

• Incorrect property use (schema mismatch)—a well-formed query in which a property is applied to an incompatible class or does not exist for that entity; this includes applying an InChIKey2D-specific property to a standard InChIKey.

• Semantic error—a query that executes but does not answer the intended question because its logical formulation is incorrect (e.g., wrong filter, join, or aggregation).

• Incompleteness—a query that omits part of a multi-part request (a missing clause or an unaddressed sub-question).

The distribution of these errors is shown in Table 2. The denominator for each configuration is the number of produced-but-incorrect queries it generated (45 for single-shot GPT-4o; 21 for MetaboT with GPT-4o mini, whose remaining failures were rejected or mis-routed before a query was produced; and 5 for MetaboT with GPT-4o). Because a single query may exhibit more than one error type, columns can sum to more than 100%.

Table 2.

Distribution of query-construction errors among produced-but-incorrect queries, per configuration

Query-construction error	GPT-4o single-shot (45)	MetaboT GPT-4o mini (21)	MetaboT GPT-4o (5)
Syntax error	0	11 (52.38%)	0
Incorrect property use/schema mismatch	43 (95.56%)	6 (28.57%)	1 (20%)
Semantic error	21 (46.67%)	7 (33.33%)	2 (40%)
Incompleteness	2 (4.44%)	3 (14.29%)	2 (40%)

Denominators are the number of produced-but-incorrect queries (45, 21, 5). A query may exhibit more than one error type, so columns can sum to more than 100%

Three observations follow. First, single-shot GPT-4o produced a syntactically valid query for every question, yet 96% of its failing queries (43 of 45) misused properties or inserted raw entity labels instead of resolved knowledge-graph identifiers; without entity resolution and schema validation, this schema-grounding error is pervasive. Second, MetaboT with GPT-4o mini stops most errors upstream—only 21 of its 43 failures reach a produced query—but when the weaker model does generate SPARQL, its dominant fault is malformed syntax (52%, 11 of 21), indicating that the smaller model cannot reliably emit well-formed queries even within the structured workflow. Third, MetaboT with GPT-4o produced only 5 incorrect queries in total; of these, one (20%) applied an InChIKey2D-specific property to a standard InChIKey entity—a schema mismatch in which the query retrieved InChIKey2Ds although the question asked for InChIKeys. With GPT-4o driving all agents, this structure-notation error occurred for only 1 of the 49 evaluation questions (1 of the 5 produced-but-incorrect queries).

Processing time and operational cost

Average query processing time was 10.04 s for the single-shot GPT-4o approach, 36.28 s for the GPT-4o mini multi-agent configuration, and 80.45 s for the GPT-4o multi-agent configuration. Processing time for single-shot GPT-4o was measured from prompt submission until SPARQL generation; for GPT-4o mini, only runs in which all agents were invoked were counted (in many cases the Validator Agent halted the workflow before it reached the SPARQL Query Runner); for the GPT-4o multi-agent configuration, time was measured for all questions end-to-end.

The MetaboT multi-agent architecture requires multiple LLM calls per query: a typical question incurs five to eight calls depending on complexity. Providing detailed schema information and examples in prompts increases token counts and operational cost. On average, each complete query-processing cycle consumes approximately 22,240 tokens (prompt plus completion), translating to an average cost of $0.06 per question at the time of evaluation. The maximum observed cost was $0.092 for a high-complexity question; the minimum was $0.041 for a low-complexity question.

Representative interactions

Figure 2 illustrates two representative MetaboT sessions.

To illustrate how MetaboT supports natural-products researchers end-to-end, we follow a single bioactivity-driven question from a biological matrix to interpretable result (Fig. 3). A researcher asks the system to identify plant extracts containing ISDB-annotated compounds with parent masses above 800 Da and inhibition rates above 50% against Trypanosoma cruzi, prioritising high-mass bioactive natural products. The Entry and Validator agents process and validate the question; the KG Agent resolves the biological target to its ChEMBL identifier; and the SPARQL Query Runner Agent generates and executes a schema-compliant query over the ENPKG endpoint. MetaboT returns a downloadable table of plant species, lab extracts, and annotated compounds (as InChIKeys), from which candidate extracts and their associated high-mass metabolites—including the chemical structures of representative compounds active against T. cruzi—can be prioritised for downstream structural inspection and activity-guided analysis. The same question, re-issued with a request to visualise the result, yields a MetaboT-generated bar chart of the number of distinct annotated compounds per plant (Additional file 1, Fig. S3).

Fig. 3.

Representative MetaboT workflow for bioactive metabolite discovery. a Bioactive natural products query. A researcher asks MetaboT to identify plant extracts containing ISDB-annotated compounds with parent masses above 800 Da and inhibition rates above 50% against Trypanosoma cruzi, aiming to prioritize high-mass bioactive natural products. b Multi-agent workflow. The entry and validator agents process and validate the query, the KG agent resolves the biological target via ChEMBL, and the SPARQL agent generates and executes a schema-compliant query over the ENPKG endpoint. c Retrieved results. MetaboT returns a downloadable table listing plant species, lab extracts, and annotated compounds (InChIKeys). d Biological interpretation. Candidate plant extracts and their associated high-mass metabolites are prioritized for downstream structural inspection and activity-guided metabolomic analysis.

Discussion

Contribution relative to existing software

MetaboT differs from prior single-model and RAG-based approaches to natural-language-to-SPARQL translation [11, 13–15] by decomposing the task into specialised agents, each with a single responsibility, and by grounding identifier choices in authoritative external resources (Wikidata, ChEMBL, NPClassifier, the GNPS API) rather than in the LLM’s parametric memory. In our evaluation, this architectural separation produces a 10-fold improvement in accuracy over single-shot GPT-4o (83.67% vs. 8.16%) and preserves accuracy on high-complexity queries that defeat the standalone model (78.95% vs. 0%).

MetaboT is complementary to the BioChatter [17] framework for biomedical LLM applications and to the BioCypher [16] ecosystem for knowledge-graph construction: both target biomedical data at large scale, whereas MetaboT is specifically tuned to the schema, identifiers, and analytical patterns of mass spectrometry metabolomics knowledge graphs. ExpasyGPT [14] shares the objective of LLM-mediated SPARQL over federated bioinformatics resources; relative to that line of work, MetaboT trades federated coverage for tight integration with a metabolomics KG, explicit entity resolution, and a transparent multi-agent workflow that can be inspected and extended agent-by-agent. Compared with tools that frame chemistry tasks around agentic LLMs (e.g., for synthesis planning), MetaboT addresses the distinct problem of querying rich, schema-constrained semantic graphs rather than invoking external computational chemistry tools. These distinctions, taken together, situate MetaboT as a targeted cheminformatics software contribution for knowledge-graph-based metabolomics.

Scalability and adaptability

A critical strength of MetaboT lies in its scalability and adaptability. Although our current demonstration focuses on ENPKG, the modular design supports extension to other mass spectrometry-based knowledge graphs with minimal reconfiguration: agents and tools can be reused, while prompts, schema fragments, and resolver endpoints are adapted to the new graph. The system can also interface with different LLM backends, a useful property given the rapidly evolving LLM landscape [40, 41], and the multi-agent architecture allows new agents or tools to be introduced without restructuring the orchestrator.

Limitations

Several limitations warrant acknowledgement.

Hallucinations. LLMs occasionally generate incorrect objects or properties, leading to errors in query construction (e.g., confusing InChIKey with InChIKey2D, or applying properties to incompatible classes). In the measured error analysis (Section Query-construction error analysis, Table 2), this schema mismatch was the residual query-construction error on the hardest queries: with GPT-4o driving all agents it affected only 1 of the 49 evaluation questions, and it persists because property-level schema constraints are not yet enforced before query execution. These hallucinations can also cause agents to invoke inappropriate tools, such as TaxonResolver for queries about biological targets.

Non-determinism. The inherent variability of LLM outputs means that identical queries may yield slightly different SPARQL commands, which occasionally benefits exploration but can also reduce consistency. We mitigate this by combining LLM reasoning with deterministic tools for identifier resolution and by extensive prompt engineering.

Model dependence and computational cost. MetaboT currently requires a high-capacity LLM for reliable performance on complex queries, as illustrated by the substantial accuracy gap between GPT-4o mini and GPT-4o within the same architecture. Each query incurs five to eight LLM calls, an average of $\sim$22,240 tokens, and $\sim$$0.06 at the time of evaluation—a non-trivial barrier for some research communities [15]. Agent prompts were tuned for specific backends (the GPT-4 family used during development and evaluation) and may require adaptation when switching models. Cost and robustness could be improved with hybrid approaches combining several models of varying capacity alongside automated prompt optimisation.

Single-graph querying. MetaboT is currently restricted to querying one knowledge graph at a time. Researchers must manually connect ENPKG data to external resources such as ChEMBL [33], Wikidata [34], or LOTUS [27] when federated answers are needed, because the system does not yet generate federated SPARQL queries. While critical external information has been integrated directly into ENPKG, implementing true federated-query capabilities would require efficient KG indexing, graph summaries for source selection, and sophisticated query-planning algorithms [42]. A dedicated federated-query module could then emit SERVICE clauses following the SPARQL 1.2 Federated Query specification (https://www.w3.org/TR/sparql12-federated-query/) to bridge ENPKG with complementary resources such as LOTUS.

Evaluation scope. The evaluation focuses on SPARQL query generation and does not benchmark the Interpreter Agent’s summaries or visualisations. Downstream interpretation accuracy is left to future work.

Future directions

Looking ahead, we envision MetaboT evolving into a broader toolbox for mass spectrometry data analysis, integrating agents and components dedicated to commonly used computational metabolomics approaches. Future developments will focus on automated benchmarking for continuous performance assessment, expanded interoperability with other metabolomics tools and knowledge graphs, and integration of emerging AI capabilities for cheminformatics and biomedical hypothesis generation [17]. These extensions will be pursued within the MetaboLinkAI programme, which brings together eight research institutions aiming to transform metabolomics data analysis through AI and knowledge-graph technologies.

Conclusions

MetaboT is a reproducible multi-agent LLM framework that bridges the gap between specialised SPARQL query writing and intuitive conversational interactions with mass spectrometry metabolomics knowledge graphs. By combining orchestrated entity resolution with schema-aware SPARQL generation and an iterative refinement loop, a multi-agent architecture powered by a high-capacity reasoning model achieves 83.67% accuracy in translating natural-language questions into executable queries on ENPKG—a 10-fold improvement over a single-shot baseline on the same benchmark. Released as open-source software with a public web demonstrator, a tagged evaluated version, and a reusable benchmark, MetaboT lowers the technical barrier for domain scientists, enables systematic semantic data mining without specialised programming expertise, and provides a concrete, extensible proof of concept for the broader MetaboLinkAI programme of AI-assisted metabolomics.

Availability and requirements

• Project name: MetaboT

• Project home page: https://github.com/HolobiomicsLab/MetaboT

• Public demonstrator: https://metabot.holobiomicslab.eu/

• Archived evaluated version: Zenodo, DOI 10.5281/zenodo.20748535 (tag v1.0-evaluation)

• Operating systems tested: macOS Sonoma (14.5), Ubuntu 22.04 LTS, Debian 11

• Programming language: Python (3.10)

• Other requirements: LangChain 0.3.27, LangGraph 0.3.34, FAISS 1.8.0, OpenAI Python library 2.32.0, pandas 2.2.1, Plotly 5.20.0. Hardware: modern CPU (Intel Core i7 13th generation or equivalent); minimum 8 GB RAM. Access to an LLM API endpoint (OpenAI GPT−5.5 recommended, minimum GPT-4o) is required for full functionality; a demonstration mode with canned responses is provided for local development without API access. A Docker configuration is included for containerised deployment.

• Access to ENPKG: https://enpkg.commons-lab.org/graphdb/repositories/ENPKG

• License: Apache 2.0

• Any restrictions to use by non-academics: none beyond the Apache 2.0 license.

• Reviewer access: during peer review, a reviewer-anonymous contributor key is provided for the public web demonstrator; please see the cover letter for the current key.

Author contributions

M.B., F.G., and L.-F.N. conceptualised the method. S.H., W.B., J.-L.W., and M.P. contributed to method conception and evaluation. M.B., L.P., B.N., E.T., F.Mi., and M.F. implemented the software. M.B. performed the analysis. M.B., Y.T., Y.Z.C., O.K., F.Me., M.L., and T.J. tested the method. W.B., F.G., and L.-F.N. co-supervised the project. M.B., W.B., F.G., and L.-F.N. wrote and edited the manuscript. All authors read and approved the final manuscript.

Funding

This work has been supported by the French government through the France 2030 investment plan managed by the National Research Agency (ANR) with reference number ANR-22-CPJ2-0048-01, ANR-15-IDEX-01, ANR-23-IACL-0001, including the MetaboLinkAI bilateral project (ANR-24-CE93-0012-01 and SNSF 10002786). L.P. was funded by the Luxembourg National Research Fund (FNR; project 17994255). E.T. received funding from the MIT International Science and Technology Initiatives through the MIT-France Program. O.K., F.M., M.P., J.-L.W. and L.-F.N. were supported by the Swiss National Science Foundation (SNSF project CRSII5_189921/1). W.B. was supported by the Research Foundation–Flanders (FWO G087625N) and the University of Antwerp Research Fund. The funders had no role in the study design, data collection and analysis, decision to publish, or manuscript preparation.

Data availability

The evaluation dataset of 50 natural-language questions with reference SPARQL queries is available in the project repository at https://github.com/HolobiomicsLab/MetaboT (app/data/evaluation_dataset.csv) and archived on Zenodo (https://doi.org/10.5281/zenodo.20748535). The Zenodo archive also contains the automated and manual evaluation output files used to compute the accuracy results reported in this study. The Experimental Natural Products Knowledge Graph (ENPKG) used for all queries is publicly accessible via a SPARQL endpoint at https://enpkg.commons-lab.org/graphdb/repositories/ENPKG. Taxonomic data are retrieved from Wikidata and biological-target data from ChEMBL; both are open-access resources.

Declarations

Ethics approval and consent to participate

Not applicable.

Consent for publication

Not applicable.

Competing interests

F.G. is co-founder and co-scientific advisor of :probabl.; E.T. is an employee of:probabl. All other authors declare no competing interests.