Conflict Resolution Strategies in Semantica: Detection and Reconciliation Methods

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

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

# 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)}")

# 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

The conflict handling system spans several modules within the repository:

File	Role
semantica/conflicts/conflict_detector.py	Implements detection algorithms and Conflict dataclass construction
semantica/conflicts/conflict_resolver.py	Provides automatic resolution via ConflictResolver
semantica/conflicts/conflict_analyzer.py	Higher-level analytics and aggregation reporting
semantica/conflicts/methods.py	Helper functions for severity and confidence calculations
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.

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, which enables the conflict detector to populate the sources field in Conflict objects with the origin of each conflicting value.

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