How ConflictDetector Distinguishes Different Types of Conflicts in Semantica

The ConflictDetector distinguishes conflict types through a dedicated ConflictType enumeration and specialized detection methods that each analyze specific data dimensions.

The ConflictDetector class in the semantica-agi/semantica repository provides a systematic approach to identifying data inconsistencies across entity collections. By categorizing conflicts into distinct semantic types, the system enables downstream components like ConflictAnalyzer and ConflictResolver to apply targeted remediation strategies based on the specific nature of each discrepancy.

The ConflictType Enumeration

At the core of the detection system lies the ConflictType enum defined at line 68 of semantica/conflicts/conflict_detector.py. This enumeration establishes five canonical categories that label every detected inconsistency:

• VALUE_CONFLICT — Divergent property values for the same entity identifier
• TYPE_CONFLICT — Inconsistent entity type declarations across sources
• RELATIONSHIP_CONFLICT — Contradictory attributes within relationship dictionaries
• TEMPORAL_CONFLICT — Incompatible time-related fields after normalization
• LOGICAL_CONFLICT — Violations of domain-specific incompatibility rules

Each detection method explicitly assigns one of these enum values when constructing Conflict objects, creating a single source of truth for conflict classification throughout the pipeline.

Specialized Detection Methods

The detector implements dedicated methods for each conflict category, ensuring precise analysis of specific data dimensions rather than generic string comparison.

Value-Based Detection

The detect_value_conflicts method (line 136) scans entity collections for property value divergences. It groups entities by their identifier, aggregates values for the specified property, and raises a Conflict with conflict_type = ConflictType.VALUE_CONFLICT when more than one distinct value is found. This method includes progress tracking and detailed provenance recording to identify which sources contributed conflicting values.

Type-Based Detection

Starting at line 655, detect_type_conflicts focuses specifically on the type or entity_type fields. After grouping entities by ID, the method gathers all observed types and creates a Conflict with conflict_type = ConflictType.TYPE_CONFLICT whenever an entity is associated with multiple incompatible types across the dataset.

Relationship-Based Detection

Found at line 339, detect_relationship_conflicts processes relationship dictionaries by generating unique relationship IDs. It validates properties against a predefined whitelist (type, properties, confidence), emitting a Conflict of type RELATIONSHIP_CONFLICT whenever any of these critical attributes differ across sources for the same relationship.

Temporal-Based Detection

Beginning at line 818, detect_temporal_conflicts handles time-related fields such as founded_year, date, and start_date. The method normalizes string dates to standardized year formats when possible, flagging a TEMPORAL_CONFLICT when normalized temporal values differ for the same entity, even if the original string representations varied.

Logical-Based Detection

Implemented at line 1026, detect_logical_conflicts enforces domain-specific ontology rules (for example, a Person cannot simultaneously be an Organization). When incompatible types appear for the same entity ID, the method produces a Conflict with conflict_type = LOGICAL_CONFLICT, capturing the specific rule violation for downstream resolution.

Unified Detection API

The detect_conflicts method serves as the primary entry point around line 1240, dispatching execution to the appropriate specialized method based on the method argument. Valid options include "value", "type", "relationship", "temporal", "logical", or "all" for comprehensive scanning. This dispatch architecture maintains clean separation of internal detection logic while providing a consumer-friendly interface that returns consistently structured Conflict objects regardless of the analysis type.

Practical Usage Examples

from semantica.conflicts import ConflictDetector

# Initialize the detector (optional custom config)

detector = ConflictDetector()

# Detect value conflicts on the "name" property

value_conflicts = detector.detect_conflicts(
    entities=my_entities, method="value", property_name="name"
)

# Returns: List of Conflict objects with conflict_type = ConflictType.VALUE_CONFLICT

# Detect type conflicts across all entities

type_conflicts = detector.detect_conflicts(
    entities=my_entities, method="type"
)

# Detect relationship conflicts in relationship dictionaries

relationship_conflicts = detector.detect_conflicts(
    entities=my_relationships, method="relationship"
)

# Detect temporal conflicts (e.g., differing founding years)

temporal_conflicts = detector.detect_conflicts(
    entities=my_entities, method="temporal"
)

# Detect logical conflicts based on domain rules

logical_conflicts = detector.detect_conflicts(
    entities=my_entities, method="logical"
)

# Run a full sweep of all detection methods

all_conflicts = detector.detect_conflicts(entities=my_entities, method="all")

Each call returns a list of Conflict instances containing the conflict_type attribute matching the appropriate enum member, along with metadata including entity ID, property name, conflicting values, source provenance, and calculated severity scores.

Summary

• Explicit enumeration via ConflictType provides a canonical taxonomy for five distinct conflict categories: value, type, relationship, temporal, and logical.
• Targeted analysis functions in semantica/conflicts/conflict_detector.py isolate specific data dimensions, with each method residing at specific line ranges (136, 339, 655, 818, and 1026).
• Consistent conflict construction ensures every detection routine populates Conflict objects with appropriate type labels, provenance tracking, and confidence metrics.
• Unified dispatch through detect_conflicts simplifies API usage while preserving internal specialization, supporting both individual method calls and comprehensive "all" scans.

Frequently Asked Questions

What are the five conflict types detected by ConflictDetector?

The detector recognizes VALUE_CONFLICT, TYPE_CONFLICT, RELATIONSHIP_CONFLICT, TEMPORAL_CONFLICT, and LOGICAL_CONFLICT. These are defined in the ConflictType enum at line 68 of conflict_detector.py and represent distinct categories of data inconsistency ranging from property value divergence to ontology rule violations.

How does the detector handle temporal inconsistencies?

The detect_temporal_conflicts method (line 818) normalizes date strings to standardized year formats when possible, then compares the normalized values across sources. If the same entity has differing normalized temporal values (such as conflicting founded_year entries), it creates a Conflict with type TEMPORAL_CONFLICT regardless of variations in the original string formatting.

Can ConflictDetector run all detection methods simultaneously?

Yes. Passing method="all" to the detect_conflicts entry point (line 1240) dispatches all five specialized detection routines in sequence. This returns a comprehensive list of Conflict objects that may contain mixed conflict types, enabling complete inconsistency analysis in a single API call.

How does relationship conflict detection differ from value conflict detection?

While detect_value_conflicts (line 136) scans arbitrary entity properties for value divergence, detect_relationship_conflicts (line 339) specifically processes relationship dictionaries. It generates relationship IDs and validates a predefined set of critical properties (type, properties, confidence), whereas value detection operates on any specified property name across standard entity collections.

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