quickstart.py

"""Minimal, runnable demo of the ontology-edit enforcement gate.

    python examples/minimal/quickstart.py

Shows, all in-process with NO heavy dependency (rdflib / pyshacl not required):

* a missing verbatim sign-off BLOCKS in enforce mode (and only WARNS in advisory);
* a substanceless ("ok") rationale BLOCKS — the >= 50-char substance floor;
* a valid verbatim + an injected SHACL pass + an injected phase pass ALLOWS;
* an injected SHACL violation BLOCKS even with a perfect rationale;
* a documented OVERRIDE bypasses the block, logged loudly.

The SHACL-conformance and phase-completion checks are injected here as tiny
callables. In production you wire those seams to a SHACL toolkit and a phase
tracker (see docs/FORKING.md); the gate's logic is identical either way.
"""
from owl_sop_enforcement_gate import (
    GateBlocked,
    OntologyEditGate,
    ShaclResult,
)

GOOD_VERBATIM = (
    "Approved this ontology change after confirming it conforms to the shapes "
    "graph and keeps the reasoner consistent."
)

# Injected seams (deterministic; no heavy deps).
pass_shacl = lambda data, shapes=None: ShaclResult(status="ok")
violate_shacl = lambda data, shapes=None: ShaclResult(status="violations", violation_count=2)
pass_phase = lambda change_set, mutation: (True, [])


def main() -> None:
    # 1. enforce mode, missing verbatim -> BLOCKS.
    gate = OntologyEditGate(mode="enforce", shacl_check=pass_shacl, phase_check=pass_phase)
    try:
        gate.enforce("ontology/core.ttl")
        print("1. missing verbatim (enforce) -> ALLOWED (unexpected!)")
    except GateBlocked as exc:
        print("1. missing verbatim (enforce) -> BLOCKED: {0}".format(exc.decision.reasons[0][:60]))

    # 2. advisory mode, same edit -> WARNS + ALLOWS.
    advisory = OntologyEditGate(mode="advisory", shacl_check=pass_shacl, phase_check=pass_phase)
    d2 = advisory.enforce("ontology/core.ttl")  # prints an ADVISORY line to stderr
    print("2. missing verbatim (advisory) -> allowed={0} (warned, not blocked)".format(d2.allowed is False))

    # 3. substanceless verbatim -> BLOCKS (the quality floor).
    try:
        gate.enforce("config/settings.json", verbatim_response="ok")
        print("3. 'ok' verbatim -> ALLOWED (unexpected!)")
    except GateBlocked as exc:
        print("3. 'ok' verbatim -> BLOCKED (substance floor): {0}".format(exc.decision.reasons[0][:48]))

    # 4. valid verbatim + SHACL pass + phase pass -> ALLOWS.
    d4 = gate.enforce("ontology/core.ttl", verbatim_response=GOOD_VERBATIM)
    print("4. valid edit                 -> outcome=allowed shacl={0}".format(d4.shacl_status))

    # 5. injected SHACL violation -> BLOCKS even with a perfect rationale.
    strict = OntologyEditGate(
        mode="enforce", shacl_check=violate_shacl, phase_check=pass_phase, shapes_graph_path="shapes.ttl"
    )
    try:
        strict.enforce("ontology/core.ttl", verbatim_response=GOOD_VERBATIM)
        print("5. SHACL violation -> ALLOWED (unexpected!)")
    except GateBlocked as exc:
        print("5. SHACL violation            -> BLOCKED ({0} violations)".format(exc.decision.shacl_violation_count))

    # 6. documented override -> ALLOWS, logged loudly.
    d6 = strict.enforce(
        "ontology/core.ttl",
        verbatim_response=GOOD_VERBATIM,
        override=True,
        override_reason="emergency hotfix authorized by the on-call lead",
    )
    print("6. override                   -> bypassed the block (logged); allowed-finding={0}".format(d6.allowed))


if __name__ == "__main__":
    main()