Keeping Semantic Authority Human
FAIR metadata standards such as Croissant make individual datasets findable and machine-readable, but they do not by themselves specify how heterogeneous datasets should be integrated into a queryable graph. The step from many well-described files to a semantically coherent knowledge graph still depends on many modelling decisions: which fields denote entities or relations, how identifiers are reconciled, which transformations are applied, and which source components are relevant for a given research purpose. These decisions are often encoded implicitly in bespoke ingestion code, where they are difficult to inspect, reproduce, or govern. We present Biotope, a command-line tool for the BioCypher ecosystem that constructs knowledge graphs from Croissant-described data while recording the construction process itself as version-controlled metadata.
Biotope is deterministic by design, and it does not select a semantic mapping on behalf of the user. Each semantic decision is made by an operator (human or software agent), and is captured as an inspectable artifact. Because the resulting configuration is version controlled through a git-based workflow, including add, commit, status, log, push/pull, and checksum verification, the same committed project state yields the same graph however it was assembled. In a cardiometabolic use case, an agent-operated build without human review of the mappings completed in 74.8 minutes and matched a hand-curated expert graph on a shared competency-question benchmark at 61.5% weighted accuracy.
The Integration Gap Between FAIR Data and AI-Ready Knowledge
Section titled “The Integration Gap Between FAIR Data and AI-Ready Knowledge”Research data management has made substantial progress in describing datasets according to the FAIR principles. Croissant and related FAIR digital object approaches provide machine-readable descriptions of data structure, provenance, licensing, and access. This makes individual datasets easier to discover and reuse, but it does not solve the integration problem. A knowledge graph requires a purpose-bound semantic representation: entities, relations, identifiers, evidence types, and transformations must be selected in relation to the questions the graph is meant to answer.
Like TensorFlow Datasets, Biotope consumes Croissant’s RecordSet and Field objects; it materialises them as graph nodes and edges rather than as tensors. Biotope thereby leverages the machine-readable structure provided by Croissant to facilitate machine-interpretable representations. This has several potential benefits:
• Flexibility: the representation is not governed by raw data structure, but by purpose. • Robustness: through the deterministic enumeration from Croissant and subsequent deterministic transformation, the resulting artifact remains provenance-bound. • Efficiency: the graph is built in hours rather than months, and answers the same questions with fewer output tokens than raw file access (see experiment).
In AI-driven research settings, large language model agents increasingly assist with data engineering and schema construction, but naive automation risks replacing hidden ingestion code with hidden model judgement. If an agent autonomously chooses a schema and emits code, the resulting graph may be technically useful but epistemically opaque. Biotope separates the construction substrate from semantic authority, so an agent can do the assembly while the modelling choices stay recorded.
Biotope: Deterministic, Agent-Operable Graph Construction
Section titled “Biotope: Deterministic, Agent-Operable Graph Construction”A Biotope project begins with an explicit statement of purpose and associated competency questions, and proceeds through a small set of command-line stages. init creates the project scaffold and records its purpose. get and add bring in data and metadata, including human- or agent-derived derivatives. map resolves how record sets and fields populate the declared entities and relations. queue tracks annotation and mapping state. build materialises the corresponding BioCypher project and rejects unresolved mappings.
Biotope consumes Croissant metadata directly, including annotations generated deterministically by the underlying Croissant Baker framework for structured formats such as CSV, FHIR, OMOP, Parquet, and bio-image metadata. Applied to the Open Targets Platform, biotope add generates annotations for all 55 integrated datasets from the platform’s Parquet resources, making public resources selectable as components alongside project-specific data. Croissant annotation removes the need to hand-write ingestion pipelines, but not the need for explicit semantic mappings.
The same workflow can be operated by a human, by a copilot agent onboarded through an AGENTS.md file generated during project initialisation, or by both. Because the tool never resolves a semantic alternative on its own, every modelling choice has an owner and a record.
We demonstrate Biotope in an ongoing cardiometabolic disease project across 23 research groups. The corpus combines single-cell differential expression results from published and in-house cohorts covering human atrial fibrillation, myocardial infarction, sepsis, and thrombosis, together with a mouse infarct model and cross-species ortholog links. The graph was scoped to the purpose of the project’s clinician-researchers and built twice; once by a human expert (computer scientist) writing BioCypher directly, once by an LLM agent using Biotope. The Biotope graph holds 1.19M nodes and 3.16M relationships, including 1.10M measurement records; the expert graph holds 81.3k nodes and 387k relationships, including 43.8k significant results.
Thirteen competency questions were evaluated under four conditions: the Biotope-built graph queried through Cypher, a hand-curated expert graph over the same domain queried through Cypher, the raw Croissant-described files, and public databases and literature. All four conditions used the same LLM harness and the same question text, so data access is the only variable. Each answer was scored deterministically with partial credit and audited manually. Queries on public sources reached 0%; nine of the thirteen questions were refused for lack of dataset-specific values, and the remaining four were answered incorrectly. Raw file access, without a graph, reached 53.8% weighted accuracy while requiring 2.8-fold more output tokens. The Biotope graph and the expert graph both reached 61.5%. The Biotope graph was assembled by an agent (using Claude Sonnet 5) without human review of the mappings, in 74.8 minutes at a compute cost of $24.32. The expert graph was constructed over several months; the exact effort was not measured, but a cost several orders of magnitude larger seems a fair assumption.
On five simpler “direct lookup” questions, the Biotope graph scores 5/5 and the expert graph 4/5; on five difficult “cross-study synthesis” questions, the Biotope graph scores 1/5 and the expert graph 2/5. Error analysis revealed that the two graphs fail differently. The Biotope graph retains non-significant measurements, so it is exact where a question needs the complete result set, but significance thresholds have to be applied at query time. The expert graph holds a corrected, significant-only subset with direct context edges, which shortens multi-hop traversal but truncates exact counts and makes an absent value indistinguishable from a measured null. On the count of significantly changed genes in atrial fibrillation cardiomyocytes, the Biotope graph returns the correct 20 while the expert graph returns 15.
Relevance and Outlook
Section titled “Relevance and Outlook”Biotope’s contribution is governed automation: software agents can perform the labour of graph assembly while semantic authority stays visible and attributable. Large, comprehensive integration projects tend toward universalising representations that are expensive to maintain and only partially aligned with any given research question. By combining reusable Croissant-described sources, deterministic build steps, and human- or agent-operated semantic mapping, Biotope makes it feasible to construct smaller, question-directed graphs on much shorter timescales.
Ongoing work extends Biotope with ontology grounding and alignment, using secondary retrieval-based anchoring of operator-chosen concepts to established vocabularies without constraining project-specific schema design. Beyond the question-answering benchmark reported here, we are developing coverage and quality measures for the constructed graphs themselves. We hope to discuss with the NFDI and broader life-science data communities how such substrates might be standardised across research data management and integrative bioinformatics workflows.