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.

13.9 KB
Raw Blame
"""Lightweight ontology engine over a prebuilt Oxigraph store.

No compilation, no native build step: pyoxigraph ships the Oxigraph engine as a
prebuilt wheel, so everything here is pure Python glue around it. This module is
deliberately MCP-free so it can be unit-tested in isolation; server.py wires it
to the MCP transport.
"""

from __future__ import annotations

from dataclasses import dataclass
from pathlib import Path

import pyoxigraph as ox

# Map friendly format names to Oxigraph RdfFormat values.
_FORMATS = {
    "turtle": ox.RdfFormat.TURTLE,
    "ttl": ox.RdfFormat.TURTLE,
    "ntriples": ox.RdfFormat.N_TRIPLES,
    "nt": ox.RdfFormat.N_TRIPLES,
    "nquads": ox.RdfFormat.N_QUADS,
    "nq": ox.RdfFormat.N_QUADS,
    "trig": ox.RdfFormat.TRIG,
    "rdfxml": ox.RdfFormat.RDF_XML,
    "rdf": ox.RdfFormat.RDF_XML,
    "xml": ox.RdfFormat.RDF_XML,
    "n3": ox.RdfFormat.N3,
    "jsonld": ox.RdfFormat.JSON_LD,
    # The W3C media-type registration and most other tooling, rdflib included,
    # spell it with the hyphen. Taking only "jsonld" rejected a correct name.
    "json-ld": ox.RdfFormat.JSON_LD,
    "json": ox.RdfFormat.JSON_LD,
}

OWL_CLASS = "http://www.w3.org/2002/07/owl#Class"
RDFS_CLASS = "http://www.w3.org/2000/01/rdf-schema#Class"
RDF_PROPERTY = "http://www.w3.org/1999/02/22-rdf-syntax-ns#Property"
_PROPERTY_TYPES = (RDF_PROPERTY,) + tuple(
    "http://www.w3.org/2002/07/owl#" + name
    for name in ("ObjectProperty", "DatatypeProperty", "AnnotationProperty")
)
_PROPERTY_VALUES = " ".join(f"<{iri}>" for iri in _PROPERTY_TYPES)
_SCHEMA_TYPES = (OWL_CLASS, RDFS_CLASS) + _PROPERTY_TYPES


def resolve_format(name: str) -> ox.RdfFormat:
    key = name.strip().lower().lstrip(".")
    if key not in _FORMATS:
        raise ValueError(
            f"unknown format {name!r}; supported: {', '.join(sorted(set(_FORMATS)))}"
        )
    return _FORMATS[key]


@dataclass
class ValidationResult:
    ok: bool
    triples: int
    error: str | None = None


