# How Semantica's ConflictDetector Identifies and Resolves Conflicting Facts in Knowledge Graphs

> Discover how Semantica's ConflictDetector identifies and resolves conflicting facts in knowledge graphs using advanced comparison and configurable resolution strategies. Learn more!

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

---

**Semantica's ConflictDetector identifies conflicting facts by comparing newly ingested triples against existing subject-predicate pairs in the knowledge graph, then resolves them using configurable strategies like priority-based selection or temporal ordering.**

The semantica-agi/semantica repository implements a robust knowledge graph construction pipeline that automatically detects contradictions during data ingestion. When heterogeneous data sources populate the graph, the **ConflictDetector** examines candidate facts to spot value mismatches and relationship ambiguities. This component ensures data consistency while preserving provenance through systematic classification and resolution workflows.

## How ConflictDetector Identifies Conflicting Facts

### Triggering Detection During Ingestion

The detection process begins in [`semantica/kg/graph_builder.py`](https://github.com/semantica-agi/semantica/blob/main/semantica/kg/graph_builder.py) where the `GraphBuilder` streams entities and relationships into the internal graph model. For every candidate fact, the builder invokes `ConflictDetector` (configured via `conflict_detection_config`) to audit incoming triples before they are committed. The detector extracts the **subject URI**, **predicate**, and **object** from each candidate to search for existing triples sharing the same subject-predicate pair.

### Conflict Classification Logic

When duplicate subject-predicate pairs exist, `ConflictDetector._classify_conflict` categorizes the clash into specific types. The system distinguishes between:

- **VALUE_CONFLICT**: Occurs when the same subject and predicate map to different object values (e.g., conflicting organization names for a person entity).
- **RELATIONSHIP_CONFLICT**: Arises from incompatible relationship definitions, such as contradictory `parentOf` edges with mismatched timestamps or cardinality violations.

### Capturing Conflict Metadata

Each identified clash generates a `Conflict` object that records granular metadata in [`semantica/conflicts/conflict_analyzer.py`](https://github.com/semantica-agi/semantica/blob/main/semantica/conflicts/conflict_analyzer.py). The system captures the originating **sources** (file paths, APIs, or ingestion modules), **confidence scores** from upstream extractors, and **timestamps** to support downstream resolution decisions and audit trails.

## Resolution Strategies in Semantica

### Configuring the ConflictResolver

After detection, `GraphBuilder` optionally delegates to `ConflictResolver` from [`semantica/conflicts/conflict_resolver.py`](https://github.com/semantica-agi/semantica/blob/main/semantica/conflicts/conflict_resolver.py). The resolver accepts a `method` argument (e.g., `voting`, `priority`, `temporal`) that determines how conflicting assertions are reconciled. This configuration allows knowledge graph administrators to enforce domain-specific consistency policies without modifying core detection logic.

### Resolution Method Implementations

The resolver examines the `Conflict` payload and applies the selected strategy:

- **Priority-based resolution**: Prefers facts from higher-ranked sources, such as curated databases over noisy LLM outputs or unverified web scrapes.
- **Credibility-weighted resolution**: Aggregates confidence scores across conflicting sources and selects the value with the highest cumulative credibility.
- **Temporal resolution**: Selects the most recent fact when timestamps differ, assuming newer data reflects updated ground truth.

### Applying Resolutions to the Knowledge Graph

The chosen strategy returns a `ResolutionResult` that either commits the winning fact to the graph or flags the conflict for manual review. In [`semantica/kg/graph_builder.py`](https://github.com/semantica-agi/semantica/blob/main/semantica/kg/graph_builder.py), the `apply_resolution` method updates the knowledge graph state, discarding inferior candidates or retaining them as **alternate edges** to maintain complete provenance trails for compliance and debugging.

## End-to-End Implementation Example

The following pattern mirrors the test suite in [`tests/conflicts/test_conflicts.py`](https://github.com/semantica-agi/semantica/blob/main/tests/conflicts/test_conflicts.py) and demonstrates the complete workflow:

```python
from semantica.conflicts import ConflictDetector, ConflictResolver
from semantica.kg.graph_builder import GraphBuilder

# Initialize the graph builder and ingest data

gb = GraphBuilder()
gb.ingest(source="data/company_profiles.json")

# Detect conflicts using the default detector

detector = ConflictDetector()
conflicts = detector.detect_conflicts(gb.graph)  # Returns List[Conflict]

# Resolve using priority-based strategy

resolver = ConflictResolver(method="priority")
resolved = resolver.resolve_conflicts(conflicts)  # Returns List[ResolutionResult]

# Commit resolutions back to the knowledge graph

gb.apply_resolution(resolved)

```

## Summary

- **Detection trigger**: `GraphBuilder` invokes `ConflictDetector` during ingestion to audit triples against existing subject-predicate pairs in [`semantica/conflicts/conflict_detector.py`](https://github.com/semantica-agi/semantica/blob/main/semantica/conflicts/conflict_detector.py).
- **Classification system**: Conflicts are categorized as `VALUE_CONFLICT` or `RELATIONSHIP_CONFLICT` via `_classify_conflict`, capturing source provenance and confidence metadata.
- **Resolution methods**: `ConflictResolver` supports priority-based, credibility-weighted, and temporal strategies configured via the `method` parameter.
- **Provenance preservation**: Resolved facts are committed to the graph while conflicting candidates may be stored as alternate edges for auditability.

## Frequently Asked Questions

### What types of conflicts can Semantica detect?

Semantica detects two primary conflict types: `VALUE_CONFLICT` for differing object values sharing the same subject-predicate pair, and `RELATIONSHIP_CONFLICT` for incompatible relationship definitions or temporal contradictions. The `ConflictDetector._classify_conflict` method in [`semantica/conflicts/conflict_detector.py`](https://github.com/semantica-agi/semantica/blob/main/semantica/conflicts/conflict_detector.py) performs this categorization based on triple structure and metadata.

### How does Semantica determine which conflicting fact to keep?

The `ConflictResolver` class applies configurable strategies including priority-based selection (preferring authoritative sources), credibility-weighted voting (aggregating confidence scores), and temporal ordering (selecting the newest fact). These methods are implemented in [`semantica/conflicts/conflict_resolver.py`](https://github.com/semantica-agi/semantica/blob/main/semantica/conflicts/conflict_resolver.py) and return `ResolutionResult` objects that specify the winning assertion.

### Can Semantica preserve conflicting facts for audit purposes?

Yes, instead of permanently deleting rejected facts, the resolution workflow in [`semantica/kg/graph_builder.py`](https://github.com/semantica-agi/semantica/blob/main/semantica/kg/graph_builder.py) can retain conflicting candidates as alternate edges linked to the primary triple. This preserves complete provenance trails including source origins, confidence scores, and timestamps for compliance and debugging.

### Where is conflict detection triggered in the ingestion pipeline?

Conflict detection is invoked by `GraphBuilder` during the ingestion phase, specifically when processing new triples in [`semantica/kg/graph_builder.py`](https://github.com/semantica-agi/semantica/blob/main/semantica/kg/graph_builder.py). The builder passes candidate facts to `ConflictDetector.detect_conflicts()`, ensuring contradictions are identified before they are permanently committed to the knowledge graph.