# Conflict Detection and Resolution Strategies in Semantica: A Complete Guide

> Explore Semantica's conflict detection and resolution strategies. Discover eight methods for finding inconsistencies and learn how to resolve them automatically with ConflictResolver.

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

---

**Semantica provides a modular `semantica.conflicts` subsystem that discovers inconsistencies across multi-source knowledge graphs through eight detection strategies and resolves them automatically via the `ConflictResolver` class or custom rule hooks.**

The open-source **semantica-agi/semantica** repository implements a comprehensive toolkit for maintaining data quality in knowledge graph construction. At the heart of this system lies the `semantica.conflicts` package, which exposes the **`ConflictDetector`** for identifying inconsistencies and the optional **`ConflictResolver`** for automated reconciliation. These components work together to audit entities, properties, relationships, and temporal data across heterogeneous sources.

## Core Architecture: Detector and Resolver

Semantica’s conflict handling is split into two primary classes that operate within the `semantica/conflicts/` directory.

**`ConflictDetector`** serves as the analysis engine, scanning knowledge graphs for specific categories of inconsistencies. It returns structured **`Conflict`** objects (defined at lines 78‑92 in [`conflict_detector.py`](https://github.com/semantica-agi/semantica/blob/main/conflict_detector.py)) that capture conflict IDs, types, severity scores, and recommended remediation actions.

**`ConflictResolver`** provides the remediation layer. When instantiated or when `auto_resolve=True` is passed to the detector, this class applies resolution strategies ranging from simple confidence-based selection to user-defined custom rules.

## Detection Strategies in Semantica

The [`conflict_detector.py`](https://github.com/semantica-agi/semantica/blob/main/conflict_detector.py) file implements eight distinct detection methods, each targeting a specific class of data inconsistency.

### Value Conflict Detection

**`detect_value_conflicts`** (line 36) identifies when the same property on the same entity holds differing values across multiple sources. This is the fundamental strategy for spotting data drift or source contradictions in fields like names, addresses, or measurements.

### Property-Wide Conflict Detection

**`detect_property_conflicts`** (line 24) functions as a thin wrapper around the value detector, running checks for a specific property name across the entire graph. This is useful for targeted audits of high-priority fields.

### Relationship Conflict Detection

**`detect_relationship_conflicts`** (line 39) scans for contradictory definitions attached to relationship IDs, including type mismatches, conflicting properties, or divergent confidence scores between sources.

### Entity-Type Conflict Detection

**`detect_type_conflicts`** (line 55) flags instances where the same entity carries incompatible type labels across different knowledge sources, such as being classified as both a `Person` and an `Organization`.

### Temporal Conflict Detection

**`detect_temporal_conflicts`** (line 18) examines timestamp and date fields for logical impossibilities, such as "Founded 1999" versus "Founded 2005" for the same company entity.

### Logical Conflict Detection

**`detect_logical_conflicts`** (line 26) enforces domain-specific business rules. For example, it can detect when an entity violates ontological constraints, such as a resource being simultaneously a `PhysicalObject` and an `AbstractConcept`.

### Entity-Wide Conflict Detection

**`detect_entity_conflicts`** (line 31) runs the value-conflict detector across every property of every entity, providing a comprehensive audit suitable for full-graph validation workflows.

### Unified Dispatch Method

**`detect_conflicts`** (line 112) acts as a router that accepts a `method` argument (`"value"`, `"property"`, `"type"`, `"relationship"`, `"temporal"`, `"logical"`, or `"entity"`) and delegates to the appropriate sub-method, streamlining batch operations.

## The Conflict Data Model

Every detection routine builds a **`Conflict`** dataclass containing:

- **Conflict metadata**: ID, type (via `ConflictType` enum), and affected entity/relationship ID
- **Provenance tracking**: Lists of conflicting values and their originating sources
- **Analytics**: Confidence scores calculated via `_calculate_conflict_confidence` and severity labels via `_calculate_severity`
- **Remediation guidance**: Recommended actions via `_recommend_action`

Progress tracking is integrated through the shared `ProgressTracker`, enabling real-time feedback during large-scale detection runs via `start_tracking`, `update_progress`, and `stop_tracking` patterns.

## Resolution Strategies in Semantica

Resolution is optional and controlled by the `auto_resolve` initialization parameter or manual invocation of the **`ConflictResolver`** class.

### Simple Value Reconciliation

When `auto_resolve=True`, the resolver automatically selects between conflicting values using recency or confidence heuristics. For binary conflicts (two values), `_recommend_action` determines the authoritative source.

### Custom Rule Hooks

Users can supply a `conflict_resolution` callable per property through the `conflict_fields` configuration. During resolution, the system applies these custom functions to conflicting values, enabling domain-specific logic such as "always take the maximum revenue figure."

### Batch Resolution Workflow

The **`resolve_conflicts`** method iterates over the `detected_conflicts` dictionary, applies the chosen strategy to each entry, and returns a summary distinguishing auto-resolved conflicts from those requiring manual review.

## Implementation Examples

### Detecting Value Conflicts for a Specific Property

```python
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)

```

### Full Audit with Automatic Resolution

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

```

### Custom Resolution Rules

```python
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)

```

### Direct Logical Conflict Detection

```python
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

| File | Role |
|------|------|
| [`semantica/conflicts/conflict_detector.py`](https://github.com/semantica-agi/semantica/blob/main/semantica/conflicts/conflict_detector.py) | Implements all detection algorithms and the `Conflict` dataclass builder |
| [`semantica/conflicts/conflict_resolver.py`](https://github.com/semantica-agi/semantica/blob/main/semantica/conflicts/conflict_resolver.py) | Provides automatic resolution helpers and the `ConflictResolver` API |
| [`semantica/conflicts/conflict_analyzer.py`](https://github.com/semantica-agi/semantica/blob/main/semantica/conflicts/conflict_analyzer.py) | Higher-level analytics for aggregation and 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) | Tracks provenance enabling the `track_provenance` option |

## Summary

- **Eight detection strategies** are available in `semantica.conflicts`, ranging from value and type conflicts to temporal and logical inconsistencies.
- **`ConflictDetector`** exposes individual methods (e.g., `detect_temporal_conflicts`) and a unified `detect_conflicts` dispatcher for flexible auditing.
- **Each conflict** is represented as a structured dataclass with confidence scores, severity ratings, and remediation recommendations.
- **Resolution** can be automatic (via `auto_resolve`), manual through `ConflictResolver`, or customized via per-property callable hooks.
- **Progress tracking** is built into the detection pipeline for monitoring large-scale knowledge graph validation.

## Frequently Asked Questions

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

Set `auto_resolve=True` when initializing `ConflictDetector`, or manually instantiate `ConflictResolver` from `semantica.conflicts` and call `resolve_conflicts()` with your detected conflict list.

### What types of conflicts can Semantica detect?

Semantica detects value conflicts, property-wide inconsistencies, relationship contradictions, entity-type mismatches, temporal inconsistencies, logical rule violations, and entity-wide multi-property conflicts through methods defined in [`conflict_detector.py`](https://github.com/semantica-agi/semantica/blob/main/conflict_detector.py).

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

Yes. Pass a dictionary of custom functions to the `ConflictResolver` constructor via the `custom_rules` parameter, mapping property names to callables that accept conflicting values and return the resolved value.

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

Provenance tracking is handled by [`source_tracker.py`](https://github.com/semantica-agi/semantica/blob/main/source_tracker.py) within the `semantica/conflicts/` package, enabling the detector to attribute each conflicting value to its originating knowledge source.