semantica/docs/reference/conflicts.md

title, description, icon

title	description	icon
Conflicts Module	Multi-source conflict detection and resolution — value, type, temporal, and logical conflicts with investigation guides.	triangle-exclamation

semantica.conflicts detects and resolves contradictions when multiple sources disagree on the same fact. It surfaces five conflict types, seven resolution strategies, and generates investigation guides for manual review — so conflicts never silently corrupt your knowledge graph.

What You Get

• ConflictDetector — value, type, temporal, logical, and relationship conflict detection
• ConflictResolver — 7 resolution strategies including voting, credibility-weighted, and temporal
• SourceTracker — track which source each conflicting fact came from, with credibility scores
• ConflictAnalyzer — pattern analysis, severity grouping, and trend identification
• InvestigationGuideGenerator — auto-generate step-by-step investigation checklists for human review

ConflictDetector

from semantica.conflicts import ConflictDetector

detector = ConflictDetector()
conflicts = detector.detect_conflicts(kg)

for conflict in conflicts:
    print(f"[{conflict.conflict_type}] '{conflict.entity}' — {conflict.attribute}")
    print(f"  Sources:  {conflict.sources}")
    print(f"  Severity: {conflict.severity:.2f}")

Detection Types

Type	What It Detects
VALUE	Same entity, same attribute, different values across sources
TYPE	Same entity classified as different types in different sources
TEMPORAL	Overlapping validity windows with contradictory facts
LOGICAL	Facts that violate ontology axioms or SHACL constraints
RELATIONSHIP	Inconsistent relationship properties across sources

Run targeted detection by type:

# Detect all types (default)
conflicts = detector.detect_conflicts(kg)

# Detect specific types only
value_conflicts    = detector.detect_value_conflicts(entities, "name")
type_conflicts     = detector.detect_type_conflicts(entities)
relation_conflicts = detector.detect_relationship_conflicts(kg)

ConflictResolver

from semantica.conflicts import ConflictResolver, ResolutionStrategy

resolver = ConflictResolver()
results = resolver.resolve_conflicts(conflicts, strategy=ResolutionStrategy.VOTING)

for result in results:
    print(f"Resolved '{result.attribute}' → {result.resolved_value}")
    print(f"  Strategy: {result.strategy}")

Resolution Strategies

Strategy	Enum	Description
Majority vote	ResolutionStrategy.VOTING	Most common value wins
Credibility-weighted	ResolutionStrategy.CREDIBILITY_WEIGHTED	Weighted by source credibility score
Most recent	ResolutionStrategy.MOST_RECENT	Prefer the most recently updated fact
First seen	ResolutionStrategy.FIRST_SEEN	Prefer the first observed value
Highest confidence	ResolutionStrategy.HIGHEST_CONFIDENCE	Prefer the fact with the highest confidence score
Manual review	ResolutionStrategy.MANUAL_REVIEW	Flag for human review
Expert review	ResolutionStrategy.EXPERT_REVIEW	Escalate to a domain expert

Use the convenience aliases for shorter code:

from semantica.conflicts import voting, credibility_weighted, most_recent, highest_confidence

results = resolver.resolve_conflicts(conflicts, strategy=voting)

Source Credibility Scoring

Assign credibility weights per source so CREDIBILITY_WEIGHTED resolution favors authoritative sources:

from semantica.conflicts import SourceTracker

tracker = SourceTracker()
tracker.set_credibility("pubmed",     0.95)
tracker.set_credibility("wikipedia",  0.80)
tracker.set_credibility("user_input", 0.60)

resolver = ConflictResolver(source_tracker=tracker)
results = resolver.resolve_conflicts(
    conflicts,
    strategy=ResolutionStrategy.CREDIBILITY_WEIGHTED
)

SourceTracker also builds full traceability chains:

from semantica.conflicts import SourceTracker

tracker = SourceTracker()
tracker.track_entity_source("apple_inc", "crunchbase")
tracker.track_property_source("apple_inc", "revenue", "annual_report_2023")

chain = tracker.get_traceability_chain("apple_inc")

ConflictAnalyzer

Identify patterns and trends across large conflict sets:

from semantica.conflicts import ConflictAnalyzer

analyzer = ConflictAnalyzer()

# Detect recurring patterns
patterns = analyzer.identify_patterns(conflicts)
for pattern in patterns:
    print(f"Pattern: {pattern.type} — {pattern.frequency} occurrences")

# Group by severity
by_severity = analyzer.group_by_severity(conflicts)
print(f"Critical: {len(by_severity['critical'])}")
print(f"High:     {len(by_severity['high'])}")
print(f"Low:      {len(by_severity['low'])}")

# Trend analysis over time
trends = analyzer.analyze_trends(conflicts, time_window="30d")

InvestigationGuideGenerator

Auto-generate human-readable investigation guides for conflicts that can't be automatically resolved:

from semantica.conflicts import InvestigationGuideGenerator, InvestigationGuide

generator = InvestigationGuideGenerator()
guide: InvestigationGuide = generator.generate(conflict)

print(guide.title)
print(guide.context)
for step in guide.steps:
    print(f"  [{step.order}] {step.description}")
    print(f"       Check: {step.check}")

Convenience Functions

from semantica.conflicts import (
    detect_conflicts, resolve_conflicts, analyze_conflicts,
    track_sources, generate_investigation_guide
)

conflicts = detect_conflicts(entities, method="value")
resolved  = resolve_conflicts(conflicts, strategy="voting")
analysis  = analyze_conflicts(conflicts, method="pattern")
guide     = generate_investigation_guide(conflicts[0])

Resolve duplicate entities before conflict detection. Logical conflicts use SHACL shapes and ontology axioms. Track which source each conflicting fact came from. The graph being checked for conflicts.