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: add thread safety and pagination to ContextGraph
ZohaibHassan161d1ae398c4e3
diff --git a/semantica/context/context_graph.py b/semantica/context/context_graph.pyindex 6cae5ff9..d9bdadff 100644--- a/semantica/context/context_graph.py+++ b/semantica/context/context_graph.py@@ -108,6 +108,7 @@ Production Use Cases:from collections import defaultdict, dequefrom dataclasses import dataclass, fieldfrom datetime import datetime, timezone+import threadingfrom typing import Any, Dict, List, Optional, Set, Tuple, Unionimport uuid@@ -270,6 +271,9 @@ class ContextGraph:self.entity_linker = self.config.get("entity_linker") or EntityLinker()+ # Thread safety lock+ self._lock = threading.RLock()+# Stable identifier so this graph can be referenced after save/loadself.graph_id: str = str(uuid.uuid4())@@ -331,37 +335,38 @@ class ContextGraph:Number of nodes added"""count = 0- for node in nodes:- # Extract content from properties if not explicit- node_props = node.get("properties", {})- content = node_props.get("content", node.get("id"))- # Restore validity windows from properties (written there by ContextNode.to_dict)- # or from top-level keys on the node dict- valid_from = (- node.get("valid_from")- or node_props.get("valid_from")- )- valid_until = (- node.get("valid_until")- or node_props.get("valid_until")- )- metadata = {- k: v for k, v in node_props.items()- if k not in ("content", "valid_from", "valid_until")- }+ with self._lock:+ for node in nodes:+ # Extract content from properties if not explicit+ node_props = node.get("properties", {})+ content = node_props.get("content", node.get("id"))+ # Restore validity windows from properties (written there by ContextNode.to_dict)+ # or from top-level keys on the node dict+ valid_from = (+ node.get("valid_from")+ or node_props.get("valid_from")+ )+ valid_until = (+ node.get("valid_until")+ or node_props.get("valid_until")+ )+ metadata = {+ k: v for k, v in node_props.items()+ if k not in ("content", "valid_from", "valid_until")+ }- internal_node = ContextNode(- node_id=node.get("id"),- node_type=node.get("type", "entity"),- content=content,- metadata=metadata,- properties=node_props,- valid_from=valid_from,- valid_until=valid_until,- )+ internal_node = ContextNode(+ node_id=node.get("id"),+ node_type=node.get("type", "entity"),+ content=content,+ metadata=metadata,+ properties=node_props,+ valid_from=valid_from,+ valid_until=valid_until,+ )- if self._add_internal_node(internal_node):- count += 1+ if self._add_internal_node(internal_node):+ count += 1return countdef add_edges(self, edges: List[Dict[str, Any]]) -> int:@@ -376,32 +381,35 @@ class ContextGraph:Number of edges added"""count = 0- for edge in edges:- edge_props = edge.get("properties", {})- # Restore validity windows — ContextEdge.to_dict() writes them at top level- valid_from = edge.get("valid_from") or edge_props.get("valid_from")- valid_until = edge.get("valid_until") or edge_props.get("valid_until")- internal_edge = ContextEdge(- source_id=edge.get("source_id"),- target_id=edge.get("target_id"),- edge_type=edge.get("type", "related_to"),- weight=edge.get("weight", 1.0),- metadata=edge_props,- valid_from=valid_from,- valid_until=valid_until,- )+ with self._lock:+ for edge in edges:+ edge_props = edge.get("properties", {})+ # Restore validity windows — ContextEdge.to_dict() writes them at top level+ valid_from = edge.get("valid_from") or edge_props.get("valid_from")+ valid_until = edge.get("valid_until") or edge_props.get("valid_until")+ internal_edge = ContextEdge(+ source_id=edge.get("source_id"),+ target_id=edge.get("target_id"),+ edge_type=edge.get("type", "related_to"),+ weight=edge.get("weight", 1.0),+ metadata=edge_props,+ valid_from=valid_from,+ valid_until=valid_until,+ )- if self._add_internal_edge(internal_edge):- count += 1+ if self._add_internal_edge(internal_edge):+ count += 1return countdef __contains__(self, node_id: object) -> bool:if not isinstance(node_id, str):return False- return node_id in self.nodes+ with self._lock:+ return node_id in self.nodesdef has_node(self, node_id: str) -> bool:- return node_id in self.nodes+ with self._lock:+ return node_id in self.nodesdef neighbors(self, node_id: str) -> List[Dict[str, Any]]:return self.get_neighbors(node_id, hops=1)@@ -411,55 +419,61 @@ class ContextGraph:node_id: str,relationship_types: Optional[List[str]] = None,) -> List[str]:- if node_id not in self.nodes:- return []+ with self._lock:+ if node_id not in self.nodes:+ return []- rel_filter = set(relationship_types) if relationship_types else None- neighbor_ids: List[str] = []- for edge in self._adjacency.get(node_id, []):- if rel_filter is None or edge.edge_type in rel_filter:- neighbor_ids.append(edge.target_id)- return neighbor_ids+ rel_filter = set(relationship_types) if relationship_types else None+ neighbor_ids: List[str] = []+ for edge in self._adjacency.get(node_id, []):+ if rel_filter is None or edge.edge_type in rel_filter:+ neighbor_ids.append(edge.target_id)+ return neighbor_idsdef get_nodes_by_label(self, label: str) -> List[Dict[str, Any]]:result = []- for nid in self.node_type_index.get(label, set()):- node = self.nodes.get(nid)- if node:- result.append({- "id": node.node_id,- "content": node.content,- "type": node.node_type,- "metadata": (node.properties or {}).copy(),- })+ with self._lock:+ for nid in self.node_type_index.get(label, set()):+ node = self.nodes.get(nid)+ if node:+ result.append({+ "id": node.node_id,+ "content": node.content,+ "type": node.node_type,+ "metadata": (node.properties or {}).copy(),+ })return resultdef get_node_property(self, node_id: str, property_name: str) -> Any:- node = self.nodes.get(node_id)- if not node:- return None- return node.properties.get(property_name)+ with self._lock:+ node = self.nodes.get(node_id)+ if not node:+ return None+ return node.properties.get(property_name)def get_node_attributes(self, node_id: str) -> Dict[str, Any]:- node = self.nodes.get(node_id)- if not node:- return {}- return node.properties.copy()+ with self._lock:+ node = self.nodes.get(node_id)+ if not node:+ return {}+ return node.properties.copy()def add_node_attribute(self, node_id: str, attributes: Dict[str, Any]) -> None:- node = self.nodes.get(node_id)- if not node:- return- node.properties.update(attributes)- node.metadata.update(attributes)+ with self._lock:+ node = self.nodes.get(node_id)+ if not node:+ return+ node.properties.update(attributes)+ node.metadata.update(attributes)def get_edge_data(self, source_id: str, target_id: str) -> Dict[str, Any]:- for edge in self._adjacency.get(source_id, []):- if edge.target_id == target_id:- data = edge.metadata.copy()- data["type"] = edge.edge_type- data["weight"] = edge.weight- return data+ with self._lock:+ for edge in self._adjacency.get(source_id, []):+ if edge.target_id == target_id:+ data = edge.metadata.copy()+ data["type"] = edge.edge_type+ data["weight"] = edge.weight+ return datareturn {}def get_neighbors(@@ -468,6 +482,8 @@ class ContextGraph:hops: int = 1,relationship_types: Optional[List[str]] = None,min_weight: float = 0.0,+ skip: int = 0,+ limit: Optional[int] = None,) -> List[Dict[str, Any]]:"""Get neighbors of a node.@@ -479,57 +495,66 @@ class ContextGraph:min_weight: Minimum edge weight required to traverse an edge (default 0.0means all edges pass). Use e.g. ``min_weight=0.5`` to follow onlystrong/high-confidence relationships.+ skip: Number of items to skip for pagination.+ limit: Maximum items to return.Returns:List of dicts with neighbor info (id, type, content, relationship, weight, hop)."""- if node_id not in self.nodes:- return []-- neighbors: List[Dict[str, Any]] = []- visited = {node_id}- queue = deque([(node_id, 0)])- rel_filter = set(relationship_types) if relationship_types else None+ with self._lock:+ if node_id not in self.nodes:+ return []- while queue:- current_id, current_hop = queue.popleft()- if current_hop >= hops:- continue+ neighbors: List[Dict[str, Any]] = []+ visited = {node_id}+ queue = deque([(node_id, 0)])+ rel_filter = set(relationship_types) if relationship_types else None- outgoing_edges = self._adjacency.get(current_id, [])- for edge in outgoing_edges:- if rel_filter is not None and edge.edge_type not in rel_filter:+ while queue:+ current_id, current_hop = queue.popleft()+ if current_hop >= hops:continue- if edge.weight < min_weight:- continue- neighbor_id = edge.target_id- if neighbor_id in visited:- continue- visited.add(neighbor_id)- queue.append((neighbor_id, current_hop + 1))- node = self.nodes.get(neighbor_id)- if not node:- continue- neighbors.append(- {- "id": node.node_id,- "type": node.node_type,- "content": node.content,- "relationship": edge.edge_type,- "weight": edge.weight,- "hop": current_hop + 1,- }- )+ outgoing_edges = self._adjacency.get(current_id, [])+ for edge in outgoing_edges:+ if rel_filter is not None and edge.edge_type not in rel_filter:+ continue+ if edge.weight < min_weight:+ continue+ neighbor_id = edge.target_id+ if neighbor_id in visited:+ continue+ visited.add(neighbor_id)+ queue.append((neighbor_id, current_hop + 1))++ node = self.nodes.get(neighbor_id)+ if not node:+ continue+ neighbors.append(+ {+ "id": node.node_id,+ "type": node.node_type,+ "content": node.content,+ "relationship": edge.edge_type,+ "weight": edge.weight,+ "hop": current_hop + 1,+ }+ )- return neighbors+ if limit is not None:+ return neighbors[skip: skip + limit]+ return neighbors[skip:]- def query(self, query: str) -> List[Dict[str, Any]]:+ def query(+ self, query: str, skip: int = 0, limit: Optional[int] = None+ ) -> List[Dict[str, Any]]:"""Execute a simple keyword search query on the graph nodes.Args:query: Keyword query string+ skip: Items to skip+ limit: Max items to returnReturns:List of matching node dicts@@ -537,22 +562,26 @@ class ContextGraph:results = []query_lower = query.lower().split()- for node in self.nodes.values():- content_lower = node.content.lower()- if any(word in content_lower for word in query_lower):- # Calculate simple score- overlap = sum(1 for word in query_lower if word in content_lower)- score = overlap / len(query_lower) if query_lower else 0.0-- results.append(- {- "node": node.to_dict(),- "score": score,- "content": node.content,- }- )+ with self._lock:+ for node in self.nodes.values():+ content_lower = node.content.lower()+ if any(word in content_lower for word in query_lower):+ # Calculate simple score+ overlap = sum(1 for word in query_lower if word in content_lower)+ score = overlap / len(query_lower) if query_lower else 0.0++ results.append(+ {+ "node": node.to_dict(),+ "score": score,+ "content": node.content,+ }+ )- return sorted(results, key=lambda x: x["score"], reverse=True)+ sorted_res = sorted(results, key=lambda x: x["score"], reverse=True)+ if limit is not None:+ return sorted_res[skip: skip + limit]+ return sorted_res[skip:]def add_node(self,@@ -574,17 +603,18 @@ class ContextGraph:content = content or node_idvalid_from = properties.pop("valid_from", None)valid_until = properties.pop("valid_until", None)- return self._add_internal_node(- ContextNode(- node_id=node_id,- node_type=node_type,- content=content,- metadata=properties,- properties=properties,- valid_from=valid_from,- valid_until=valid_until,+ with self._lock:+ return self._add_internal_node(+ ContextNode(+ node_id=node_id,+ node_type=node_type,+ content=content,+ metadata=properties,+ properties=properties,+ valid_from=valid_from,+ valid_until=valid_until,+ ))- )def add_edge(self,@@ -607,17 +637,18 @@ class ContextGraph:"""valid_from = properties.pop("valid_from", None)valid_until = properties.pop("valid_until", None)- return self._add_internal_edge(- ContextEdge(- source_id=source_id,- target_id=target_id,- edge_type=edge_type,- weight=weight,- metadata=properties,- valid_from=valid_from,- valid_until=valid_until,+ with self._lock:+ return self._add_internal_edge(+ ContextEdge(+ source_id=source_id,+ target_id=target_id,+ edge_type=edge_type,+ weight=weight,+ metadata=properties,+ valid_from=valid_from,+ valid_until=valid_until,+ ))- )def save_to_file(self, path: str) -> None:"""@@ -628,25 +659,26 @@ class ContextGraph:"""import json- # Serialise cross-graph link metadata (object references are not serialisable,- # so we store other_graph_id; callers can reconnect with resolve_links()).- links_data = []- for link_id, (other_graph, source_node_id, target_node_id) in self._linked_graphs.items():- links_data.append(- {- "link_id": link_id,- "source_node_id": source_node_id,- "target_node_id": target_node_id,- "other_graph_id": other_graph.graph_id,- }- )+ with self._lock:+ # Serialise cross-graph link metadata (object references are not serialisable,+ # so we store other_graph_id; callers can reconnect with resolve_links()).+ links_data = []+ for link_id, (other_graph, source_node_id, target_node_id) in self._linked_graphs.items():+ links_data.append(+ {+ "link_id": link_id,+ "source_node_id": source_node_id,+ "target_node_id": target_node_id,+ "other_graph_id": other_graph.graph_id,+ }+ )- data = {- "graph_id": self.graph_id,- "nodes": [node.to_dict() for node in self.nodes.values()],- "edges": [edge.to_dict() for edge in self.edges],- "links": links_data,- }+ data = {+ "graph_id": self.graph_id,+ "nodes": [node.to_dict() for node in self.nodes.values()],+ "edges": [edge.to_dict() for edge in self.edges],+ "links": links_data,+ }with open(path, "w", encoding="utf-8") as f:json.dump(data, f, indent=2, ensure_ascii=False)@@ -670,72 +702,80 @@ class ContextGraph:with open(path, "r", encoding="utf-8") as f:data = json.load(f)- # Clear existing- self.nodes.clear()- self.edges.clear()- self._adjacency.clear()- self.node_type_index.clear()- self.edge_type_index.clear()- self._linked_graphs.clear()- self._unresolved_links.clear()-- # Restore stable graph identity- if "graph_id" in data:- self.graph_id = data["graph_id"]-- # Load nodes- nodes = data.get("nodes", [])- self.add_nodes(nodes)-- # Load edges- edges = data.get("edges", [])- self.add_edges(edges)-- # Restore link metadata — object references require resolve_links() to reconnect- for link_meta in data.get("links", []):- link_id = link_meta.get("link_id")- if link_id:- self._unresolved_links[link_id] = link_meta+ with self._lock:+ # Clear existing+ self.nodes.clear()+ self.edges.clear()+ self._adjacency.clear()+ self.node_type_index.clear()+ self.edge_type_index.clear()+ self._linked_graphs.clear()+ self._unresolved_links.clear()++ if "graph_id" in data:+ self.graph_id = data["graph_id"]+++ nodes = data.get("nodes", [])+ self.add_nodes(nodes)++ edges = data.get("edges", [])+ self.add_edges(edges)+++ for link_meta in data.get("links", []):+ link_id = link_meta.get("link_id")+ if link_id:+ self._unresolved_links[link_id] = link_metaself.logger.info(f"Loaded context graph from {path}")def find_node(self, node_id: str) -> Optional[Dict[str, Any]]:"""Find a node by ID."""- node = self.nodes.get(node_id)- if node:- merged_metadata = {}- merged_metadata.update(getattr(node, "metadata", {}) or {})- merged_metadata.update(getattr(node, "properties", {}) or {})- return {- "id": node.node_id,- "type": node.node_type,- "content": node.content,- "metadata": merged_metadata,- }- return None+ with self._lock:+ node = self.nodes.get(node_id)+ if node:+ merged_metadata = {}+ merged_metadata.update(getattr(node, "metadata", {}) or {})+ merged_metadata.update(getattr(node, "properties", {}) or {})+ return {+ "id": node.node_id,+ "type": node.node_type,+ "content": node.content,+ "metadata": merged_metadata,+ }+ return None- def find_nodes(self, node_type: Optional[str] = None) -> List[Dict[str, Any]]:+ def find_nodes(+ self, node_type: Optional[str] = None, skip: int = 0, limit: Optional[int] = None+ ) -> List[Dict[str, Any]]:"""Find nodes, optionally filtered by type."""- if node_type:- node_ids = self.node_type_index.get(node_type, set())- nodes = [self.nodes[nid] for nid in node_ids]- else:- nodes = self.nodes.values()-- return [- {- "id": n.node_id,- "type": n.node_type,- "content": n.content,- "metadata": {**(getattr(n, "metadata", {}) or {}), **(getattr(n, "properties", {}) or {})},- }- for n in nodes- ]+ with self._lock:+ if node_type:+ node_ids = self.node_type_index.get(node_type, set())+ nodes = [self.nodes[nid] for nid in node_ids]+ else:+ nodes = list(self.nodes.values())++ results = [+ {+ "id": n.node_id,+ "type": n.node_type,+ "content": n.content,+ "metadata": {**(getattr(n, "metadata", {}) or {}), **(getattr(n, "properties", {}) or {})},+ }+ for n in nodes+ ]+ if limit is not None:+ return results[skip: skip + limit]+ return results[skip:]def find_active_nodes(self,node_type: Optional[str] = None,at_time: Optional[datetime] = None,+ skip: int = 0,+ limit: Optional[int] = None,) -> List[Dict[str, Any]]:"""Find nodes that are currently active within their validity window.@@ -745,32 +785,38 @@ class ContextGraph:Args:node_type: Optional node type filter.at_time: Point in time to evaluate validity (defaults to ``datetime.utcnow()``).+ skip: Items to skip+ limit: Max items to returnReturns:List of active node dicts (same format as :meth:`find_nodes`)."""now = at_time or datetime.utcnow()- if node_type:- node_ids = self.node_type_index.get(node_type, set())- nodes_iter = [self.nodes[nid] for nid in node_ids if nid in self.nodes]- else:- nodes_iter = list(self.nodes.values())-- result = []- for node in nodes_iter:- if node.is_active(now):- result.append(- {- "id": node.node_id,- "type": node.node_type,- "content": node.content,- "metadata": {- **(getattr(node, "metadata", {}) or {}),- **(getattr(node, "properties", {}) or {}),- },- }- )- return result+ with self._lock:+ if node_type:+ node_ids = self.node_type_index.get(node_type, set())+ nodes_iter = [self.nodes[nid] for nid in node_ids if nid in self.nodes]+ else:+ nodes_iter = list(self.nodes.values())++ result = []+ for node in nodes_iter:+ if node.is_active(now):+ result.append(+ {+ "id": node.node_id,+ "type": node.node_type,+ "content": node.content,+ "metadata": {+ **(getattr(node, "metadata", {}) or {}),+ **(getattr(node, "properties", {}) or {}),+ },+ }+ )++ if limit is not None:+ return result[skip: skip + limit]+ return result[skip:]def link_graph(self,@@ -799,38 +845,36 @@ class ContextGraph:KeyError: If source_node_id is not in this graph or target_node_id is notin other_graph."""- if source_node_id not in self.nodes:- raise KeyError(f"Source node '{source_node_id}' not found in this graph")- if target_node_id not in other_graph.nodes:- raise KeyError(f"Target node '{target_node_id}' not found in other_graph")+ with self._lock:+ if source_node_id not in self.nodes:+ raise KeyError(f"Source node '{source_node_id}' not found in this graph")+ if target_node_id not in other_graph.nodes:+ raise KeyError(f"Target node '{target_node_id}' not found in other_graph")- link_id = str(uuid.uuid4())- self._linked_graphs[link_id] = (other_graph, source_node_id, target_node_id)+ link_id = str(uuid.uuid4())+ self._linked_graphs[link_id] = (other_graph, source_node_id, target_node_id)- # Create a dedicated marker node so it is clearly typed and does not pollute- # the entity namespace. _add_internal_edge auto-creates missing targets as- # "entity" nodes — by pre-inserting a "cross_graph_link" node we prevent that.- marker_node_id = f"__cross_graph_{link_id}"- self._add_internal_node(- ContextNode(- node_id=marker_node_id,- node_type="cross_graph_link",- content=f"Cross-graph link → {target_node_id}",- metadata={"cross_graph": True, "link_id": link_id, "target_node_id": target_node_id},- properties={},+ marker_node_id = f"__cross_graph_{link_id}"+ self._add_internal_node(+ ContextNode(+ node_id=marker_node_id,+ node_type="cross_graph_link",+ content=f"Cross-graph link → {target_node_id}",+ metadata={"cross_graph": True, "link_id": link_id, "target_node_id": target_node_id},+ properties={},+ ))- )- # Record a marker edge so the link shows up in graph traversal- self._add_internal_edge(- ContextEdge(- source_id=source_node_id,- target_id=marker_node_id,- edge_type=link_type,- weight=1.0,- metadata={"cross_graph": True, "link_id": link_id},++ self._add_internal_edge(+ ContextEdge(+ source_id=source_node_id,+ target_id=marker_node_id,+ edge_type=link_type,+ weight=1.0,+ metadata={"cross_graph": True, "link_id": link_id},+ ))- )- return link_id+ return link_iddef navigate_to(self, link_id: str) -> Tuple["ContextGraph", str]:"""@@ -885,59 +929,69 @@ class ContextGraph:resolved = g1b.resolve_links({g2b.graph_id: g2b})"""resolved = 0- for link_id, meta in list(self._unresolved_links.items()):- other_graph_id = meta.get("other_graph_id")- if other_graph_id in graphs:- other_graph = graphs[other_graph_id]- source_node_id = meta["source_node_id"]- target_node_id = meta["target_node_id"]- # Validate target node still exists in the restored graph- if target_node_id in other_graph.nodes:- self._linked_graphs[link_id] = (other_graph, source_node_id, target_node_id)- del self._unresolved_links[link_id]- resolved += 1- else:- self.logger.warning(- f"resolve_links: target node '{target_node_id}' not found in "- f"graph '{other_graph_id}' for link '{link_id}'"- )+ with self._lock:+ for link_id, meta in list(self._unresolved_links.items()):+ other_graph_id = meta.get("other_graph_id")+ if other_graph_id in graphs:+ other_graph = graphs[other_graph_id]+ source_node_id = meta["source_node_id"]+ target_node_id = meta["target_node_id"]+ # Validate target node still exists in the restored graph+ if target_node_id in other_graph.nodes:+ self._linked_graphs[link_id] = (other_graph, source_node_id, target_node_id)+ del self._unresolved_links[link_id]+ resolved += 1+ else:+ self.logger.warning(+ f"resolve_links: target node '{target_node_id}' not found in "+ f"graph '{other_graph_id}' for link '{link_id}'"+ )return resolved- def find_edges(self, edge_type: Optional[str] = None) -> List[Dict[str, Any]]:+ def find_edges(+ self, edge_type: Optional[str] = None, skip: int = 0, limit: Optional[int] = None+ ) -> List[Dict[str, Any]]:"""Find edges, optionally filtered by type."""- if edge_type:- edges = self.edge_type_index.get(edge_type, [])- else:- edges = self.edges+ with self._lock:+ if edge_type:+ edges = self.edge_type_index.get(edge_type, [])+ else:+ edges = self.edges- return [- {- "source": e.source_id,- "target": e.target_id,- "type": e.edge_type,- "weight": e.weight,- "metadata": e.metadata,- }- for e in edges- ]+ results = [+ {+ "source": e.source_id,+ "target": e.target_id,+ "type": e.edge_type,+ "weight": e.weight,+ "metadata": e.metadata,+ }+ for e in edges+ ]++ if limit is not None:+ return results[skip: skip + limit]+ return results[skip:]def stats(self) -> Dict[str, Any]:"""Get graph statistics."""- return {- "node_count": len(self.nodes),- "edge_count": len(self.edges),- "node_types": {k: len(v) for k, v in self.node_type_index.items()},- "edge_types": {k: len(v) for k, v in self.edge_type_index.items()},- "density": self.density(),- }+ with self._lock:+ return {+ "node_count": len(self.nodes),+ "edge_count": len(self.edges),+ "node_types": {k: len(v) for k, v in self.node_type_index.items()},+ "edge_types": {k: len(v) for k, v in self.edge_type_index.items()},+ "density": self.density(),+ }def density(self) -> float:"""Calculate graph density."""- n = len(self.nodes)- if n < 2:- return 0.0- max_edges = n * (n - 1) # Directed graph- return len(self.edges) / max_edges+ with self._lock:+ n = len(self.nodes)+ if n < 2:+ return 0.0+ max_edges = n * (n - 1)+ return len(self.edges) / max_edges# --- Internal Helpers ---@@ -977,31 +1031,33 @@ class ContextGraph:def _add_internal_node(self, node: ContextNode) -> bool:"""Internal method to add a node."""- self.nodes[node.node_id] = node- # Handle edge case where node_type might be None or not a string- if hasattr(node, 'node_type') and isinstance(node.node_type, str):- self.node_type_index[node.node_type].add(node.node_id)- else:- # Use 'unknown' as fallback for invalid node_type- self.node_type_index['unknown'].add(node.node_id)- return True+ with self._lock:+ self.nodes[node.node_id] = node+ # Handle edge case where node_type might be None or not a string+ if hasattr(node, 'node_type') and isinstance(node.node_type, str):+ self.node_type_index[node.node_type].add(node.node_id)+ else:+ # Use 'unknown' as fallback for invalid node_type+ self.node_type_index['unknown'].add(node.node_id)+ return Truedef _add_internal_edge(self, edge: ContextEdge) -> bool:"""Internal method to add an edge."""- # Ensure nodes exist- if edge.source_id not in self.nodes:- self._add_internal_node(- ContextNode(edge.source_id, "entity", edge.source_id)- )- if edge.target_id not in self.nodes:- self._add_internal_node(- ContextNode(edge.target_id, "entity", edge.target_id)- )+ with self._lock:+ # Ensure nodes exist+ if edge.source_id not in self.nodes:+ self._add_internal_node(+ ContextNode(edge.source_id, "entity", edge.source_id)+ )+ if edge.target_id not in self.nodes:+ self._add_internal_node(+ ContextNode(edge.target_id, "entity", edge.target_id)+ )- self.edges.append(edge)- self.edge_type_index[edge.edge_type].append(edge)- self._adjacency[edge.source_id].append(edge)- return True+ self.edges.append(edge)+ self.edge_type_index[edge.edge_type].append(edge)+ self._adjacency[edge.source_id].append(edge)+ return True# --- Builder Methods (Legacy/Utility) ---diff --git a/semantica/explorer/session.py b/semantica/explorer/session.pyindex de0ff3b2..5c61984b 100644--- a/semantica/explorer/session.py+++ b/semantica/explorer/session.py@@ -128,20 +128,23 @@ class GraphSession:) -> tuple[list[dict[str, Any]], int]:"""Return a paginated slice of nodes and the total count."""with self._lock:- all_nodes = self.graph.find_nodes(node_type=node_type)-- # Optional keyword filter- if search:- search_lower = search.lower()- all_nodes = [- n for n in all_nodes- if search_lower in n.get("id", "").lower()- or search_lower in n.get("content", "").lower()- or search_lower in str(n.get("metadata", {})).lower()- ]-- total = len(all_nodes)- page = all_nodes[skip: skip + limit]+ # We fetch all nodes if there is a search filter as we need to filter them in memory,+ # otherwise we let the context graph handle the pagination natively.+ if search:+ all_nodes = self.graph.find_nodes(node_type=node_type)+ search_lower = search.lower()+ all_nodes = [+ n for n in all_nodes+ if search_lower in n.get("id", "").lower()+ or search_lower in n.get("content", "").lower()+ or search_lower in str(n.get("metadata", {})).lower()+ ]+ total = len(all_nodes)+ page = all_nodes[skip: skip + limit]+ else:+ total = self.graph.stats().get("node_types", {}).get(node_type, 0) if node_type else self.graph.stats().get("node_count", 0)+ page = self.graph.find_nodes(node_type=node_type, skip=skip, limit=limit)+return page, totaldef get_edges(@@ -154,15 +157,18 @@ class GraphSession:) -> tuple[list[dict[str, Any]], int]:"""Return a paginated slice of edges and the total count."""with self._lock:- all_edges = self.graph.find_edges(edge_type=edge_type)-- if source:- all_edges = [e for e in all_edges if e.get("source") == source]- if target:- all_edges = [e for e in all_edges if e.get("target") == target]-- total = len(all_edges)- page = all_edges[skip: skip + limit]+ if source or target:+ all_edges = self.graph.find_edges(edge_type=edge_type)+ if source:+ all_edges = [e for e in all_edges if e.get("source") == source]+ if target:+ all_edges = [e for e in all_edges if e.get("target") == target]+ total = len(all_edges)+ page = all_edges[skip: skip + limit]+ else:+ total = self.graph.stats().get("edge_types", {}).get(edge_type, 0) if edge_type else self.graph.stats().get("edge_count", 0)+ page = self.graph.find_edges(edge_type=edge_type, skip=skip, limit=limit)+return page, totaldef get_neighbors(self, node_id: str, depth: int = 1) -> List[Dict[str, Any]]: