microbiomekg 0.1.0__tar.gz

microbiomekg-0.1.0/.gitignore

@@ -0,0 +1,33 @@
+# Third-party raw input: 7.5 GB, operator-owned. Never committed, and never
+# pruned by anything in this repo — three of its origins (HMDB, MiMeDB, MASI)
+# are browser-only downloads that no script can re-fetch. `make
+# check-data-bounds` reports its size and touches nothing.
+data/raw/
+# In this checkout `data` and `graph` are symlinks into the sibling
+# MicrobiomeKG-Data/ folder (raw/, graph/), so the library tree stays
+# clean; the two links are local state like everything they point at.
+/data
+/graph
+*.kgl
+graph/
+# Written by scripts/build.py beside the graph; a pure function of the sources.
+ontology.json
+
+docs/_build/
+.venv/
+__pycache__/
+.pytest_cache/
+.ruff_cache/
+.DS_Store
+
+# The local working system: plans, scratch, the todo index (dev-docs/) and the
+# cross-project channel (inbox/). Local state, never committed — each folder's
+# own README.md is its layout map, and CLAUDE.md's R4 table names every tier's
+# bound and owner. `make check-dev-docs` enforces the size bound.
+/dev-docs/
+/inbox/
+
+# Agent skill trees are local working state for this checkout, not part of the
+# public repository. The local `make gate` still verifies the adapter mirror.
+.claude/skills/
+.agents/skills/

microbiomekg-0.1.0/.readthedocs.yaml

@@ -0,0 +1,19 @@
+# Read the Docs configuration for the `microbiomekg` project, served at
+# https://microbiomekg.readthedocs.io (docs/design/release-readiness.md §5).
+# See https://docs.readthedocs.io/en/stable/config-file/v2.html
+
+version: 2
+
+build:
+  os: ubuntu-24.04
+  tools:
+    python: "3.12"
+
+sphinx:
+  configuration: docs/conf.py
+
+python:
+  install:
+    - requirements: docs/requirements.txt
+    - method: pip
+      path: .

microbiomekg-0.1.0/CHANGELOG.md

