Conflict Detection and Resolution Strategies in Semantica: A Complete Guide

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

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

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

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

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	Implements all detection algorithms and the Conflict dataclass builder
semantica/conflicts/conflict_resolver.py	Provides automatic resolution helpers and the ConflictResolver API
semantica/conflicts/conflict_analyzer.py	Higher-level analytics for aggregation and reporting
semantica/conflicts/methods.py	Helper functions for severity and confidence calculations
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.

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 within the semantica/conflicts/ package, enabling the detector to attribute each conflicting value to its originating knowledge source.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}