Change Management¶

Enterprise-grade version control and audit trails for knowledge graphs and ontologies with data integrity verification

Overview¶

The Semantica change management module provides enterprise-grade version control, audit trails, and compliance tracking for knowledge graphs and ontologies. Designed for high-stakes domains where every change must be tracked, verified, and auditable with complete data integrity guarantees.

Key Features¶

• ✅ Enterprise Version Control — Complete snapshot management with SHA-256 integrity verification
• ✅ Dual Storage Backends — InMemory (development) and SQLite (production) with ACID guarantees
• ✅ Knowledge Graph Versioning — Entity and relationship-level change tracking with detailed diffs
• ✅ Ontology Versioning — Structural change tracking for classes, properties, and axioms
• ✅ Audit Trail Compliance — Complete change logs with author attribution and timestamps
• ✅ Data Integrity — SHA-256 checksums for tamper detection and verification
• ✅ Change Comparison — Detailed diff algorithms for entities, relationships, and ontology structures
• ✅ Backward Compatibility — Legacy support for existing ontology version management

Quick Start¶

from semantica.change_management import TemporalVersionManager

# Initialize version manager
manager = TemporalVersionManager(storage_path="versions.db")

# Create versioned snapshot
snapshot = manager.create_snapshot(
    graph={"entities": [...], "relationships": [...]},
    version_label="v1.0",
    author="user@example.com",
    description="Initial knowledge graph"
)

# Compare versions
diff = manager.compare_versions("v1.0", "v2.0")

What this does: - Initializes version manager with persistent SQLite storage - Creates a versioned snapshot of knowledge graph data - Compares two versions to detect changes - Provides complete audit trail with author attribution

Core Components¶

ChangeLogEntry¶

Standardized metadata for tracking version changes with validation.

from semantica.change_management import ChangeLogEntry

@dataclass
class ChangeLogEntry:
    timestamp: str          # ISO 8601 format
    author: str             # Email address
    description: str        # Max 500 characters
    change_id: Optional[str] = None

Key Method: - create_now(author, description, change_id=None) - Create entry with current timestamp

Storage Backends¶

InMemoryVersionStorage¶

Fast, volatile storage for development and testing.

from semantica.change_management import InMemoryVersionStorage

storage = InMemoryVersionStorage()

SQLiteVersionStorage¶

Persistent storage with ACID guarantees for production.

from semantica.change_management import SQLiteVersionStorage

storage = SQLiteVersionStorage("versions.db")

VersionStorage (Abstract)¶

Base interface for custom storage implementations.

Core Methods: - save(snapshot) - Store version snapshot - get(label) - Retrieve by version label - list_all() - List all versions - exists(label) - Check if version exists - delete(label) - Remove version

Version Managers¶

BaseVersionManager¶

Abstract base class providing common version management functionality.

from semantica.change_management import BaseVersionManager

manager = BaseVersionManager(storage_path="versions.db")

Common Methods: - list_versions() - Get all version metadata - get_version(label) - Retrieve specific version - verify_checksum(snapshot) - Validate data integrity

TemporalVersionManager¶

Knowledge Graph Version Management

Perfect for tracking changes in knowledge graphs with entity and relationship diffs.

from semantica.change_management import TemporalVersionManager

manager = TemporalVersionManager(storage_path="kg_versions.db")

# Create snapshot
snapshot = manager.create_snapshot(
    graph={
        "entities": [
            {"id": "e1", "name": "Entity 1", "type": "Person"},
            {"id": "e2", "name": "Entity 2", "type": "Organization"}
        ],
        "relationships": [
            {"source": "e1", "target": "e2", "type": "works_for"}
        ]
    },
    version_label="v1.0",
    author="user@example.com",
    description="Initial knowledge graph"
)

# Compare versions with detailed diffs
diff = manager.compare_versions("v1.0", "v2.0")
print(f"Entities added: {diff['summary']['entities_added']}")
print(f"Relationships modified: {diff['summary']['relationships_modified']}")

Key Features: - Entity-level change tracking - Relationship diff analysis - SHA-256 checksums for integrity - Detailed change summaries

OntologyVersionManager¶

Ontology Version Management

Designed for structural changes in ontologies with class, property, and axiom tracking.

from semantica.change_management import OntologyVersionManager

manager = OntologyVersionManager(storage_path="ontology_versions.db")

# Create ontology snapshot
snapshot = manager.create_snapshot(
    ontology={
        "uri": "https://example.com/ontology",
        "structure": {
            "classes": ["Person", "Organization"],
            "properties": ["name", "email"],
            "axioms": ["Person hasEmail exactly 1 Email"]
        }
    },
    version_label="ont_v1.0",
    author="architect@example.com",
    description="Initial ontology design"
)

# Compare structural changes
diff = manager.compare_versions("ont_v1.0", "ont_v2.0")
print(f"Classes added: {diff['classes_added']}")
print(f"Axioms modified: {diff['axioms_modified']}")

Key Features: - Class and property tracking - Axiom change detection - Structural comparison - Import/export support

Data Integrity¶

compute_checksum¶

Generate SHA-256 checksum for data integrity verification.

from semantica.change_management import compute_checksum

data = {"entities": [...], "relationships": [...]}
checksum = compute_checksum(data)
print(f"SHA-256: {checksum}")

Use cases: - Verify data integrity before storing snapshots - Detect unauthorized modifications to version data - Ensure consistency across distributed systems - Generate unique identifiers for data versions

verify_checksum¶

Validate data integrity using stored checksums.

from semantica.change_management import verify_checksum

snapshot = manager.get_version("v1.0")
is_valid = verify_checksum(snapshot)

if not is_valid:
    print("WARNING: Data integrity compromised!")

Use cases: - Validate snapshot integrity after retrieval - Detect data corruption or tampering - Ensure compliance with data integrity requirements - Verify backup and restore operations

Legacy Support¶

VersionManager¶

Original ontology version manager for backward compatibility.

from semantica.change_management import VersionManager, OntologyVersion

Note: Use OntologyVersionManager for new projects.

Error Handling¶

from semantica.utils.exceptions import ValidationError, ProcessingError

try:
    snapshot = manager.create_snapshot(...)
except ValidationError as e:
    print(f"Invalid input: {e}")
except ProcessingError as e:
    print(f"Operation failed: {e}")

Common Errors: - ValidationError - Invalid email, missing fields, bad timestamps - ProcessingError - Database issues, file system errors

Best Practices¶

Performance Tips¶

• Use InMemoryVersionStorage for development/testing
• Use SQLiteVersionStorage for production
• Implement retention policies for old versions

Security Considerations¶

• Validate author emails for audit trails
• Use checksums for data integrity
• Store sensitive data with appropriate permissions

Usage Patterns¶

from semantica.change_management import TemporalVersionManager

# Development workflow
dev_manager = TemporalVersionManager()  # In-memory

# Production workflow  
prod_manager = TemporalVersionManager(
    storage_path="secure/production_versions.db"
)

# Audit trail generation
for version in prod_manager.list_versions():
    print(f"{version['timestamp']}: {version['description']} by {version['author']}")