Graph-Native Infrastructure for Context and Accountable AI Systems
Python agent-memoryaiai-governanceai-infrastructureartificial-intelligencecontext-engineeringcontext-graphsdata-engineeringdecision-intelligencedeveloper-toolsexplainable-aigenerative-aigraph-ragknowledge-graphllmontologyprovenancepythonreasoningsemantic-search
fix: resolve Qodo review bugs and quality issues (DuplicateDetector + ConflictDetector)
KaifAhmad121c2f190f8f4
diff --git a/semantica/conflicts/conflict_detector.py b/semantica/conflicts/conflict_detector.pyindex d7396c14..3efd3dd5 100644--- a/semantica/conflicts/conflict_detector.py+++ b/semantica/conflicts/conflict_detector.py@@ -1247,7 +1247,10 @@ class ConflictDetector:elif method == "relationship":relationships = kwargs.get("relationships", [])if isinstance(relationships, dict):- relationships = relationships.get("relationships", [relationships])+ inner = relationships.get("relationships", relationships)+ relationships = inner if isinstance(inner, list) else [inner]+ if not isinstance(relationships, list):+ relationships = [relationships]return self.detect_relationship_conflicts(relationships)elif method == "temporal":return self.detect_temporal_conflicts(entities)diff --git a/semantica/deduplication/duplicate_detector.py b/semantica/deduplication/duplicate_detector.pyindex 52710b8e..fcc52aaa 100644--- a/semantica/deduplication/duplicate_detector.py+++ b/semantica/deduplication/duplicate_detector.py@@ -147,14 +147,28 @@ class DuplicateDetector:self.confidence_threshold = confidence_thresholdself.use_clustering = use_clustering- # Result limiting / ranking options- self.max_results = max_results- self.top_k_per_entity = top_k_per_entity- self.min_similarity = min_similarity+ # Result limiting / ranking options — validate at construction time+ if max_results is not None and (not isinstance(max_results, int) or max_results < 0):+ raise ValueError(+ f"max_results must be None or a non-negative int, got {max_results!r}"+ )+ if top_k_per_entity is not None and (+ not isinstance(top_k_per_entity, int) or top_k_per_entity < 0+ ):+ raise ValueError(+ f"top_k_per_entity must be None or a non-negative int, got {top_k_per_entity!r}"+ )+ if min_similarity is not None and not (0.0 <= min_similarity <= 1.0):+ raise ValueError(+ f"min_similarity must be None or a float in [0.0, 1.0], got {min_similarity!r}"+ )if sort_by not in ("confidence", "similarity_score"):raise ValueError(f"sort_by must be 'confidence' or 'similarity_score', got {sort_by!r}")+ self.max_results = max_results+ self.top_k_per_entity = top_k_per_entity+ self.min_similarity = min_similarityself.sort_by = sort_by# Initialize progress tracker and ensure it's enabled@@ -179,8 +193,10 @@ class DuplicateDetector:Detect duplicate entities from a list.This method compares all pairs of entities and identifies duplicates based- on similarity scores and confidence thresholds. Returns candidates sorted- by confidence (highest first).+ on similarity scores and confidence thresholds. Results are filtered and+ ranked by ``_apply_result_limits`` using the instance ``sort_by`` field+ (default: ``"confidence"``), then capped by ``top_k_per_entity`` and+ ``max_results``.Args:entities: List of entity dictionaries to check for duplicates.@@ -189,8 +205,9 @@ class DuplicateDetector:**options: Additional detection options passed to similarity calculatorReturns:- List of DuplicateCandidate objects, sorted by confidence (highest first).- Each candidate contains:+ List of DuplicateCandidate objects sorted by the ``sort_by`` field+ (highest first, default ``"confidence"``), capped by ``top_k_per_entity``+ and ``max_results``. Each candidate contains:- entity1, entity2: The duplicate entity pair- similarity_score: Similarity score (0.0 to 1.0)- confidence: Confidence score (0.0 to 1.0)@@ -547,7 +564,9 @@ class DuplicateDetector:Returns:List of DuplicateCandidate objects representing duplicates between- new and existing entities, sorted by confidence (highest first).+ new and existing entities, sorted by the ``sort_by`` field (highest+ first, default ``"confidence"``), capped by ``top_k_per_entity`` and+ ``max_results``.Example:>>> new_entities = [{"id": "3", "name": "Apple Corp"}]@@ -668,19 +687,20 @@ class DuplicateDetector:# 2. Sort descending by the chosen fieldcandidates.sort(key=lambda c: getattr(c, self.sort_by), reverse=True)- # 3. top_k_per_entity+ # 3. top_k_per_entity — keep a candidate if *either* entity is still under+ # quota; once an entity reaches k it no longer sponsors new candidates.if self.top_k_per_entity is not None:entity_counts: Dict[str, int] = {}kept: List[DuplicateCandidate] = []for c in candidates:- id1 = self._get_entity_value(c.entity1, "id") or id(c.entity1)- id2 = self._get_entity_value(c.entity2, "id") or id(c.entity2)- count1 = entity_counts.get(str(id1), 0)- count2 = entity_counts.get(str(id2), 0)- if count1 < self.top_k_per_entity and count2 < self.top_k_per_entity:+ nid1 = self._normalize_entity_id(c.entity1)+ nid2 = self._normalize_entity_id(c.entity2)+ count1 = entity_counts.get(nid1, 0)+ count2 = entity_counts.get(nid2, 0)+ if count1 < self.top_k_per_entity or count2 < self.top_k_per_entity:kept.append(c)- entity_counts[str(id1)] = count1 + 1- entity_counts[str(id2)] = count2 + 1+ entity_counts[nid1] = count1 + 1+ entity_counts[nid2] = count2 + 1candidates = kept# 4. max_results global cap@@ -689,6 +709,13 @@ class DuplicateDetector:return candidates+ def _normalize_entity_id(self, entity: Any) -> str:+ """Return a stable string key for an entity, used as a dict key throughout the class."""+ raw = self._get_entity_value(entity, "id")+ if raw is None:+ raw = id(entity)+ return str(raw)+def _get_entity_value(self, entity: Any, key: str, default: Any = None) -> Any:"""Get value from entity dictionary or object safely."""if hasattr(entity, "__dict__"):@@ -784,12 +811,8 @@ class DuplicateDetector:groups = []for candidate in candidates:- entity1_id = self._get_entity_value(candidate.entity1, "id") or id(- candidate.entity1- )- entity2_id = self._get_entity_value(candidate.entity2, "id") or id(- candidate.entity2- )+ entity1_id = self._normalize_entity_id(candidate.entity1)+ entity2_id = self._normalize_entity_id(candidate.entity2)group1 = entity_to_group.get(entity1_id)group2 = entity_to_group.get(entity2_id)diff --git a/tests/deduplication/test_deduplication.py b/tests/deduplication/test_deduplication.pyindex b538adac..7a76617f 100644--- a/tests/deduplication/test_deduplication.py+++ b/tests/deduplication/test_deduplication.py@@ -334,24 +334,26 @@ class TestResultLimiting(unittest.TestCase):# ------------------------------------------------------------------def test_top_k_per_entity_k1(self):+ # OR semantics: keep if EITHER entity is under quota.+ # A popular entity can appear > k times (each new partner brings it back).+ # Invariant: no (entity1, entity2) pair is returned more than once.k = 1results = self._base_detector(top_k_per_entity=k).detect_duplicates(self.entities)- counts: Dict[str, int] = {}- for c in results:- for eid in (c.entity1["id"], c.entity2["id"]):- counts[eid] = counts.get(eid, 0) + 1- for eid, count in counts.items():- self.assertLessEqual(count, k, f"Entity {eid!r} appears {count} times, expected <= {k}")+ pairs = [(c.entity1["id"], c.entity2["id"]) for c in results]+ self.assertEqual(len(pairs), len(set(pairs)), "No duplicate pairs should appear")+ # OR gives >= results than AND — at least 1 result when matches exist+ and_results = self._base_detector().detect_duplicates(self.entities)+ if and_results:+ self.assertGreater(len(results), 0)def test_top_k_per_entity_k2(self):+ # Same OR semantics: no pair appears twice; result is bounded below by k=1 countk = 2results = self._base_detector(top_k_per_entity=k).detect_duplicates(self.entities)- counts: Dict[str, int] = {}- for c in results:- for eid in (c.entity1["id"], c.entity2["id"]):- counts[eid] = counts.get(eid, 0) + 1- for eid, count in counts.items():- self.assertLessEqual(count, k)+ pairs = [(c.entity1["id"], c.entity2["id"]) for c in results]+ self.assertEqual(len(pairs), len(set(pairs)), "No duplicate pairs should appear")+ k1_results = self._base_detector(top_k_per_entity=1).detect_duplicates(self.entities)+ self.assertGreaterEqual(len(results), len(k1_results))def test_top_k_per_entity_large_k_same_as_none(self):uncapped = self._base_detector().detect_duplicates(self.entities)@@ -426,6 +428,73 @@ class TestResultLimiting(unittest.TestCase):self._base_detector(sort_by="bogus_field")self.assertIn("bogus_field", str(ctx.exception))+ # ------------------------------------------------------------------+ # Input validation (bug_002 / bug_003)+ # ------------------------------------------------------------------++ def test_max_results_negative_raises(self):+ with self.assertRaises(ValueError):+ self._base_detector(max_results=-1)++ def test_max_results_float_raises(self):+ with self.assertRaises(ValueError):+ self._base_detector(max_results=1.5)++ def test_top_k_per_entity_negative_raises(self):+ with self.assertRaises(ValueError):+ self._base_detector(top_k_per_entity=-1)++ def test_top_k_per_entity_float_raises(self):+ with self.assertRaises(ValueError):+ self._base_detector(top_k_per_entity=2.5)++ def test_min_similarity_above_1_raises(self):+ with self.assertRaises(ValueError):+ self._base_detector(min_similarity=1.1)++ def test_min_similarity_below_0_raises(self):+ with self.assertRaises(ValueError):+ self._base_detector(min_similarity=-0.1)++ def test_max_results_zero_is_valid(self):+ # 0 is a non-negative int — must not raise+ detector = self._base_detector(max_results=0)+ self.assertEqual(detector.detect_duplicates(self.entities), [])++ def test_top_k_per_entity_zero_is_valid(self):+ detector = self._base_detector(top_k_per_entity=0)+ self.assertEqual(detector.detect_duplicates(self.entities), [])++ def test_min_similarity_boundary_0_valid(self):+ self._base_detector(min_similarity=0.0) # must not raise++ def test_min_similarity_boundary_1_valid(self):+ self._base_detector(min_similarity=1.0) # must not raise++ # ------------------------------------------------------------------+ # top_k_per_entity OR semantics (bug_001)+ # ------------------------------------------------------------------++ def test_top_k_or_semantics_keeps_candidate_if_either_under_quota(self):+ """A high-ranked candidate must survive even if one of its entities hit k,+ as long as the other entity is still under quota."""+ # With k=1 and OR semantics, every entity can appear in AT LEAST one+ # candidate. Verify that more candidates survive than would under AND.+ k = 1+ or_results = self._base_detector(top_k_per_entity=k).detect_duplicates(self.entities)+ # Each entity should appear at least once — no entity completely starved+ seen_ids: set = set()+ for c in or_results:+ seen_ids.add(c.entity1["id"])+ seen_ids.add(c.entity2["id"])+ # Entities that have at least one match above threshold must appear+ all_ids_in_any_pair: set = set()+ uncapped = self._base_detector().detect_duplicates(self.entities)+ for c in uncapped:+ all_ids_in_any_pair.add(c.entity1["id"])+ all_ids_in_any_pair.add(c.entity2["id"])+ self.assertEqual(seen_ids, all_ids_in_any_pair)+# ------------------------------------------------------------------# Combined options# ------------------------------------------------------------------@@ -440,14 +509,12 @@ class TestResultLimiting(unittest.TestCase):def test_min_similarity_and_top_k_combined(self):floor, k = 0.5, 1results = self._base_detector(min_similarity=floor, top_k_per_entity=k).detect_duplicates(self.entities)+ # min_similarity floor still appliesfor c in results:self.assertGreaterEqual(c.similarity_score, floor)- counts: Dict[str, int] = {}- for c in results:- for eid in (c.entity1["id"], c.entity2["id"]):- counts[eid] = counts.get(eid, 0) + 1- for count in counts.values():- self.assertLessEqual(count, k)+ # OR semantics: no pair duplicated+ pairs = [(c.entity1["id"], c.entity2["id"]) for c in results]+ self.assertEqual(len(pairs), len(set(pairs)))def test_all_four_options_combined(self):results = self._base_detector(@@ -493,12 +560,9 @@ class TestResultLimiting(unittest.TestCase):new_e, existing = self.entities[:3], self.entities[3:]k = 1results = self._base_detector(top_k_per_entity=k).incremental_detect(new_e, existing)- counts: Dict[str, int] = {}- for c in results:- for eid in (c.entity1["id"], c.entity2["id"]):- counts[eid] = counts.get(eid, 0) + 1- for count in counts.values():- self.assertLessEqual(count, k)+ # OR semantics: no pair appears twice+ pairs = [(c.entity1["id"], c.entity2["id"]) for c in results]+ self.assertEqual(len(pairs), len(set(pairs)))def test_incremental_detect_empty_new_entities(self):detector = self._base_detector(max_results=5)