Companion to NCATSTranslator/Babel#1077, which asks the same of Babel's release artifacts.
babel-explorer is a CLI for debugging Babel cliques. It reads Babel's intermediate Parquet files directly and uses Node Normalization for labels, Biolink types, and clique membership — the verdict, against the concords' evidence. Three things it depends on are not in the README, so they are currently encoded as assumptions in our source, verified by probing live deployments rather than read from a spec.
What we could not find
1. The /status endpoint, and babel_version in particular. Not mentioned in the README. We rely on it: babel-explorer refuses (soon: warns — babel-explorer#30) when the NodeNorm it queries reports a different babel_version than the Babel release whose Parquet files it is reading, because labels and cliques from one release do not match cross-references from another.
Measured today, to show why this matters:
| Deployment |
babel_version |
nodenormalization-sri.renci.org |
2025sep1 |
nodenormalization-exp.apps.renci.org |
2026jul22 |
Nearly a year apart, and nothing in the docs would tell a consumer that, or which endpoint to prefer. Worth documenting: that /status exists, that babel_version is part of its contract, and — ideally — a note on which deployments track which Babel releases.
2. conflate and drug_chemical_conflate. Absent from the README. We send both as true on every get_normalized_nodes call, which is a policy decision we made by imitation rather than from documentation. What each one merges, what the defaults are, and when a consumer would want to turn one off, would all be useful.
3. The get_normalized_nodes response shape. Not described in the README (the OpenAPI spec is presumably authoritative, but a consumer has to know to go there). We parse equivalent_identifiers entries for identifier, label, type, taxa and description, and treat an unrecognised CURIE as a null value rather than a missing key — that last detail in particular was learned by observation and would be easy to get wrong.
Documents in babel-explorer worth reading
These show concretely what a consumer ends up assuming:
core/nodenorm.py — our whole client. get_babel_version() is our /status contract; _fetch_normalized() is our request and response contract, including the batching we do (100 CURIEs per request) and the null-for-unknown-CURIE handling.cli.py → check_babel_versions() — what we do with babel_version.AGENTS.md → "Domain context" (in PR #31) — our summary of how Babel, NodeNorm and conflation relate, with everything we could not verify marked as such. The gaps flagged there are the shortest statement of what this issue asks for.
Happy to send a PR against the README if that is easier than writing it — we would rather the authoritative version came from you, but we can draft from what we have inferred and let you correct it.
Companion to NCATSTranslator/Babel#1077, which asks the same of Babel's release artifacts.
babel-explorer is a CLI for debugging Babel cliques. It reads Babel's intermediate Parquet files directly and uses Node Normalization for labels, Biolink types, and clique membership — the verdict, against the concords' evidence. Three things it depends on are not in the README, so they are currently encoded as assumptions in our source, verified by probing live deployments rather than read from a spec.
What we could not find
1. The
/statusendpoint, andbabel_versionin particular. Not mentioned in the README. We rely on it: babel-explorer refuses (soon: warns — babel-explorer#30) when the NodeNorm it queries reports a differentbabel_versionthan the Babel release whose Parquet files it is reading, because labels and cliques from one release do not match cross-references from another.Measured today, to show why this matters:
babel_versionnodenormalization-sri.renci.org2025sep1nodenormalization-exp.apps.renci.org2026jul22Nearly a year apart, and nothing in the docs would tell a consumer that, or which endpoint to prefer. Worth documenting: that
/statusexists, thatbabel_versionis part of its contract, and — ideally — a note on which deployments track which Babel releases.2.
conflateanddrug_chemical_conflate. Absent from the README. We send both astrueon everyget_normalized_nodescall, which is a policy decision we made by imitation rather than from documentation. What each one merges, what the defaults are, and when a consumer would want to turn one off, would all be useful.3. The
get_normalized_nodesresponse shape. Not described in the README (the OpenAPI spec is presumably authoritative, but a consumer has to know to go there). We parseequivalent_identifiersentries foridentifier,label,type,taxaanddescription, and treat an unrecognised CURIE as anullvalue rather than a missing key — that last detail in particular was learned by observation and would be easy to get wrong.Documents in babel-explorer worth reading
These show concretely what a consumer ends up assuming:
core/nodenorm.py— our whole client.get_babel_version()is our/statuscontract;_fetch_normalized()is our request and response contract, including the batching we do (100 CURIEs per request) and the null-for-unknown-CURIE handling.cli.py→check_babel_versions()— what we do withbabel_version.AGENTS.md→ "Domain context" (in PR #31) — our summary of how Babel, NodeNorm and conflation relate, with everything we could not verify marked as such. The gaps flagged there are the shortest statement of what this issue asks for.Happy to send a PR against the README if that is easier than writing it — we would rather the authoritative version came from you, but we can draft from what we have inferred and let you correct it.