@@ -0,0 +1,135 @@
+# Changelog
+
+All notable changes to MicrobiomeKG will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+User-visible changes land under `[Unreleased]` as they happen; a release
+promotes that section into a version block. Internal refactors, test-only
+changes and formatting do not get entries.
+
+## [Unreleased]
+
+## [0.1.0] - 2026-09-09
+
+### Added
+- **Guidance in the data-loading path.** `prepare(data_dir)` creates the input
+  layout and prints a dataset table with availability, total size and oldest
+  local file age. Missing files and files above `max_age_days` (30 by default;
+  CLI `--max-age-days`) get download URLs and expected filenames. `status` and the CLI fetch report share the same guidance;
+  `status --create` creates the layout from the shell. Python `status` remains
+  a silent evaluator with per-file metadata on `SourceStatus.files`.
+- **Fetch missing inputs.** `fetch(data_dir, missing=True)` and `fetch --missing`
+  select fetchers for missing required inputs, deduplicating shared sources
+  and excluding optional KEGG unless explicitly selected with `only` / `--only`.
+  Selected fetchers retain their existing cache and update behavior.
+- **PyPI publishing.** `[project.urls]` (homepage, repository, docs,
+  changelog, issues) so the PyPI page links somewhere, and
+  `.github/workflows/publish.yml`: trusted publishing on a `v*` tag, a wheel
+  **and** an sdist with the artifact set asserted before and after the upload,
+  and a verification job that installs the *published* wheel into a clean venv
+  outside any checkout and runs the CLI there.
+- **`CITATION.cff` and `CONTRIBUTING.md`**, and a **Licence** section in the
+  README: the code is MIT and covers only this repository; no data and no built
+  graph is distributed; every edge carries the `source_licence` it came with,
+  and 80,118 of them carry an `-unstated` token against 68,752 that are CC0.
+  Per-source terms stay in `docs/sources.md`.
+- **The sdist carries `blueprint.json` and `CHANGELOG.md`.** The composed
+  blueprint is what the fragment-drift gate reads at the repo root, so it was
+  missing from the one distribution that ships the tests; the gate now runs
+  from an unpacked sdist.
+- **G6, coverage of two external curations.** `microbiomekg.coverage` reads
+  HMDAD and Peryton, reconciles them the way the preps do, and reports how
+  many of their (taxon, disease) pairs the graph asserts, with the evidence
+  histogram and direction agreement; neither set is loaded. Both are fetched
+  by `microbiomekg fetch --only hmdad` / `--only peryton`, and the numbers
+  ride into `docs/benchmarks.md` from a tracked capture.
+- **G7, the breadth proxy against a published meta-analysis.** D14's
+  signature-breadth ranking scored against Duvallet et al. 2017's non-specific
+  genus set: nine of the top ten at genus rank, claim-gated in
+  `docs/benchmarks.md`. The reference set is fetched by
+  `microbiomekg fetch --only duvallet2017` and cut to a checked-in table.
+- **Source to graph, with nothing on disk in between.** Every prep is a
+  function, `run(raw, store, ...)`, that puts its tables into one in-memory
+  store; the build composes a blueprint whose `files:` section declares each
+  table as a frame and loads it with kglite 0.16.23's `frames=`. The
+  `BuildResult` carries the store, ledgers included.
+- **The package surface.** `import microbiomekg` gives `status(data_dir)`,
+  `fetch(data_dir)` and `build(data_dir)` over one data directory; `build`
+  returns a `BuildResult` holding the kglite graph and a `BuildReport`. The
+  `microbiomekg` console script runs the same three verbs over `--data`, plus
+  `serve` over `--graph`. The package is a wheel: `make check-install` builds it and proves
+  it in a clean venv.
+- **`SourceStatus`.** Every prep declares `RAW_INPUTS`, and `status` reports
+  each source as `absent`, `present`, `stale` or `manual`, with the missing
+  files and a `how_to_get` line as data — the three browser-only origins'
+  instructions included.
+- **A build with nothing in it succeeds.** An empty data directory exits 0,
+  names every source as skipped, and writes no graph; a directory holding only
+  the NCBI taxdump builds the Taxon spine and says "taxonomy-only".
+- `docs/benchmarks.md`: the association-layer shape, reconciliation confidence,
+  the two drug-screen headline reproductions, BugSigDB loader fidelity and
+  cross-source direction agreement, every number executed by the claim gate.
+- The Sphinx docs (`make docs`, built under `-W`) and the human-first README,
+  also claim-gated.
+
+### Changed
+- **The benchmark harness's scratch directory defaults to a sibling of the
+  checkout** (`../MicrobiomeKG-bench`) instead of one machine's absolute path.
+  `MICROBIOMEKG_BENCH_SCRATCH` moves it per machine, `--scratch` per run.
+- **`docs/sources.md` reads in numeric order** — the MONDO section (11) sat
+  after 17.
+- **The kglite floor is `>=0.17.1`.** The graph rebuilds table-for-table
+  identical on it (56 tables, 864,132 taxa, 112,966 `taxon_condition` rows),
+  and the full suite — the acceptance goldens, the documented queries and the
+  claim gate against a 0.17.1-built graph — is unchanged. 0.17.0 also closes
+  two more `docs/model.md` §8 engine asks: a Cypher query can force the exact
+  vector scan with `{exact: true}` and read which lane served it from the
+  result's retrieval diagnostics, and the ontology audits *node* properties
+  as well as edge ones.
+- **A blueprint fragment names its input with `file` only.** The pre-0.16.23
+  `csv` spelling, which the build and `declared_types` still accepted and
+  rewrote, is no longer read; no fragment used it.
+- **`mondo.obo` is a declared input.** The three preps that key conditions on
+  MONDO list `mondo/mondo.obo` in `RAW_INPUTS`, `status` reports it, `fetch`
+  pulls it (`--only mondo`, and with BugSigDB and gutMDisorder), and an absent
+  file skips the source with the reason instead of silently writing every
+  disease under its source's own id. Withholding any declared input — not only
+  the first — now makes its prep refuse by name; that also caught MiMeDB's
+  microbes dump and four of the five taxonomy dumps.
+- `--csv` and `--skip-prep` are gone from the build: there is no CSV
+  directory to point at or reuse, and `microbiomekg build --data D` reads
+  `D/raw/` only. A prep's absent input is a `MissingInput` exception the
+  build reports as the skip, not an exit code.
+- kglite ≥ 0.16.23 is required.
+- The preps, blueprint fragments, MCP manifest and skills, and the build,
+  fetch and serve modules moved into the package (`microbiomekg/preps/`,
+  `microbiomekg/blueprints/`, `microbiomekg/mcp/`, `pipeline.py`,
+  `download.py`, `serve.py`); `scripts/*.py` are thin callers. The build runs
+  preps as `python -m microbiomekg.preps.<name>`.
+- The build no longer rewrites the tracked `blueprint.json`; `make gate`
+  composes it in `--check` mode.
+- The claim gate covers tracked markdown pages (`DOC_UNITS`), not only the
+  MCP prose.
+
+### Fixed
+- Data guidance uses the chosen data directory, quotes shell paths, and
+  distinguishes missing automatic inputs within a partly manual source.
+  Malformed manifest shapes no longer prevent status inspection. The fetch
+  CLI now exits unsuccessfully when a fetcher raises, while still displaying
+  the remaining input status.
+- **A malformed raw file skips its source instead of ending the build.** The
+  workbook preps (Maier 2018, Zimmermann 2019, NJC19) raised `SystemExit`
+  when a sheet or header row was not where the paper put it, or when a rule
+  derived from the file stopped reproducing the paper's own numbers; the
+  build caught none of it, so one renamed header ended a multi-minute build
+  with no report and no census. They raise `MalformedInput` now, the build
+  reports the source as present-but-malformed beside the absent ones, and
+  `<graph>.build.json` carries every skip's reason under `skip_reasons`.
+- Ten preps reported a missing NCBI taxdump through argparse (exit 2), which
+  the build reads as fatal; every prep now exits 3, the skip code.
+- A relative `--csv` loaded the ontology from a doubled path; the build
+  resolves its paths first.
+- `docs/evaluation.md` §5 compared the comparator's disease *nodes* to ours
+  and quoted a stale metabolite count; `docs/usecases-and-pitfalls.md` D17
+  quoted pre-MASI goldens.

