Semantic Diff¶
trails.kg_diff provides git-style change tracking for knowledge graphs. Compare
two KG states -- either live store instances or N-Triples serializations -- and get
a structured KGDiff with added, removed, and modified triples. Format the diff as
a human-readable table, replayable SPARQL UPDATE, or machine-readable JSON.
No AI/LLM dependency. No external libraries beyond the Trails kernel.
See ADR-0036 for the full design rationale.
Quick start¶
from trails.kg_diff import diff_stores, diff_snapshots, format_diff
# Compare two live store instances
diff = diff_stores(store_a, store_b, trace_id="my-diff")
print(format_diff(diff, fmt="table"))
# 2 added, 1 removed, 1 modified, 42 unchanged
# Compare two N-Triples strings (e.g. from `trails kg dump --format nt`)
diff = diff_snapshots(snapshot_before, snapshot_after)
# Render as replayable SPARQL (apply to store_a to get store_b)
print(format_diff(diff, fmt="sparql"))
# DELETE DATA { ... } ;
# INSERT DATA { ... }
# Machine-readable JSON for CI pipelines
print(format_diff(diff, fmt="json"))
Key types¶
| Type | Description |
|---|---|
KGDiff |
Structured delta: added, removed (triple lists), modified (field-level changes), summary (counts) |
API¶
| Function | Signature | Description |
|---|---|---|
diff_stores |
(store_a, store_b, *, graph=None, trace_id="diff") -> KGDiff |
Compare two live store instances |
diff_snapshots |
(snapshot_a: str, snapshot_b: str) -> KGDiff |
Compare two N-Triples serializations |
format_diff |
(diff, fmt="table") -> str |
Render as "table", "sparql", or "json" |