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
Optimize structural precedent search on large context graphs (#2008)
careli-toolsee7ccff7b71e
diff --git a/semantica/context/context_graph.py b/semantica/context/context_graph.pyindex b5381114..935a4187 100644--- a/semantica/context/context_graph.py+++ b/semantica/context/context_graph.py@@ -117,6 +117,7 @@ import statimport tempfileimport threadingimport uuid+from bisect import bisect_leftfrom collections import defaultdict, dequefrom dataclasses import dataclass, fieldfrom datetime import date, datetime, timezone@@ -4599,6 +4600,14 @@ class ContextGraph:entity_candidates.update(self._entity_index.get(entity, set()))candidates = candidates.intersection(entity_candidates)+ # Reuse a query-local snapshot of node types and outgoing degrees. The+ # structural score is the maximum over all other nodes, so scanning and+ # sorting the entire graph once per decision is unnecessary.+ structural_scores = (+ self._precedent_structural_scores(candidates)+ if self.config.get("advanced_analytics") else {}+ )+# Calculate similaritiesprecedents = []for decision_id in candidates:@@ -4614,9 +4623,7 @@ class ContextGraph:content_sim = self._calculate_decision_content_similarity(scenario, decision)# Structural similarity (graph-based)- structural_sim = 0.0- if self.config.get("advanced_analytics"):- structural_sim = self._calculate_structural_similarity_for_decision(decision_id, scenario)+ structural_sim = structural_scores.get(decision_id, 0.0)# Combined similaritycombined_sim = 0.7 * content_sim + 0.3 * structural_sim@@ -5505,6 +5512,48 @@ class ContextGraph:self.logger.exception("Content similarity calculation failed")return 0.0+ def _precedent_structural_scores(self, decision_ids: Set[str]) -> Dict[str, float]:+ """Return the existing structural score without per-decision graph scans.++ ``find_similar_nodes(..., similarity_type="structural")`` compares node+ type and outgoing degree. Its highest score is therefore determined by+ the nearest *other* degree of the same type. Keep this index local to the+ call so graph mutations and reloads cannot leave stale scores behind.+ """+ degree_counts: Dict[str, Dict[int, int]] = defaultdict(lambda: defaultdict(int))+ decision_degrees: Dict[str, Tuple[str, int]] = {}+ with self._lock:+ for node_id, node in self.nodes.items():+ degree_counts[node.node_type][len(self._adjacency.get(node_id, ()))] += 1+ for decision_id in decision_ids:+ node = self.nodes.get(decision_id)+ if node is not None:+ decision_degrees[decision_id] = (+ node.node_type,+ len(self._adjacency.get(decision_id, ())),+ )++ sorted_degrees = {+ node_type: sorted(counts)+ for node_type, counts in degree_counts.items()+ }+ scores: Dict[str, float] = {}+ for decision_id, (node_type, degree) in decision_degrees.items():+ counts = degree_counts[node_type]+ if counts[degree] > 1:+ scores[decision_id] = 1.0+ continue+ degrees = sorted_degrees[node_type]+ position = bisect_left(degrees, degree)+ lower = degrees[position - 1] if position > 0 else None+ upper = degrees[position + 1] if position + 1 < len(degrees) else None+ scores[decision_id] = max(+ (1.0 - abs(degree - other) / max(degree, other, 1)+ for other in (lower, upper) if other is not None),+ default=0.0,+ )+ return scores+def _calculate_structural_similarity_for_decision(self, decision_id: str, scenario: str) -> float:"""Calculate structural similarity using graph algorithms."""try:diff --git a/tests/context/test_precedent_structural_scores.py b/tests/context/test_precedent_structural_scores.pynew file mode 100644index 00000000..ba9b34d5--- /dev/null+++ b/tests/context/test_precedent_structural_scores.py@@ -0,0 +1,138 @@+"""Structural precedent scores preserve full-scan ranking and follow graph changes."""++import math+import unittest+from concurrent.futures import ThreadPoolExecutor++from semantica.context import ContextGraph+++class TestPrecedentStructuralScores(unittest.TestCase):+ def make_graph(self):+ graph = ContextGraph(advanced_analytics=True)+ for index in range(4):+ graph.add_node(f"target-{index}", "target")+ decisions = [+ graph.record_decision(+ category="test",+ scenario=f"case {index} shared term",+ reasoning="fixture",+ outcome="retain",+ confidence=0.8,+ )+ for index in range(4)+ ]+ graph.add_edge(decisions[0], "target-0")+ graph.add_edge(decisions[0], "target-1")+ graph.add_edge(decisions[1], "target-0")+ graph.add_edge(decisions[2], "target-0")+ return graph, decisions++ def test_structural_scores_equal_full_scan_and_follow_mutations(self):+ graph, decisions = self.make_graph()+ for decision_id in decisions:+ with self.subTest(decision_id=decision_id):+ fast = graph._precedent_structural_scores(set(decisions))[decision_id]+ slow = graph._calculate_structural_similarity_for_decision(+ decision_id, "case"+ )+ self.assertTrue(math.isclose(fast, slow))++ before = graph._precedent_structural_scores(set(decisions))+ graph.add_edge(decisions[3], "target-2")+ after = graph._precedent_structural_scores(set(decisions))+ self.assertNotEqual(before, after)+ self.assertTrue(graph.config["advanced_analytics"])++ def test_structural_scores_equal_full_scan_with_mixed_node_types(self):+ graph = ContextGraph(advanced_analytics=True)+ targets = [f"target-{index}" for index in range(6)]+ for target in targets:+ graph.add_node(target, "entity")+ decisions = [+ graph.record_decision(+ category="test", scenario=f"case {index}", reasoning="fixture",+ outcome="retain", confidence=0.8,+ )+ for index in range(5)+ ]+ # Same-type nodes that are not recorded decisions still count.+ graph.add_node("bare-decision", "decision")+ # An entity hub one degree away from decisions[0]; it must be ignored.+ graph.add_node("hub", "entity")+ for target in targets[:4]:+ graph.add_edge("hub", target)++ # Each decision starts with one category edge.+ graph.add_edge(decisions[0], decisions[0]) # self-loop+ graph.add_edge(decisions[0], targets[0])+ for target in targets[:3]:+ graph.add_edge(decisions[1], target)+ graph.add_edge(decisions[1], targets[0], edge_type="cites")+ for target in targets:+ graph.add_edge(decisions[4], target)+ # decisions[2] and decisions[3] share degree 1; bare-decision has 0.++ node_ids = set(decisions) | {"bare-decision"}+ fast = graph._precedent_structural_scores(node_ids)+ for node_id in node_ids:+ with self.subTest(node_id=node_id):+ slow = graph._calculate_structural_similarity_for_decision(+ node_id, "case"+ )+ self.assertEqual(fast[node_id], slow)++ def test_singleton_and_same_degree_nodes(self):+ graph = ContextGraph(advanced_analytics=True)+ first = graph.record_decision(+ category="test", scenario="first", reasoning="fixture",+ outcome="retain", confidence=0.8,+ )+ self.assertEqual(graph._precedent_structural_scores({first})[first], 0.0)+ second = graph.record_decision(+ category="test", scenario="second", reasoning="fixture",+ outcome="retain", confidence=0.8,+ )+ scores = graph._precedent_structural_scores({first, second})+ self.assertEqual(scores[first], 1.0)+ self.assertEqual(scores[second], 1.0)++ def test_precedent_ranking_matches_full_scan(self):+ graph, decisions = self.make_graph()+ scenario = "case 0 shared term"+ expected = []+ for decision_id in decisions:+ decision = graph._decisions[decision_id]+ content = graph._calculate_decision_content_similarity(scenario, decision)+ structural = graph._calculate_structural_similarity_for_decision(+ decision_id, scenario+ )+ expected.append((decision_id, 0.7 * content + 0.3 * structural))+ expected.sort(key=lambda item: item[1], reverse=True)++ actual = graph.find_precedents_by_scenario(+ scenario, limit=4, similarity_threshold=0.0+ )+ # Set iteration makes the order of equal-scoring decisions undefined.+ self.assertEqual(actual[0]["decision"]["id"], decisions[0])+ self.assertEqual(+ sorted((row["decision"]["id"], row["similarity"]) for row in actual),+ sorted(expected),+ )+ self.assertEqual(+ [row["similarity"] for row in actual],+ [score for _, score in expected],+ )++ def test_parallel_readers_share_no_index_state(self):+ graph, decisions = self.make_graph()+ with ThreadPoolExecutor(max_workers=4) as pool:+ results = list(pool.map(+ lambda _: graph.find_precedents_by_scenario(+ "case 0 shared term", limit=4, similarity_threshold=0.0+ ),+ range(8),+ ))+ ids = [[row["decision"]["id"] for row in rows] for rows in results]+ self.assertTrue(all(row == ids[0] for row in ids))+ self.assertEqual(len(ids[0]), len(decisions))