Skip to content

Graph-Native Infrastructure for Context and Accountable AI Systems

5.8 KB
Raw Blame
"""Verification of Semantica's RDF exports.

Three checks a generation pipeline cannot run on itself, in the order that a
failure in one makes the next meaningless:

1. **Syntax, strictly.** Whether the output is RDF 1.1 at all. rdflib is lenient
   by design and will resolve a relative reference like ``<Acme Corp>`` against
   the file location, producing a ``file://`` IRI and a warning rather than an
   error, so a graph can "load" and still be nothing like what was meant.
   Oxigraph refuses it, which is the answer you want before publishing.

2. **Vocabulary, closed-world.** Whether the terms used were declared. RDF is
   open-world, so an invented predicate is unknown rather than wrong and passes
   both parsing and SHACL untouched. Closing the world against a declared
   vocabulary is the only way to separate a real term from a plausible one, and
   it is exactly the check an extraction pipeline needs, because inventing
   plausible terms is what extractors do when they are unsure.

3. **Shapes, with an audit of what was examined.** Whether constraints held, and
   how many nodes they held over. A shapes graph whose targets are absent from
   the data reports conformance having checked nothing, and that report is
   indistinguishable from a real pass. Every verdict here carries the focus-node
   count behind it.

Runs on ``open-ontologies-lite``, a pure-Python package over the Oxigraph engine.
No Rust toolchain, no service to run, no network.
"""

from __future__ import annotations

from dataclasses import dataclass, field
from typing import Any


@dataclass
class VerificationReport:
    """What an independent engine says about an export."""

    parses: bool
    triples: int = 0
    parse_error: str | None = None

    undeclared_terms: list[str] = field(default_factory=list)
    vocabulary_checked: bool = False

    conforms: bool | None = None
    violations: list[dict] = field(default_factory=list)
    focus_nodes: int | None = None
    unmatched_shapes: list[dict] = field(default_factory=list)

    @property
    def ok(self) -> bool:
        """True only when every check that ran gave a positive answer.

        A withheld SHACL verdict (``conforms is None``) is not a pass. Nothing
        was examined, so there is nothing to pass.
        """
        if not self.parses:
            return False
        if self.undeclared_terms:
            return False
        if self.conforms is False or (self.conforms is None and self.unmatched_shapes):
            return False
        return True

    def summary(self) -> str:
        if not self.parses:
            return f"not valid RDF: {self.parse_error}"
        parts = [f"{self.triples} triples"]
        if self.undeclared_terms:
            parts.append(f"{len(self.undeclared_terms)} undeclared term(s)")
        elif self.vocabulary_checked:
            parts.append("vocabulary clean")
        if self.conforms is False:
            parts.append(f"{len(self.violations)} SHACL violation(s)")
        elif self.conforms is None and self.unmatched_shapes:
            parts.append(
                f"SHACL verdict withheld: {len(self.unmatched_shapes)} shape(s) "
                f"matched nothing"
            )
        elif self.conforms is True:
            parts.append(f"conforms over {self.focus_nodes} focus node(s)")
        return ", ".join(parts)

    def to_dict(self) -> dict[str, Any]:
        return {
            "ok": self.ok,
            "parses": self.parses,
            "triples": self.triples,
            "parse_error": self.parse_error,
            "undeclared_terms": self.undeclared_terms,
            "conforms": self.conforms,
            "focus_nodes": self.focus_nodes,
            "unmatched_shapes": self.unmatched_shapes,
            "violations": self.violations,
            "summary": self.summary(),
        }


class VerificationError(RuntimeError):
    """Raised when a verified export would have written something unsound."""

    def __init__(self, report: VerificationReport):
        self.report = report
        super().__init__(report.summary())


def verify_rdf(
    rdf: str,
    *,
    fmt: str = "turtle",
    ontology: str | None = None,
    shapes: str | None = None,
    policed_namespaces: list[str] | None = None,
) -> VerificationReport:
    """Verify an RDF string and report what an independent engine finds.

    `ontology` enables the closed-world vocabulary check. Without it, or without
    `policed_namespaces`, that check is skipped rather than passed: there is
    nothing to check against, and a green light from an empty vocabulary is the
    failure the check exists to prevent.

    `shapes` enables SHACL. It needs `open-ontologies-lite[shacl]`.
    """
    from open_ontologies_lite import OntologyEngine, vocab_check

    report = VerificationReport(parses=False)

    # 1. Strict RDF 1.1 syntax.
    result = OntologyEngine.validate(rdf, fmt)
    report.parses = result.ok
    report.triples = result.triples
    report.parse_error = result.error
    if not result.ok:
        # Nothing downstream can be trusted about a graph that did not parse.
        return report

    # 2. Closed-world vocabulary.
    if ontology and policed_namespaces:
        vocab = vocab_check(
            ontology,
            rdf,
            data_format=fmt,
            extra_namespaces=policed_namespaces,
        )
        report.vocabulary_checked = "warning" not in vocab
        report.undeclared_terms = vocab["undeclared_terms"]

    # 3. Shapes, with the focus-node audit.
    if shapes:
        from open_ontologies_lite.shacl import shacl_validate

        shacl = shacl_validate(rdf, shapes, data_format=fmt)
        report.conforms = shacl["conforms"]
        report.violations = shacl["violations"]
        report.focus_nodes = shacl["focus_nodes"]
        report.unmatched_shapes = shacl["unmatched_shapes"]

    return report