microbiomekg-0.1.0/CITATION.cff

@@ -0,0 +1,34 @@
+cff-version: 1.2.0
+title: "MicrobiomeKG: a microbiome knowledge graph pipeline with an auditable evidence model"
+message: >-
+  If you use this software, please cite it as below — and cite the sources you
+  actually loaded, which docs/sources.md lists with their papers and licences.
+type: software
+authors:
+  - family-names: "Kollsgård"
+    given-names: "Kristian de Figueiredo"
+repository-code: "https://github.com/kkollsga/microbiomekg"
+url: "https://github.com/kkollsga/microbiomekg"
+license: MIT
+version: 0.1.0
+abstract: >-
+  A pipeline that builds a microbiome knowledge graph on kglite from curated
+  public sources over NCBI taxonomy. Its point is the evidence model rather
+  than the size: every association edge carries its provenance set — primary
+  source, source record id, source licence, study design, assay, both group
+  sizes and the citing paper — nothing is stored as a score, direction is
+  recorded per study and never aggregated, and measured negatives ("somebody
+  looked and found nothing") are first-class edges rather than absent rows.
+  Names that will not resolve go to a ledger with the reason, so "dropped" is
+  a number the graph can report. The software is MIT-licensed; no data and no
+  built graph is distributed, and each edge carries the licence of the source
+  it came from.
+keywords:
+  - microbiome
+  - knowledge graph
+  - evidence
+  - provenance
+  - cypher
+  - kglite
+  - bioinformatics
+  - NCBI taxonomy

microbiomekg-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,84 @@
+# Contributing
+
+Thanks for looking. This is a research pipeline with an unusually strict rule
+about prose, so the short version is worth reading before you open a PR.
+
+## The loop
+
+1. **Branch** — `feat/…`, `fix/…`, `refactor/…`. Never work on `main`.
+2. **Commit per phase.** A change that has steps gets one commit per step, each
+   independently runnable and testable, so a bisect lands on something small.
+   Format: `type: short description` (`feat`, `fix`, `docs`, `refactor`,
+   `test`, `chore`).
+3. **Open a draft PR** and let CI run: the gate, the full suite on Python
+   3.11–3.14, `sphinx -W`, and a build against an empty data directory.
+4. **Mark it ready** when every required check is green.
+
+## The gate
+
+```bash
+make venv    # provision .venv and install the package editable
+make gate    # ruff, adapter mirror, accumulation bounds, blueprint composition,
+             # and the two truth gates (~30 s)
+make test    # the full suite
+make docs    # sphinx -W
+```
+
+Run `make gate` before every push. It is fast, and it catches the things CI
+cannot: **CI has no built graph**, so the acceptance goldens, the documented
+queries and the claim gate self-skip there. A green PR does not mean those
+passed — only a local run against a built graph does. A skipped test is not a
+pass.
+
+Building the graph needs raw input the repository does not ship
+(`docs/sources.md` says where each source comes from, and three of them are
+browser-only downloads). `microbiomekg status --data ./data` prints the
+to-do list. Without it you can still change and test everything that is
+fixture-backed, which is most of the suite.
+
+## Two rules that are not style preferences
+
+**A claim in prose is executed.** Every number and every existential phrase in
+`microbiomekg/mcp/` — the skills an LLM agent reads — and in the pages listed
+in `tests/skill_claims.py` (`README.md`, `docs/benchmarks.md`,
+`docs/queries-by-task.md`) is covered by a claim in `tests/claims/` or
+`docs/claims/`, and every graph claim is run against the built graph. If your
+change moves a number, re-measure it and update the claim. **Never loosen the
+gate to make a sentence pass.** The gate exists because a shipped skill once
+told agents there was no `CONSUMES` edge in a graph holding 4,784 of them,
+while every test passed.
+
+**A fix lands with the test that fails without it**, in the same commit, and a
+new gate is not trusted until it has been seen red — break the thing it guards,
+watch it fail, restore, and say so in the commit message.
+
+## Adding a source
+
+A source is four files and edits no shared file:
+
+| file | what it carries |
+|---|---|
+| `microbiomekg/preps/prep_<src>.py` | `run(raw, store, …)`: raw files → tables, plus `DEPENDS_ON` and `RAW_INPUTS` |
+| `microbiomekg/blueprints/<src>.json` | the node types and junction edges it writes rows into |
+| `microbiomekg/ontology/<src>.py` | its audit rules, evidence mapping and licence |
+| `tests/test_<src>.py` | its fixture-backed tests, against a real cut of the source |
+
+Preps are discovered, not listed, so nothing central needs editing — and the
+test file is what notices a source that forgot one of the four. Fixtures carry
+real NCBI ids, cut from the real source; an invented id resolves to something
+real and wrong the day the dump moves.
+
+A source's edges must be able to say where they came from: `primary_source`,
+`source_record_id`, `source_licence`, the study design, both group sizes and
+the citing paper. An edge that cannot does not get written, and a value nobody
+has read is `not_provided` rather than a plausible default — the point is that
+the gap stays countable.
+
+`docs/model.md` is the graph model, `docs/usecases-and-pitfalls.md` is the user
+contract, and `CLAUDE.md` is the full set of conventions this repository works
+under.
+
+## Licence
+
+Contributions are accepted under the MIT licence in `LICENSE`, which covers the
+code only. No data is redistributed here (see the README's Licence section).

microbiomekg-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Kristian de Figueiredo Kollsgård
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

microbiomekg-0.1.0/PKG-INFO

@@ -0,0 +1,230 @@
+Metadata-Version: 2.5
+Name: microbiomekg
+Version: 0.1.0
+Summary: A microbiome knowledge graph on kglite, with the evidence model as the point.
+Project-URL: Homepage, https://github.com/kkollsga/microbiomekg
+Project-URL: Repository, https://github.com/kkollsga/microbiomekg
+Project-URL: Documentation, https://microbiomekg.readthedocs.io
+Project-URL: Changelog, https://github.com/kkollsga/microbiomekg/blob/main/CHANGELOG.md
+Project-URL: Issues, https://github.com/kkollsga/microbiomekg/issues
+Author: Kristian dF Kollsgård
+License-Expression: MIT
+License-File: LICENSE
+Keywords: bugsigdb,cypher,evidence,kglite,knowledge-graph,llm-agents,mcp,microbiome,ncbi-taxonomy
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Science/Research
+Classifier: Operating System :: MacOS
+Classifier: Operating System :: Microsoft :: Windows
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Programming Language :: Python :: Implementation :: CPython
+Classifier: Topic :: Database
+Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
+Requires-Python: >=3.11
+Requires-Dist: kglite>=0.17.1
+Requires-Dist: openpyxl>=3.1
+Requires-Dist: pandas>=2.0
+Requires-Dist: requests>=2.31
+Provides-Extra: docs
+Requires-Dist: furo; extra == 'docs'
+Requires-Dist: myst-parser; extra == 'docs'
+Requires-Dist: sphinx-autoapi; extra == 'docs'
+Requires-Dist: sphinx-copybutton; extra == 'docs'
+Requires-Dist: sphinx>=8.1.3; extra == 'docs'
+Provides-Extra: test
+Requires-Dist: pytest-timeout>=2.3; extra == 'test'
+Requires-Dist: pytest>=8.0; extra == 'test'
+Description-Content-Type: text/markdown
+
+# MicrobiomeKG
+
+A microbiome knowledge graph on [kglite](https://github.com/kkollsga/kglite),
+**with the evidence model as the point**. Every association edge carries the
+study design, the direction, both group sizes and the citing paper; nothing is
+stored as a score; direction is per study and never aggregated, so forty
+reports on one pair stay forty reports, dissent included. And the **measured
+negatives are first-class**: 61,127 edges record that somebody looked and found
+nothing — 42,233 drugs that did not inhibit a gut isolate, 17,479 that no
+strain metabolised, 894 metabolites with no exchange, and 521 curated
+non-effects — each as its own relationship, so no query mistakes "never
+tested" for "tested and clean".
+
+Eleven curated sources over NCBI taxonomy: BugSigDB, gutMDisorder, CARD, HMDB,
+Reactome, ChEMBL, MiMeDB, NJC19, the Maier 2018 and Zimmermann 2019 drug
+screens, and MASI. 934,206 nodes and 1,324,684 edges; 105,880
+microbe–disease reports over 56,306 distinct pairs. KEGG has a loader and is
+off by default, because its licence forbids redistributing a graph carrying it.
+
+No data and no built graph ships. What ships is the pipeline: one directory
+is the entire input, a source is discovered rather than listed, and a source
+whose raw files are absent is skipped loudly, never silently.
+
+## Install, get the data and build
+
+Install MicrobiomeKG from PyPI, then use one data directory throughout:
+
+```bash
+python -m pip install microbiomekg
+microbiomekg status --data ./my-data --create
+microbiomekg fetch  --data ./my-data --missing
+microbiomekg build  --data ./my-data
+```
+
+`status --create` creates the required raw-input directories and shows a table
+of dataset availability, size and age. Missing files and files older than the
+configurable age threshold get a download URL and expected filename below the
+table. It does not download anything. `fetch --missing` selects the automatic fetchers needed
+for missing default inputs, then prints the same report so remaining manual
+work stays visible. A build can use a partial data directory and names every
+source it skipped. See the [getting-started guide](docs/getting-started.md) for
+the browser-only inputs and Python equivalent.
+
+## Python
+
+```python
+import microbiomekg as mkg
+
+data = "./my-data"
+mkg.prepare(data)                         # create directories and print the input report
+mkg.fetch(data, missing=True)             # fetch missing automatic inputs; report again
+result = mkg.build(data)                  # build from what is present; does not save by default
+g = result.graph
+
+g.cypher("""
+MATCH (t:Taxon {id: 851})-[r:ASSOCIATED_WITH]->(d:Disease {id: 'MONDO:0005575'})
+RETURN r.direction, r.evidence_level, r.study_design, r.group_1_size, r.pmid
+ORDER BY r.evidence_level
+""")
+```
+
+That query — *Fusobacterium nucleatum* in colorectal cancer — returns 40 rows
+from 21 studies, one of them `decreased`. It is never one aggregated row, and
+the dissent is never removed. The twenty documented queries in
+[`docs/usecases-and-pitfalls.md`](docs/usecases-and-pitfalls.md) are the user
+contract; each has a golden the test suite asserts.
+
+## Cypher
+
+The graph is a kglite `.kgl` file: open it in Python, or over Bolt for driver
+tooling. Three of the documented queries, as the shape of what it answers:
+
+```cypher
+// D17 — where do studies disagree, and which pairs rest on a single cohort?
+MATCH (t:Taxon)-[r:ASSOCIATED_WITH]->(d:Disease)
+WITH t, d, collect(DISTINCT r.direction) AS directions,
+     count(DISTINCT r.study_id) AS n_studies, count(r) AS n_edges
+RETURN t.title, d.title, directions, n_studies,
+       size(directions) > 1 AS direction_conflict, n_studies = 1 AS single_cohort
+ORDER BY n_edges DESC LIMIT 50
+```
+
+```cypher
+// D8 — does a drug inhibit gut bacteria, and is it metabolised by them?
+MATCH (d:Drug {pref_name: 'METFORMIN'})-[r]->(t:Taxon)
+RETURN type(r) AS relationship, count(*) AS strains
+```
+
+```cypher
+// D6 — which taxa consume a metabolite, and which produce it? (cross-feeding)
+MATCH (m:Metabolite {title: 'Butyric acid'})
+OPTIONAL MATCH (p:Taxon)-[:PRODUCES]->(m)
+OPTIONAL MATCH (c:Taxon)-[:CONSUMES]->(m)
+RETURN count(DISTINCT p) AS producers, count(DISTINCT c) AS consumers
+```
+
+The model — node types, the evidence-field contract, the reconciliation ledger
+— is [`docs/model.md`](docs/model.md); the per-source licences and provenance
+are [`docs/sources.md`](docs/sources.md); what the graph reproduces and
+against what is [`docs/benchmarks.md`](docs/benchmarks.md).
+
+## MCP
+
+```bash
+microbiomekg serve --selftest    # green/red configuration check
+microbiomekg serve               # kglite's MCP server on stdio, read-only
+```
+
+The manifest and the skills ship inside the package. One skill per use-case
+family, injected into the tool descriptions an agent reads, so the evidence
+rules travel with the tool; the prose in them is held to the graph by the
+same claim gate that holds this README.
+
+## Adding a source
+
+A source is four files, discovered rather than listed, and adding one never
+edits a shared file:
+
+| file | what it carries |
+|---|---|
+| `microbiomekg/preps/prep_<src>.py` | `run(raw, store, …)`: raw files → tables in the build's store, plus `DEPENDS_ON` and `RAW_INPUTS` |
+| `microbiomekg/blueprints/<src>.json` | the node types and junction edges it writes rows into |
+| `microbiomekg/ontology/<src>.py` | its audit rules, evidence mapping and licence |
+| `tests/test_<src>.py` | its fixture-backed tests, against a real cut of the source |
+
+Fragments merge and never override: declaring the same key with a different
+value is a build error naming both fragments.
+
+## Layout
+
+- `microbiomekg/` — the package: `api.py` (the three verbs), `cli.py`, the
+  preps, the blueprint fragments, the ontology modules, `pipeline.py` (the
+  build), `download.py` (fetch), `sources.py` (status), `serve.py`, and `mcp/`.
+- `scripts/` — thin callers into the package, so `scripts/build.py` and
+  friends work from a checkout; `scripts/check_install.py` is the wheel proof.
+- `docs/` — the guides, the design notes, and the Sphinx build (`make docs`).
+- `tests/` — offline, fixture-backed; the graph-backed suites read the built
+  `graph/microbiomekg.kgl`. `tests/claims/` and `docs/claims/` hold the claims
+  the truth gate executes.
+- `bench/` — the longitudinal cost record.
+- `data/` and `graph/` are not in the tree: a checkout symlinks them to the
+  sibling `../MicrobiomeKG-Data/` (`raw/`, `graph/`), and
+  `--data ../MicrobiomeKG-Data` names the same directory without the links.
+
+## Building and testing
+
+```bash
+make venv          # provision .venv and install the package editable
+make build         # the graph (minutes; needs data/raw — see docs/sources.md)
+make gate          # the pre-commit gate: ruff, bounds, blueprint composition, the truth gates
+make test          # the full suite
+make docs          # sphinx -W
+```
+
+Two flags are off by default. `--with-kegg` is a licence gate. `--with-vectors`
+is a cost gate: the character-n-gram vector index buys query-time tolerance for
+a *misspelt* organism name and nothing else, while costing +82.6 s of build,
+`.kgl` 46.7 MB → 212.7 MB, load 1.03 s → 2.41 s and serving RSS 1.2 GB → 3.7 GB
+(the `2026-09-03` capture, `bench/results/`). A default build says in its report
+that the lane was skipped and which flag turns it on.
+
+The conventions an agent works under are `CLAUDE.md`, and `CONTRIBUTING.md` is
+the short version for a contributor.
+
+## Licence
+
+**The code is MIT** (`LICENSE`). That covers this repository — the preps, the
+blueprint fragments, the ontology modules, the build and the MCP surface — and
+nothing else.
+
+**The data is not ours to relicense, and none of it ships here.** No raw input
+and no built graph is distributed: a build reads sources the operator fetched
+under each source's own terms, and every edge carries the `source_licence` it
+came with. In a default build that is `CC-BY-4.0`, `CC0-1.0`,
+`CC-BY-SA-3.0`, `CARD-noncommercial`, `HMDB-noncommercial`, `unknown`, and an
+`-unstated` token on the sources whose papers state no redistribution terms —
+so a query can select exactly the cut it is allowed to pass on. It is a real
+constraint: 80,118 edges carry an `-unstated` token, against 68,752 that are
+CC0.
+
+Per-source terms are in `docs/sources.md` ("Redistribution: what blocks
+shipping a built graph"); what that leaves a redistributable cut looking like
+is measured in `docs/evaluation.md`. KEGG is behind `--with-kegg` for exactly
+this reason.
+
+If you use this pipeline in published work, `CITATION.cff` has the citation —
+and cite the sources you actually loaded, which `docs/sources.md` lists with
+their papers.