Implementation: P1.2 Knowledge Graph Reasoning (Offline OWL RL Materialization)

Scope

Offline reasoning + validation + artifact publishing pipeline that works locally and in CI, with minimal runtime changes (load precomputed inferred triples). Runtime inference stays rdfs, SHACL remains pyshacl, and offline reasoning is forward-chaining (OWL RL subset via Jena OWL Mini reasoner).

Non-negotiable constraints (project-aligned)

• No runtime behavior change beyond loading precomputed inferred triples.
• Runtime inference stays rdfs (current default in pyshacl and existing adapters).
• Offline reasoning is forward-chaining materialization (no query-time entailment).
• Use containerized tooling for OWL reasoning (avoid Java on dev machines).
• Deterministic output with stable ordering and hashes.
• Prevent scaling hazards (e.g., owl:sameAs blowups) via rule restrictions and guardrails.

Inputs

• Ontology TBox: ontologies/sea-debt.ttl (including imports if present).
• SHACL shapes: ontologies/sea-shapes.v1.shacl (fallback ontologies/sea-shapes.shacl).
• ABox data: RDF triples derived from SEA IR via tools/ir_to_kgs.py (explicit export handled by tools/kg_export_explicit.py).

Outputs (artifacts)

Generated under artifacts/kg/<GIT_SHA>/:

• explicit.nq (all explicit triples)
• inferred.nq (inferred only)
• merged.nq (explicit + inferred)
• manifest.json (git SHA, timestamp, inputs, sha256, triple counts, shapes version, ontology version IRI)
• shacl_report.json (pyshacl report)

Implementation (current)

• Explicit export: tools/kg_export_explicit.py
• OWL RL materialization: tools/kg-reasoner/Dockerfile (Jena 4.10.0, OWL Mini reasoner)
• SHACL validation: tools/kg_validate.py (N-Quads supported)
• Manifest generation: tools/kg_manifest.py
• Drift warning: tools/kg_drift_check.py (warn-only against baselines/kg/inferred.nq)
• Entry point: scripts/reason_materialize.sh and just reason-materialize

Local usage

Run end-to-end pipeline:

1
just reason-materialize

Optional environment overrides:

• KG_CTX (default: governance-runtime)
• KG_IR_PATH (explicit IR path override)
• KG_ONTOLOGY_PATH (default: ontologies/sea-debt.ttl)
• KG_SHAPES_PATH (default: ontologies/sea-shapes.v1.shacl)
• KG_SHAPES_VERSION (default: v1)
• KG_ARTIFACT_ROOT (default: artifacts/kg)
• KG_REASONER_IMAGE (default: sea-kg-reasoner:jena-4.10.0)
• KG_INFERRED_MAX_MULTIPLIER (default: 10)
• KG_REASONER_ALLOW_SAME_AS (default: false)

Runtime loading support

The Knowledge Graph service loads precomputed artifacts when configured:

• KG_ARTIFACT_DIR → load merged.nq from artifact directory (or explicit.nq + inferred.nq)
• KG_LOAD_MERGED_PATH → load a specific merged.nq

Startup logs include triple counts per file and the manifest.json sha256 if present.

CI integration

• CI job runs just reason-materialize.
• Artifacts under artifacts/kg/<sha>/ are uploaded.
• SHACL violations fail the job.
• Drift check runs in warn-only mode against baselines/kg/inferred.nq.

Determinism and guardrails

• All artifact files are lexically sorted (LC_ALL=C sort).
• owl:sameAs statements fail reasoning by default unless explicitly allowed.
• Inferred triples are capped by KG_INFERRED_MAX_MULTIPLIER to prevent runaway growth.