# How to Implement Change Management and Conflict Resolution Workflows for Knowledge Graphs in Semantica

> Learn how to implement change management and conflict resolution for knowledge graphs using Semantica's GraphBuilder, ConflictDetector, and SourceTracker components. Streamline your graph development.

- Repository: [Semantica /semantica](https://github.com/semantica-agi/semantica)
- Tags: how-to-guide
- Published: 2026-08-14

---

**Semantica provides a built-in pipeline for building, versioning, and reconciling knowledge graphs through `GraphBuilder`, `ConflictDetector`, and `SourceTracker` components.**

Knowledge graphs derived from multiple data sources inevitably face schema drift, entity duplication, and conflicting property values. The Semantica framework treats **change management** and **conflict resolution** as first-class architectural concerns, enabling teams to track graph evolution, detect inconsistencies automatically, and resolve disputes with full audit trails.

---

## Core Components for Graph Change Management

Semantica's workflow orchestration centers on four interconnected modules:

| Component | Primary Role | Source Path |
|-----------|-----------|-------------|
| **`GraphBuilder`** | Orchestrates extraction, entity resolution, temporal graph construction, and snapshotting | [`semantica/kg/graph_builder.py`](https://github.com/semantica-agi/semantica/blob/main/semantica/kg/graph_builder.py) |
| **`ConflictDetector`** | Analyzes entities and relationships for four conflict categories | [`semantica/conflicts/conflict_detector.py`](https://github.com/semantica-agi/semantica/blob/main/semantica/conflicts/conflict_detector.py) |
| **`SourceTracker`** | Maintains provenance for every property value contributing to conflicts | [`semantica/provenance/manager.py`](https://github.com/semantica-agi/semantica/blob/main/semantica/provenance/manager.py) |
| **`ProgressTracker`** | Emits fine-grained progress events for monitoring long-running jobs | [`semantica/utils/progress_tracker.py`](https://github.com/semantica-agi/semantica/blob/main/semantica/utils/progress_tracker.py) |

These modules enable **end-to-end change management workflows** that preserve historical states while surfacing data quality issues for resolution.

---

## Configuring Change Management in GraphBuilder

The `GraphBuilder` class in [`semantica/kg/graph_builder.py`](https://github.com/semantica-agi/semantica/blob/main/semantica/kg/graph_builder.py) centralizes all change-management capabilities. Enable temporal support, versioning, and history tracking through constructor parameters:

```python
from semantica.kg import GraphBuilder

builder = GraphBuilder(
    merge_entities=True,
    resolve_conflicts=True,
    enable_temporal=True,
    track_history=True,
    version_snapshots=True,
    temporal_granularity="day",
)

```

Key parameters for **change management workflows**:

- **`enable_temporal`** – Activates time-aware graph construction
- **`version_snapshots`** – Enables point-in-time graph captures
- **`track_history`** – Preserves modification history for auditability
- **`temporal_granularity`** – Defines resolution ("day", "hour", "minute")

### Creating and Querying Temporal Snapshots

After building your graph, create immutable snapshots for version control:

```python
from datetime import datetime

# Build from source data

graph = builder.build(sources=my_sources)

# Create a point-in-time snapshot

snapshot = builder.create_temporal_snapshot(timestamp=datetime.utcnow())

# Query historical state

historic_graph = builder.query_temporal(at=datetime(2024, 5, 1))

```

Snapshots integrate with any **`GraphStore`** implementation. Configure persistence via the `graph_store` attribute:

```python
builder.graph_store = MyNeo4jStore(uri="bolt://localhost:7687")
builder.graph_store.save(graph)

```

---

## Conflict Detection Categories

The `ConflictDetector` class in [`semantica/conflicts/conflict_detector.py`](https://github.com/semantica-agi/semantica/blob/main/semantica/conflicts/conflict_detector.py) implements four distinct **conflict resolution workflows**:

| Category | Detection Method | Trigger Scenario |
|----------|---------------|----------------|
| **Value conflicts** | `detect_value_conflicts()` | Same property holds different values across sources |
| **Type conflicts** | `detect_type_conflicts()` | Entity identifier annotated with incompatible types |
| **Temporal conflicts** | `detect_temporal_conflicts()` | Inconsistent timestamps (e.g., two `founded_year` values) |
| **Logical conflicts** | `detect_logical_conflicts()` | Semantically incompatible type combinations |

Each detection method returns structured `Conflict` objects containing severity levels, confidence scores, and source provenance.

---

## Step-by-Step Conflict Resolution Workflow

### Step 1: Access the Detector

The conflict detector initializes automatically when `resolve_conflicts=True`:

```python
conflict_detector = builder.conflict_detector

```

### Step 2: Run Targeted Detection

Execute blanket scans or targeted queries:

```python

# Detect all conflict types across entities

all_conflicts = conflict_detector.detect_conflicts(entities)

# Detect only value conflicts for specific property

name_conflicts = conflict_detector.detect_conflicts(
    entities, method="value", property_name="name"
)

```

### Step 3: Inspect Conflict Metadata

Each `Conflict` object exposes diagnostic fields:

```python
for c in all_conflicts:
    print(f"{c.conflict_id}: {c.severity} – {c.recommended_action}")
    print(f"  Confidence: {c.confidence}")
    print(f"  Sources: {[s.document_id for s in c.sources]}")

```

### Step 4: Choose Resolution Strategy

**Automatic resolution** applies heuristics (e.g., most-recent-source-wins):

```python
conflict_detector = ConflictDetector(auto_resolve=True)

```

**Manual review** surfaces conflicts to domain experts via the `sources` list:

```python
critical = [c for c in all_conflicts if c.severity == "critical"]

# Present c.sources in analyst UI for confirmation

```

### Step 5: Integrate Resolved Data

Filter or reconcile entities before rebuilding:

```python
critical_ids = {c.entity_id for c in critical}
clean_entities = [
    e for e in raw_entities
    if e["id"] not in critical_ids
]

graph = builder.build(sources=[{
    "entities": clean_entities,
    "relationships": raw_rels
}])

```

---

## Provenance Tracking with SourceTracker

Every conflict links to its origin through `SourceTracker` (accessed via `conflicts.source_tracker` and implemented in [`semantica/provenance/manager.py`](https://github.com/semantica-agi/semantica/blob/main/semantica/provenance/manager.py)). This enables **audit trails** for regulatory compliance and debugging:

- Original document identifier
- Page or section location
- Extraction confidence score
- Timestamp of ingestion

The provenance graph is queryable for impact analysis—identify which source documents contributed to specific entity properties.

---

## Complete Implementation Example

The following demonstrates **end-to-end change management and conflict resolution**:

```python
from datetime import datetime
from semantica.kg import GraphBuilder

# ----------------------------------------------------------------------

# 1. Configure builder with full change management

# ----------------------------------------------------------------------

builder = GraphBuilder(
    merge_entities=True,
    resolve_conflicts=True,
    enable_temporal=True,
    track_history=True,
    version_snapshots=True,
    temporal_granularity="day",
    conflict_detection={"auto_resolve": False},  # manual review

)

# ----------------------------------------------------------------------

# 2. Supply raw sources with intentional conflicts

# ----------------------------------------------------------------------

sources = [
    {
        "entities": [
            {"id": "E1", "name": "Acme Corp", "type": "Organization", "source": "docA"},
            {"id": "E1", "name": "Acme Corp.", "type": "Company", "source": "docB"},
        ],
        "relationships": [
            {"source": "E1", "target": "E2", "type": "EMPLOYS"},
        ],
    },
]

# ----------------------------------------------------------------------

# 3. Build with automatic conflict detection

# ----------------------------------------------------------------------

graph = builder.build(sources=sources)

# ----------------------------------------------------------------------

# 4. Review generated conflict report

# ----------------------------------------------------------------------

conflicts = builder.conflict_detector.get_conflict_report()
for c in conflicts["conflicts"]:
    print(
        f"{c['conflict_id']} – {c['severity']} – "
        f"{c['recommended_action']} – sources: {c['sources']}"
    )

# ----------------------------------------------------------------------

# 5. Create versioned snapshot

# ----------------------------------------------------------------------

snapshot = builder.create_temporal_snapshot(timestamp=datetime.utcnow())

```

This workflow emits progress events through `ProgressTracker`, enabling real-time monitoring in CI pipelines or dashboard UIs.

---

## Key Source Files Reference

| File | Responsibility |
|------|---------------|
| [`semantica/kg/graph_builder.py`](https://github.com/semantica-agi/semantica/blob/main/semantica/kg/graph_builder.py) | Orchestration, temporal construction, snapshotting |
| [`semantica/conflicts/conflict_detector.py`](https://github.com/semantica-agi/semantica/blob/main/semantica/conflicts/conflict_detector.py) | Detection algorithms and conflict object generation |
| [`semantica/provenance/manager.py`](https://github.com/semantica-agi/semantica/blob/main/semantica/provenance/manager.py) | Provenance tracking and audit trails |
| [`semantica/utils/progress_tracker.py`](https://github.com/semantica-agi/semantica/blob/main/semantica/utils/progress_tracker.py) | Progress event emission for monitoring |
| [`semantica/kg/graph_store/neo4j_store.py`](https://github.com/semantica-agi/semantica/blob/main/semantica/kg/graph_store/neo4j_store.py) | Example persistence backend |

---

## Summary

- **Change management** in Semantica relies on `GraphBuilder` flags (`enable_temporal`, `version_snapshots`, `track_history`) to preserve graph evolution
- **Conflict resolution workflows** use `ConflictDetector` to categorize and surface value, type, temporal, and logical inconsistencies
- **Provenance tracking** via `SourceTracker` ensures every conflict is traceable to source documents
- **Flexible resolution** supports both automatic heuristics and manual analyst review
- **Progress monitoring** through `ProgressTracker` integrates with operational tooling

---

## Frequently Asked Questions

### What conflict types does Semantica detect automatically?

Semantica detects four conflict categories: value conflicts (differing property values), type conflicts (incompatible entity types), temporal conflicts (inconsistent timestamps), and logical conflicts (semantically impossible type combinations). Each category has a dedicated detection method in [`conflict_detector.py`](https://github.com/semantica-agi/semantica/blob/main/conflict_detector.py).

### How does Semantica track which source documents caused a conflict?

The `SourceTracker` class in [`semantica/provenance/manager.py`](https://github.com/semantica-agi/semantica/blob/main/semantica/provenance/manager.py) records provenance for every property value, including document identifier, location, confidence score, and ingestion timestamp. This metadata attaches directly to `Conflict` objects for auditability.

### Can I disable automatic conflict resolution and require manual review?

Yes. Set `conflict_detection={"auto_resolve": False}` in `GraphBuilder` or instantiate `ConflictDetector(auto_resolve=False)`. This surfaces all conflicts through `get_conflict_report()` for analyst review rather than applying resolution heuristics.

### What storage backends support temporal snapshots?

Any `GraphStore` implementation can persist snapshots. Semantica provides reference implementations including `Neo4jStore` in [`semantica/kg/graph_store/neo4j_store.py`](https://github.com/semantica-agi/semantica/blob/main/semantica/kg/graph_store/neo4j_store.py). The snapshot mechanism is storage-agnostic—backends receive the serialized graph state at the specified timestamp.