Skip to content

Graph-Native Infrastructure for Context and Accountable AI Systems

Optimize structural precedent search on large context graphs (#2008)

careli-toolsee7ccff7b71e
diff --git a/semantica/context/context_graph.py b/semantica/context/context_graph.py
index b5381114..935a4187 100644
--- a/semantica/context/context_graph.py
+++ b/semantica/context/context_graph.py
@@ -117,6 +117,7 @@ import stat
import tempfile
import threading
import uuid
+from bisect import bisect_left
from collections import defaultdict, deque
from dataclasses import dataclass, field
from 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 similarities
precedents = []
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 similarity
combined_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.py
new file mode 100644
index 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))