Run deduplication, conflict resolution, merges, or any graph modification. The version manager tracks nothing automatically: you control when snapshots are taken.
Snapshot before every destructive operation. Call manager.create_snapshot() before running deduplication, conflict resolution, or merge operations. restore_snapshot() is only possible if a snapshot exists before the change.
# List all versions: returns List[Dict] with label, author, timestamp, checksum, entity_countversions = manager.list_versions()for v in versions: print(v["label"], "|", v["author"], "|", v["timestamp"], "|", v["checksum"][:8], "...")# Retrieve a specific version (returns full snapshot dict)snapshot = manager.get_version("v1.0")
Use diff() for code review and incident investigation.manager.diff("v1.0", "v2.0") returns a plain dict with "summary", "entities_added", "entities_removed", and "entities_modified": use the "summary" sub-dict to get counts and "entities_modified" to inspect property-level changes.
diff() return schema
# diff() / compare_versions() returns a plain dict:{ "version1": str, # first version label "version2": str, # second version label "summary": { "entities_added": int, "entities_removed": int, "entities_modified": int, "relationships_added": int, "relationships_removed": int, "relationships_modified": int, # also present as nodes_*/edges_* aliases }, "entities_added": List[Dict], # full entity dicts "entities_removed": List[Dict], "entities_modified": List[Dict], # {id, before, after, changes} "relationships_added": List[Dict], "relationships_removed": List[Dict], "relationships_modified": List[Dict], # {key, before, after, changes} # node_*/edge_* aliases point to the same lists}
from semantica.change_management import SQLiteVersionStorage, TemporalVersionManager# Pass path directly to the manager (recommended)manager = TemporalVersionManager(storage_path="versions.db")
Persists all version history to disk. Survives process restarts. Recommended for any environment where you need to retain the audit trail.
from semantica.change_management import InMemoryVersionStorage, TemporalVersionManager# Default (no storage_path) uses in-memory storage automaticallymanager = TemporalVersionManager()
Fast and zero-setup. Data is not persisted: all version history is lost when the process exits. Use this for unit tests and development only.
The default TemporalVersionManager() with no arguments uses in-memory storage. Always pass storage_path="versions.db" or an explicit SQLiteVersionStorage in production: otherwise your entire version history disappears on restart.
Use SQLiteVersionStorage in production. The default in-memory storage loses all version history when the process exits. Pass storage_path="versions.db" to TemporalVersionManager or create SQLiteVersionStorage(db_path="versions.db") explicitly.
SHA-256 checksums detect any unauthorized modification to a graph between snapshots:
from semantica.change_management import compute_checksum, verify_checksum# Compute a checksum for any dictchecksum = compute_checksum({"nodes": [], "edges": []})# verify_checksum takes the snapshot dict directly.# It reads the "checksum" key from the snapshot and recomputes to compare.snapshot = manager.get_version("v1.0")is_valid = verify_checksum(snapshot)if not is_valid: raise RuntimeError("Snapshot has been tampered with")
verify_checksum takes the full snapshot dict (which contains the stored "checksum" key). Pass the dict returned by create_snapshot or get_version directly: no separate expected_checksum argument is needed.
ChangeLogEntry is the internal metadata object created inside create_snapshot. It validates the author (must be a valid email address) and description (non-empty, max 500 characters) before the snapshot is stored.
from semantica.change_management.change_log import ChangeLogEntry# Create using current timestampentry = ChangeLogEntry.create_now( author="user@example.com", # must be a valid email description="Initial snapshot" # max 500 chars, non-empty)print(entry.timestamp) # ISO 8601 timestampprint(entry.author) # "user@example.com"print(entry.description) # "Initial snapshot"
ChangeLogEntry schema
@dataclassclass ChangeLogEntry: timestamp: str # ISO 8601 timestamp author: str # valid email address (validated on init) description: str # change description, max 500 chars change_id: Optional[str] # optional unique identifier related_changes: List[str] # optional list of related change IDs
All version snapshots form a tamper-evident audit trail. Use list_versions() and diff() to reconstruct and review changes for regulatory purposes:
from semantica.change_management import TemporalVersionManagermanager = TemporalVersionManager(storage_path="versions.db")# Enumerate the full version historyfor v in manager.list_versions(): print(v["timestamp"], "|", v["author"], "|", v["label"], "|", v["description"])# Diff any two snapshots for a change reportdiff = manager.diff("v1.0", "v2.0")s = diff["summary"]print("Added: %d | Removed: %d | Modified: %d" % ( s["entities_added"], s["entities_removed"], s["entities_modified"]))
Use list_versions() and diff() for compliance reviews.manager.list_versions() returns a list of metadata dicts (with label, author, timestamp, checksum). Run verify_checksum(snapshot) on the dict returned by get_version() to confirm integrity before any export.
Use verify_checksum() before any compliance export to confirm snapshot integrity:
from semantica.change_management import verify_checksumsnapshot = manager.get_version("v1.0")is_valid = verify_checksum(snapshot)if not is_valid: raise RuntimeError("Snapshot has been modified since it was recorded")
Per-node mutation history is available for HIPAA subject-access and SOX audit workflows:
# Get full mutation history for a specific nodehistory = manager.get_node_history("patient_001")for record in history: print(record["timestamp"], record["operation"], record["version_label"])
Use manager.get_node_history("patient_001") to retrieve every recorded mutation on a patient entity. Each MutationRecord includes timestamp, operation, entity_id, payload, and version_label. The SHA-256 checksum on each snapshot proves the record has not been altered.
SOX: quarterly reviews
Use manager.list_versions() to enumerate all snapshots and manager.diff(v1, v2) to scope the change report to the relevant quarter. The immutable snapshot chain provides the chain of custody required by SOX Section 404.
GDPR: right to erasure verification
After deleting a data subject’s entities, snapshot the graph and diff against the pre-deletion snapshot. diff["entities_removed"] provides a machine-readable record of exactly what was deleted and when, satisfying Article 17 documentation requirements.
FDA 21 CFR Part 11: electronic records
Every snapshot dict includes author, timestamp, and checksum: the three fields required for a compliant electronic record. verify_checksum(snapshot) provides the tamper-evidence required by 21 CFR § 11.10(e).
