Plan, apply and roll back changes to a production ontology, with a blast radius report and a proof an auditor can re-check.
Rust ai-nativedescription-logicsformal-verificationinfrastructure-as-codeisabelle-languageknowledge-graphleanlean4mcpmcp-serverontologyowlowl2reasoningrustshaclsparqltheorem-proving
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.mdindex 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 enginediff --git a/python/pyproject.toml b/python/pyproject.tomlindex 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__.pyindex 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+ passdiff --git a/python/src/open_ontologies_lite/align.py b/python/src/open_ontologies_lite/align.pynew file mode 100644index 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.pynew file mode 100644index 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 csdiff --git a/python/src/open_ontologies_lite/server.py b/python/src/open_ontologies_lite/server.pyindex 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 argparsediff --git a/python/tests/test_align.py b/python/tests/test_align.pynew file mode 100644index 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) == 2diff --git a/python/tests/test_kgcl.py b/python/tests/test_kgcl.pynew file mode 100644index 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 == []