Skip to content

Plan, apply and roll back changes to a production ontology, with a blast radius report and a proof an auditor can re-check.

feat(python): KGCL diff + HNSW alignment index in open-ontologies-lite (0.2.0)

Fabio Rovaibe0e57cabe96
diff --git a/python/README.md b/python/README.md
index 9cab0a5c..b7f0a7e7 100644
--- a/python/README.md
+++ b/python/README.md
@@ -34,6 +34,40 @@ print(OntologyEngine.convert(ttl, "turtle", "ntriples"))
See [examples/python_usage.py](examples/python_usage.py) for a runnable end-to-end script.
+### Version governance with KGCL
+
+```python
+from open_ontologies_lite import kgcl_diff
+
+cs = kgcl_diff(open("v1.ttl").read(), open("v2.ttl").read())
+print(cs.counts()) # {'node_creation': 1, 'node_rename': 1, ...}
+print(cs.to_kgcl()) # KGCL change records, one per line
+```
+
+`kgcl_diff` classifies the change between two ontology versions into KGCL records
+(node created/deleted, renamed, annotation changed, edge created/deleted). Pure
+structural comparison, no model. Also exposed as the `onto_kgcl_diff` MCP tool.
+
+### Alignment candidate generation with HNSW (optional `[align]` extra)
+
+```bash
+pip install "open-ontologies-lite[align]"
+```
+
+```python
+from open_ontologies_lite import AlignmentIndex
+
+idx = AlignmentIndex(dim=384)
+idx.add("flw:PC-BAK", vec_bakery) # vectors come from YOUR embedder
+idx.add("FOODON:00001626", vec_foodon)
+idx.build()
+idx.query(vec_query, k=5) # -> [Candidate(id, score), ...]
+```
+
+MCP-native by design: the package owns the HNSW index, **you supply the vectors**.
+Lite never calls an embedding model; bring vectors from your orchestrator and let it
+adjudicate the candidates.
+
## Use as an MCP server
```bash
@@ -63,6 +97,7 @@ Register it with any MCP client (e.g. Claude):
| `onto_save` | Serialize the store to a file |
| `onto_convert` | Convert between Turtle / N-Triples / N-Quads / TriG / RDF-XML / N3 / JSON-LD |
| `onto_diff` | Triple-level diff between two ontologies |
+| `onto_kgcl_diff` | KGCL change records between two versions (governance / change logs) |
| `onto_lint` | Missing labels, domains, ranges |
## Relationship to the Rust engine
diff --git a/python/pyproject.toml b/python/pyproject.toml
index 6b8fc53f..bb22ad07 100644
--- a/python/pyproject.toml
+++ b/python/pyproject.toml
@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
[project]
name = "open-ontologies-lite"
-version = "0.1.1"
+version = "0.2.0"
description = "Lightweight Python bridge to the Oxigraph RDF/OWL engine, MCP server included. No Rust toolchain, no compilation."
readme = "README.md"
requires-python = ">=3.10"
@@ -23,6 +23,7 @@ dependencies = [
[project.optional-dependencies]
shacl = ["pyshacl>=0.26"]
+align = ["hnswlib>=0.8"]
dev = ["pytest>=8"]
[project.scripts]
diff --git a/python/src/open_ontologies_lite/__init__.py b/python/src/open_ontologies_lite/__init__.py
index 70d2164a..9b23b689 100644
--- a/python/src/open_ontologies_lite/__init__.py
+++ b/python/src/open_ontologies_lite/__init__.py
@@ -3,6 +3,22 @@ Oxigraph RDF/OWL engine. No Rust toolchain, no compilation, prebuilt wheels only
"""
from .engine import OntologyEngine, ValidationResult, resolve_format
+from .kgcl import ChangeSet, kgcl_diff
-__version__ = "0.1.1"
-__all__ = ["OntologyEngine", "ValidationResult", "resolve_format", "__version__"]
+__version__ = "0.2.0"
+__all__ = [
+ "OntologyEngine",
+ "ValidationResult",
+ "resolve_format",
+ "ChangeSet",
+ "kgcl_diff",
+ "__version__",
+]
+
+# AlignmentIndex needs the optional [align] extra (hnswlib); export it only when
+# importable so the base package stays dependency-light.
+try: # pragma: no cover
+ from .align import AlignmentIndex, Candidate # noqa: F401
+ __all__ += ["AlignmentIndex", "Candidate"]
+except ImportError: # pragma: no cover
+ pass
diff --git a/python/src/open_ontologies_lite/align.py b/python/src/open_ontologies_lite/align.py
new file mode 100644
index 00000000..75f37369
--- /dev/null
+++ b/python/src/open_ontologies_lite/align.py
@@ -0,0 +1,95 @@
+"""HNSW alignment index: an approximate-nearest-neighbour candidate generator.
+
+This is a *primitive*, deliberately MCP-native: the package owns the index, the
+caller owns the vectors. Open Ontologies Lite never generates embeddings and never
+calls a model. You bring vectors (from whatever embedding model your orchestrator
+uses); this builds an HNSW index over them and returns nearest-neighbour candidates
+for ontology alignment. Adjudicating those candidates into actual mappings is the
+orchestrator's job, not the server's.
+
+Requires the optional extra: pip install "open-ontologies-lite[align]"
+
+Reference: hnswlib, https://github.com/nmslib/hnswlib
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+
+def _require_hnswlib():
+ try:
+ import hnswlib # noqa: F401
+ return hnswlib
+ except ImportError as exc: # pragma: no cover - exercised only without the extra
+ raise ImportError(
+ "AlignmentIndex needs the optional 'align' extra. "
+ 'Install with: pip install "open-ontologies-lite[align]"'
+ ) from exc
+
+
+@dataclass
+class Candidate:
+ id: str
+ score: float # similarity in [0, 1] for cosine space (1.0 = identical direction)
+
+
+class AlignmentIndex:
+ """An HNSW index over caller-supplied vectors, keyed by string ids.
+
+ Typical use::
+
+ idx = AlignmentIndex(dim=384)
+ idx.add("flw:PC-BAK", vec_bakery) # vectors come from YOUR embedder
+ idx.add("FOODON:00001626", vec_foodon)
+ idx.build()
+ idx.query(vec_query, k=5) # -> [Candidate(id, score), ...]
+ """
+
+ def __init__(self, dim: int, space: str = "cosine", max_elements: int = 100_000,
+ ef_construction: int = 200, M: int = 16) -> None:
+ self._hnswlib = _require_hnswlib()
+ self.dim = dim
+ self.space = space
+ self._index = self._hnswlib.Index(space=space, dim=dim)
+ self._index.init_index(max_elements=max_elements, ef_construction=ef_construction, M=M)
+ self._ids: list[str] = []
+ self._built = False
+
+ def add(self, id: str, vector) -> int:
+ """Add one (id, vector). Returns the internal integer label."""
+ if len(vector) != self.dim:
+ raise ValueError(f"vector length {len(vector)} != index dim {self.dim}")
+ label = len(self._ids)
+ self._ids.append(id)
+ self._index.add_items([list(vector)], [label])
+ self._built = True
+ return label
+
+ def add_many(self, items) -> int:
+ """Add an iterable of (id, vector). Returns the count added."""
+ n = 0
+ for id, vec in items:
+ self.add(id, vec)
+ n += 1
+ return n
+
+ def build(self, ef: int = 50) -> None:
+ """Set the query-time ef parameter (higher = more accurate, slower)."""
+ self._index.set_ef(ef)
+ self._built = True
+
+ def query(self, vector, k: int = 5) -> list[Candidate]:
+ """Return up to k nearest candidates for a query vector, best first."""
+ if not self._ids:
+ return []
+ self._index.set_ef(max(k * 4, 50))
+ labels, distances = self._index.knn_query([list(vector)], k=min(k, len(self._ids)))
+ out = []
+ for lbl, dist in zip(labels[0], distances[0]):
+ # cosine space: hnswlib distance = 1 - cosine_similarity
+ score = 1.0 - float(dist) if self.space == "cosine" else -float(dist)
+ out.append(Candidate(id=self._ids[int(lbl)], score=round(score, 4)))
+ return out
+
+ def __len__(self) -> int:
+ return len(self._ids)
diff --git a/python/src/open_ontologies_lite/kgcl.py b/python/src/open_ontologies_lite/kgcl.py
new file mode 100644
index 00000000..611148eb
--- /dev/null
+++ b/python/src/open_ontologies_lite/kgcl.py
@@ -0,0 +1,158 @@
+"""KGCL (Knowledge Graph Change Language) diff.
+
+A deterministic, model-free primitive: given two versions of an ontology, classify
+the difference into KGCL change records (node created/deleted, node renamed,
+annotation changed, edge created/deleted) and render them in KGCL text syntax.
+
+This is scaffolding, not intelligence: it reports *what* changed between two graphs
+so an orchestrator (or a human governance process) can decide what it means. No LLM,
+no heuristics beyond structural triple comparison.
+
+Reference: KGCL, https://github.com/INCATools/kgcl
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+
+import pyoxigraph as ox
+
+from .engine import resolve_format
+
+RDF_TYPE = "http://www.w3.org/1999/02/22-rdf-syntax-ns#type"
+LABEL_PREDICATES = {
+ "http://www.w3.org/2000/01/rdf-schema#label",
+ "http://www.w3.org/2004/02/skos/core#prefLabel",
+}
+ANNOTATION_PREDICATES = {
+ "http://www.w3.org/2000/01/rdf-schema#comment",
+ "http://www.w3.org/2004/02/skos/core#definition",
+ "http://purl.org/dc/terms/description",
+}
+
+
+def _term(t) -> str:
+ """Render a pyoxigraph term as a comparable/printable string."""
+ if isinstance(t, ox.NamedNode):
+ return t.value
+ if isinstance(t, ox.BlankNode):
+ return f"_:{t.value}"
+ # Literal
+ return f'"{t.value}"' + (f"@{t.language}" if getattr(t, "language", None) else "")
+
+
+def _parse(data: str, fmt: str):
+ """Return (triples_set, by_subject dict) for a serialized graph."""
+ triples = set()
+ by_subj: dict[str, set] = {}
+ for q in ox.parse(data.encode("utf-8"), format=resolve_format(fmt)):
+ tr = getattr(q, "triple", q)
+ s, p, o = _term(tr.subject), _term(tr.predicate), _term(tr.object)
+ triples.add((s, p, o))
+ by_subj.setdefault(s, set()).add((p, o))
+ return triples, by_subj
+
+
+def _short(iri: str) -> str:
+ for sep in ("#", "/"):
+ if sep in iri:
+ return iri.rsplit(sep, 1)[-1]
+ return iri
+
+
+@dataclass
+class ChangeSet:
+ """A classified set of KGCL changes between two ontology versions."""
+
+ changes: list[dict] = field(default_factory=list)
+
+ def counts(self) -> dict[str, int]:
+ c: dict[str, int] = {}
+ for ch in self.changes:
+ c[ch["type"]] = c.get(ch["type"], 0) + 1
+ return c
+
+ def to_kgcl(self) -> str:
+ """Render the change set in KGCL text syntax (one statement per line)."""
+ lines = []
+ for ch in self.changes:
+ t = ch["type"]
+ if t == "node_creation":
+ lbl = f' "{ch["label"]}"' if ch.get("label") else ""
+ lines.append(f'create node <{ch["node"]}>{lbl}')
+ elif t == "node_deletion":
+ lines.append(f'delete node <{ch["node"]}>')
+ elif t == "node_rename":
+ lines.append(f'rename <{ch["node"]}> from "{ch["old"]}" to "{ch["new"]}"')
+ elif t == "node_annotation_change":
+ lines.append(
+ f'change annotation of <{ch["node"]}> <{ch["predicate"]}> '
+ f'from "{ch["old"]}" to "{ch["new"]}"'
+ )
+ elif t == "edge_creation":
+ lines.append(f'create edge <{ch["subject"]}> <{ch["predicate"]}> {ch["object"]}')
+ elif t == "edge_deletion":
+ lines.append(f'delete edge <{ch["subject"]}> <{ch["predicate"]}> {ch["object"]}')
+ return "\n".join(lines)
+
+
+def _label_of(triples: set, predicates: set) -> str | None:
+ for p, o in triples:
+ if p in predicates and o.startswith('"'):
+ return o[1:].split('"')[0]
+ return None
+
+
+def kgcl_diff(old: str, new: str, fmt: str = "turtle") -> ChangeSet:
+ """Classify the change from ``old`` to ``new`` into KGCL change records.
+
+ Detected change types: node_creation, node_deletion, node_rename,
+ node_annotation_change, edge_creation, edge_deletion.
+ """
+ old_t, old_s = _parse(old, fmt)
+ new_t, new_s = _parse(new, fmt)
+ cs = ChangeSet()
+
+ subjects = set(old_s) | set(new_s)
+ accounted: set[tuple] = set() # (s,p,o) handled as node/rename/annotation, not raw edge
+
+ for s in sorted(subjects):
+ o_tr = old_s.get(s, set())
+ n_tr = new_s.get(s, set())
+ s_is_node = any(p == RDF_TYPE for p, _ in (n_tr or o_tr))
+
+ if s not in old_s and s in new_s:
+ cs.changes.append({"type": "node_creation", "node": s,
+ "label": _label_of(n_tr, LABEL_PREDICATES)})
+ accounted |= {(s, p, o) for p, o in n_tr}
+ continue
+ if s in old_s and s not in new_s:
+ cs.changes.append({"type": "node_deletion", "node": s,
+ "label": _label_of(o_tr, LABEL_PREDICATES)})
+ accounted |= {(s, p, o) for p, o in o_tr}
+ continue
+
+ # Subject in both: look for label / annotation changes per predicate.
+ for preds, ctype in ((LABEL_PREDICATES, "node_rename"),
+ (ANNOTATION_PREDICATES, "node_annotation_change")):
+ for p in preds:
+ ov = {o for q, o in o_tr if q == p}
+ nv = {o for q, o in n_tr if q == p}
+ if ov != nv and ov and nv:
+ old_v = next(iter(ov)); new_v = next(iter(nv))
+ rec = {"type": ctype, "node": s,
+ "old": old_v.strip('"').split('"@')[0],
+ "new": new_v.strip('"').split('"@')[0]}
+ if ctype == "node_annotation_change":
+ rec["predicate"] = p
+ cs.changes.append(rec)
+ accounted |= {(s, p, old_v), (s, p, new_v)}
+
+ # Remaining raw triple differences become edge creations / deletions.
+ for (s, p, o) in sorted(new_t - old_t):
+ if (s, p, o) not in accounted and p not in LABEL_PREDICATES | ANNOTATION_PREDICATES:
+ cs.changes.append({"type": "edge_creation", "subject": s, "predicate": p, "object": o})
+ for (s, p, o) in sorted(old_t - new_t):
+ if (s, p, o) not in accounted and p not in LABEL_PREDICATES | ANNOTATION_PREDICATES:
+ cs.changes.append({"type": "edge_deletion", "subject": s, "predicate": p, "object": o})
+
+ return cs
diff --git a/python/src/open_ontologies_lite/server.py b/python/src/open_ontologies_lite/server.py
index e2dc30b0..653c94fb 100644
--- a/python/src/open_ontologies_lite/server.py
+++ b/python/src/open_ontologies_lite/server.py
@@ -86,6 +86,20 @@ def onto_lint() -> dict:
return _engine.lint()
+def onto_kgcl_diff(data_a: str, data_b: str, format: str = "turtle") -> dict:
+ """Classify the change from version A to B as KGCL change records.
+
+ Returns structured changes (node_creation/deletion, node_rename,
+ node_annotation_change, edge_creation/deletion), their counts, and a KGCL
+ text rendering. Use for ontology version governance and change logs.
+ """
+ from .kgcl import kgcl_diff
+
+ cs = kgcl_diff(data_a, data_b, format)
+ return {"changes": cs.changes, "counts": cs.counts(), "kgcl": cs.to_kgcl()}
+
+
def main() -> None:
import argparse
diff --git a/python/tests/test_align.py b/python/tests/test_align.py
new file mode 100644
index 00000000..a1bf613e
--- /dev/null
+++ b/python/tests/test_align.py
@@ -0,0 +1,36 @@
+"""AlignmentIndex tests. Skipped unless the [align] extra (hnswlib) is installed.
+
+Run: pip install -e ".[align,dev]" && pytest -q
+"""
+import pytest
+
+hnswlib = pytest.importorskip("hnswlib") # noqa: F841
+
+from open_ontologies_lite import AlignmentIndex # noqa: E402
+
+
+def test_nearest_neighbour_recovers_match():
+ # Three orthogonal-ish concept vectors; query close to the first.
+ idx = AlignmentIndex(dim=3)
+ idx.add("flw:PC-BAK", [1.0, 0.0, 0.0])
+ idx.add("flw:PC-DRY", [0.0, 1.0, 0.0])
+ idx.add("flw:PC-VEG", [0.0, 0.0, 1.0])
+ idx.build()
+ out = idx.query([0.9, 0.1, 0.0], k=2)
+ assert out[0].id == "flw:PC-BAK"
+ assert out[0].score > out[1].score # best candidate ranks first
+ assert 0.0 <= out[0].score <= 1.0
+
+
+def test_dim_mismatch_raises():
+ idx = AlignmentIndex(dim=4)
+ with pytest.raises(ValueError):
+ idx.add("x", [1.0, 2.0, 3.0])
+
+
+def test_len_and_empty_query():
+ idx = AlignmentIndex(dim=2)
+ assert len(idx) == 0
+ assert idx.query([1.0, 0.0]) == []
+ idx.add_many([("a", [1.0, 0.0]), ("b", [0.0, 1.0])])
+ assert len(idx) == 2
diff --git a/python/tests/test_kgcl.py b/python/tests/test_kgcl.py
new file mode 100644
index 00000000..f4b720bb
--- /dev/null
+++ b/python/tests/test_kgcl.py
@@ -0,0 +1,43 @@
+"""KGCL diff tests. Run: pytest -q"""
+
+from open_ontologies_lite import kgcl_diff
+
+V1 = """
+@prefix ex: <http://example.org/> .
+@prefix skos: <http://www.w3.org/2004/02/skos/core#> .
+ex:Apple a skos:Concept ; skos:prefLabel "Apple" ; skos:definition "A pome fruit." ; skos:broader ex:Fruit .
+ex:Pear a skos:Concept ; skos:prefLabel "Pear" ; skos:broader ex:Fruit .
+"""
+
+# Changes vs V1: Pear deleted; Plum created; Apple renamed + definition changed;
+# Apple's broader edge changed Fruit -> PomeFruit.
+V2 = """
+@prefix ex: <http://example.org/> .
+@prefix skos: <http://www.w3.org/2004/02/skos/core#> .
+ex:Apple a skos:Concept ; skos:prefLabel "Apple (Malus)" ; skos:definition "A pome fruit of Malus." ; skos:broader ex:PomeFruit .
+ex:Plum a skos:Concept ; skos:prefLabel "Plum" ; skos:broader ex:Fruit .
+"""
+
+
+def test_kgcl_change_types():
+ cs = kgcl_diff(V1, V2)
+ types = {c["type"] for c in cs.changes}
+ assert "node_creation" in types # Plum
+ assert "node_deletion" in types # Pear
+ assert "node_rename" in types # Apple label
+ assert "node_annotation_change" in types # Apple definition
+ assert "edge_creation" in types or "edge_deletion" in types # broader moved
+
+
+def test_kgcl_counts_and_text():
+ cs = kgcl_diff(V1, V2)
+ counts = cs.counts()
+ assert counts.get("node_creation") == 1
+ assert counts.get("node_deletion") == 1
+ text = cs.to_kgcl()
+ assert "create node" in text and "delete node" in text and "rename" in text
+
+
+def test_kgcl_identical_is_empty():
+ cs = kgcl_diff(V1, V1)
+ assert cs.changes == []