Skip to content

Graph-Native Infrastructure for Context and Accountable AI Systems

26.6 KB
Raw Blame
import json
import unittest
from datetime import datetime
from unittest.mock import MagicMock, patch

from semantica.conflicts.conflict_analyzer import ConflictAnalyzer
from semantica.conflicts.conflict_detector import (
    Conflict,
    ConflictDetector,
    ConflictType,
)
from semantica.conflicts.conflict_resolver import ConflictResolver
from semantica.conflicts.investigation_guide import InvestigationGuideGenerator
from semantica.conflicts.source_tracker import SourceReference, SourceTracker


class TestConflictsModule(unittest.TestCase):
    def setUp(self):
        # Mock progress tracker
        self.mock_tracker_patcher = patch(
            "semantica.utils.progress_tracker.get_progress_tracker"
        )
        self.mock_get_tracker = self.mock_tracker_patcher.start()
        self.mock_tracker = MagicMock()
        self.mock_get_tracker.return_value = self.mock_tracker

        self.setUp_data()

    def tearDown(self):
        self.mock_tracker_patcher.stop()

    def setUp_data(self):
        # Setup common data for tests
        self.entities = [
            {
                "id": "e1",
                "type": "Person",
                "name": "John Doe",
                "properties": {"age": 30, "location": "New York"},
                "source": "source1",
                "page": 1,
                "confidence": 0.9,
                "metadata": {"timestamp": "2023-01-01T10:00:00"},
            },
            {
                "id": "e1",
                "type": "Person",
                "name": "John Doe",
                "properties": {"age": 32, "location": "Boston"},
                "source": "source2",
                "page": 5,
                "confidence": 0.8,
                "metadata": {"timestamp": "2023-06-01T10:00:00"},
            },
        ]

        self.source1 = SourceReference(
            document="doc1", page=1, confidence=0.9, timestamp=datetime(2023, 1, 1)
        )
        self.source2 = SourceReference(
            document="doc2", page=2, confidence=0.8, timestamp=datetime(2023, 6, 1)
        )

    def test_source_tracker(self):
        tracker = SourceTracker()

        # Test tracking property source
        tracker.track_property_source("e1", "age", 30, self.source1)
        tracker.track_property_source("e1", "age", 32, self.source2)

        # Test getting property sources
        prop_source = tracker.get_property_sources("e1", "age")
        self.assertIsNotNone(prop_source)
        self.assertEqual(len(prop_source.sources), 2)
        self.assertEqual(prop_source.value, 32)  # Should store latest value

        # Test finding disagreements
        disagreements = tracker.find_source_disagreements("e1", "age")
        # Since we tracked different sources for the same property, there might be
        # disagreements based on how find_source_disagreements works.
        self.assertTrue(len(disagreements) > 0)

        # Test tracking entity source
        tracker.track_entity_source("e1", self.source1)
        sources = tracker.get_entity_sources("e1")
        self.assertTrue(len(sources) >= 1)

    def test_track_sources_batch_failure_not_counted(self):
        """Test that track_sources_batch does not increment stats when tracking fails (#783)."""
        tracker = SourceTracker()
        source_data = [
            {
                "type": "property",
                "entity_id": "e1",
                "property_name": "age",
                "value": 30,
                "source": self.source1,
            },
            {
                "type": "property",
                "entity_id": "e2",
                "property_name": "age",
                "value": 25,
                "source": self.source2,
            },
        ]
        with patch.object(tracker, "track_property_source", return_value=False):
            stats = tracker.track_sources_batch(source_data)
            self.assertEqual(stats["properties_tracked"], 0)
            self.assertEqual(stats["total_tracked"], 0)

    def test_conflict_detector(self):
        detector = ConflictDetector()

        # We need to flatten the entities structure for detect_value_conflicts since it
        # expects properties at top-level (value = entity[property_name]).

        flat_entities = [
            {"id": "e1", "age": 30, "source": "source1", "confidence": 0.9},
            {"id": "e1", "age": 32, "source": "source2", "confidence": 0.8},
        ]

        conflicts = detector.detect_value_conflicts(flat_entities, "age")

        self.assertEqual(len(conflicts), 1)
        conflict = conflicts[0]
        self.assertEqual(conflict.entity_id, "e1")
        self.assertEqual(conflict.property_name, "age")
        self.assertEqual(conflict.conflict_type, ConflictType.VALUE_CONFLICT)
        self.assertEqual(len(conflict.conflicting_values), 2)
        self.assertIn(30, conflict.conflicting_values)
        self.assertIn(32, conflict.conflicting_values)

        # Test type conflicts
        type_entities = [
            {"id": "e2", "type": "Person", "source": "s1"},
            {"id": "e2", "type": "Organization", "source": "s2"},
        ]
        type_conflicts = detector.detect_type_conflicts(type_entities)
        self.assertEqual(len(type_conflicts), 1)
        self.assertEqual(type_conflicts[0].conflict_type, ConflictType.TYPE_CONFLICT)

    def test_conflict_resolver(self):
        resolver = ConflictResolver()

        conflict = Conflict(
            conflict_id="c1",
            conflict_type=ConflictType.VALUE_CONFLICT,
            entity_id="e1",
            property_name="age",
            conflicting_values=[30, 30, 32],
            sources=[
                {
                    "document": "doc1",
                    "confidence": 0.9,
                    "metadata": {"timestamp": datetime(2023, 1, 1)},
                },
                {
                    "document": "doc3",
                    "confidence": 0.9,
                    "metadata": {"timestamp": datetime(2023, 1, 2)},
                },
                {
                    "document": "doc2",
                    "confidence": 0.8,
                    "metadata": {"timestamp": datetime(2023, 6, 1)},
                },
            ],
        )

        # Test Voting
        result_voting = resolver.resolve_conflict(conflict, strategy="voting")
        self.assertTrue(result_voting.resolved)
        self.assertEqual(result_voting.resolved_value, 30)  # 30 appears twice

        # Test Most Recent
        result_recent = resolver.resolve_conflict(conflict, strategy="most_recent")
        self.assertTrue(result_recent.resolved)
        self.assertEqual(result_recent.resolved_value, 32)  # doc2 is most recent (June)

        # Test Highest Confidence
        # doc1 and doc3 have 0.9, doc2 has 0.8. Should pick 30 (first max confidence)
        result_conf = resolver.resolve_conflict(conflict, strategy="highest_confidence")
        self.assertTrue(result_conf.resolved)
        self.assertEqual(result_conf.resolved_value, 30)

    def test_conflict_analyzer(self):
        analyzer = ConflictAnalyzer()

        conflicts = [
            Conflict(
                conflict_id="c1",
                conflict_type=ConflictType.VALUE_CONFLICT,
                entity_id="e1",
                property_name="age",
                conflicting_values=[30, 32],
                sources=[{"document": "doc1"}, {"document": "doc2"}],
                severity="medium",
            ),
            Conflict(
                conflict_id="c2",
                conflict_type=ConflictType.TYPE_CONFLICT,
                entity_id="e2",
                property_name="type",
                conflicting_values=["Person", "Org"],
                sources=[{"document": "doc1"}, {"document": "doc3"}],
                severity="critical",
            ),
        ]

        analysis = analyzer.analyze_conflicts(conflicts)

        self.assertEqual(analysis["total_conflicts"], 2)
        self.assertEqual(analysis["by_severity"]["counts"]["critical"], 1)
        self.assertEqual(analysis["by_severity"]["counts"]["medium"], 1)
        self.assertIn("recommendations", analysis)

    def test_investigation_guide(self):
        generator = InvestigationGuideGenerator()

        conflict = Conflict(
            conflict_id="c1",
            conflict_type=ConflictType.VALUE_CONFLICT,
            entity_id="e1",
            property_name="age",
            conflicting_values=[30, 32],
            sources=[{"document": "doc1"}, {"document": "doc2"}],
            severity="medium",
        )

        guide = generator.generate_guide(conflict)

        self.assertEqual(guide.conflict_id, "c1")
        self.assertEqual(guide.severity, "medium")
        self.assertTrue(len(guide.investigation_steps) > 0)
        self.assertTrue(len(guide.recommended_actions) > 0)

        # Test checklist export
        checklist = generator.export_investigation_checklist(guide, format="text")
        self.assertIn("INVESTIGATION GUIDE: c1", checklist)

    def test_conflict_resolver_credibility_weighted(self):
        """Test credibility-weighted resolution strategy (#865)."""
        resolver = ConflictResolver()

        # Boost the credibility of "doc_trusted" so its value should win
        # even though it only has one vote, vs. two lower-credibility votes.
        # Use the validated setter rather than mutating the internal dict
        # directly, so the test stays coupled to the public API surface.
        resolver.source_tracker.set_source_credibility("doc_trusted", 1.0)
        resolver.source_tracker.set_source_credibility("doc_flaky", 0.1)

        conflict = Conflict(
            conflict_id="c_cred",
            conflict_type=ConflictType.VALUE_CONFLICT,
            entity_id="e1",
            property_name="age",
            conflicting_values=[30, 30, 40],
            sources=[
                {"document": "doc_flaky", "confidence": 0.9},
                {"document": "doc_flaky", "confidence": 0.9},
                {"document": "doc_trusted", "confidence": 0.9},
            ],
        )

        result = resolver.resolve_conflict(conflict, strategy="credibility_weighted")
        self.assertTrue(result.resolved)
        self.assertEqual(result.resolved_value, 40)
        self.assertEqual(result.resolution_strategy, "credibility_weighted")
        self.assertGreater(result.confidence, 0.0)

    def test_conflict_resolver_first_seen(self):
        """Test first-seen resolution strategy (#865)."""
        resolver = ConflictResolver()

        conflict = Conflict(
            conflict_id="c_first",
            conflict_type=ConflictType.VALUE_CONFLICT,
            entity_id="e1",
            property_name="age",
            conflicting_values=[30, 32],
            sources=[
                {"document": "doc1", "confidence": 0.9},
                {"document": "doc2", "confidence": 0.9},
            ],
        )

        result = resolver.resolve_conflict(conflict, strategy="first_seen")
        self.assertTrue(result.resolved)
        self.assertEqual(result.resolved_value, 30)  # first value in the list
        self.assertEqual(result.resolution_strategy, "first_seen")
        self.assertEqual(result.sources_used, ["doc1"])

    def test_conflict_resolver_manual_review(self):
        """Test manual-review resolution strategy flags without resolving (#865)."""
        resolver = ConflictResolver()

        conflict = Conflict(
            conflict_id="c_manual",
            conflict_type=ConflictType.VALUE_CONFLICT,
            entity_id="e1",
            property_name="age",
            conflicting_values=[30, 32],
            sources=[{"document": "doc1"}, {"document": "doc2"}],
            severity="high",
        )

        result = resolver.resolve_conflict(conflict, strategy="manual_review")
        self.assertFalse(result.resolved)
        self.assertEqual(result.resolution_strategy, "manual_review")
        self.assertTrue(result.metadata.get("requires_manual_review"))
        self.assertEqual(result.metadata.get("severity"), "high")

    def test_conflict_resolver_expert_review(self):
        """Test expert-review resolution strategy flags without resolving (#865)."""
        resolver = ConflictResolver()

        conflict = Conflict(
            conflict_id="c_expert",
            conflict_type=ConflictType.VALUE_CONFLICT,
            entity_id="e1",
            property_name="age",
            conflicting_values=[30, 32],
            sources=[{"document": "doc1"}, {"document": "doc2"}],
            severity="critical",
        )

        result = resolver.resolve_conflict(conflict, strategy="expert_review")
        self.assertFalse(result.resolved)
        self.assertEqual(result.resolution_strategy, "expert_review")
        self.assertTrue(result.metadata.get("requires_expert_review"))
        self.assertEqual(result.metadata.get("severity"), "critical")

    def test_conflict_detector_relationship_conflicts(self):
        """Test relationship conflict detection (#865)."""
        detector = ConflictDetector()

        relationships = [
            {
                "id": "r1",
                "source_id": "e1",
                "target_id": "e2",
                "type": "works_at",
                "source": "doc1",
            },
            {
                "id": "r1",
                "source_id": "e1",
                "target_id": "e2",
                "type": "founded",
                "source": "doc2",
            },
        ]

        conflicts = detector.detect_relationship_conflicts(relationships)
        self.assertEqual(len(conflicts), 1)
        conflict = conflicts[0]
        self.assertEqual(conflict.conflict_type, ConflictType.RELATIONSHIP_CONFLICT)
        self.assertEqual(conflict.relationship_id, "r1")
        self.assertEqual(conflict.property_name, "type")
        self.assertIn("works_at", conflict.conflicting_values)
        self.assertIn("founded", conflict.conflicting_values)

    def test_conflict_detector_relationship_conflicts_no_conflict(self):
        """Relationships with a single occurrence should not raise conflicts (#865)."""
        detector = ConflictDetector()

        relationships = [
            {"id": "r1", "source_id": "e1", "target_id": "e2", "type": "works_at"},
        ]

        conflicts = detector.detect_relationship_conflicts(relationships)
        self.assertEqual(len(conflicts), 0)

    def test_conflict_detector_temporal_conflicts(self):
        """Test temporal conflict detection (#865)."""
        detector = ConflictDetector()

        entities = [
            {"id": "e1", "founded": "1998", "source": "doc1", "confidence": 0.9},
            {"id": "e1", "founded": "2004", "source": "doc2", "confidence": 0.8},
        ]

        conflicts = detector.detect_temporal_conflicts(entities)
        self.assertEqual(len(conflicts), 1)
        conflict = conflicts[0]
        self.assertEqual(conflict.conflict_type, ConflictType.TEMPORAL_CONFLICT)
        self.assertEqual(conflict.entity_id, "e1")
        self.assertEqual(conflict.property_name, "founded")
        self.assertIn("1998", conflict.conflicting_values)
        self.assertIn("2004", conflict.conflicting_values)

    def test_conflict_detector_temporal_conflicts_no_conflict(self):
        """Matching temporal values across sources should not raise conflicts (#865)."""
        detector = ConflictDetector()

        entities = [
            {"id": "e1", "founded": "1998", "source": "doc1"},
            {"id": "e1", "founded": "1998", "source": "doc2"},
        ]

        conflicts = detector.detect_temporal_conflicts(entities)
        self.assertEqual(len(conflicts), 0)

    def test_conflict_detector_logical_conflicts(self):
        """Test logical conflict detection for incompatible entity types (#865)."""
        detector = ConflictDetector()

        entities = [
            {"id": "e1", "type": "Person", "source": "doc1"},
            {"id": "e1", "type": "Organization", "source": "doc2"},
        ]

        conflicts = detector.detect_logical_conflicts(entities)
        self.assertEqual(len(conflicts), 1)
        conflict = conflicts[0]
        self.assertEqual(conflict.conflict_type, ConflictType.LOGICAL_CONFLICT)
        self.assertEqual(conflict.entity_id, "e1")
        self.assertEqual(conflict.severity, "critical")
        self.assertIn("Person", conflict.conflicting_values)
        self.assertIn("Organization", conflict.conflicting_values)

    def test_conflict_detector_logical_conflicts_compatible_types(self):
        """Compatible/unrelated types should not raise logical conflicts (#865)."""
        detector = ConflictDetector()

        entities = [
            {"id": "e1", "type": "Person", "source": "doc1"},
            {"id": "e1", "type": "Employee", "source": "doc2"},
        ]

        conflicts = detector.detect_logical_conflicts(entities)
        self.assertEqual(len(conflicts), 0)

    def test_conflict_analyzer_by_source_breakdown(self):
        """Test the by_source breakdown of analyze_conflicts (#902)."""
        analyzer = ConflictAnalyzer()

        conflicts = [
            Conflict(
                conflict_id="c1",
                conflict_type=ConflictType.VALUE_CONFLICT,
                entity_id="e1",
                property_name="age",
                conflicting_values=[30, 32],
                sources=[{"document": "doc1"}, {"document": "doc2"}],
                severity="medium",
            ),
            Conflict(
                conflict_id="c2",
                conflict_type=ConflictType.TYPE_CONFLICT,
                entity_id="e2",
                property_name="type",
                conflicting_values=["Person", "Org"],
                sources=[{"document": "doc1"}, {"document": "doc3"}],
                severity="critical",
            ),
        ]

        analysis = analyzer.analyze_conflicts(conflicts)

        self.assertIn("by_source", analysis)
        by_source = analysis["by_source"]

        # doc1 appears in both conflicts, doc2 and doc3 in one each.
        self.assertEqual(by_source["counts"]["doc1"], 2)
        self.assertEqual(by_source["counts"]["doc2"], 1)
        self.assertEqual(by_source["counts"]["doc3"], 1)

        top_sources = {
            s["source"]: s["conflict_count"] for s in by_source["top_sources"]
        }
        self.assertEqual(top_sources["doc1"], 2)

        self.assertIn("doc1", by_source["details"])
        doc1_entries = by_source["details"]["doc1"]
        self.assertEqual(len(doc1_entries), 2)
        self.assertEqual({e["conflict_id"] for e in doc1_entries}, {"c1", "c2"})

    def test_conflict_analyzer_analyze_trends(self):
        """Test analyze_trends over deterministic, time-ordered data (#902)."""
        analyzer = ConflictAnalyzer()

        def make_conflict(conflict_id, timestamp):
            return Conflict(
                conflict_id=conflict_id,
                conflict_type=ConflictType.VALUE_CONFLICT,
                entity_id="e1",
                property_name="age",
                conflicting_values=[30, 32],
                sources=[{"document": "doc1", "metadata": {"timestamp": timestamp}}],
            )

        # January: 1 conflict. February: 3 conflicts (>10% increase -> "increasing").
        conflicts = [
            make_conflict("c1", "2023-01-05T00:00:00"),
            make_conflict("c2", "2023-02-01T00:00:00"),
            make_conflict("c3", "2023-02-10T00:00:00"),
            make_conflict("c4", "2023-02-20T00:00:00"),
        ]

        trends = analyzer.analyze_trends(conflicts)

        self.assertEqual(len(trends), 2)
        self.assertEqual(trends[0]["period"], "2023-01")
        self.assertEqual(trends[0]["conflict_count"], 1)
        self.assertEqual(trends[1]["period"], "2023-02")
        self.assertEqual(trends[1]["conflict_count"], 3)
        self.assertEqual(trends[1]["trend"], "increasing")
        self.assertEqual(trends[1]["trend_direction"], "up")

    def test_conflict_analyzer_analyze_trends_insufficient_data(self):
        """Single-period data should report insufficient_data, not crash (#902)."""
        analyzer = ConflictAnalyzer()

        conflict = Conflict(
            conflict_id="c1",
            conflict_type=ConflictType.VALUE_CONFLICT,
            entity_id="e1",
            property_name="age",
            conflicting_values=[30, 32],
            sources=[
                {"document": "doc1", "metadata": {"timestamp": "2023-01-05T00:00:00"}}
            ],
        )

        trends = analyzer.analyze_trends([conflict])

        self.assertEqual(len(trends), 1)
        self.assertEqual(trends[0]["trend"], "insufficient_data")
        self.assertEqual(trends[0]["conflict_count"], 1)

    def test_resolve_by_voting_with_unhashable_values(self):
        """Voting must handle unhashable values (dict/list) without crashing."""
        resolver = ConflictResolver()

        val_a = {"city": "New York", "zip": "10001"}
        val_b = {"city": "Boston", "zip": "02101"}
        conflict = Conflict(
            conflict_id="c_unhashable_vote",
            conflict_type=ConflictType.VALUE_CONFLICT,
            entity_id="e1",
            property_name="address",
            conflicting_values=[val_a, val_a, val_b],
            sources=[
                {"document": "doc1", "confidence": 0.9},
                {"document": "doc2", "confidence": 0.8},
                {"document": "doc3", "confidence": 0.7},
            ],
        )

        result = resolver.resolve_conflict(conflict, strategy="voting")
        self.assertTrue(result.resolved)
        # The majority value (val_a appears twice) must win and be returned
        # as the original dict, not a stringified key.
        self.assertEqual(result.resolved_value, val_a)
        self.assertIsInstance(result.resolved_value, dict)

    def test_resolve_by_credibility_with_unhashable_values(self):
        """Credibility-weighted resolution must handle unhashable values."""
        resolver = ConflictResolver()
        resolver.source_tracker.set_source_credibility("doc_trusted", 1.0)
        resolver.source_tracker.set_source_credibility("doc_flaky", 0.1)

        val_a = ["tag1", "tag2"]
        val_b = ["tag3"]
        conflict = Conflict(
            conflict_id="c_unhashable_cred",
            conflict_type=ConflictType.VALUE_CONFLICT,
            entity_id="e1",
            property_name="tags",
            conflicting_values=[val_a, val_a, val_b],
            sources=[
                {"document": "doc_flaky", "confidence": 0.9},
                {"document": "doc_flaky", "confidence": 0.9},
                {"document": "doc_trusted", "confidence": 0.9},
            ],
        )

        result = resolver.resolve_conflict(conflict, strategy="credibility_weighted")
        self.assertTrue(result.resolved)
        # doc_trusted has far higher credibility, so val_b should win and be
        # returned as the original list.
        self.assertEqual(result.resolved_value, val_b)
        self.assertIsInstance(result.resolved_value, list)

    def test_voting_does_not_alias_struct_with_its_json_text(self):
        """A dict and a string equal to its JSON text must not be merged.

        Regression for PR #1208 review: type-tagged keys must keep a
        serialized structure distinct from a scalar string that happens to
        equal that serialization, so the majority string wins instead of the
        single dict.
        """
        resolver = ConflictResolver()

        struct = {"a": 1}
        json_text = json.dumps(struct, sort_keys=True)  # '{"a": 1}'
        conflict = Conflict(
            conflict_id="c_alias_vote",
            conflict_type=ConflictType.VALUE_CONFLICT,
            entity_id="e1",
            property_name="payload",
            conflicting_values=[struct, json_text, json_text],
            sources=[
                {"document": "doc1", "confidence": 0.9},
                {"document": "doc2", "confidence": 0.8},
                {"document": "doc3", "confidence": 0.7},
            ],
        )

        result = resolver.resolve_conflict(conflict, strategy="voting")
        self.assertTrue(result.resolved)
        # The two identical json_text strings are the true majority; they must
        # not be aliased with the dict.
        self.assertEqual(result.resolved_value, json_text)
        self.assertIsInstance(result.resolved_value, str)

    def test_voting_aggregates_int_and_float_equal_values(self):
        """1 and 1.0 must aggregate as the same voting value.

        Python defines 1 == 1.0 and hash(1) == hash(1.0).  The hashable-key
        path must preserve this semantics so that a conflict containing both
        int and float representations of the same number counts them together
        rather than splitting them into separate buckets.
        """
        resolver = ConflictResolver()

        conflict = Conflict(
            conflict_id="c_int_float_vote",
            conflict_type=ConflictType.VALUE_CONFLICT,
            entity_id="e1",
            property_name="score",
            # 1 (int) and 1.0 (float) should merge → 3 votes vs 1 vote for 2
            conflicting_values=[1, 1.0, 1, 2],
            sources=[
                {"document": "doc1", "confidence": 0.9},
                {"document": "doc2", "confidence": 0.9},
                {"document": "doc3", "confidence": 0.9},
                {"document": "doc4", "confidence": 0.9},
            ],
        )

        result = resolver.resolve_conflict(conflict, strategy="voting")
        self.assertTrue(result.resolved)
        # 1 and 1.0 are equal in Python; the merged bucket has 3 votes and wins
        self.assertEqual(result.resolved_value, 1)
        self.assertNotEqual(result.resolved_value, 2)

    def test_voting_aggregates_bool_and_int_equal_values(self):
        """True and 1 must aggregate as the same voting value.

        Python defines True == 1 and hash(True) == hash(1).  The hashable-key
        path must preserve this semantics so that boolean True and integer 1
        are treated as the same candidate rather than split across separate
        buckets.
        """
        resolver = ConflictResolver()

        conflict = Conflict(
            conflict_id="c_bool_int_vote",
            conflict_type=ConflictType.VALUE_CONFLICT,
            entity_id="e1",
            property_name="flag",
            # True and 1 should merge → 3 votes vs 1 vote for False
            conflicting_values=[True, 1, True, False],
            sources=[
                {"document": "doc1", "confidence": 0.9},
                {"document": "doc2", "confidence": 0.9},
                {"document": "doc3", "confidence": 0.9},
                {"document": "doc4", "confidence": 0.9},
            ],
        )

        result = resolver.resolve_conflict(conflict, strategy="voting")
        self.assertTrue(result.resolved)
        # True and 1 are equal in Python; the merged bucket has 3 votes and wins
        self.assertTrue(result.resolved_value == 1)  # True == 1 passes
        self.assertNotEqual(result.resolved_value, False)


if __name__ == "__main__":
    unittest.main()