Skip to content

Graph-Native Infrastructure for Context and Accountable AI Systems

fix: resolve Qodo review bugs and quality issues (DuplicateDetector + ConflictDetector)

KaifAhmad121c2f190f8f4
diff --git a/semantica/conflicts/conflict_detector.py b/semantica/conflicts/conflict_detector.py
index 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.py
index 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_threshold
self.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_similarity
self.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 calculator
Returns:
- 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 field
candidates.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 + 1
candidates = 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.py
index 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 = 1
results = 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 count
k = 2
results = 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, 1
results = self._base_detector(min_similarity=floor, top_k_per_entity=k).detect_duplicates(self.entities)
+ # min_similarity floor still applies
for 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 = 1
results = 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)