# Conflict Resolution Strategies in Semantica: Detection and Reconciliation Methods

> Explore Semantica's eight conflict detection strategies and three resolution approaches for automatic knowledge graph reconciliation. Resolve value, type, relationship, and temporal inconsistencies.

- Repository: [Semantica /semantica](https://github.com/semantica-agi/semantica)
- Tags: deep-dive
- Published: 2026-09-13

---

**Semantica provides eight distinct conflict detection strategies and three resolution approaches through its `semantica.conflicts` package, enabling automatic reconciliation of value, type, relationship, and temporal inconsistencies across multi-source knowledge graphs.**

The Semantica framework implements a modular conflict-handling subsystem designed to maintain data integrity across aggregated knowledge sources. Located within the `semantica.conflicts` package, this system combines the **`ConflictDetector`** class for identifying inconsistencies with the optional **`ConflictResolver`** for automated reconciliation. Understanding these conflict resolution strategies in Semantica is essential for building robust knowledge graphs that harmonize conflicting information from heterogeneous data sources.

## Core Architecture of the Conflict Handling System

The conflict management pipeline centers on two primary components implemented in [`semantica/conflicts/conflict_detector.py`](https://github.com/semantica-agi/semantica/blob/main/semantica/conflicts/conflict_detector.py) and [`semantica/conflicts/conflict_resolver.py`](https://github.com/semantica-agi/semantica/blob/main/semantica/conflicts/conflict_resolver.py). The **ConflictDetector** discovers inconsistencies across multi-source knowledge graphs through specialized detection methods, while the **ConflictResolver** handles automatic reconciliation when the `auto_resolve` flag is enabled during initialization.

Each detection routine constructs a **`Conflict`** dataclass (defined at lines 78-92 of [`conflict_detector.py`](https://github.com/semantica-agi/semantica/blob/main/conflict_detector.py)) that captures the conflict ID, type, entity or relationship identifiers, property names, conflicting values with provenance sources, confidence scores, severity labels, and recommended remediation actions. Progress tracking is integrated via the shared `ProgressTracker` to provide feedback during large-scale runs.

## Conflict Detection Strategies

Semantica implements eight distinct detection strategies accessible through individual methods or a unified dispatch interface. The central `detect_conflicts` method (line 112 of [`conflict_detector.py`](https://github.com/semantica-agi/semantica/blob/main/conflict_detector.py)) routes requests to appropriate sub-methods based on the `method` parameter.

### Value and Property Conflict Detection

**Value conflicts** occur when the same property on the same entity contains differing values across multiple sources. The `detect_value_conflicts` method (line 36) identifies these discrepancies, while `detect_property_conflicts` (line 24) provides a thin wrapper for checking specific properties. For comprehensive audits, `detect_entity_conflicts` (line 31) runs value-conflict detection across every property of every entity.

### Relationship and Entity-Type Conflicts

**Relationship conflicts** are detected via `detect_relationship_conflicts` (line 39), which identifies contradictory definitions including type, properties, or confidence values for the same relationship ID. **Entity-type conflicts**, flagged by `detect_type_conflicts` (line 55), occur when identical entities receive incompatible type labels across different sources.

### Temporal and Logical Consistency Checks

**Temporal conflicts** involve inconsistent timestamp or founded-year information (for example, "Founded 1999" versus "Founded 2005"), detected by `detect_temporal_conflicts` at line 18. **Logical conflicts** enforce domain-specific rules through `detect_logical_conflicts` (line 26), such as preventing an entity from being simultaneously classified as both a *Person* and an *Organization*.

## The Conflict Data Structure

Every detection strategy returns **`Conflict`** objects containing structured metadata essential for resolution decisions. The dataclass stores provenance information through the `sources` field, calculates conflict severity via `_calculate_severity`, and determines confidence scores through `_calculate_conflict_confidence`. The recommended remediation action is populated by `_recommend_action`, which guides both automatic and manual resolution workflows.

## Conflict Resolution Strategies

Resolution is optional and controlled by the `auto_resolve` parameter in `ConflictDetector.__init__`. When enabled, the detector invokes the **ConflictResolver** class to process detected inconsistencies through three primary approaches.

### Automatic Simple Value Reconciliation

For conflicts involving exactly two values, the resolver automatically selects the most recent or highest-confidence source. This logic executes within the `_recommend_action` method, providing zero-configuration resolution for straightforward discrepancies.

### Custom Rule Hooks

Users can supply property-specific resolution functions through the `conflict_fields` configuration. These custom rules receive conflicting values as parameters and return the reconciled result. For example, a revenue property might use `lambda a, b: max(a, b)` to always retain the larger value.

### Batch Resolution Workflow

The `resolve_conflicts` method iterates over the `detected_conflicts` dictionary, applies the chosen strategy to each entry, and returns a summary report indicating how many conflicts were resolved versus flagged for manual review. This batch processing capability integrates with the `ProgressTracker` for visibility into resolution progress.

## Implementation Examples

The following examples demonstrate practical usage of detection and resolution strategies in Semantica:

```python

# Detect all value conflicts for the property "name"

from semantica.conflicts import ConflictDetector

detector = ConflictDetector()
conflicts = detector.detect_conflicts(
    entities=my_graph,
    method="value",
    property_name="name"
)
print(f"Found {len(conflicts)} name conflicts")
for c in conflicts:
    print(c.conflict_id, c.conflicting_values, c.sources)

```

```python

# Run full audit with auto-resolution enabled

detector = ConflictDetector(auto_resolve=True)
all_conflicts = detector.detect_conflicts(my_graph, method="all")
print(f"Total conflicts detected: {len(all_conflicts)}")

```

```python

# Custom resolution rules

from semantica.conflicts import ConflictResolver

resolver = ConflictResolver(
    custom_rules={"revenue": lambda a, b: max(a, b)}
)
resolution_report = resolver.resolve_conflicts(all_conflicts)
print(resolution_report)

```

```python

# Direct logical conflict detection

logical_conflicts = ConflictDetector().detect_logical_conflicts(my_entities)
for c in logical_conflicts:
    print(f"Logical issue on {c.entity_id}: {c.recommended_action}")

```

## Key Source Files

The conflict handling system spans several modules within the repository:

| File | Role |
|------|------|
| [`semantica/conflicts/conflict_detector.py`](https://github.com/semantica-agi/semantica/blob/main/semantica/conflicts/conflict_detector.py) | Implements detection algorithms and `Conflict` dataclass construction |
| [`semantica/conflicts/conflict_resolver.py`](https://github.com/semantica-agi/semantica/blob/main/semantica/conflicts/conflict_resolver.py) | Provides automatic resolution via `ConflictResolver` |
| [`semantica/conflicts/conflict_analyzer.py`](https://github.com/semantica-agi/semantica/blob/main/semantica/conflicts/conflict_analyzer.py) | Higher-level analytics and aggregation reporting |
| [`semantica/conflicts/methods.py`](https://github.com/semantica-agi/semantica/blob/main/semantica/conflicts/methods.py) | Helper functions for severity and confidence calculations |
| [`semantica/conflicts/source_tracker.py`](https://github.com/semantica-agi/semantica/blob/main/semantica/conflicts/source_tracker.py) | Provenance tracking for conflict source identification |

## Summary

- Semantica provides **eight detection strategies** covering value, property, relationship, type, temporal, and logical conflicts through the `ConflictDetector` class.
- The **`Conflict`** dataclass captures comprehensive metadata including provenance, confidence scores, and severity ratings for each inconsistency.
- **Three resolution approaches** include automatic simple value reconciliation, custom rule hooks via `conflict_fields`, and batch processing through `ConflictResolver`.
- Enable automatic resolution by setting `auto_resolve=True` when instantiating `ConflictDetector`, or manually invoke `ConflictResolver.resolve_conflicts()` for controlled reconciliation workflows.
- All components integrate with `ProgressTracker` to provide visibility during large-scale knowledge graph audits.

## Frequently Asked Questions

### How do I enable automatic conflict resolution in Semantica?

Set the `auto_resolve` parameter to `True` when initializing `ConflictDetector`. This invokes the `ConflictResolver` automatically after detection completes, applying simple value reconciliation to qualifying conflicts while leaving complex inconsistencies for manual review.

### What types of conflicts can Semantica detect?

Semantica detects value conflicts, property-wide conflicts, relationship conflicts, entity-type conflicts, temporal conflicts, logical conflicts, and comprehensive entity-wide conflicts through dedicated methods in [`semantica/conflicts/conflict_detector.py`](https://github.com/semantica-agi/semantica/blob/main/semantica/conflicts/conflict_detector.py).

### Can I define custom rules for resolving specific property conflicts?

Yes. Pass a dictionary of property names to lambda functions via the `custom_rules` parameter when instantiating `ConflictResolver`. These functions receive conflicting values as arguments and must return the resolved value.

### Where does Semantica track the source of conflicting values?

Provenance tracking is handled by [`semantica/conflicts/source_tracker.py`](https://github.com/semantica-agi/semantica/blob/main/semantica/conflicts/source_tracker.py), which enables the conflict detector to populate the `sources` field in `Conflict` objects with the origin of each conflicting value.