class OntologyEngine:
    """A single in-memory ontology store with the core lifecycle operations."""

    def __init__(self) -> None:
        self.store = ox.Store()

    # ---- validation -------------------------------------------------------
    @staticmethod
    def validate(data: str, fmt: str = "turtle") -> ValidationResult:
        """Parse RDF without loading it; report syntax validity and triple count."""
        rdf_format = resolve_format(fmt)
        try:
            count = sum(1 for _ in ox.parse(data.encode("utf-8"), format=rdf_format))
        except (SyntaxError, ValueError) as exc:
            return ValidationResult(ok=False, triples=0, error=str(exc))
        return ValidationResult(ok=True, triples=count)

    # ---- load / clear -----------------------------------------------------
    def load(self, data: str, fmt: str = "turtle") -> int:
        """Load RDF text into the store; return total triple count afterwards."""
        self.store.load(data.encode("utf-8"), format=resolve_format(fmt))
        return len(self.store)

    def load_path(self, path: str, fmt: str | None = None) -> int:
        p = Path(path)
        rdf_format = resolve_format(fmt) if fmt else ox.RdfFormat.from_extension(p.suffix.lstrip("."))
        if rdf_format is None:
            raise ValueError(f"cannot infer format from {path!r}; pass fmt explicitly")
        self.store.load(path=str(p), format=rdf_format)
        return len(self.store)

    def load_rows(
        self,
        rows_or_df,
        base_iri: str = "http://example.org/data/",
        class_iri: str | None = None,
        id_column: str | None = None,
    ) -> int:
        """Load tabular rows (or any dataframe-like object — fenic, polars,
        pandas, pyarrow) into the store as RDF; return total triple count."""
        from .dataframe import rows_from_dataframe, rows_to_turtle

        rows = rows_from_dataframe(rows_or_df)
        ntriples = rows_to_turtle(rows, base_iri=base_iri, class_iri=class_iri, id_column=id_column)
        return self.load(ntriples, "ntriples")

    def clear(self) -> None:
        self.store.clear()

    # ---- stats ------------------------------------------------------------
    def stats(self) -> dict[str, int]:
        return {
            "triples": len(self.store),
            "classes": self._count(
                f"SELECT (COUNT(DISTINCT ?c) AS ?n) WHERE {{ ?c a ?t "
                f"VALUES ?t {{ <{OWL_CLASS}> <{RDFS_CLASS}> }} }}"
            ),
            "properties": self._count(
                f"SELECT (COUNT(DISTINCT ?p) AS ?n) WHERE {{ ?p a ?t VALUES ?t {{ {_PROPERTY_VALUES} }} }}"
            ),
            "individuals": self._count(
                "SELECT (COUNT(DISTINCT ?i) AS ?n) WHERE { ?i a ?t "
                "FILTER(?t NOT IN (" + ", ".join(f"<{iri}>" for iri in _SCHEMA_TYPES) + ")) }"
            ),
        }

    def _count(self, sparql: str) -> int:
        for sol in self.store.query(sparql):
            return int(sol["n"].value)
        return 0

    # ---- query ------------------------------------------------------------
    def query(self, sparql: str) -> dict:
        """Run SPARQL. Returns a typed dict for SELECT / ASK / CONSTRUCT/DESCRIBE."""
        result = self.store.query(sparql)
        if isinstance(result, ox.QueryBoolean):
            return {"type": "boolean", "boolean": bool(result)}
        if isinstance(result, ox.QuerySolutions):
            var_objs = list(result.variables)
            names = [str(v).lstrip("?") for v in var_objs]
            rows = []
            for sol in result:
                row = {}
                for name, var in zip(names, var_objs):
                    term = sol[var]
                    row[name] = _query_value(term)
                rows.append(row)
            return {"type": "table", "variables": names, "rows": rows}
        # QueryTriples (CONSTRUCT / DESCRIBE)
        triples = [
            {"subject": _query_value(t.subject), "predicate": _query_value(t.predicate),
             "object": _query_value(t.object)}
            for t in result
        ]
        return {"type": "graph", "triples": triples}

    # ---- save / convert ---------------------------------------------------
    def save(self, path: str, fmt: str | None = None) -> str:
        p = Path(path)
        rdf_format = resolve_format(fmt) if fmt else ox.RdfFormat.from_extension(p.suffix.lstrip("."))
        if rdf_format is None:
            raise ValueError(f"cannot infer format from {path!r}; pass fmt explicitly")
        _dump(self.store, str(p), rdf_format)
        return str(p)

    def dump(self, fmt: str = "turtle") -> str:
        """Serialize the loaded store to a string (needed to hand it to pySHACL)."""
        out = _dump(self.store, None, resolve_format(fmt))
        return out.decode("utf-8") if isinstance(out, (bytes, bytearray)) else str(out)

    @staticmethod
    def convert(data: str, from_fmt: str, to_fmt: str) -> str:
        tmp = ox.Store()
        tmp.load(data.encode("utf-8"), format=resolve_format(from_fmt))
        out = _dump(tmp, None, resolve_format(to_fmt))
        return out.decode("utf-8") if isinstance(out, (bytes, bytearray)) else str(out)

    # ---- diff -------------------------------------------------------------
    @staticmethod
    def diff(data_a: str, data_b: str, fmt: str = "turtle") -> dict:
        """Triple-level diff between two ontologies (added/removed vs A→B)."""
        rdf_format = resolve_format(fmt)
        a = {_triple_key(t) for t in ox.parse(data_a.encode("utf-8"), format=rdf_format)}
        # Reuse parsed blank-node identities for the same input document.
        b = a if data_a == data_b else {
            _triple_key(t) for t in ox.parse(data_b.encode("utf-8"), format=rdf_format)
        }
        return {
            "added": sorted(b - a),
            "removed": sorted(a - b),
            "added_count": len(b - a),
            "removed_count": len(a - b),
            "unchanged_count": len(a & b),
        }

    # ---- lint -------------------------------------------------------------
    def lint(self) -> dict:
        """Cheap structural hygiene checks: missing labels, domains, ranges."""
        missing_labels = self._terms(
            f"SELECT DISTINCT ?c WHERE {{ ?c a ?t VALUES ?t {{ <{OWL_CLASS}> <{RDFS_CLASS}> }} "
            "FILTER NOT EXISTS {{ ?c <http://www.w3.org/2000/01/rdf-schema#label> ?l }} }"
        )
        missing_domain = self._terms(
            f"SELECT DISTINCT ?p WHERE {{ ?p a ?t VALUES ?t {{ {_PROPERTY_VALUES} }} "
            "FILTER NOT EXISTS {{ ?p <http://www.w3.org/2000/01/rdf-schema#domain> ?d }} }"
        )
        missing_range = self._terms(
            f"SELECT DISTINCT ?p WHERE {{ ?p a ?t VALUES ?t {{ {_PROPERTY_VALUES} }} "
            "FILTER NOT EXISTS {{ ?p <http://www.w3.org/2000/01/rdf-schema#range> ?r }} }"
        )
        issues = (
            [{"rule": "missing-label", "term": t} for t in missing_labels]
            + [{"rule": "missing-domain", "term": t} for t in missing_domain]
            + [{"rule": "missing-range", "term": t} for t in missing_range]
        )
        return {"issue_count": len(issues), "issues": issues}

    def _terms(self, sparql: str) -> list[str]:
        result = self.store.query(sparql)
        var = result.variables[0]
        out = []
        for sol in result:
            val = sol[var]
            if val is not None:
                out.append(val.value)
        return out

    # ---- certified reasoning ----------------------------------------------
    def reason_horn(
        self,
        certificate_dir: str,
        *,
        rules=None,
        graphs: str | list[str] = "default",
        check: bool = True,
        checker: str | None = None,
        timeout: float = 120.0,
        max_iterations: int | None = None,
    ) -> dict:
        """Derive the closure of a Horn rule table over the loaded store and
        write a certificate the proved-sound Lean checker in `lean/` verifies.

        With `rules=None` this runs the BUILT-IN table, whose bytes are shipped
        with the package and written verbatim. That is the only table that can
        earn the absolute verdict, and `oo-horn` decides whether it did. Pass a
        path or a list of `RulePattern` to run a table you wrote: those rules are
        ASSUMED and never checked, so a certificate over them holds only in
        models of the asserted graph that ALSO satisfy them. A rule saying every
        supplier is compliant produces certificates that check green for ever.

        Nothing is materialised. A conclusion drawn under a supplied rule table
        holds only in models that satisfy that table, so it is not written into
        the store beside the assertions; the certificate is the output of the
        run.

        `check=False` writes the certificate and does not run the checker. The
        returned report then says `not_requested` and carries no verdict, exactly
        as it does when the checker is not installed.
        """
        from .horn.certify import CertificateUnreadable, check_horn
        from .horn.reason import run_horn
        from .horn.rules import RulePattern, parse_rules

        source = None
        if rules is None:
            table = None
        elif isinstance(rules, (str, Path)):
            path = Path(rules)
            table = parse_rules(path.read_text(encoding="utf-8"))
            source = str(path)
        else:
            table = list(rules)
            for r in table:
                if not isinstance(r, RulePattern):
                    raise TypeError(
                        f"rules must be a path or a sequence of RulePattern, got "
                        f"{type(r).__name__}"
                    )
        result = run_horn(
            self.store,
            table,
            certificate_dir=certificate_dir,
            graphs=graphs,
            max_iterations=max_iterations,
            rules_source=source,
        )
        report = result.to_dict()
        if not check:
            report["check"] = {
                "status": "not_requested",
                "checked": False,
                "verdict": None,
                "pronounced_by": None,
                "check_with": report["certificate"]["check_with"],
                "warning": (
                    "the certificate was written and NOT checked, because check=False. "
                    "Nothing here has been proved; these are the claims of an untrusted "
                    "engine"
                ),
            }
            return report
        outcome = check_horn(certificate_dir, checker=checker, timeout=timeout)
        report["check"] = outcome
        if outcome["status"] == "unreadable":
            # This method wrote the three files itself, so a checker that cannot
            # read or parse them is an emitter bug and not a data problem. Folding
            # it into the missing-binary branch is how such a bug gets mistaken
            # for an uninstalled checker and never investigated.
            raise CertificateUnreadable(
                f"{outcome['check_with']} could not read the certificate this run had "
                f"just written, which is a defect in this emitter and not a rejection: "
                f"{outcome['error']}"
            )
        return report


def _query_value(term) -> str | None:
    """Keep scalar query values; spell RDF triple terms that have no .value."""
    if term is None:
        return None
    return str(term) if isinstance(term, ox.Triple) else term.value


def _triple_key(t) -> str:
    tr = getattr(t, "triple", t)
    return f"{tr.subject} {tr.predicate} {tr.object}"


def _dump(store: ox.Store, output, rdf_format: ox.RdfFormat):
    """Dump a store, selecting the default graph for triples-only formats.

    A Store holds quads, so dumping to a dataset-incapable format (N-Triples,
    Turtle, RDF/XML, N3) requires naming a single graph to flatten.
    """
    if not rdf_format.supports_datasets:
        return store.dump(output=output, format=rdf_format, from_graph=ox.DefaultGraph())
    return store.dump(output=output, format=rdf_format)