ontologies: NCBITaxon .owl/.db version-alignment gate (completes #604)#607
Conversation
Completes the remaining piece of #604. metatraits/lpsn/bacdive do label + lineage lookups against the OAK-fetched ncbitaxon.db (whose release is whatever OAK last downloaded), while the NCBITaxon transform emits nodes from ncbitaxon.owl — nothing pinned the two to the same release. - assert_ncbitaxon_version_alignment(db_path): compares ncbitaxon.owl's versionIRI release with the db's owl:versionInfo (via _ncbitaxon_db_release, a small SemSQL query) and fails loudly on mismatch; KG_NCBITAXON_VERSION_CHECK =warn downgrades to a warning. No-op when either stamp is unreadable. - Generalized _obo_release_from_head to also match NCBITaxon's versionIRI form (`ncbitaxon/DATE/`, no `releases/` segment). - Factored the strictness resolution shared with the GO gate into _version_check_strict. - Wired the gate into metatraits `_ensure_ncbitaxon_db_ready` (both the happy-path and cache-repair success branches). Verified on the current sources: ncbitaxon.owl and ncbitaxon.db are both 2026-05-13 → gate passes silently. 7 new tests (owl/db release parsing, aligned/mismatch/env-warn/missing-stamp); GO gate unchanged (11 tests). Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
There was a problem hiding this comment.
Pull request overview
This PR completes the NCBITaxon half of #604 by adding a version-alignment gate that detects when the NCBITaxon OWL used by the ontologies transform and the SemSQL SQLite DB used for downstream lookups are from different releases, preventing silent drift across ontology artifacts.
Changes:
- Extends
_obo_release_from_head()to also parse NCBITaxon-styleversionIRIstamps (.../ncbitaxon/YYYY-MM-DD/...without areleases/segment). - Adds
assert_ncbitaxon_version_alignment()(+ shared_version_check_strict()helper) and wires the NCBITaxon gate into metatraits’_ensure_ncbitaxon_db_ready(). - Adds a new focused test suite covering OWL/db release parsing and strict vs warn/no-op behaviors.
Reviewed changes
Copilot reviewed 3 out of 3 changed files in this pull request and generated 3 comments.
| File | Description |
|---|---|
kg_microbe/utils/ontology_utils.py |
Adds strictness resolution helper, extends OWL release parsing, and introduces NCBITaxon .owl/.db alignment gate + DB release reader. |
kg_microbe/transform_utils/metatraits/metatraits.py |
Calls the new NCBITaxon alignment gate during metatraits’ DB preflight validation/repair. |
tests/test_ncbitaxon_version_alignment.py |
New tests for NCBITaxon OWL/db stamp parsing and alignment gate behavior. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
| row = conn.execute( | ||
| "SELECT value FROM statements WHERE predicate = 'owl:versionInfo' " | ||
| "AND value IS NOT NULL LIMIT 1" | ||
| ).fetchone() |
| metatraits/lpsn/bacdive do label + lineage lookups against ``ncbitaxon.db`` | ||
| (an OAK-fetched prebuilt SemSQL DB whose release is whatever OAK last | ||
| downloaded), while the NCBITaxon transform output is built from | ||
| ``ncbitaxon.owl``. If the two are different releases, lookups can resolve |
| f"NCBITaxon source version mismatch: ncbitaxon.owl={owl_release} vs " | ||
| f"ncbitaxon.db={db_release}. metatraits/lpsn/bacdive look taxa up in " | ||
| "ncbitaxon.db while the transform emits nodes from ncbitaxon.owl; the " |
Addresses PR #607 review: - #1 (MEDIUM): the gate only ran under `if use_mp:` — so sequential metatraits (METATRAITS_MULTIPROCESSING=false / single worker) skipped it entirely. Moved the alignment call to run unconditionally in run() (no-ops if the DB isn't materialized yet), keeping the MP-only cache-repair pre-flight as-is. - #2 (MEDIUM): default the NCBITaxon gate to WARN, not raise — the OAK cache and the pinned ncbitaxon.owl legitimately drift (OAK auto-refreshes) and NCBITaxon labels/lineage are stable, so a mismatch is worth surfacing loudly but not aborting a previously-green run. KG_NCBITAXON_VERSION_CHECK=strict (or strict=True) opts back into fail-loud. _version_check_strict grew a per-gate default_strict; GO stays strict. - #3 (LOW/MED): target the ontology node in the versionInfo query (`subject LIKE '%ncbitaxon%'`) instead of relying on a single row. - #4 (LOW): correct the docstring/message — only metatraits invokes the gate (not lpsn/bacdive). - Tests: default-warn, env-strict-upgrade, subject-targeting (decoy row), and corrupt-db→None (21 total; GO's 11 unchanged). Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
|
Review addressed. #1 (MEDIUM, the important one) — the gate only ran under |
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Completes the remaining piece of #604 (NCBITaxon
.dbrelease pinning; the GO portion + version-gate framework shipped in #606).Problem
metatraits/lpsn/bacdive resolve taxa against the OAK-fetched
ncbitaxon.db(whose release is whatever OAK last downloaded), while the NCBITaxon transform emits nodes fromncbitaxon.owl. Nothing pinned the two to the same release, so a drifted OAK cache could resolve lookups against different taxa than the transform emitted.Change
assert_ncbitaxon_version_alignment(db_path)— comparesncbitaxon.owl's versionIRI release with the db'sowl:versionInfo(read via a tiny SemSQL query,_ncbitaxon_db_release) and fails loudly on mismatch;KG_NCBITAXON_VERSION_CHECK=warndowngrades to a warning. No-op when either stamp is unreadable (fail-safe — only two readable-but-different stamps trip it)._obo_release_from_headto match NCBITaxon'sversionIRIform (ncbitaxon/DATE/, which has noreleases/segment, unlike GO)._version_check_strict(used by both gates)._ensure_ncbitaxon_db_ready(both the happy-path and cache-repair success branches — the pre-flight validation that all consumers rely on).Verification
2026-05-13→ gate passes silently (verified).With this, #604 is fully addressed — both GO and NCBITaxon
.owl/.dbalignment are now gated.🤖 Generated with Claude Code