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
Feat/pr 1548 global drift retrieval (#1628)
Zohaib Hassnaina7420916c083
diff --git a/semantica/cli.py b/semantica/cli.pyindex 28d36e64..df8d4c77 100644--- a/semantica/cli.py+++ b/semantica/cli.py@@ -1702,6 +1702,218 @@ def kg_validate_cmd(cli_ctx: CLIContext, local_json: bool) -> None:_run_with_error_handling(_action)[email protected]("global")[email protected]("query_str")+ "--reports",+ "reports_path",+ type=click.Path(exists=True),+ default=None,+ help="Path to JSON file containing community reports.",+)+ "--hierarchy",+ "hierarchy_path",+ type=click.Path(exists=True),+ default=None,+ help="Path to JSON file containing community hierarchy.",+)+ "--level",+ type=int,+ default=None,+ help="Coarsening level to query.",+)+ "--max-tokens",+ type=int,+ default=4000,+ show_default=True,+ help="Token budget for retrieval context.",+)+ "--min-relevance",+ type=float,+ default=0.0,+ show_default=True,+ help="Minimum relevance score (0.0 to 10.0).",+)[email protected]("--json", "local_json", is_flag=True, default=False)+def kg_global_cmd(+ cli_ctx: CLIContext,+ query_str: str,+ reports_path: Optional[str],+ hierarchy_path: Optional[str],+ level: Optional[int],+ max_tokens: int,+ min_relevance: float,+ local_json: bool,+) -> None:+ """Run global Map-Reduce search over hierarchical community reports."""+ cli_ctx = _require_ctx(cli_ctx)+ json_out = _is_json(cli_ctx, local_json)++ def _action() -> None:+ try:+ from .context.methods import retrieve_global+ from .kg.community_hierarchy import CommunityHierarchy+ except ImportError as exc:+ raise click.ClickException(f"Module not available: {exc}") from exc++ loaded_reports = None+ if reports_path:+ try:+ with open(reports_path, "r", encoding="utf-8") as f:+ loaded_reports = json.load(f)+ except Exception as exc:+ raise click.ClickException(+ f"Failed to read reports file '{reports_path}': {exc}"+ ) from exc+ else:+ raise click.ClickException(+ "Global retrieval requires --reports. "+ "Please provide a path to community reports."+ )++ loaded_hierarchy = None+ if hierarchy_path:+ try:+ with open(hierarchy_path, "r", encoding="utf-8") as f:+ h_data = json.load(f)+ loaded_hierarchy = CommunityHierarchy.from_dict(h_data)+ except Exception as exc:+ raise click.ClickException(+ f"Failed to read hierarchy file '{hierarchy_path}': {exc}"+ ) from exc++ result = retrieve_global(+ query=query_str,+ reports=loaded_reports,+ hierarchy=loaded_hierarchy,+ level=level,+ max_context_tokens=max_tokens,+ min_relevance_score=min_relevance,+ )++ if json_out:+ _jecho(result.to_dict())+ else:+ _ok(+ cli_ctx,+ f"Global Search Results (Level {result.level}, "+ f"Reports: {len(result.community_reports_used)}):",+ )+ console.print(f"\n{result.response}\n")+ if result.citations:+ console.print(f"Citations: {', '.join(result.citations)}")+ console.print(+ f"Key Points: {len(result.key_points)} | "+ f"Time: {result.metrics.get('time_taken', 0.0):.2f}s"+ )++ _run_with_error_handling(_action)++[email protected]("drift")[email protected]("query_str")+ "--reports",+ "reports_path",+ type=click.Path(exists=True),+ default=None,+ help="Path to JSON file containing community reports.",+)+ "--graph",+ "graph_path",+ type=click.Path(exists=True),+ default=None,+ help="Path to JSON file containing knowledge graph.",+)+ "--depth",+ type=int,+ default=2,+ show_default=True,+ help="Traversal depth for entity exploration.",+)+ "--drift-threshold",+ type=float,+ default=0.35,+ show_default=True,+ help="Threshold for semantic drift pruning.",+)[email protected]("--json", "local_json", is_flag=True, default=False)+def kg_drift_cmd(+ cli_ctx: CLIContext,+ query_str: str,+ reports_path: Optional[str],+ graph_path: Optional[str],+ depth: int,+ drift_threshold: float,+ local_json: bool,+) -> None:+ """Run DRIFT hybrid search combining global framing and local exploration."""+ cli_ctx = _require_ctx(cli_ctx)+ json_out = _is_json(cli_ctx, local_json)++ def _action() -> None:+ try:+ from .context.methods import retrieve_drift+ except ImportError as exc:+ raise click.ClickException(f"Module not available: {exc}") from exc++ loaded_reports = None+ if reports_path:+ try:+ with open(reports_path, "r", encoding="utf-8") as f:+ loaded_reports = json.load(f)+ except Exception as exc:+ raise click.ClickException(+ f"Failed to read reports file '{reports_path}': {exc}"+ ) from exc++ loaded_graph = None+ if graph_path:+ try:+ with open(graph_path, "r", encoding="utf-8") as f:+ loaded_graph = json.load(f)+ except Exception as exc:+ raise click.ClickException(+ f"Failed to read graph file '{graph_path}': {exc}"+ ) from exc++ result = retrieve_drift(+ query=query_str,+ knowledge_graph=loaded_graph,+ reports=loaded_reports,+ max_depth=depth,+ drift_threshold=drift_threshold,+ )++ if json_out:+ _jecho(result.to_dict())+ else:+ _ok(+ cli_ctx,+ f"DRIFT Hybrid Search Results (Depth {result.depth_reached}, "+ f"Facts: {len(result.verified_local_contexts)}):",+ )+ console.print(f"\n{result.answer}\n")+ if result.citations:+ console.print(f"Citations: {', '.join(result.citations)}")+ console.print(+ f"Facets Explored: {len(result.facets_explored)} | "+ f"Pruned Facts: {result.pruned_fact_count} | "+ f"Time: {result.metrics.get('time_taken', 0.0):.2f}s"+ )++ _run_with_error_handling(_action)++# ─── Data In ──────────────────────────────────────────────────────────────────diff --git a/semantica/context/__init__.py b/semantica/context/__init__.pyindex 0e0b8c4e..9bebf243 100644--- a/semantica/context/__init__.py+++ b/semantica/context/__init__.py@@ -46,7 +46,8 @@ Enhanced Analytics:Main Classes:- AgentContext: High-level interface with KG integration- - ContextGraph: In-memory graph store with KG algorithm support and comprehensive decision management+ - ContextGraph: In-memory graph store with KG algorithm support and+ comprehensive decision management- ContextNode/ContextEdge: Graph data structures- AgentMemory: Persistent agent memory with RAG- MemoryItem: Memory item data structure@@ -65,24 +66,24 @@ Decision Tracking Classes:Example Usage:>>> from semantica.context import AgentContext, ContextGraph>>> # Simple AgentContext with decision tracking- >>> context = AgentContext(vector_store=vs, knowledge_graph=kg,+ >>> context = AgentContext(vector_store=vs, knowledge_graph=kg,... decision_tracking=True,... advanced_analytics=True,... kg_algorithms=True,... vector_store_features=True)>>> memory_id = context.store("User asked about Python", conversation_id="conv1")>>> results = context.retrieve("Python programming")- >>> decision_id = context.record_decision(category="approval",+ >>> decision_id = context.record_decision(category="approval",... scenario="Loan application",... reasoning="Good credit score",... outcome="approved",... confidence=0.95)- >>> precedents = context.find_precedents_advanced("Loan application",+ >>> precedents = context.find_precedents_advanced("Loan application",... category="approval",... use_kg_features=True)>>> influence = context.analyze_decision_influence(decision_id)>>> insights = context.get_context_insights()-+>>> # Comprehensive ContextGraph with all decision features>>> graph = ContextGraph(advanced_analytics=True, enable_causality=True)>>> decision_id = graph.record_decision(@@ -108,14 +109,18 @@ Production Examples:from .agent_context import AgentContextfrom .agent_memory import AgentMemory, MemoryItemfrom .context_graph import ContextEdge, ContextGraph, ContextNode-from .context_retriever import ContextRetriever, RetrievedContext, TemporalGraphRetriever+from .context_retriever import (+ ContextRetriever,+ RetrievedContext,+ TemporalGraphRetriever,+)from .decision_context import DecisionContextfrom .entity_linker import EntityLink, EntityLinker, LinkedEntityfrom .erasure import ErasureCoordinator, ErasureReceipt# Decision tracking importsfrom .decision_models import (- Decision, DecisionContext as DecisionContextModel, Policy,+ Decision, DecisionContext as DecisionContextModel, Policy,PolicyException, Precedent, ApprovalChain)from .decision_recorder import DecisionRecorder@@ -130,6 +135,30 @@ from .decision_methods import ()from .graph_schema import setup_decision_schema, verify_schema, get_schema_info+# Global GraphRAG and DRIFT search imports+from .global_retriever import (+ GlobalGraphRetriever,+ GlobalSearchResult,+ MapKeyPoint,+ MapPointSchema,+ MapResponseSchema,+)+from .drift_search import (+ DriftFacet,+ DriftFacetSchema,+ DriftFacetsResponseSchema,+ DriftSearchEngine,+ DriftSearchResult,+)+from .registry import MethodRegistry, method_registry+from .methods import (+ drift_search,+ global_search,+ retrieve_context,+ retrieve_drift,+ retrieve_global,+)+__all__ = [# High-level interface"AgentContext",@@ -151,7 +180,7 @@ __all__ = ["ErasureReceipt",# Decision tracking models"Decision",- "DecisionContextModel",+ "DecisionContextModel","Policy","PolicyException","Precedent",@@ -178,6 +207,24 @@ __all__ = ["setup_decision_schema","verify_schema","get_schema_info",+ # Global GraphRAG & DRIFT Search+ "GlobalGraphRetriever",+ "GlobalSearchResult",+ "MapKeyPoint",+ "MapPointSchema",+ "MapResponseSchema",+ "DriftSearchEngine",+ "DriftSearchResult",+ "DriftFacet",+ "DriftFacetSchema",+ "DriftFacetsResponseSchema",+ "MethodRegistry",+ "method_registry",+ "retrieve_global",+ "retrieve_drift",+ "retrieve_context",+ "global_search",+ "drift_search",]# Backward compatibility aliasdiff --git a/semantica/context/context_graph.py b/semantica/context/context_graph.pyindex 1bb2ec84..04f77f40 100644--- a/semantica/context/context_graph.py+++ b/semantica/context/context_graph.py@@ -476,7 +476,14 @@ class ContextEdge:self.source_id = str(self.source_id)self.target_id = str(self.target_id)self.edge_type = str(self.edge_type or "related_to")- self.weight = _coerce_float(self.weight, default=1.0)+ if isinstance(self.weight, dict):+ if not isinstance(self.metadata, dict):+ self.metadata = {}+ dict_meta = dict(self.weight)+ self.weight = _coerce_float(dict_meta.pop("weight", 1.0), default=1.0)+ self.metadata = {**dict_meta, **self.metadata}+ else:+ self.weight = _coerce_float(self.weight, default=1.0)if not isinstance(self.metadata, dict):self.metadata = {}self.edge_id, self.family_id = _resolve_edge_identity(@@ -1173,6 +1180,9 @@ class ContextGraph:**properties: Additional properties. Use `valid_from` and `valid_until`(ISO datetime strings) to define a temporal validity window."""+ if isinstance(weight, dict):+ properties = {**weight, **properties}+ weight = properties.pop("weight", 1.0)valid_from = properties.pop("valid_from", None)valid_until = properties.pop("valid_until", None)explicit_edge_id = properties.pop("id", properties.pop("edge_id", None))diff --git a/semantica/context/context_retriever.py b/semantica/context/context_retriever.pyindex b7adec96..495bda13 100644--- a/semantica/context/context_retriever.py+++ b/semantica/context/context_retriever.py@@ -122,12 +122,22 @@ class ContextRetriever:• Real-time context updates"""- def __init__(self, config: Optional[Dict[str, Any]] = None, **kwargs):+ def __init__(+ self,+ config: Optional[Dict[str, Any]] = None,+ community_hierarchy: Optional[Any] = None,+ community_reports: Optional[Any] = None,+ llm: Optional[Any] = None,+ **kwargs,+ ):"""Initialize context retriever.Args:config: Configuration dictionary+ community_hierarchy: Optional CommunityHierarchy instance+ community_reports: Optional community reports collection+ llm: Optional LLM instance for global/drift synthesis**kwargs: Additional configuration options:- memory_store: Memory store instance- knowledge_graph: Knowledge graph instance@@ -145,6 +155,22 @@ class ContextRetriever:self.knowledge_graph = self.config.get("knowledge_graph")self.vector_store = self.config.get("vector_store")+ self.community_hierarchy = (+ community_hierarchy+ if community_hierarchy is not None+ else self.config.get("community_hierarchy")+ )+ self.community_reports = (+ community_reports+ if community_reports is not None+ else self.config.get("community_reports")+ )+ self.llm = (+ llm+ if llm is not None+ else self.config.get("llm")+ )+self.use_graph_expansion = self.config.get("use_graph_expansion", True)self.max_expansion_hops = self.config.get("max_expansion_hops", 2)self.hybrid_alpha = self.config.get("hybrid_alpha", 0.5)@@ -158,7 +184,7 @@ class ContextRetriever:# Initialize decision-specific componentsself.hybrid_calculator = HybridSimilarityCalculator()self.decision_pipeline: Optional[DecisionEmbeddingPipeline] = None-+# Initialize KG algorithms if knowledge graph availableif self.knowledge_graph:self.path_finder = PathFinder()@@ -170,7 +196,7 @@ class ContextRetriever:self.centrality_calculator = Noneself.community_detector = Noneself.similarity_calculator = None-+# Initialize decision pipeline if vector store availableif self.vector_store:self.decision_pipeline = DecisionEmbeddingPipeline(@@ -185,6 +211,7 @@ class ContextRetriever:max_results: int = 5,use_graph_expansion: Optional[bool] = None,min_relevance_score: float = 0.0,+ mode: str = "local",**options,) -> List[RetrievedContext]:"""@@ -195,6 +222,7 @@ class ContextRetriever:max_results: Maximum number of resultsuse_graph_expansion: Use graph expansion (overrides config)min_relevance_score: Minimum relevance score+ mode: Retrieval mode ('local', 'global', 'drift', 'hybrid')**options: Additional options:- entity_ids: Filter by entity IDs- node_types: Filter by node types@@ -203,6 +231,53 @@ class ContextRetriever:Returns:List of retrieved context items"""+ norm_mode = str(mode).lower().strip()+ if norm_mode == "global":+ return self.retrieve_global(+ query,+ max_results=max_results,+ min_relevance_score=min_relevance_score,+ as_contexts=True,+ **options,+ )+ elif norm_mode == "drift":+ return self.retrieve_drift(+ query,+ max_results=max_results,+ min_relevance_score=min_relevance_score,+ as_contexts=True,+ **options,+ )+ elif norm_mode == "hybrid":+ local_res = self.retrieve(+ query,+ max_results=max_results * 2,+ use_graph_expansion=use_graph_expansion,+ min_relevance_score=min_relevance_score,+ mode="local",+ **options,+ )+ global_res = self.retrieve_global(+ query,+ max_results=max_results * 2,+ min_relevance_score=min_relevance_score,+ as_contexts=True,+ **options,+ )+ merged = self._rank_and_merge(local_res + global_res, query)+ eff_min_score = (+ max(0.0, min(1.0, min_relevance_score / 10.0))+ if min_relevance_score > 1.0+ else max(0.0, min(1.0, min_relevance_score))+ )+ filtered = [r for r in merged if r.score >= eff_min_score]+ return filtered[:max_results]+ elif norm_mode != "local":+ raise ValueError(+ f"Unsupported retrieval mode '{mode}'. Supported modes: "+ "'local', 'global', 'drift', 'hybrid'"+ )+# Track context retrievaltracking_id = self.progress_tracker.start_tracking(file=None,@@ -257,8 +332,13 @@ class ContextRetriever:ranked_results = self._rank_and_merge(all_results, query)# Filter by minimum score+ eff_min_score = (+ max(0.0, min(1.0, min_relevance_score / 10.0))+ if min_relevance_score > 1.0+ else max(0.0, min(1.0, min_relevance_score))+ )filtered_results = [- r for r in ranked_results if r.score >= min_relevance_score+ r for r in ranked_results if r.score >= eff_min_score]self.progress_tracker.stop_tracking(@@ -275,6 +355,140 @@ class ContextRetriever:)raise+ def retrieve_global(+ self,+ query: str,+ level: Optional[int] = None,+ max_results: int = 5,+ min_relevance_score: float = 0.0,+ as_contexts: bool = False,+ **options,+ ) -> Union[Any, List[RetrievedContext]]:+ """+ Execute global search over community reports.++ Args:+ query: Search query+ level: Target coarsening hierarchy level+ max_results: Maximum results when returning contexts+ min_relevance_score: Minimum relevance score+ as_contexts: If True, return List[RetrievedContext];+ if False, return GlobalSearchResult+ **options: Additional options passed to GlobalGraphRetriever++ Returns:+ GlobalSearchResult or List[RetrievedContext]+ """+ from .global_retriever import GlobalGraphRetriever++ reports = options.pop("reports", None)+ if reports is None:+ reports = options.pop("community_reports", self.community_reports)+ else:+ options.pop("community_reports", None)++ hierarchy = options.pop("hierarchy", None)+ if hierarchy is None:+ hierarchy = options.pop("community_hierarchy", self.community_hierarchy)+ else:+ options.pop("community_hierarchy", None)++ llm = options.pop("llm", self.llm)++ retriever = GlobalGraphRetriever(+ reports=reports,+ hierarchy=hierarchy,+ llm=llm,+ min_relevance_score=min_relevance_score,+ **options,+ )+ res = retriever.search(+ query,+ level=level,+ min_relevance_score=min_relevance_score,+ **options,+ )+ if as_contexts:+ context_threshold = (+ max(0.0, min(1.0, min_relevance_score / 10.0))+ if min_relevance_score > 1.0+ else max(0.0, min(1.0, min_relevance_score))+ )+ contexts = [+ c for c in res.to_retrieved_contexts()+ if c.score >= context_threshold+ ]+ return contexts[:max_results]+ return res++ def retrieve_drift(+ self,+ query: str,+ max_depth: int = 2,+ max_results: int = 5,+ min_relevance_score: float = 0.0,+ as_contexts: bool = False,+ **options,+ ) -> Union[Any, List[RetrievedContext]]:+ """+ Execute DRIFT hybrid search combining global framing and local graph traversal.++ Args:+ query: Search query+ max_depth: Maximum graph expansion depth+ max_results: Maximum results when returning contexts+ min_relevance_score: Minimum relevance score+ as_contexts: If True, return List[RetrievedContext];+ if False, return DriftSearchResult+ **options: Additional options passed to DriftSearchEngine++ Returns:+ DriftSearchResult or List[RetrievedContext]+ """+ from .drift_search import DriftSearchEngine++ kg = options.pop("knowledge_graph", None)+ if kg is None:+ kg = options.pop("graph", self.knowledge_graph)+ else:+ options.pop("graph", None)++ reports = options.pop("reports", None)+ if reports is None:+ reports = options.pop("community_reports", self.community_reports)+ else:+ options.pop("community_reports", None)++ hierarchy = options.pop("hierarchy", None)+ if hierarchy is None:+ hierarchy = options.pop("community_hierarchy", self.community_hierarchy)+ else:+ options.pop("community_hierarchy", None)++ llm = options.pop("llm", self.llm)++ engine = DriftSearchEngine(+ knowledge_graph=kg,+ reports=reports,+ hierarchy=hierarchy,+ llm=llm,+ max_depth=max_depth,+ **options,+ )+ res = engine.search(query, max_depth=max_depth, **options)+ if as_contexts:+ context_threshold = (+ max(0.0, min(1.0, min_relevance_score / 10.0))+ if min_relevance_score > 1.0+ else max(0.0, min(1.0, min_relevance_score))+ )+ contexts = [+ c for c in res.to_retrieved_contexts()+ if c.score >= context_threshold+ ]+ return contexts[:max_results]+ return res+def _retrieve_from_vector(self, query: str, max_results: int) -> List[RetrievedContext]:@@ -738,52 +952,94 @@ class ContextRetriever:self, results: List[RetrievedContext], query: str) -> List[RetrievedContext]:"""Rank and merge results from multiple sources with GraphRAG optimization."""+ def is_graph_source(s: Optional[str]) -> bool:+ if not s:+ return False+ return (+ s.startswith("graph")+ or s.startswith("global")+ or s.startswith("drift")+ or s.startswith("community")+ or s in ("global_search", "drift_search", "local_graph")+ )+# Separate results by source (handle None source gracefully)vector_results = [r for r in results if r.source and r.source.startswith("vector:")]- graph_results = [r for r in results if r.source and r.source.startswith("graph:")]+ graph_results = [r for r in results if is_graph_source(r.source)]memory_results = [r for r in results if r.source and r.source.startswith("memory:")]+ other_results = [+ r for r in results+ if (+ r not in vector_results+ and r not in graph_results+ and r not in memory_results+ )+ ]# Normalize scores within each source (0-1 range)def normalize_scores(source_results):- if not source_results:+ unweighted = [+ r for r in source_results+ if not (r.metadata and r.metadata.get("_source_weighted"))+ ]+ if not unweighted:return source_results- scores = [r.score for r in source_results]+ scores = [r.score for r in unweighted]if not scores:return source_resultsmin_score, max_score = min(scores), max(scores)if max_score > min_score:- for r in source_results:+ for r in unweighted:r.score = (r.score - min_score) / (max_score - min_score)return source_results-+vector_results = normalize_scores(vector_results)graph_results = normalize_scores(graph_results)memory_results = normalize_scores(memory_results)-+ other_results = normalize_scores(other_results)+# Apply hybrid_alpha weighting: 0=vector only, 1=graph only, 0.5=balancedalpha = self.hybrid_alphafor r in vector_results:- r.score = r.score * (1 - alpha) # Weight vector results+ if r.metadata is None:+ r.metadata = {}+ if not r.metadata.get("_source_weighted"):+ r.score = r.score * (1 - alpha) # Weight vector results+ r.metadata["_source_weighted"] = Truefor r in graph_results:- r.score = r.score * alpha # Weight graph results- # Boost graph results with more context (more related entities/relationships)- context_boost = min(- 0.2, # Max 20% boost- (len(r.related_entities) + len(r.related_relationships or [])) * 0.01- )- r.score += context_boost+ if r.metadata is None:+ r.metadata = {}+ if not r.metadata.get("_source_weighted"):+ r.score = r.score * alpha # Weight graph results+ # Boost graph results with more context+ context_boost = min(+ 0.2, # Max 20% boost+ (len(r.related_entities) + len(r.related_relationships or [])) * 0.01+ )+ r.score += context_boost+ r.metadata["_source_weighted"] = Truefor r in memory_results:- r.score = r.score * 0.3 # Lower weight for memory+ if r.metadata is None:+ r.metadata = {}+ if not r.metadata.get("_source_weighted"):+ r.score = r.score * 0.3 # Lower weight for memory+ r.metadata["_source_weighted"] = True+ for r in other_results:+ if r.metadata is None:+ r.metadata = {}+ if not r.metadata.get("_source_weighted"):+ r.score = r.score * 0.5 # Neutral weight for other+ r.metadata["_source_weighted"] = True# Deduplicate by entity ID (for graph) or content (for others)seen_entities = {} # entity_id -> resultseen_content = {} # content_hash -> result- all_results = vector_results + graph_results + memory_results+ all_results = vector_results + graph_results + memory_results + other_resultsfor result in all_results:# For graph results, deduplicate by entity ID- if result.source and result.source.startswith("graph:"):+ if is_graph_source(result.source):entity_id = result.metadata.get("node_id")if entity_id:if entity_id not in seen_entities:@@ -817,7 +1073,7 @@ class ContextRetriever:if rel_key not in existing_rel_ids:existing.related_relationships.append(rel)existing_rel_ids.add(rel_key)- continue+ continue# For non-graph results, deduplicate by contentcontent_key = result.content[:100] if result.content else ""@@ -830,8 +1086,11 @@ class ContextRetriever:# Combine deduplicated resultsmerged_results = list(seen_entities.values()) + [- r for r in seen_content.values()- if not (r.source and r.source.startswith("graph:")) or r.metadata.get("node_id") not in seen_entities+ r for r in seen_content.values()+ if (+ not is_graph_source(r.source)+ or r.metadata.get("node_id") not in seen_entities+ )]# Re-rank with query relevance boostdiff --git a/semantica/context/drift_search.py b/semantica/context/drift_search.pynew file mode 100644index 00000000..cea8e75a--- /dev/null+++ b/semantica/context/drift_search.py@@ -0,0 +1,1789 @@+"""+DRIFT Search Engine Module.++Implements Directed Reasoning and Iterative Filtering Tree (DRIFT) hybrid+search combining global thematic community framing, directed facet reasoning,+local entity-hop graph retrieval, semantic drift pruning, and dual-attributed+executive synthesis.+"""++from collections.abc import Callable, Iterable+from dataclasses import dataclass, field+import hashlib+import json+import math+import re+import time+from typing import Any, Dict, List, Optional, Sequence, Set, Union++from pydantic import AliasChoices, BaseModel, ConfigDict, Field, field_validator++from ..kg.community_hierarchy import CommunityHierarchy+from ..kg.community_summarizer import CommunityReport, estimate_tokens+from ..utils.logging import get_logger+from .context_retriever import RetrievedContext++logger = get_logger("drift_search")+++@dataclass+class DriftFacet:+ """Targeted sub-query and seed entity target for directed reasoning."""++ sub_query: str+ target_entities: List[str] = field(default_factory=list)+ rationale: str = ""+ depth: int = 0+ relevance_score: float = 1.0++ def __post_init__(self) -> None:+ self.sub_query = str(self.sub_query).strip()+ self.rationale = str(self.rationale).strip()+ self.depth = max(0, int(self.depth))+ try:+ r_val = float(self.relevance_score)+ if math.isnan(r_val) or math.isinf(r_val):+ r_val = 1.0+ except (ValueError, TypeError):+ r_val = 1.0+ self.relevance_score = max(0.0, min(1.0, r_val))++ if self.target_entities:+ self.target_entities = sorted(+ set(str(e).strip() for e in self.target_entities if e)+ )+ else:+ self.target_entities = []++ def to_dict(self) -> Dict[str, Any]:+ """Convert DriftFacet to dictionary."""+ return {+ "sub_query": self.sub_query,+ "target_entities": list(self.target_entities),+ "rationale": self.rationale,+ "depth": self.depth,+ "relevance_score": self.relevance_score,+ }++ @classmethod+ def from_dict(cls, d: Dict[str, Any]) -> "DriftFacet":+ """Reconstruct DriftFacet from dictionary."""+ depth_val = d.get("depth")+ score_val = d.get("relevance_score")+ if score_val is None:+ score_val = d.get("score")+ return cls(+ sub_query=str(d.get("sub_query") or ""),+ target_entities=list(d.get("target_entities") or []),+ rationale=str(d.get("rationale") or ""),+ depth=int(depth_val) if depth_val is not None else 0,+ relevance_score=float(score_val) if score_val is not None else 1.0,+ )+++class DriftFacetSchema(BaseModel):+ """Pydantic schema for individual DRIFT facets."""++ model_config = ConfigDict(extra="ignore")++ sub_query: str = Field(description="Targeted follow-up question")+ target_entities: List[str] = Field(+ default_factory=list, description="Seed entities to explore"+ )+ rationale: str = Field(+ default="", description="Reasoning behind exploring this facet"+ )+ relevance_score: float = Field(+ default=1.0,+ validation_alias=AliasChoices("relevance_score", "score"),+ description="Priority score between 0.0 and 1.0",+ )++ @field_validator("target_entities", mode="before")+ @classmethod+ def normalize_entities(cls, v: Any) -> List[str]:+ """Normalize target entities to list of strings."""+ if isinstance(v, list):+ return [str(e).strip() for e in v if e]+ if isinstance(v, str):+ return [s.strip() for s in v.split(",") if s.strip()]+ return []++ @field_validator("relevance_score", mode="before")+ @classmethod+ def clamp_score(cls, v: Any) -> float:+ """Clamp relevance score to 0.0 - 1.0."""+ try:+ val = float(v)+ if math.isnan(val) or math.isinf(val):+ return 1.0+ return max(0.0, min(1.0, val))+ except (ValueError, TypeError):+ return 1.0+++class DriftFacetsResponseSchema(BaseModel):+ """Pydantic v2 schema for LLM facet generation response."""++ model_config = ConfigDict(extra="ignore")++ facets: List[DriftFacetSchema] = Field(+ default_factory=list, description="Generated exploration facets"+ )++ @field_validator("facets", mode="before")+ @classmethod+ def normalize_facets(cls, v: Any) -> List[Any]:+ """Normalize flexible facet outputs into valid schema objects."""+ if not isinstance(v, list):+ if isinstance(v, (dict, str)):+ v = [v]+ else:+ return []++ normalized = []+ for item in v:+ if isinstance(item, DriftFacetSchema):+ normalized.append(item)+ elif isinstance(item, dict):+ sq = (+ item.get("sub_query")+ or item.get("query")+ or item.get("question")+ or ""+ )+ ents = (+ item.get("target_entities")+ or item.get("entities")+ or item.get("seed_entities")+ or []+ )+ rat = item.get("rationale") or item.get("explanation") or ""+ score = (+ item.get("relevance_score")+ if item.get("relevance_score") is not None+ else item.get("score", 1.0)+ )+ normalized.append(+ {+ "sub_query": str(sq),+ "target_entities": ents,+ "rationale": str(rat),+ "relevance_score": score,+ }+ )+ elif isinstance(item, str):+ normalized.append(+ {+ "sub_query": item.strip(),+ "target_entities": [],+ "rationale": "",+ "relevance_score": 1.0,+ }+ )+ return normalized+++@dataclass+class DriftSearchResult:+ """Result of DRIFT hybrid search."""++ query: str+ answer: str+ thematic_framing: str = ""+ global_reports_used: List[str] = field(default_factory=list)+ verified_local_contexts: List[Dict[str, Any]] = field(default_factory=list)+ facets_explored: List[DriftFacet] = field(default_factory=list)+ depth_reached: int = 0+ pruned_fact_count: int = 0+ citations: List[str] = field(default_factory=list)+ metrics: Dict[str, Any] = field(default_factory=dict)++ def to_retrieved_contexts(self) -> List[RetrievedContext]:+ """+ Convert DRIFT search result into standard RetrievedContext objects.++ Primary answer is placed first with score 1.0, followed by verified+ local graph contexts. Returns an empty list if no global reports or+ verified local contexts are present.+ """+ contexts: List[RetrievedContext] = []++ if not self.global_reports_used and not self.verified_local_contexts:+ return contexts++ # Primary executive answer+ contexts.append(+ RetrievedContext(+ content=self.answer,+ score=1.0,+ source="drift_search",+ metadata={+ "query": self.query,+ "thematic_framing": self.thematic_framing,+ "depth_reached": self.depth_reached,+ "pruned_fact_count": self.pruned_fact_count,+ "citations": list(self.citations),+ "metrics": dict(self.metrics),+ },+ related_entities=[],+ related_relationships=[],+ )+ )++ # Verified local graph contexts+ for fact in self.verified_local_contexts:+ src = str(fact.get("source", ""))+ tgt = str(fact.get("target", ""))+ src_name = str(fact.get("source_name") or src)+ tgt_name = str(fact.get("target_name") or tgt)+ rel = str(fact.get("relation", "RELATED_TO"))+ desc = str(fact.get("description", ""))++ content_text = f"({src_name}) -[{rel}]-> ({tgt_name})"+ if desc:+ content_text += f": {desc}"++ score_val = float(fact.get("alignment_score", fact.get("score", 0.8)))+ scaled_score = max(0.0, min(1.0, score_val))++ entities = [{"id": src, "name": src_name}]+ if tgt and tgt != src:+ entities.append({"id": tgt, "name": tgt_name})++ rel_data = {+ "source": src,+ "target": tgt,+ "type": rel,+ **dict(fact.get("attributes", {})),+ }++ contexts.append(+ RetrievedContext(+ content=content_text,+ score=scaled_score,+ source=str(fact.get("source_id", "local_graph")),+ metadata={+ "source": src,+ "target": tgt,+ "source_name": src_name,+ "target_name": tgt_name,+ "relation": rel,+ "canonical_id": fact.get("canonical_id", ""),+ "edge_id": fact.get("edge_id", ""),+ "depth": fact.get("depth", 0),+ "alignment_score": score_val,+ **dict(fact.get("attributes", {})),+ },+ related_entities=entities,+ related_relationships=[rel_data],+ )+ )++ return contexts++ def to_dict(self) -> Dict[str, Any]:+ """Serialize DriftSearchResult to dictionary."""+ return {+ "query": self.query,+ "answer": self.answer,+ "thematic_framing": self.thematic_framing,+ "global_reports_used": list(self.global_reports_used),+ "verified_local_contexts": list(self.verified_local_contexts),+ "facets_explored": [f.to_dict() for f in self.facets_explored],+ "depth_reached": self.depth_reached,+ "pruned_fact_count": self.pruned_fact_count,+ "citations": list(self.citations),+ "metrics": dict(self.metrics),+ }++ @classmethod+ def from_dict(cls, d: Dict[str, Any]) -> "DriftSearchResult":+ """Deserialize DriftSearchResult from dictionary."""+ raw_facets = d.get("facets_explored", [])+ facets = [+ DriftFacet.from_dict(f) if isinstance(f, dict) else f+ for f in raw_facets+ ]+ return cls(+ query=str(d.get("query", "")),+ answer=str(d.get("answer", "")),+ thematic_framing=str(d.get("thematic_framing", "")),+ global_reports_used=list(d.get("global_reports_used", [])),+ verified_local_contexts=list(d.get("verified_local_contexts", [])),+ facets_explored=facets,+ depth_reached=int(d.get("depth_reached", 0)),+ pruned_fact_count=int(d.get("pruned_fact_count", 0)),+ citations=list(d.get("citations", [])),+ metrics=dict(d.get("metrics", {})),+ )+++def _cosine_similarity(vec_a: Sequence[float], vec_b: Sequence[float]) -> float:+ """Compute cosine similarity between two numerical vectors."""+ if not vec_a or not vec_b or len(vec_a) != len(vec_b):+ return 0.0+ dot = 0.0+ norm_a = 0.0+ norm_b = 0.0+ for a, b in zip(vec_a, vec_b):+ dot += a * b+ norm_a += a * a+ norm_b += b * b+ if norm_a <= 0.0 or norm_b <= 0.0:+ return 0.0+ return dot / (math.sqrt(norm_a) * math.sqrt(norm_b))+++def _extract_words(text: str) -> Set[str]:+ """Extract normalized lowercase alphanumeric word tokens from text."""+ if not text:+ return set()+ return set(re.findall(r"\b\w+\b", text.lower()))+++def _truncate_to_tokens(+ text: str,+ max_tokens: int,+ token_counter: Optional[Callable[[str], int]] = None,+) -> str:+ """Truncate text to fit within max_tokens without breaking prematurely."""+ if not text or max_tokens <= 0:+ return ""+ if estimate_tokens(text, token_counter) <= max_tokens:+ return text+ low = 0+ high = len(text)+ best = 0+ while low <= high:+ mid = (low + high) // 2+ cand = text[:mid]+ if estimate_tokens(cand, token_counter) <= max_tokens:+ best = mid+ low = mid + 1+ else:+ high = mid - 1+ return text[:best].rstrip()+++def _first_non_none(+ d: Dict[str, Any], keys: Sequence[str], default: Any = None+) -> Any:+ """Return first value in d matching any key whose value is not None."""+ for k in keys:+ if k in d and d[k] is not None:+ return d[k]+ return default+++def _first_attr_non_none(+ obj: Any, attrs: Sequence[str], default: Any = None+) -> Any:+ """Return first attribute on obj matching any attr name whose value is not None."""+ for a in attrs:+ if hasattr(obj, a):+ val = getattr(obj, a)+ if val is not None:+ return val+ return default+++class DriftSearchEngine:+ """+ DRIFT Hybrid Search Engine for Hierarchical GraphRAG.++ Executes global thematic framing, directed reasoning facet generation,+ local entity-hop traversal with in-memory adjacency indexing, semantic+ drift filtering, iterative deepening, and dual-attributed synthesis.+ """++ def __init__(+ self,+ knowledge_graph: Optional[Any] = None,+ reports: Optional[+ Union[+ Sequence[Union[CommunityReport, Dict[str, Any]]],+ Dict[str, Any],+ ]+ ] = None,+ hierarchy: Optional[CommunityHierarchy] = None,+ llm: Optional[Any] = None,+ embedder: Optional[Callable[[str], List[float]]] = None,+ token_counter: Optional[Callable[[str], int]] = None,+ drift_threshold: float = 0.35,+ max_depth: int = 2,+ top_k_reports: int = 3,+ max_facets: int = 3,+ max_context_tokens: int = 4000,+ **kwargs: Any,+ ) -> None:+ self.logger = get_logger("drift_search")+ self.hierarchy = hierarchy+ self.llm = llm+ self.embedder = embedder+ self.token_counter = token_counter+ self.drift_threshold = max(0.0, min(1.0, float(drift_threshold)))+ self.max_depth = max(1, int(max_depth))+ self.top_k_reports = max(1, int(top_k_reports))+ self.max_facets = max(1, int(max_facets))+ self.max_context_tokens = max(1, int(max_context_tokens))+ self.response_token_budget = max(+ 1, int(kwargs.get("response_token_budget", 500))+ )+ self.config = kwargs+ self._reports: List[CommunityReport] = []+ self._report_index: Dict[str, CommunityReport] = {}+ self._adjacency_index: Dict[str, List[Dict[str, Any]]] = {}+ self._node_meta: Dict[str, Dict[str, Any]] = {}+ self._alias_to_id: Dict[str, str] = {}++ if reports:+ self.set_reports(reports)+ if knowledge_graph is not None:+ self.set_knowledge_graph(knowledge_graph)++ def _resolve_node_id(self, entity_str: Any) -> str:+ """Resolve an entity name, alias, or ID to its canonical node ID."""+ if entity_str is None or str(entity_str).strip() == "":+ return ""+ s = str(entity_str).strip()+ if s in self._adjacency_index:+ return s+ lower = s.lower()+ if lower in self._alias_to_id:+ return self._alias_to_id[lower]+ return s++ def set_reports(+ self,+ reports: Union[+ Sequence[Union[CommunityReport, Dict[str, Any]]],+ Dict[str, Any],+ ],+ ) -> None:+ """Update active community reports collection."""+ loaded: List[CommunityReport] = []+ if isinstance(reports, dict):+ if "community_id" in reports and "summary" in reports:+ loaded.append(CommunityReport.from_dict(reports))+ else:+ for rep in reports.values():+ if isinstance(rep, CommunityReport):+ loaded.append(rep)+ elif isinstance(rep, dict):+ loaded.append(CommunityReport.from_dict(rep))+ elif isinstance(reports, Iterable) and not isinstance(reports, (str, bytes)):+ for rep in reports:+ if isinstance(rep, CommunityReport):+ loaded.append(rep)+ elif isinstance(rep, dict):+ loaded.append(CommunityReport.from_dict(rep))+ self._reports = loaded++ def set_knowledge_graph(self, graph: Any) -> None:+ """+ Build fast in-memory adjacency index from knowledge graph representation.++ Supports dictionary representations ('nodes'/'edges',+ 'entities'/'relationships'), NetworkX graphs, and Semantica+ GraphStore/ContextGraph objects.+ """+ adj: Dict[str, List[Dict[str, Any]]] = {}+ nodes_info: Dict[str, Dict[str, Any]] = {}++ # 1. Extract nodes if present+ raw_nodes = None+ if isinstance(graph, dict):+ raw_nodes = graph.get("nodes") or graph.get("entities")+ else:+ nodes_attr = getattr(graph, "nodes", None)+ if isinstance(nodes_attr, dict):+ raw_nodes = nodes_attr+ elif (+ nodes_attr is not None+ and not isinstance(nodes_attr, (str, bytes))+ and hasattr(nodes_attr, "get")+ and callable(nodes_attr.get)+ ):+ if hasattr(graph, "get_nodes") and callable(graph.get_nodes):+ try:+ raw_nodes = graph.get_nodes(limit=10000)+ except TypeError:+ raw_nodes = graph.get_nodes()+ else:+ try:+ raw_nodes = nodes_attr.get(limit=10000)+ except TypeError:+ raw_nodes = nodes_attr.get()+ elif callable(nodes_attr):+ try:+ raw_nodes = nodes_attr(data=True)+ except Exception:+ raw_nodes = nodes_attr()+ elif nodes_attr is not None:+ raw_nodes = nodes_attr+ elif hasattr(graph, "get_nodes") and callable(graph.get_nodes):+ try:+ raw_nodes = graph.get_nodes(limit=10000)+ except TypeError:+ raw_nodes = graph.get_nodes()+ else:+ raw_nodes = getattr(graph, "entities", None)++ def _extract_node_entry(+ val: Any, fallback_id: Any = None+ ) -> tuple[str, Dict[str, Any]]:+ if isinstance(val, dict):+ raw_nid = _first_non_none(+ val,+ ("id", "name", "entity_id", "node_id"),+ fallback_id,+ )+ nid = str(raw_nid).strip() if raw_nid is not None else ""+ d = dict(val)+ props = (+ d.get("properties")+ if isinstance(d.get("properties"), dict)+ else (d.get("n") if isinstance(d.get("n"), dict) else {})+ )+ raw_name = _first_non_none(d, ("name", "label"), None)+ if raw_name is None and isinstance(props, dict):+ raw_name = _first_non_none(props, ("name", "label"), None)+ if raw_name is None:+ raw_name = nid+ d.setdefault("name", str(raw_name))+ d.setdefault("id", nid)+ return nid, d+ if hasattr(val, "to_dict") and callable(val.to_dict):+ d = dict(val.to_dict())+ raw_nid = _first_non_none(+ d, ("id", "node_id", "name"), fallback_id+ )+ nid = str(raw_nid).strip() if raw_nid is not None else ""+ props = (+ d.get("properties")+ if isinstance(d.get("properties"), dict)+ else {}+ )+ raw_name = _first_non_none(d, ("name", "label"), None)+ if raw_name is None and isinstance(props, dict):+ raw_name = _first_non_none(props, ("name", "label"), None)+ if raw_name is None:+ raw_name = nid+ d.setdefault("name", str(raw_name))+ d.setdefault("id", nid)+ return nid, d+ if hasattr(val, "node_id"):+ raw_nid = getattr(val, "node_id", None)+ if raw_nid is None:+ raw_nid = fallback_id+ nid = str(raw_nid).strip() if raw_nid is not None else ""+ props = dict(getattr(val, "properties", {}) or {})+ meta = dict(getattr(val, "metadata", {}) or {})+ raw_name = _first_non_none(+ props,+ ("name", "label"),+ _first_non_none(meta, ("label",), nid),+ )+ d = {+ "id": nid,+ "name": str(raw_name),+ "type": str(getattr(val, "node_type", "")),+ "content": str(getattr(val, "content", "")),+ **props,+ **meta,+ }+ return nid, d+ raw_nid = fallback_id if fallback_id is not None else val+ nid = str(raw_nid).strip() if raw_nid is not None else ""+ return nid, {"id": nid, "name": nid}++ if isinstance(raw_nodes, dict):+ for k, v in raw_nodes.items():+ nid, d = _extract_node_entry(v, k)+ if nid != "":+ nodes_info[nid] = d+ elif isinstance(raw_nodes, Iterable) and not isinstance(+ raw_nodes, (str, bytes)+ ):+ for item in raw_nodes:+ if isinstance(item, tuple) and len(item) == 2:+ nid = str(item[0]).strip() if item[0] is not None else ""+ if isinstance(item[1], dict):+ d = dict(item[1])+ d.setdefault("id", nid)+ props = (+ d.get("properties")+ if isinstance(d.get("properties"), dict)+ else {}+ )+ raw_name = _first_non_none(+ d,+ ("name", "label"),+ _first_non_none(props, ("name", "label"), nid),+ )+ d.setdefault("name", str(raw_name))+ if nid != "":+ nodes_info[nid] = d+ else:+ if nid != "":+ nodes_info[nid] = {"id": nid, "name": nid}+ else:+ nid, d = _extract_node_entry(item)+ if nid != "":+ nodes_info[nid] = d++ alias_map: Dict[str, str] = {}+ for nid, info in nodes_info.items():+ if nid != "":+ alias_map[nid.lower()] = nid+ name_val = info.get("name")+ if name_val is not None and str(name_val).strip():+ alias_map[str(name_val).strip().lower()] = nid+ label_val = info.get("label")+ if label_val is not None and str(label_val).strip():+ alias_map[str(label_val).strip().lower()] = nid+ aliases = info.get("aliases")+ if isinstance(aliases, (list, tuple, set)):+ for a in aliases:+ if a is not None and str(a).strip():+ alias_map[str(a).strip().lower()] = nid+ props = info.get("properties")+ if isinstance(props, dict):+ for prop_k in ("name", "label", "title"):+ pv = props.get(prop_k)+ if pv is not None and str(pv).strip():+ alias_map[str(pv).strip().lower()] = nid++ # 2. Extract edges+ raw_edges = None+ if isinstance(graph, dict):+ raw_edges = graph.get("edges") or graph.get("relationships")+ else:+ rel_attr = getattr(graph, "relationships", None)+ if (+ rel_attr is not None+ and not isinstance(rel_attr, dict)+ and not isinstance(rel_attr, (str, bytes))+ and hasattr(rel_attr, "get")+ and callable(rel_attr.get)+ ):+ if hasattr(graph, "get_relationships") and callable(+ graph.get_relationships+ ):+ try:+ raw_edges = graph.get_relationships(limit=10000)+ except TypeError:+ raw_edges = graph.get_relationships()+ else:+ try:+ raw_edges = rel_attr.get(limit=10000)+ except TypeError:+ raw_edges = rel_attr.get()+ else:+ raw_edges = getattr(graph, "edges", None)+ if callable(raw_edges):+ try:+ raw_edges = raw_edges(data=True)+ except Exception:+ raw_edges = raw_edges()+ elif raw_edges is None:+ raw_edges = getattr(graph, "relationships", None)+ if callable(raw_edges):+ raw_edges = raw_edges()+ elif raw_edges is None:+ raw_edges = getattr(graph, "get_all_relationships", None)+ if callable(raw_edges):+ raw_edges = raw_edges()+ elif hasattr(graph, "get_relationships") and callable(+ graph.get_relationships+ ):+ try:+ raw_edges = graph.get_relationships(limit=10000)+ except TypeError:+ raw_edges = graph.get_relationships()++ if raw_edges:+ edge_iterable = (+ raw_edges.values() if isinstance(raw_edges, dict) else raw_edges+ )+ for item in edge_iterable:+ src, tgt, rel, attrs, desc, edge_id = self._parse_edge_item(item)+ if src == "" or tgt == "":+ continue++ if edge_id:+ canonical_id = f"{src}->{rel}->{tgt}:{edge_id}"+ else:+ payload = json.dumps(+ {"rel": rel, "desc": desc, "attrs": attrs},+ sort_keys=True,+ default=str,+ )+ h = hashlib.sha256(payload.encode("utf-8")).hexdigest()[:12]+ canonical_id = f"{src}->{rel}->{tgt}:{h}"++ edge_dict = {+ "source": src,+ "target": tgt,+ "relation": rel,+ "description": desc,+ "attributes": attrs,+ "canonical_id": canonical_id,+ }+ if edge_id:+ edge_dict["edge_id"] = edge_id+ adj.setdefault(src, []).append(edge_dict)+ # For undirected retrieval traversal, allow bidirection lookup+ if src != tgt:+ inv_dict = {+ "source": tgt,+ "target": src,+ "relation": rel,+ "description": desc,+ "attributes": attrs,+ "canonical_id": canonical_id,+ "is_inverse": True,+ }+ if edge_id:+ inv_dict["edge_id"] = edge_id+ adj.setdefault(tgt, []).append(inv_dict)++ for ep in (src, tgt):+ if ep not in nodes_info:+ nodes_info[ep] = {"id": ep, "name": ep}+ if ep.lower() not in alias_map:+ alias_map[ep.lower()] = ep++ self._adjacency_index = adj+ self._node_meta = nodes_info+ self._alias_to_id = alias_map++ def _parse_edge_item(+ self, item: Any+ ) -> tuple[str, str, str, Dict[str, Any], str, str]:+ """Normalize raw edge into src, tgt, rel, attrs, desc, edge_id."""+ src_val = None+ tgt_val = None+ rel = "RELATED_TO"+ attrs: Dict[str, Any] = {}+ desc = ""+ edge_id = ""++ if isinstance(item, (tuple, list)):+ if len(item) >= 2:+ src_val = item[0]+ tgt_val = item[1]+ if len(item) >= 3:+ third = item[2]+ if isinstance(third, str):+ rel = third+ elif isinstance(third, dict):+ attrs = dict(third)+ rel = str(+ attrs.get("type")+ or attrs.get("relation")+ or attrs.get("rel")+ or attrs.get("rel_type")+ or attrs.get("edge_type")+ or attrs.get("predicate")+ or rel+ )+ desc = str(attrs.get("description") or attrs.get("desc") or "")+ edge_id = str(+ attrs.get("id")+ or attrs.get("edge_id")+ or attrs.get("rel_id")+ or attrs.get("relationship_id")+ or ""+ )+ if len(item) >= 4 and isinstance(item[3], dict):+ fourth = dict(item[3])+ attrs.update(fourth)+ rel = str(+ attrs.get("type")+ or attrs.get("relation")+ or attrs.get("rel")+ or attrs.get("rel_type")+ or attrs.get("edge_type")+ or attrs.get("predicate")+ or rel+ )+ if not desc:+ desc = str(attrs.get("description") or attrs.get("desc") or "")+ if not edge_id:+ edge_id = str(+ attrs.get("id")+ or attrs.get("edge_id")+ or attrs.get("rel_id")+ or attrs.get("relationship_id")+ or ""+ )+ elif isinstance(item, dict):+ src_val = _first_non_none(+ item,+ (+ "source",+ "source_id",+ "start_node_id",+ "start_id",+ "start",+ "from",+ "subject",+ "src",+ ),+ None,+ )+ tgt_val = _first_non_none(+ item,+ (+ "target",+ "target_id",+ "end_node_id",+ "end_id",+ "end",+ "to",+ "object",+ "dst",+ ),+ None,+ )+ rel = str(+ item.get("relation")+ or item.get("type")+ or item.get("rel_type")+ or item.get("predicate")+ or item.get("rel")+ or "RELATED_TO"+ )+ props = (+ item.get("properties")+ if isinstance(item.get("properties"), dict)+ else (item.get("r") if isinstance(item.get("r"), dict) else {})+ )+ desc = str(+ item.get("description")+ or item.get("desc")+ or props.get("description")+ or props.get("desc")+ or ""+ )+ raw_edge_id = _first_non_none(+ item,+ ("id", "edge_id", "rel_id", "relationship_id"),+ _first_non_none(+ props,+ ("id", "edge_id", "rel_id", "relationship_id"),+ None,+ ),+ )+ edge_id = str(raw_edge_id).strip() if raw_edge_id is not None else ""+ attrs = dict(item.get("attributes") or {})+ if props and not attrs:+ attrs.update(props)+ for k, v in item.items():+ if k not in (+ "source",+ "source_id",+ "start_node_id",+ "start_id",+ "start",+ "target",+ "target_id",+ "end_node_id",+ "end_id",+ "end",+ "from",+ "to",+ "subject",+ "object",+ "src",+ "dst",+ "relation",+ "type",+ "rel_type",+ "predicate",+ "description",+ "desc",+ "attributes",+ "properties",+ "r",+ "id",+ "edge_id",+ "rel_id",+ "relationship_id",+ ):+ attrs[k] = v+ else:+ src_val = _first_attr_non_none(+ item,+ (+ "source",+ "source_id",+ "start_node_id",+ "start_id",+ "start",+ "from_node",+ "from",+ "subject",+ "src",+ ),+ None,+ )+ tgt_val = _first_attr_non_none(+ item,+ (+ "target",+ "target_id",+ "end_node_id",+ "end_id",+ "end",+ "to_node",+ "to",+ "object",+ "dst",+ ),+ None,+ )+ rel = str(+ getattr(item, "edge_type", None)+ or getattr(item, "type", None)+ or getattr(item, "rel_type", None)+ or getattr(item, "relation", None)+ or getattr(item, "predicate", None)+ or getattr(item, "rel", "RELATED_TO")+ or "RELATED_TO"+ )+ attrs_obj = (+ getattr(item, "attributes", None)+ or getattr(item, "metadata", None)+ or getattr(item, "properties", None)+ or {}+ )+ attrs = dict(attrs_obj) if isinstance(attrs_obj, dict) else {}+ raw_edge_id = _first_attr_non_none(+ item,+ ("id", "edge_id", "rel_id", "relationship_id"),+ _first_non_none(+ attrs,+ ("id", "edge_id", "rel_id", "relationship_id"),+ None,+ ),+ )+ edge_id = str(raw_edge_id).strip() if raw_edge_id is not None else ""+ desc = str(+ getattr(item, "description", "")+ or getattr(item, "desc", "")+ or (attrs.get("description", "") if isinstance(attrs, dict) else "")+ or (attrs.get("desc", "") if isinstance(attrs, dict) else "")+ or ""+ )++ src = str(src_val).strip() if src_val is not None else ""+ tgt = str(tgt_val).strip() if tgt_val is not None else ""+ return (src, tgt, rel.strip(), attrs, desc.strip(), edge_id.strip())++ def _extract_thematic_framing(+ self, query: str, query_embedding: Optional[List[float]] = None+ ) -> tuple[str, List[str]]:+ """Stage 1: Extract top-K global community reports for thematic framing."""+ if not self._reports:+ return ("No global community reports provided.", [])++ scored: List[tuple[float, CommunityReport]] = []+ query_words = _extract_words(query)++ for rep in self._reports:+ score = 0.0+ if (+ query_embedding is not None+ and rep.embedding is not None+ and len(rep.embedding) == len(query_embedding)+ ):+ score = _cosine_similarity(query_embedding, rep.embedding)+ else:+ text = f"{rep.title} {rep.summary}"+ words = _extract_words(text)+ if query_words and words:+ intersection = len(query_words & words)+ union = len(query_words | words)+ jaccard = intersection / float(union) if union > 0 else 0.0+ else:+ jaccard = 0.0+ norm_rank = max(0.0, min(1.0, rep.rank))+ norm_impact = max(0.0, min(1.0, (rep.impact_rating - 1.0) / 9.0))+ score = (jaccard * 0.5) + (norm_rank * 0.3) + (norm_impact * 0.2)++ scored.append((score, rep))++ scored.sort(+ key=lambda item: (-item[0], -item[1].impact_rating, item[1].community_id)+ )++ selected = [item[1] for item in scored[: self.top_k_reports]]+ framing_parts: List[str] = []+ for r in selected:+ framing_parts.append(+ f"- [Community {r.community_id}] (Level {r.level}): "+ f"{r.title}. {r.summary}"+ )++ framing_text = "\n".join(framing_parts)+ report_ids = [r.community_id for r in selected]+ return (framing_text, report_ids)++ def _extract_json(self, text: str) -> Union[Dict[str, Any], List[Any]]:+ """Extract and parse JSON object from LLM response text."""+ cleaned = text.strip()+ try:+ val = json.loads(cleaned)+ if isinstance(val, (dict, list)):+ return val+ except Exception:+ pass++ match = re.search(r"```(?:json)?\s*([\s\S]*?)\s*```", cleaned, re.DOTALL)+ if match:+ block = match.group(1).strip()+ try:+ val = json.loads(block)+ if isinstance(val, (dict, list)):+ return val+ except Exception:+ pass++ decoder = json.JSONDecoder()+ for i in range(len(cleaned)):+ if cleaned[i] in ("{", "["):+ try:+ obj, _ = decoder.raw_decode(cleaned[i:])+ if isinstance(obj, (dict, list)):+ return obj+ except Exception:+ pass++ raise ValueError(f"No valid JSON in response: {cleaned[:100]}...")++ def _coerce_facets_response(+ self, res: Any+ ) -> Optional[DriftFacetsResponseSchema]:+ """Coerce arbitrary response into DriftFacetsResponseSchema."""+ if isinstance(res, DriftFacetsResponseSchema):+ return res+ if isinstance(res, list):+ return DriftFacetsResponseSchema(facets=res)+ if isinstance(res, dict):+ if "facets" not in res and any(+ k in res+ for k in ("sub_query", "query", "question", "target_entities")+ ):+ return DriftFacetsResponseSchema(facets=[res])+ return DriftFacetsResponseSchema.model_validate(res)+ if hasattr(res, "model_dump") and callable(res.model_dump):+ return DriftFacetsResponseSchema.model_validate(res.model_dump())+ if hasattr(res, "__dict__"):+ try:+ return DriftFacetsResponseSchema.model_validate(vars(res))+ except Exception:+ pass+ if isinstance(res, str):+ try:+ parsed = self._extract_json(res)+ if isinstance(parsed, list):+ return DriftFacetsResponseSchema(facets=parsed)+ elif isinstance(parsed, dict):+ if "facets" not in parsed and any(+ k in parsed+ for k in (+ "sub_query",+ "query",+ "question",+ "target_entities",+ )+ ):+ return DriftFacetsResponseSchema(facets=[parsed])+ return DriftFacetsResponseSchema.model_validate(parsed)+ except Exception:+ pass+ return None++ def _generate_facets(+ self, query: str, thematic_framing: str+ ) -> List[DriftFacet]:+ """Stage 2: Directed reasoning to produce follow-up exploration facets."""+ llm = self.llm+ if llm is None:+ return self._extractive_facets_fallback(query)++ prompt_scaffold = (+ "You are a directed reasoning engine in a GraphRAG system.\n"+ "User Query: \n\n"+ "Global Thematic Framing:\n\n\n"+ "Instructions:\n"+ f"1. Generate up to {self.max_facets} targeted follow-up sub-queries "+ "to drill down into local knowledge graph relationships.\n"+ "2. For each sub-query, identify 1-3 seed target entities to inspect.\n"+ "3. Return the response in JSON with 'facets': list of "+ "{'sub_query', 'target_entities', 'rationale', 'relevance_score'}."+ )+ base_tokens = estimate_tokens(prompt_scaffold, self.token_counter)+ response_reserve = min(+ getattr(self, "response_token_budget", 500),+ max(10, self.max_context_tokens // 5),+ )+ available_content = max(+ 0, self.max_context_tokens - base_tokens - response_reserve+ )+ query_budget = max(1, available_content // 2) if available_content > 0 else 0+ budgeted_query = (+ _truncate_to_tokens(query, query_budget, self.token_counter)+ if query_budget > 0+ else ""+ )+ query_tokens = (+ estimate_tokens(f"User Query: {budgeted_query}\n\n", self.token_counter)+ - estimate_tokens("User Query: \n\n", self.token_counter)+ if budgeted_query+ else 0+ )+ remaining_for_framing = max(+ 0,+ self.max_context_tokens - base_tokens - query_tokens - response_reserve,+ )+ budgeted_framing = (+ _truncate_to_tokens(+ thematic_framing, remaining_for_framing, self.token_counter+ )+ if remaining_for_framing > 0+ else ""+ )++ prompt = (+ "You are a directed reasoning engine in a GraphRAG system.\n"+ f"User Query: {budgeted_query}\n\n"+ f"Global Thematic Framing:\n{budgeted_framing}\n\n"+ "Instructions:\n"+ f"1. Generate up to {self.max_facets} targeted follow-up sub-queries "+ "to drill down into local knowledge graph relationships.\n"+ "2. For each sub-query, identify 1-3 seed target entities to inspect.\n"+ "3. Return the response in JSON with 'facets': list of "+ "{'sub_query', 'target_entities', 'rationale', 'relevance_score'}."+ )++ facets_resp = None+ # Tier 1: generate_typed+ if hasattr(llm, "generate_typed") and callable(llm.generate_typed):+ try:+ try:+ res = llm.generate_typed(+ prompt, schema=DriftFacetsResponseSchema+ )+ except TypeError:+ res = llm.generate_typed(prompt)+ facets_resp = self._coerce_facets_response(res)+ except Exception as e:+ self.logger.warning(f"Drift Tier 1 generate_typed failed: {e}")++ # Tier 2: provider.generate_typed+ if (+ facets_resp is None+ and hasattr(llm, "provider")+ and hasattr(llm.provider, "generate_typed")+ and callable(llm.provider.generate_typed)+ ):+ try:+ try:+ res = llm.provider.generate_typed(+ prompt, schema=DriftFacetsResponseSchema+ )+ except TypeError:+ res = llm.provider.generate_typed(prompt)+ facets_resp = self._coerce_facets_response(res)+ except Exception as e:+ self.logger.warning(f"Drift Tier 2 failed: {e}")++ # Tier 3: generate_structured+ if facets_resp is None and hasattr(llm, "generate_structured"):+ try:+ res = llm.generate_structured(prompt)+ facets_resp = self._coerce_facets_response(res)+ except Exception as e:+ self.logger.warning(f"Drift Tier 3 failed: {e}")++ # Tier 4: generate + JSON parse+ if facets_resp is None and hasattr(llm, "generate"):+ try:+ res = llm.generate(prompt)+ facets_resp = self._coerce_facets_response(res)+ except Exception as e:+ self.logger.warning(f"Drift Tier 4 failed: {e}")++ # Tier 5: callable+ if facets_resp is None and callable(llm):+ try:+ res = llm(prompt)+ facets_resp = self._coerce_facets_response(res)+ except Exception as e:+ self.logger.warning(f"Drift Tier 5 failed: {e}")++ if facets_resp and facets_resp.facets:+ return [+ DriftFacet(+ sub_query=f.sub_query,+ target_entities=f.target_entities,+ rationale=f.rationale,+ depth=0,+ relevance_score=f.relevance_score,+ )+ for f in facets_resp.facets[: self.max_facets]+ ]++ return self._extractive_facets_fallback(query)++ def _extractive_facets_fallback(self, query: str) -> List[DriftFacet]:+ """Deterministic extractive fallback for facet generation."""+ query_words = _extract_words(query)+ candidate_entities: List[str] = []++ # Find matching entities in active reports or graph index+ for rep in self._reports:+ for ent in rep.member_entities:+ if ent.lower() in query.lower() or _extract_words(ent) & query_words:+ if ent not in candidate_entities:+ candidate_entities.append(ent)++ for nid, meta in self._node_meta.items():+ name = str(meta.get("name") or "")+ label = str(meta.get("label") or "")+ aliases = (+ meta.get("aliases")+ if isinstance(meta.get("aliases"), list)+ else []+ )+ names_to_check = [nid, name, label] + list(aliases)+ matched = any(+ n and (+ n.lower() in query.lower()+ or bool(_extract_words(n) & query_words)+ )+ for n in names_to_check+ )+ if matched:+ cand = name if name else nid+ if cand not in candidate_entities:+ candidate_entities.append(cand)++ for nid in self._adjacency_index.keys():+ if nid.lower() in query.lower() or _extract_words(nid) & query_words:+ cand = str(self._node_meta.get(nid, {}).get("name") or nid)+ if cand not in candidate_entities:+ candidate_entities.append(cand)++ if not candidate_entities and self._adjacency_index:+ for nid in sorted(self._adjacency_index.keys())[:3]:+ cand = str(self._node_meta.get(nid, {}).get("name") or nid)+ if cand not in candidate_entities:+ candidate_entities.append(cand)++ facets: List[DriftFacet] = []+ for ent in candidate_entities[: self.max_facets]:+ facets.append(+ DriftFacet(+ sub_query=f"Explore connections for {ent} regarding {query}",+ target_entities=[ent],+ rationale=f"Direct seed match for query entity: {ent}",+ depth=0,+ relevance_score=1.0,+ )+ )++ if not facets:+ facets.append(+ DriftFacet(+ sub_query=query,+ target_entities=[],+ rationale="General fallback facet",+ depth=0,+ relevance_score=1.0,+ )+ )++ return facets++ def _compute_alignment_score(+ self,+ fact_text: str,+ query_context: str,+ query_embedding: Optional[List[float]] = None,+ ) -> float:+ """Compute semantic alignment score for Stage 4 drift pruning."""+ if self.embedder is not None and query_embedding is not None:+ try:+ fact_emb = self.embedder(fact_text)+ return _cosine_similarity(query_embedding, fact_emb)+ except Exception as e:+ self.logger.debug(f"Fact embedding alignment failed: {e}")++ # Heuristic token overlap & substring alignment+ fact_words = _extract_words(fact_text)+ query_words = _extract_words(query_context)+ if not fact_words or not query_words:+ return 0.0++ overlap = len(fact_words & query_words)+ union = len(fact_words | query_words)+ jaccard = overlap / float(union) if union > 0 else 0.0++ # Substring bonus capped to prevent runaway scores+ bonus = 0.0+ for qw in query_words:+ if len(qw) > 3 and qw in fact_text.lower():+ bonus += 0.15+ bonus = min(0.3, bonus)++ return min(1.0, (jaccard * 1.5) + bonus)++ def _traverse_and_prune(+ self,+ facets: List[DriftFacet],+ query: str,+ thematic_framing: str,+ query_embedding: Optional[List[float]] = None,+ max_depth: Optional[int] = None,+ drift_threshold: Optional[float] = None,+ ) -> tuple[List[Dict[str, Any]], int, int]:+ """+ Stages 3, 4, and 5: Local entity-hop traversal, drift pruning, and deepening.+ """+ verified_facts: List[Dict[str, Any]] = []+ visited_entities: Set[str] = set()+ seen_edges: Set[str] = set()+ pruned_count = 0+ depth_reached = 0+ accumulated_tokens = 0+ budget_reached = False++ eff_max_depth = (+ self.max_depth if max_depth is None else max(1, int(max_depth))+ )+ eff_drift_thresh = (+ self.drift_threshold+ if drift_threshold is None+ else max(0.0, min(1.0, float(drift_threshold)))+ )++ query_context = f"{query} {thematic_framing}"++ # Scaffold tokens measurement for budget allocation+ hybrid_scaffold = (+ "You are an authoritative intelligence analyst synthesizing a hybrid "+ f"knowledge answer.\nQuery: {query}\n\n"+ f"Macro Thematic Context:\n{thematic_framing}\n\n"+ "Verified Local Graph Relationships:\n\n\n"+ "Instructions:\n"+ "1. Synthesize a comprehensive answer directly resolving the query.\n"+ "2. Dual Attribution: cite macro assertions with [Community <id>] "+ "and cite micro local relationships as (EntityA -[REL]-> EntityB).\n"+ "3. Ground all assertions strictly in the provided macro and micro "+ "evidence.\n"+ "4. Be concise, coherent, and executive-ready."+ )+ scaffold_tokens = estimate_tokens(hybrid_scaffold, self.token_counter)+ response_reserve = min(500, max(10, self.max_context_tokens // 5))+ facts_budget = max(+ min(50, self.max_context_tokens),+ self.max_context_tokens - scaffold_tokens - response_reserve,+ )++ # Collect initial seed entities from facets, resolving names through alias map+ current_frontier: Set[str] = set()+ for f in facets:+ for ent in f.target_entities:+ if not ent:+ continue+ resolved_id = self._resolve_node_id(ent)+ if resolved_id and resolved_id in self._adjacency_index:+ current_frontier.add(resolved_id)+ elif ent in self._adjacency_index:+ current_frontier.add(ent)++ for depth in range(eff_max_depth):+ if not current_frontier or budget_reached:+ break+ depth_reached = depth + 1+ next_frontier: Set[str] = set()++ for entity in sorted(current_frontier):+ if entity in visited_entities or budget_reached:+ continue+ visited_entities.add(entity)++ edges = self._adjacency_index.get(entity, [])+ for edge in edges:+ if budget_reached:+ break+ src = edge["source"]+ tgt = edge["target"]+ canon_id = edge.get(+ "canonical_id", f"{src}->{edge['relation']}->{tgt}"+ )+ if canon_id in seen_edges:+ continue+ seen_edges.add(canon_id)++ src_name = str(+ self._node_meta.get(src, {}).get("name") or src+ )+ tgt_name = str(+ self._node_meta.get(tgt, {}).get("name") or tgt+ )++ if edge.get("is_inverse"):+ fact_text = (+ f"({tgt_name}) -[{edge['relation']}]-> ({src_name}): "+ f"{edge.get('description', '')}"+ )+ else:+ fact_text = (+ f"({src_name}) -[{edge['relation']}]-> ({tgt_name}): "+ f"{edge.get('description', '')}"+ )++ score = self._compute_alignment_score(+ fact_text, query_context, query_embedding+ )++ if score >= eff_drift_thresh:+ fact_cost = estimate_tokens(fact_text, self.token_counter)+ if accumulated_tokens + fact_cost > facts_budget:+ budget_reached = True+ break+ if edge.get("is_inverse"):+ verified_edge = {+ "source": tgt,+ "target": src,+ "source_name": tgt_name,+ "target_name": src_name,+ "relation": edge["relation"],+ "description": edge.get("description", ""),+ "attributes": dict(edge.get("attributes", {})),+ }+ else:+ verified_edge = {+ "source": src,+ "target": tgt,+ "source_name": src_name,+ "target_name": tgt_name,+ "relation": edge["relation"],+ "description": edge.get("description", ""),+ "attributes": dict(edge.get("attributes", {})),+ }+ verified_edge["canonical_id"] = canon_id+ if edge.get("edge_id"):+ verified_edge["edge_id"] = edge["edge_id"]+ verified_edge["alignment_score"] = score+ verified_edge["depth"] = depth_reached+ verified_facts.append(verified_edge)+ accumulated_tokens += fact_cost+ if tgt != "" and tgt not in visited_entities:+ next_frontier.add(tgt)+ else:+ pruned_count += 1++ if budget_reached:+ break++ if budget_reached:+ break++ current_frontier = next_frontier++ return (verified_facts, depth_reached, pruned_count)++ def _synthesize_hybrid(+ self,+ query: str,+ thematic_framing: str,+ verified_facts: List[Dict[str, Any]],+ ) -> str:+ """Stage 6: Authoritative dual-attributed executive synthesis."""+ llm = self.llm+ sorted_facts = sorted(+ verified_facts,+ key=lambda f: (+ -float(f.get("alignment_score", 0.0)),+ str(f.get("source", "")),+ str(f.get("target", "")),+ ),+ )++ # Token budgeting to guarantee prompt does not exceed max_context_tokens+ prompt_scaffold = (+ "You are an authoritative intelligence analyst synthesizing a hybrid "+ "knowledge answer.\nQuery: \n\n"+ "Macro Thematic Context:\n\n\n"+ "Verified Local Graph Relationships:\nNone\n\n"+ "Instructions:\n"+ "1. Synthesize a comprehensive answer directly resolving the query.\n"+ "2. Dual Attribution: cite macro assertions with [Community <id>] "+ "and cite micro local relationships as (EntityA -[REL]-> EntityB).\n"+ "3. Ground all assertions strictly in the provided macro and micro "+ "evidence.\n"+ "4. Be concise, coherent, and executive-ready."+ )+ base_tokens = estimate_tokens(prompt_scaffold, self.token_counter)+ response_reserve = min(+ getattr(self, "response_token_budget", 500),+ max(10, self.max_context_tokens // 5),+ )+ available_content = max(+ 0, self.max_context_tokens - base_tokens - response_reserve+ )+ query_budget = max(1, available_content // 3) if available_content > 0 else 0+ budgeted_query = (+ _truncate_to_tokens(query, query_budget, self.token_counter)+ if query_budget > 0+ else ""+ )+ query_tokens = (+ estimate_tokens(f"Query: {budgeted_query}\n\n", self.token_counter)+ - estimate_tokens("Query: \n\n", self.token_counter)+ if budgeted_query+ else 0+ )+ available_for_context = max(+ 0, self.max_context_tokens - base_tokens - query_tokens - response_reserve+ )+ framing_target = (+ available_for_context // 2 if available_for_context > 0 else 0+ )+ budgeted_framing = (+ _truncate_to_tokens(+ thematic_framing, framing_target, self.token_counter+ )+ if framing_target > 0+ else ""+ )+ framing_tokens = (+ estimate_tokens(budgeted_framing, self.token_counter)+ if budgeted_framing+ else 0+ )+ facts_budget = max(0, available_for_context - framing_tokens)++ facts_preview: List[str] = []+ accumulated_fact_tokens = 0+ for fact in sorted_facts:+ src = fact.get("source_name") or fact["source"]+ tgt = fact.get("target_name") or fact["target"]+ rel = fact["relation"]+ desc = fact.get("description", "")+ line = f"- ({src}) -[{rel}]-> ({tgt})"+ if desc:+ line += f": {desc}"+ line_cost = estimate_tokens(line + "\n", self.token_counter)+ if accumulated_fact_tokens + line_cost <= facts_budget:+ facts_preview.append(line)+ accumulated_fact_tokens += line_cost+ else:+ break++ facts_text = "\n".join(facts_preview) if facts_preview else "None"++ if llm is None:+ # Deterministic synthesis+ display_query = budgeted_query if budgeted_query else query+ lines = [f"DRIFT Hybrid Response for: '{display_query}'\n"]+ if budgeted_framing:+ lines.append("Macro Context:")+ lines.append(budgeted_framing)+ lines.append("")+ if facts_preview:+ lines.append("Verified Local Graph Facts:")+ lines.extend(facts_preview)+ return "\n".join(lines)++ prompt = (+ "You are an authoritative intelligence analyst synthesizing a hybrid "+ f"knowledge answer.\nQuery: {budgeted_query}\n\n"+ f"Macro Thematic Context:\n{budgeted_framing}\n\n"+ f"Verified Local Graph Relationships:\n{facts_text}\n\n"+ "Instructions:\n"+ "1. Synthesize a comprehensive answer directly resolving the query.\n"+ "2. Dual Attribution: cite macro assertions with [Community <id>] "+ "and cite micro local relationships as (EntityA -[REL]-> EntityB).\n"+ "3. Ground all assertions strictly in the provided macro and micro "+ "evidence.\n"+ "4. Be concise, coherent, and executive-ready."+ )++ try:+ if hasattr(llm, "generate") and callable(llm.generate):+ res = llm.generate(prompt)+ elif callable(llm):+ res = llm(prompt)+ else:+ raise TypeError(f"Unsupported LLM type: {type(llm)}")+ if isinstance(res, dict):+ return str(+ res.get("text")+ or res.get("response")+ or res.get("content")+ or json.dumps(res)+ )+ return str(res).strip()+ except Exception as e:+ self.logger.warning(f"DRIFT synthesis LLM failed: {e}")+ return (+ f"DRIFT answer for '{query}':\n\n{budgeted_framing}\n\n"+ f"Verified Facts:\n{facts_text}"+ )++ def search(+ self,+ query: str,+ query_embedding: Optional[List[float]] = None,+ max_depth: Optional[int] = None,+ drift_threshold: Optional[float] = None,+ **kwargs: Any,+ ) -> DriftSearchResult:+ """+ Execute full DRIFT hybrid global-local search pipeline.++ Args:+ query: User query string.+ query_embedding: Optional precomputed query vector.+ max_depth: Depth limit for local entity-hop exploration.+ drift_threshold: Alignment score cutoff to prune graph drift.+ **kwargs: Additional runtime options.++ Returns:+ DriftSearchResult with answer, verified contexts, citations, and metrics.+ """+ start_time = time.time()+ eff_max_depth = (+ self.max_depth if max_depth is None else max(1, int(max_depth))+ )+ eff_drift_thresh = (+ self.drift_threshold+ if drift_threshold is None+ else max(0.0, min(1.0, float(drift_threshold)))+ )++ if query_embedding is None and self.embedder is not None:+ try:+ query_embedding = self.embedder(query)+ except Exception as e:+ self.logger.warning(f"Query embedding calculation failed: {e}")++ # Stage 1: Thematic framing+ thematic_framing, global_reports_used = self._extract_thematic_framing(+ query, query_embedding+ )++ # Stage 2: Directed reasoning and facet generation+ facets = self._generate_facets(query, thematic_framing)++ # Stages 3, 4, 5: Local traversal, drift pruning, deepening+ (+ verified_facts,+ depth_reached,+ pruned_count,+ ) = self._traverse_and_prune(+ facets,+ query,+ thematic_framing,+ query_embedding,+ max_depth=eff_max_depth,+ drift_threshold=eff_drift_thresh,+ )++ # Sort verified_facts descending by alignment_score+ verified_facts.sort(+ key=lambda f: (+ -float(f.get("alignment_score", 0.0)),+ str(f.get("source", "")),+ str(f.get("target", "")),+ )+ )++ # Stage 6: Authoritative dual-attributed synthesis+ answer = self._synthesize_hybrid(query, thematic_framing, verified_facts)++ # Citation extraction+ raw_comm_cits = re.findall(+ r"\[Community\s+([A-Za-z0-9_\-]+)\]", answer, re.IGNORECASE+ )+ raw_rel_cits = re.findall(+ r"\(([^()]+?)\s*-\s*\[([^\]]+)\]\s*->\s*([^()]+?)\)",+ answer,+ )++ valid_comm_ids = set(str(c) for c in global_reports_used)+ comm_cits = [+ f"[Community {c}]"+ for c in sorted(set(raw_comm_cits))+ if str(c) in valid_comm_ids+ ]++ valid_triples_map = {}+ for f in verified_facts:+ s_id = str(f.get("source", "")).strip()+ t_id = str(f.get("target", "")).strip()+ s_name = str(f.get("source_name") or s_id).strip()+ t_name = str(f.get("target_name") or t_id).strip()+ rel = str(f.get("relation", "")).strip()+ disp = (s_name, rel, t_name)+ valid_triples_map[(s_id.lower(), rel.lower(), t_id.lower())] = disp+ valid_triples_map[(s_name.lower(), rel.lower(), t_name.lower())] = disp+ valid_triples_map[(s_name.lower(), rel.lower(), t_id.lower())] = disp+ valid_triples_map[(s_id.lower(), rel.lower(), t_name.lower())] = disp++ rel_cits: List[str] = []+ seen_rel_cits: Set[str] = set()+ for src_raw, rel_raw, tgt_raw in raw_rel_cits:+ s_clean = src_raw.strip()+ r_clean = rel_raw.strip()+ t_clean = tgt_raw.strip()+ t_clean_cand = (+ t_clean.split(":", 1)[0].strip() if ":" in t_clean else t_clean+ )+ key = (s_clean.lower(), r_clean.lower(), t_clean.lower())+ key_cand = (s_clean.lower(), r_clean.lower(), t_clean_cand.lower())+ canonical_triple = valid_triples_map.get(key) or valid_triples_map.get(+ key_cand+ )+ if canonical_triple:+ s_canon, r_canon, t_canon = canonical_triple+ cit_str = f"({s_canon} -[{r_canon}]-> {t_canon})"+ if cit_str not in seen_rel_cits:+ seen_rel_cits.add(cit_str)+ rel_cits.append(cit_str)++ citations = comm_cits + rel_cits+ if not citations and global_reports_used:+ citations = [f"[Community {c}]" for c in global_reports_used]++ duration = time.time() - start_time+ metrics = {+ "time_taken": duration,+ "depth_reached": depth_reached,+ "facets_generated": len(facets),+ "verified_facts_count": len(verified_facts),+ "pruned_facts_count": pruned_count,+ "global_reports_count": len(global_reports_used),+ "citations_count": len(citations),+ }++ return DriftSearchResult(+ query=query,+ answer=answer,+ thematic_framing=thematic_framing,+ global_reports_used=global_reports_used,+ verified_local_contexts=verified_facts,+ facets_explored=facets,+ depth_reached=depth_reached,+ pruned_fact_count=pruned_count,+ citations=citations,+ metrics=metrics,+ )diff --git a/semantica/context/global_retriever.py b/semantica/context/global_retriever.pynew file mode 100644index 00000000..3a142010--- /dev/null+++ b/semantica/context/global_retriever.py@@ -0,0 +1,1284 @@+"""+Global Graph Retrieval Engine for Hierarchical GraphRAG.++Implements Map-Reduce query retrieval over hierarchical community reports,+dynamic level selection, token budgeting, parallel Map execution, and+dual-tier executive synthesis with explicit citations.+"""++from collections.abc import Callable, Iterable+import concurrent.futures+from dataclasses import dataclass, field+import json+import math+import re+import time+from typing import Any, Dict, List, Optional, Sequence, Set, Union++from pydantic import AliasChoices, BaseModel, ConfigDict, Field, field_validator++from ..kg.community_hierarchy import CommunityHierarchy+from ..kg.community_summarizer import CommunityReport, estimate_tokens+from ..utils.logging import get_logger+from .context_retriever import RetrievedContext++logger = get_logger("global_retriever")+++@dataclass+class MapKeyPoint:+ """Intermediate key finding extracted during the Map phase."""++ point: str+ description: str = ""+ relevance_score: float = 5.0+ community_id: str = ""+ level: int = 0+ entities: List[str] = field(default_factory=list)+ metadata: Dict[str, Any] = field(default_factory=dict)++ def __post_init__(self) -> None:+ self.point = str(self.point).strip()+ self.description = str(self.description).strip()+ self.community_id = (+ "" if self.community_id is None else str(self.community_id).strip()+ )+ self.level = int(self.level)+ try:+ r_val = float(self.relevance_score)+ if math.isnan(r_val) or math.isinf(r_val):+ r_val = 5.0+ except (ValueError, TypeError):+ r_val = 5.0+ self.relevance_score = max(0.0, min(10.0, r_val))++ if self.entities:+ self.entities = sorted(set(str(e).strip() for e in self.entities if e))+ else:+ self.entities = []++ if not isinstance(self.metadata, dict):+ self.metadata = {}++ def to_dict(self) -> Dict[str, Any]:+ """Convert MapKeyPoint to dictionary."""+ return {+ "point": self.point,+ "description": self.description,+ "relevance_score": self.relevance_score,+ "community_id": self.community_id,+ "level": self.level,+ "entities": self.entities,+ "metadata": dict(self.metadata),+ }++ @classmethod+ def from_dict(cls, d: Dict[str, Any]) -> "MapKeyPoint":+ """Reconstruct MapKeyPoint from dictionary."""+ score_val = d.get("relevance_score")+ if score_val is None:+ score_val = d.get("score")+ level_val = d.get("level")+ return cls(+ point=str(d.get("point") or ""),+ description=str(d.get("description") or ""),+ relevance_score=float(score_val) if score_val is not None else 5.0,+ community_id=str(d.get("community_id") or ""),+ level=int(level_val) if level_val is not None else 0,+ entities=list(d.get("entities") or []),+ metadata=dict(d.get("metadata") or {}),+ )+++class MapPointSchema(BaseModel):+ """Pydantic schema for individual mapped key points."""++ model_config = ConfigDict(extra="ignore")++ point: str = Field(description="Key finding or core assertion")+ description: str = Field(+ default="", description="Supporting explanation and context"+ )+ relevance_score: float = Field(+ default=5.0,+ validation_alias=AliasChoices("relevance_score", "score"),+ description="Relevance to query (0.0 to 10.0)",+ )+ entities: List[str] = Field(+ default_factory=list, description="Key entities mentioned"+ )++ @field_validator("relevance_score", mode="before")+ @classmethod+ def clamp_score(cls, v: Any) -> float:+ """Clamp relevance score to 0.0 - 10.0."""+ try:+ val = float(v)+ if math.isnan(val) or math.isinf(val):+ return 5.0+ return max(0.0, min(10.0, val))+ except (ValueError, TypeError):+ return 5.0++ @field_validator("entities", mode="before")+ @classmethod+ def normalize_entities(cls, v: Any) -> List[str]:+ """Normalize entities list."""+ if isinstance(v, list):+ return [str(item).strip() for item in v if item]+ if isinstance(v, str):+ return [s.strip() for s in v.split(",") if s.strip()]+ return []+++class MapResponseSchema(BaseModel):+ """Pydantic v2 schema for structured Map phase LLM output."""++ model_config = ConfigDict(extra="ignore")++ points: List[MapPointSchema] = Field(+ default_factory=list, description="List of key points extracted"+ )+ relevance_explanation: str = Field(+ default="", description="Rationale for relevance evaluations"+ )++ @field_validator("points", mode="before")+ @classmethod+ def normalize_points(cls, v: Any) -> List[Any]:+ """Normalize flexible point representations into valid schema items."""+ if not isinstance(v, list):+ if isinstance(v, (dict, str)):+ v = [v]+ else:+ return []++ normalized = []+ for item in v:+ if isinstance(item, MapPointSchema):+ normalized.append(item)+ elif isinstance(item, dict):+ p_text = (+ item.get("point")+ or item.get("finding")+ or item.get("summary")+ or item.get("title")+ or item.get("claim")+ or ""+ )+ desc = (+ item.get("description")+ or item.get("explanation")+ or item.get("detail")+ or item.get("evidence")+ or ""+ )+ score = (+ item.get("relevance_score")+ if item.get("relevance_score") is not None+ else item.get("score", 5.0)+ )+ ents = item.get("entities") or item.get("member_entities") or []+ normalized.append(+ {+ "point": str(p_text),+ "description": str(desc),+ "relevance_score": score,+ "entities": ents,+ }+ )+ elif isinstance(item, str):+ normalized.append(+ {+ "point": item.strip(),+ "description": "",+ "relevance_score": 5.0,+ "entities": [],+ }+ )+ return normalized+++@dataclass+class GlobalSearchResult:+ """Result of global hierarchical GraphRAG search."""++ query: str+ response: str+ level: int = 0+ key_points: List[MapKeyPoint] = field(default_factory=list)+ community_reports_used: List[str] = field(default_factory=list)+ citations: List[str] = field(default_factory=list)+ metrics: Dict[str, Any] = field(default_factory=dict)++ def to_retrieved_contexts(self) -> List[RetrievedContext]:+ """+ Convert global search result into standard RetrievedContext objects.++ The executive response is placed first with score 1.0, followed by+ individual intermediate key points scaled to 0.0 - 1.0. Returns an+ empty list if no community reports or key points are present.+ """+ contexts: List[RetrievedContext] = []++ if not self.community_reports_used and not self.key_points:+ return contexts++ # Primary executive answer+ contexts.append(+ RetrievedContext(+ content=self.response,+ score=1.0,+ source="global_search",+ metadata={+ "query": self.query,+ "level": self.level,+ "community_reports_used": list(self.community_reports_used),+ "citations": list(self.citations),+ "metrics": dict(self.metrics),+ },+ related_entities=[],+ related_relationships=[],+ )+ )++ # Supporting key points+ for kp in self.key_points:+ scaled_score = max(0.0, min(1.0, kp.relevance_score / 10.0))+ content_parts = [kp.point]+ if kp.description:+ content_parts.append(kp.description)+ kp_content = ": ".join(content_parts)++ contexts.append(+ RetrievedContext(+ content=kp_content,+ score=scaled_score,+ source=f"community_{kp.community_id}",+ metadata={+ "community_id": kp.community_id,+ "level": kp.level,+ "relevance_score": kp.relevance_score,+ **dict(kp.metadata),+ },+ related_entities=[+ {"id": ent, "name": ent} for ent in kp.entities+ ],+ related_relationships=[],+ )+ )++ return contexts++ def to_dict(self) -> Dict[str, Any]:+ """Serialize GlobalSearchResult to dictionary."""+ return {+ "query": self.query,+ "response": self.response,+ "level": self.level,+ "key_points": [kp.to_dict() for kp in self.key_points],+ "community_reports_used": list(self.community_reports_used),+ "citations": list(self.citations),+ "metrics": dict(self.metrics),+ }++ @classmethod+ def from_dict(cls, d: Dict[str, Any]) -> "GlobalSearchResult":+ """Deserialize GlobalSearchResult from dictionary."""+ raw_kps = d.get("key_points", [])+ kps = [+ MapKeyPoint.from_dict(kp)+ if isinstance(kp, dict)+ else kp+ for kp in raw_kps+ ]+ return cls(+ query=d.get("query", ""),+ response=d.get("response", ""),+ level=int(d.get("level", 0)),+ key_points=kps,+ community_reports_used=list(d.get("community_reports_used", [])),+ citations=list(d.get("citations", [])),+ metrics=dict(d.get("metrics", {})),+ )+++def _cosine_similarity(vec_a: Sequence[float], vec_b: Sequence[float]) -> float:+ """Compute cosine similarity between two numerical vectors."""+ if not vec_a or not vec_b or len(vec_a) != len(vec_b):+ return 0.0+ dot = 0.0+ norm_a = 0.0+ norm_b = 0.0+ for a, b in zip(vec_a, vec_b):+ dot += a * b+ norm_a += a * a+ norm_b += b * b+ if norm_a <= 0.0 or norm_b <= 0.0:+ return 0.0+ return dot / (math.sqrt(norm_a) * math.sqrt(norm_b))+++def _extract_words(text: str) -> Set[str]:+ """Extract normalized lowercase alphanumeric word tokens from text."""+ if not text:+ return set()+ return set(re.findall(r"\b\w+\b", text.lower()))+++class GlobalGraphRetriever:+ """+ Map-Reduce global query retrieval engine for Hierarchical GraphRAG.++ Executes dynamic level promotion, token-budgeted pruning, concurrent Map+ evaluations across community reports, and executive Reduce synthesis with+ attribution.+ """++ def __init__(+ self,+ reports: Optional[+ Union[+ Sequence[Union[CommunityReport, Dict[str, Any]]],+ Dict[str, Any],+ ]+ ] = None,+ hierarchy: Optional[CommunityHierarchy] = None,+ llm: Optional[Any] = None,+ embedder: Optional[Callable[[str], List[float]]] = None,+ token_counter: Optional[Callable[[str], int]] = None,+ max_context_tokens: int = 4000,+ response_token_budget: int = 600,+ fixed_overhead: int = 300,+ min_relevance_score: float = 0.0,+ max_workers: int = 4,+ timeout: float = 60.0,+ auto_promote_level: bool = True,+ **kwargs: Any,+ ) -> None:+ self.logger = get_logger("global_retriever")+ self.hierarchy = hierarchy+ self.llm = llm+ self.embedder = embedder+ self.token_counter = token_counter+ self.max_context_tokens = max(1, int(max_context_tokens))+ self.response_token_budget = max(10, int(response_token_budget))+ self.fixed_overhead = max(0, int(fixed_overhead))+ self.min_relevance_score = max(0.0, min(10.0, float(min_relevance_score)))+ self.max_workers = max(1, int(max_workers))+ self.timeout = max(0.001, float(timeout))+ self.auto_promote_level = bool(auto_promote_level)+ self.config = kwargs++ self._reports: List[CommunityReport] = []+ if reports is not None:+ self.set_reports(reports)++ def set_reports(+ self,+ reports: Union[+ Sequence[Union[CommunityReport, Dict[str, Any]]],+ Dict[str, Any],+ ],+ ) -> None:+ """Update active community reports collection."""+ loaded: List[CommunityReport] = []+ if isinstance(reports, dict):+ # Check if dict is {community_id: report} or single report dict+ if "community_id" in reports and "summary" in reports:+ loaded.append(CommunityReport.from_dict(reports))+ else:+ for rep in reports.values():+ if isinstance(rep, CommunityReport):+ loaded.append(rep)+ elif isinstance(rep, dict):+ loaded.append(CommunityReport.from_dict(rep))+ elif isinstance(reports, Iterable) and not isinstance(reports, (str, bytes)):+ for rep in reports:+ if isinstance(rep, CommunityReport):+ loaded.append(rep)+ elif isinstance(rep, dict):+ loaded.append(CommunityReport.from_dict(rep))++ self._reports = loaded++ def _estimate_report_tokens(self, report: CommunityReport) -> int:+ """Estimate token cost of a single community report."""+ findings_parts = []+ for f in report.findings:+ if isinstance(f, dict):+ s = str(f.get("summary") or "")+ e = str(f.get("explanation") or "")+ part = f"{s} {e}".strip()+ if part:+ findings_parts.append(part)+ elif f is not None:+ findings_parts.append(str(f))+ findings_str = " ".join(findings_parts)+ full_text = f"{report.title or ''}\n{report.summary or ''}\n{findings_str}"+ return estimate_tokens(full_text, self.token_counter)++ def _group_reports_by_level(self) -> Dict[int, List[CommunityReport]]:+ """Group active reports by coarsening hierarchy level."""+ grouped: Dict[int, List[CommunityReport]] = {}+ for r in self._reports:+ grouped.setdefault(r.level, []).append(r)+ return grouped++ def select_level_and_budget(+ self,+ query: str,+ target_level: Optional[int] = None,+ query_embedding: Optional[List[float]] = None,+ auto_promote_level: Optional[bool] = None,+ ) -> tuple[int, List[CommunityReport]]:+ """+ Dynamically select hierarchy level and apply token-budgeted pruning.++ Promotes to coarser level L+1 if total tokens at level L exceed budget+ and auto_promote_level is True. If promotion is exhausted or disabled,+ prunes low-relevance reports at the selected level.+ """+ grouped = self._group_reports_by_level()+ if not grouped:+ return (0, [])++ available_levels = sorted(grouped.keys())++ if target_level is not None and target_level in grouped:+ current_level = target_level+ else:+ current_level = available_levels[0]++ effective_auto_promote = (+ self.auto_promote_level+ if auto_promote_level is None+ else bool(auto_promote_level)+ )++ # Dynamic level promotion+ if effective_auto_promote:+ while current_level < available_levels[-1]:+ candidates = grouped.get(current_level, [])+ total_tokens = sum(+ self._estimate_report_tokens(r) for r in candidates+ )+ if total_tokens <= self.max_context_tokens:+ break+ # Promote to next available level+ higher_levels = [lvl for lvl in available_levels if lvl > current_level]+ if not higher_levels:+ break+ current_level = higher_levels[0]++ candidates = grouped.get(current_level, [])+ total_tokens = sum(self._estimate_report_tokens(r) for r in candidates)++ if total_tokens <= self.max_context_tokens:+ return (current_level, candidates)++ # Budget exceeded: prune candidate reports at current_level+ if query_embedding is None and self.embedder is not None:+ try:+ query_embedding = self.embedder(query)+ except Exception as e:+ self.logger.warning(f"Query embedding generation failed: {e}")++ scored_candidates: List[tuple[float, CommunityReport]] = []+ query_words = _extract_words(query)++ for rep in candidates:+ score = 0.0+ if (+ query_embedding is not None+ and rep.embedding is not None+ and len(rep.embedding) == len(query_embedding)+ ):+ score = _cosine_similarity(query_embedding, rep.embedding)+ else:+ findings_gen = (+ str(f.get("summary", ""))+ for f in rep.findings+ if isinstance(f, dict)+ )+ rep_text = f"{rep.title} {rep.summary} " + " ".join(findings_gen)+ rep_words = _extract_words(rep_text)+ if query_words and rep_words:+ intersection = len(query_words & rep_words)+ union = len(query_words | rep_words)+ jaccard = intersection / float(union) if union > 0 else 0.0+ else:+ jaccard = 0.0++ norm_rank = max(0.0, min(1.0, rep.rank))+ norm_impact = max(0.0, min(1.0, (rep.impact_rating - 1.0) / 9.0))+ score = (jaccard * 0.5) + (norm_rank * 0.3) + (norm_impact * 0.2)++ scored_candidates.append((score, rep))++ # Sort descending by score, tie-break by impact_rating and community_id+ scored_candidates.sort(+ key=lambda item: (-item[0], -item[1].impact_rating, item[1].community_id)+ )++ retained: List[CommunityReport] = []+ accumulated_tokens = 0+ for _, rep in scored_candidates:+ cost = self._estimate_report_tokens(rep)+ if accumulated_tokens + cost <= self.max_context_tokens:+ retained.append(rep)+ accumulated_tokens += cost+ else:+ continue++ return (current_level, retained)++ def _extract_json(self, text: str) -> Union[Dict[str, Any], List[Any]]:+ """Extract and parse JSON from LLM response."""+ cleaned = text.strip()+ try:+ val = json.loads(cleaned)+ if isinstance(val, (dict, list)):+ return val+ except Exception:+ pass++ match = re.search(r"```(?:json)?\s*([\s\S]*?)\s*```", cleaned, re.DOTALL)+ if match:+ block = match.group(1).strip()+ try:+ val = json.loads(block)+ if isinstance(val, (dict, list)):+ return val+ except Exception:+ pass++ decoder = json.JSONDecoder()+ for i in range(len(cleaned)):+ if cleaned[i] in ("{", "["):+ try:+ obj, _ = decoder.raw_decode(cleaned[i:])+ if isinstance(obj, (dict, list)):+ return obj+ except Exception:+ pass++ raise ValueError(f"No valid JSON found in LLM output: {cleaned[:100]}...")++ def _coerce_map_response(+ self, res: Any, report: CommunityReport+ ) -> Optional[MapResponseSchema]:+ """Coerce raw LLM output to MapResponseSchema."""+ if isinstance(res, MapResponseSchema):+ return res+ if isinstance(res, list):+ return MapResponseSchema(points=res)+ if isinstance(res, dict):+ if "points" not in res and any(+ k in res+ for k in ("point", "finding", "summary", "title", "claim")+ ):+ return MapResponseSchema(points=[res])+ return MapResponseSchema.model_validate(res)+ if hasattr(res, "model_dump") and callable(res.model_dump):+ return MapResponseSchema.model_validate(res.model_dump())+ if hasattr(res, "__dict__"):+ try:+ return MapResponseSchema.model_validate(vars(res))+ except Exception:+ pass+ if isinstance(res, str):+ try:+ parsed = self._extract_json(res)+ if isinstance(parsed, list):+ return MapResponseSchema(points=parsed)+ elif isinstance(parsed, dict):+ if "points" not in parsed and any(+ k in parsed+ for k in ("point", "finding", "summary", "title", "claim")+ ):+ return MapResponseSchema(points=[parsed])+ return MapResponseSchema.model_validate(parsed)+ except Exception:+ # Freeform text fallback: treat as single point+ cleaned = res.strip()+ if cleaned:+ return MapResponseSchema(+ points=[+ MapPointSchema(+ point=f"Finding from Community {report.community_id}",+ description=cleaned[:300],+ relevance_score=5.0,+ entities=list(report.member_entities[:5]),+ )+ ],+ relevance_explanation="Extracted from freeform LLM response.",+ )+ return None++ def _extractive_map_fallback(+ self, report: CommunityReport, query: str+ ) -> MapResponseSchema:+ """Deterministic keyword-based extractive fallback for Map phase."""+ query_words = _extract_words(query)+ points: List[MapPointSchema] = []++ rep_text = f"{report.title} {report.summary}"+ rep_words = _extract_words(rep_text)+ overlap = len(query_words & rep_words) if query_words else 0+ base_score = 5.0 + min(5.0, overlap * 1.5) if query_words else 5.0++ if report.summary:+ points.append(+ MapPointSchema(+ point=report.title or f"Community {report.community_id} Overview",+ description=report.summary,+ relevance_score=base_score,+ entities=list(report.member_entities[:5]),+ )+ )++ for finding in report.findings:+ if isinstance(finding, dict):+ f_summary = str(+ finding.get("summary")+ if finding.get("summary") is not None+ else (+ finding.get("title")+ if finding.get("title") is not None+ else (+ finding.get("finding")+ if finding.get("finding") is not None+ else ""+ )+ )+ ).strip()+ f_expl = str(+ finding.get("explanation")+ if finding.get("explanation") is not None+ else (+ finding.get("description")+ if finding.get("description") is not None+ else ""+ )+ ).strip()+ f_words = _extract_words(f"{f_summary} {f_expl}")+ f_overlap = len(query_words & f_words) if query_words else 0+ f_score = (+ max(1.0, min(10.0, 4.0 + f_overlap * 2.0))+ if query_words+ else 5.0+ )++ points.append(+ MapPointSchema(+ point=f_summary or "Community Finding",+ description=f_expl,+ relevance_score=f_score,+ entities=list(report.member_entities[:3]),+ )+ )++ if not points:+ members_preview = ", ".join(report.member_entities[:5])+ points.append(+ MapPointSchema(+ point=f"Community {report.community_id} Data",+ description=f"Contains entities: {members_preview}",+ relevance_score=5.0,+ entities=list(report.member_entities[:5]),+ )+ )++ return MapResponseSchema(+ points=points,+ relevance_explanation="Generated via extractive keyword fallback.",+ )++ def _call_map_llm(+ self, prompt: str, report: CommunityReport, query: str = "", **kwargs: Any+ ) -> MapResponseSchema:+ """Execute 6-tier LLM unwrap for Map phase evaluation."""+ llm = kwargs.get("llm") or self.llm+ fallback_query = query if query else prompt+ if llm is None:+ return self._extractive_map_fallback(report, fallback_query)++ # Tier 1: llm.generate_typed+ if hasattr(llm, "generate_typed") and callable(llm.generate_typed):+ try:+ try:+ res = llm.generate_typed(+ prompt, schema=MapResponseSchema, **kwargs+ )+ except TypeError:+ res = llm.generate_typed(prompt, schema=MapResponseSchema)+ schema = self._coerce_map_response(res, report)+ if schema is not None:+ return schema+ except Exception as e:+ self.logger.warning(f"Tier 1 generate_typed failed: {e}")++ # Tier 2: llm.provider.generate_typed+ if (+ hasattr(llm, "provider")+ and hasattr(llm.provider, "generate_typed")+ and callable(llm.provider.generate_typed)+ ):+ try:+ try:+ res = llm.provider.generate_typed(+ prompt, schema=MapResponseSchema, **kwargs+ )+ except TypeError:+ res = llm.provider.generate_typed(+ prompt, schema=MapResponseSchema+ )+ schema = self._coerce_map_response(res, report)+ if schema is not None:+ return schema+ except Exception as e:+ self.logger.warning(f"Tier 2 provider.generate_typed failed: {e}")++ # Tier 3: llm.generate_structured+ if hasattr(llm, "generate_structured") and callable(+ llm.generate_structured+ ):+ try:+ try:+ res = llm.generate_structured(prompt, **kwargs)+ except TypeError:+ res = llm.generate_structured(prompt)+ schema = self._coerce_map_response(res, report)+ if schema is not None:+ return schema+ except Exception as e:+ self.logger.warning(f"Tier 3 generate_structured failed: {e}")++ # Tier 4: llm.generate + JSON regex+ if hasattr(llm, "generate") and callable(llm.generate):+ try:+ try:+ text_res = llm.generate(prompt, **kwargs)+ except TypeError:+ text_res = llm.generate(prompt)+ schema = self._coerce_map_response(text_res, report)+ if schema is not None:+ return schema+ except Exception as e:+ self.logger.warning(f"Tier 4 generate failed: {e}")++ # Tier 5: callable(llm)+ if callable(llm):+ try:+ try:+ res = llm(prompt, **kwargs)+ except TypeError:+ res = llm(prompt)+ schema = self._coerce_map_response(res, report)+ if schema is not None:+ return schema+ except Exception as e:+ self.logger.warning(f"Tier 5 callable failed: {e}")++ # Tier 6: Extractive keyword fallback+ self.logger.warning("All LLM tiers failed; using extractive Map fallback.")+ return self._extractive_map_fallback(report, fallback_query)++ def _map_report(+ self, report: CommunityReport, query: str+ ) -> List[MapKeyPoint]:+ """Execute Map task for a single community report."""+ findings_bullets = []+ for f in report.findings:+ if isinstance(f, dict):+ s = str(f.get("summary") or "").strip()+ e = str(f.get("explanation") or "").strip()+ if s and e:+ findings_bullets.append(f"- {s}: {e}")+ elif s:+ findings_bullets.append(f"- {s}")+ elif e:+ findings_bullets.append(f"- {e}")+ elif f is not None:+ findings_bullets.append(f"- {str(f).strip()}")+ findings_text = "\n".join(findings_bullets) if findings_bullets else "None"++ entities_preview = ", ".join(report.member_entities[:10])++ prompt = (+ "You are evaluating a knowledge graph community report for the "+ f"following user query.\nQuery: {query}\n\n"+ f"Community ID: {report.community_id} (Level {report.level})\n"+ f"Community Title: {report.title}\n"+ f"Summary: {report.summary}\n"+ f"Entities: {entities_preview}\n"+ f"Key Findings:\n{findings_text}\n\n"+ "Instructions:\n"+ "1. Extract key points relevant to the query from this report.\n"+ "2. For each point, assign a relevance_score between 0.0 and 10.0.\n"+ "3. Return response in JSON with 'points' (list of {'point', "+ "'description', 'relevance_score', 'entities'}) and "+ "'relevance_explanation'."+ )++ response_schema = self._call_map_llm(prompt, report, query=query)++ key_points: List[MapKeyPoint] = []+ for p in response_schema.points:+ ents = p.entities if p.entities else list(report.member_entities[:5])+ key_points.append(+ MapKeyPoint(+ point=p.point,+ description=p.description,+ relevance_score=p.relevance_score,+ community_id=report.community_id,+ level=report.level,+ entities=ents,+ metadata={"source_title": report.title},+ )+ )++ return key_points++ def _execute_parallel_map(+ self, reports: List[CommunityReport], query: str+ ) -> List[MapKeyPoint]:+ """Execute Map phase concurrently across reports with worker error isolation."""+ if not reports:+ return []++ all_points: List[MapKeyPoint] = []+ num_workers = min(self.max_workers, len(reports))+ completed_futures: Set[concurrent.futures.Future] = set()++ executor = concurrent.futures.ThreadPoolExecutor(max_workers=num_workers)+ try:+ future_to_report = {+ executor.submit(self._map_report, rep, query): rep+ for rep in reports+ }++ try:+ for future in concurrent.futures.as_completed(+ future_to_report, timeout=self.timeout+ ):+ completed_futures.add(future)+ rep = future_to_report[future]+ try:+ points = future.result()+ all_points.extend(points)+ except Exception as exc:+ self.logger.warning(+ f"Map worker failed for {rep.community_id}: {exc}; "+ "falling back to extractive."+ )+ fallback_schema = self._extractive_map_fallback(rep, query)+ for p in fallback_schema.points:+ all_points.append(+ MapKeyPoint(+ point=p.point,+ description=p.description,+ relevance_score=p.relevance_score,+ community_id=rep.community_id,+ level=rep.level,+ entities=(+ p.entities or list(rep.member_entities[:5])+ ),+ metadata={"source_title": rep.title},+ )+ )+ except concurrent.futures.TimeoutError:+ self.logger.warning(+ f"Map phase reached timeout ({self.timeout}s); falling back to "+ "extractive points for unfinished reports."+ )+ for f in future_to_report:+ f.cancel()+ try:+ executor.shutdown(wait=False, cancel_futures=True)+ except TypeError:+ executor.shutdown(wait=False)++ for future, rep in future_to_report.items():+ if future not in completed_futures:+ fallback_schema = self._extractive_map_fallback(rep, query)+ for p in fallback_schema.points:+ all_points.append(+ MapKeyPoint(+ point=p.point,+ description=p.description,+ relevance_score=p.relevance_score,+ community_id=rep.community_id,+ level=rep.level,+ entities=(+ p.entities or list(rep.member_entities[:5])+ ),+ metadata={"source_title": rep.title},+ )+ )+ finally:+ try:+ executor.shutdown(wait=False, cancel_futures=True)+ except TypeError:+ executor.shutdown(wait=False)++ return all_points++ def _pack_reduce_context(+ self, key_points: List[MapKeyPoint], budget: int+ ) -> tuple[str, List[MapKeyPoint]]:+ """Pack sorted key points into Reduce prompt within token budget."""+ packed_lines: List[str] = []+ retained_points: List[MapKeyPoint] = []+ tokens_used = 0++ for kp in key_points:+ ents_str = f" ({', '.join(kp.entities[:3])})" if kp.entities else ""+ line = (+ f"- [Community {kp.community_id}]{ents_str}: {kp.point}. "+ f"{kp.description} (relevance: {kp.relevance_score:.1f}/10)\n"+ )+ cost = estimate_tokens(line, self.token_counter)+ if tokens_used + cost <= budget:+ packed_lines.append(line)+ retained_points.append(kp)+ tokens_used += cost+ else:+ continue++ return ("".join(packed_lines), retained_points)++ def _ensure_evidence_citations(+ self, response_text: str, key_points: List[MapKeyPoint]+ ) -> str:+ """Validate and append missing community and member-entity citations."""+ if not key_points:+ return response_text++ grouped_by_comm: Dict[str, List[MapKeyPoint]] = {}+ for kp in key_points:+ cid = str(kp.community_id).strip() if kp.community_id is not None else ""+ if cid and cid != "None":+ grouped_by_comm.setdefault(cid, []).append(kp)++ missing_entries: List[str] = []+ for comm_id, pts in grouped_by_comm.items():+ has_comm_citation = bool(+ re.search(+ rf"\[Community\s+{re.escape(comm_id)}\]",+ response_text,+ re.IGNORECASE,+ )+ )+ comm_ents: List[str] = []+ for p in pts:+ for e in (p.entities or []):+ if e and e not in comm_ents:+ comm_ents.append(e)++ has_entity_mention = bool(+ not comm_ents+ or any(+ bool(+ re.search(+ rf"\b{re.escape(e)}\b", response_text, re.IGNORECASE+ )+ )+ for e in comm_ents+ )+ )++ if not has_comm_citation or not has_entity_mention:+ ents_label = (+ f" (Entities: {', '.join(comm_ents)})" if comm_ents else ""+ )+ pts_summary = (+ "; ".join(p.point for p in pts if p.point)+ or "; ".join(p.description for p in pts if p.description)+ or "Supporting findings"+ )+ missing_entries.append(+ f"- [Community {comm_id}]{ents_label}: {pts_summary}"+ )++ if not missing_entries:+ return response_text++ to_append = [e for e in missing_entries if e not in response_text]+ if not to_append:+ return response_text++ prefix = f"{response_text.rstrip()}\n\n" if response_text.strip() else ""+ if "Sources / Evidence:" in response_text:+ return f"{response_text.rstrip()}\n" + "\n".join(to_append)+ return prefix + "Sources / Evidence:\n" + "\n".join(to_append)++ def _synthesize_reduce(+ self, query: str, context_text: str, key_points: List[MapKeyPoint]+ ) -> str:+ """Synthesize final executive answer from packed key points."""+ llm = self.llm+ if llm is None:+ # Deterministic synthesis fallback+ grouped_by_comm: Dict[str, List[tuple[str, List[str]]]] = {}+ for kp in key_points:+ cid = (+ str(kp.community_id).strip()+ if kp.community_id is not None+ else ""+ )+ if not cid or cid == "None":+ cid = "Unknown"+ grouped_by_comm.setdefault(cid, []).append(+ (+ f"{kp.point}: {kp.description}".strip(": "),+ kp.entities or [],+ )+ )++ lines = [f"Executive Synthesis for query: '{query}'\n"]+ for comm_id, pts_with_ents in grouped_by_comm.items():+ all_ents: List[str] = []+ for _, ents in pts_with_ents:+ for e in ents:+ if e and e not in all_ents:+ all_ents.append(e)+ ents_hdr = f" (Entities: {', '.join(all_ents)})" if all_ents else ""+ lines.append(f"From [Community {comm_id}]{ents_hdr}:")+ for pt, ents in pts_with_ents:+ ents_str = (+ f" (Entities: {', '.join(ents)})" if ents else ""+ )+ lines.append(f" • {pt}{ents_str}")+ raw_response = "\n".join(lines)+ return self._ensure_evidence_citations(raw_response, key_points)++ prompt = (+ "You are an executive knowledge analyst synthesizing global findings.\n\n"+ f"Query: {query}\n\n"+ f"Key Points from Community Reports:\n{context_text}\n\n"+ "Instructions:\n"+ "1. Synthesize a comprehensive, executive-level answer that directly "+ "answers the query.\n"+ "2. You MUST cite each source community using [Community <id>] whenever "+ "making assertions.\n"+ "3. You MUST cite key member entities (Entities: <entity1>, <entity2>) "+ "in parentheses alongside the community citations.\n"+ "4. Provide a coherent, well-structured response."+ )++ try:+ if hasattr(llm, "generate") and callable(llm.generate):+ res = llm.generate(prompt)+ elif callable(llm):+ res = llm(prompt)+ else:+ raise TypeError(f"Unsupported LLM type: {type(llm)}")+ if isinstance(res, dict):+ raw_text = str(+ res.get("text")+ or res.get("response")+ or res.get("content")+ or json.dumps(res)+ )+ else:+ raw_text = str(res).strip()+ return self._ensure_evidence_citations(raw_text, key_points)+ except Exception as e:+ self.logger.warning(f"Reduce LLM synthesis failed: {e}")+ # Deterministic fallback+ grouped_by_comm_err: Dict[str, List[tuple[str, List[str]]]] = {}+ for kp in key_points:+ cid = (+ str(kp.community_id).strip()+ if kp.community_id is not None+ else ""+ )+ if not cid or cid == "None":+ cid = "Unknown"+ grouped_by_comm_err.setdefault(cid, []).append(+ (+ f"{kp.point}: {kp.description}".strip(": "),+ kp.entities or [],+ )+ )+ lines = [+ f"Global synthesis for '{query}' based on community findings:\n"+ ]+ for comm_id, pts_with_ents in grouped_by_comm_err.items():+ all_ents_err: List[str] = []+ for _, ents in pts_with_ents:+ for e in ents:+ if e and e not in all_ents_err:+ all_ents_err.append(e)+ ents_hdr = (+ f" (Entities: {', '.join(all_ents_err)})" if all_ents_err else ""+ )+ lines.append(f"From [Community {comm_id}]{ents_hdr}:")+ for pt, ents in pts_with_ents:+ ents_str = (+ f" (Entities: {', '.join(ents)})" if ents else ""+ )+ lines.append(f" • {pt}{ents_str}")+ fallback_text = "\n".join(lines)+ return self._ensure_evidence_citations(fallback_text, key_points)++ def search(+ self,+ query: str,+ level: Optional[int] = None,+ query_embedding: Optional[List[float]] = None,+ min_relevance_score: Optional[float] = None,+ **kwargs: Any,+ ) -> GlobalSearchResult:+ """+ Execute Map-Reduce global search across community reports.++ Args:+ query: Natural language query.+ level: Target hierarchy level (coarsening level).+ query_embedding: Optional precomputed embedding for the query.+ min_relevance_score: Minimum relevance threshold for key points.+ **kwargs: Additional runtime options.++ Returns:+ GlobalSearchResult containing response, key points, citations, and metrics.+ """+ start_time = time.time()+ effective_min_relevance = (+ self.min_relevance_score+ if min_relevance_score is None+ else max(0.0, min(10.0, float(min_relevance_score)))+ )++ # Level selection and report budgeting+ selected_level, candidate_reports = self.select_level_and_budget(+ query,+ target_level=level,+ query_embedding=query_embedding,+ auto_promote_level=kwargs.get("auto_promote_level"),+ )++ if not candidate_reports:+ return GlobalSearchResult(+ query=query,+ response="No community reports available for global search.",+ level=selected_level,+ key_points=[],+ community_reports_used=[],+ citations=[],+ metrics={+ "time_taken": time.time() - start_time,+ "level_used": selected_level,+ "reports_evaluated": 0,+ "reports_mapped": 0,+ "key_points_generated": 0,+ "key_points_retained": 0,+ "citations_count": 0,+ },+ )++ # Parallel Map Phase+ raw_key_points = self._execute_parallel_map(candidate_reports, query)++ # Filter key points by relevance cutoff+ filtered_points = [+ p for p in raw_key_points if p.relevance_score >= effective_min_relevance+ ]++ # Sort descending by relevance score, tie-break by community_id and point text+ filtered_points.sort(+ key=lambda p: (-p.relevance_score, str(p.community_id), str(p.point))+ )++ # Reduce phase token budget+ remaining_budget = (+ self.max_context_tokens+ - self.fixed_overhead+ - self.response_token_budget+ )+ if remaining_budget <= 0:+ duration = time.time() - start_time+ return GlobalSearchResult(+ query=query,+ response="No sufficiently relevant community findings were available.",+ level=selected_level,+ key_points=[],+ community_reports_used=[],+ citations=[],+ metrics={+ "time_taken": duration,+ "level_used": selected_level,+ "reports_evaluated": len(candidate_reports),+ "reports_mapped": len(candidate_reports),+ "key_points_generated": len(raw_key_points),+ "key_points_retained": 0,+ "citations_count": 0,+ },+ )++ reduce_budget = remaining_budget++ packed_context, retained_points = self._pack_reduce_context(+ filtered_points, reduce_budget+ )++ if not retained_points:+ duration = time.time() - start_time+ return GlobalSearchResult(+ query=query,+ response="No sufficiently relevant community findings were available.",+ level=selected_level,+ key_points=[],+ community_reports_used=[],+ citations=[],+ metrics={+ "time_taken": duration,+ "level_used": selected_level,+ "reports_evaluated": len(candidate_reports),+ "reports_mapped": len(candidate_reports),+ "key_points_generated": len(raw_key_points),+ "key_points_retained": 0,+ "citations_count": 0,+ },+ )++ # Executive Reduce synthesis+ response_text = self._synthesize_reduce(query, packed_context, retained_points)++ # Extract citations+ raw_citations = re.findall(+ r"\[Community\s+([A-Za-z0-9_\-]+)\]", response_text, re.IGNORECASE+ )+ valid_ids = {+ str(kp.community_id)+ for kp in retained_points+ if kp.community_id is not None and str(kp.community_id).strip()+ }+ citations = sorted(set(str(c) for c in raw_citations if str(c) in valid_ids))+ if not citations and valid_ids:+ citations = sorted(valid_ids)++ reports_used = sorted(set(r.community_id for r in candidate_reports))++ duration = time.time() - start_time+ metrics = {+ "time_taken": duration,+ "level_used": selected_level,+ "reports_evaluated": len(candidate_reports),+ "reports_mapped": len(candidate_reports),+ "key_points_generated": len(raw_key_points),+ "key_points_retained": len(retained_points),+ "citations_count": len(citations),+ }++ return GlobalSearchResult(+ query=query,+ response=response_text,+ level=selected_level,+ key_points=retained_points,+ community_reports_used=reports_used,+ citations=citations,+ metrics=metrics,+ )diff --git a/semantica/context/methods.py b/semantica/context/methods.pynew file mode 100644index 00000000..cca0d1af--- /dev/null+++ b/semantica/context/methods.py@@ -0,0 +1,196 @@+"""+Context Retrieval and Search Methods.++Provides high-level functional APIs for global Map-Reduce retrieval, DRIFT+hybrid search, and unified context retrieval, with registration into the+context method registry.+"""++from typing import Any, List, Optional, Union++from ..kg.community_hierarchy import CommunityHierarchy+from ..kg.community_summarizer import CommunityReport+from ..utils.logging import get_logger+from .context_retriever import ContextRetriever, RetrievedContext+from .drift_search import DriftSearchEngine, DriftSearchResult+from .global_retriever import GlobalGraphRetriever, GlobalSearchResult+from .registry import method_registry++logger = get_logger("context_methods")+++def retrieve_global(+ query: str,+ reports: Optional[+ Union[+ List[Union[CommunityReport, dict]],+ dict,+ ]+ ] = None,+ hierarchy: Optional[CommunityHierarchy] = None,+ llm: Optional[Any] = None,+ level: Optional[int] = None,+ max_context_tokens: int = 4000,+ min_relevance_score: float = 0.0,+ **kwargs: Any,+) -> GlobalSearchResult:+ """+ Execute global hierarchical GraphRAG retrieval over community reports.++ Args:+ query: Natural language query string.+ reports: Community reports collection or mapping.+ hierarchy: Optional hierarchical community structure.+ llm: LLM client or callable for Map and Reduce phases.+ level: Coarsening level to query.+ max_context_tokens: Maximum token budget.+ min_relevance_score: Minimum relevance threshold (0.0 - 10.0).+ **kwargs: Additional options for GlobalGraphRetriever.++ Returns:+ GlobalSearchResult with synthesized answer, key points, and citations.+ """+ retriever = GlobalGraphRetriever(+ reports=reports,+ hierarchy=hierarchy,+ llm=llm,+ max_context_tokens=max_context_tokens,+ min_relevance_score=min_relevance_score,+ **kwargs,+ )+ return retriever.search(+ query,+ level=level,+ min_relevance_score=min_relevance_score,+ **kwargs,+ )+++def retrieve_drift(+ query: str,+ knowledge_graph: Optional[Any] = None,+ reports: Optional[+ Union[+ List[Union[CommunityReport, dict]],+ dict,+ ]+ ] = None,+ hierarchy: Optional[CommunityHierarchy] = None,+ llm: Optional[Any] = None,+ max_depth: int = 2,+ drift_threshold: float = 0.35,+ **kwargs: Any,+) -> DriftSearchResult:+ """+ Execute DRIFT hybrid search combining global framing and local graph exploration.++ Args:+ query: Natural language search query.+ knowledge_graph: Knowledge graph store or dictionary.+ reports: Community reports collection or mapping.+ hierarchy: Optional hierarchical community structure.+ llm: LLM client or callable for reasoning and synthesis.+ max_depth: Entity traversal depth limit.+ drift_threshold: Minimum alignment score for pruning graph drift.+ **kwargs: Additional options for DriftSearchEngine.++ Returns:+ DriftSearchResult with answer, verified contexts, citations, and metrics.+ """+ engine = DriftSearchEngine(+ knowledge_graph=knowledge_graph,+ reports=reports,+ hierarchy=hierarchy,+ llm=llm,+ max_depth=max_depth,+ drift_threshold=drift_threshold,+ **kwargs,+ )+ return engine.search(+ query,+ max_depth=max_depth,+ drift_threshold=drift_threshold,+ **kwargs,+ )+++def retrieve_context(+ query: str,+ retriever: Optional[ContextRetriever] = None,+ mode: str = "local",+ max_results: int = 5,+ **kwargs: Any,+) -> List[RetrievedContext]:+ """+ Unified context retrieval supporting local, global, drift, and hybrid modes.++ Args:+ query: Search query string.+ retriever: ContextRetriever instance (created if not provided).+ mode: Retrieval mode ('local', 'global', 'drift', 'hybrid').+ max_results: Maximum number of contexts to return.+ **kwargs: Additional options passed to retriever.++ Returns:+ List of RetrievedContext objects.+ """+ if retriever is None:+ retriever = ContextRetriever(**kwargs)+ return retriever.retrieve(+ query, max_results=max_results, mode=mode, **kwargs+ )+++# Functional aliases+global_search = retrieve_global+drift_search = retrieve_drift++# Pre-register in semantica.context method registry+method_registry.register(+ "retrieval",+ "global",+ retrieve_global,+ metadata={+ "description": "Global Map-Reduce retrieval across community reports",+ "parameters": ["query", "reports", "hierarchy", "llm", "level"],+ },+ capabilities=["map_reduce", "dynamic_levels", "citations"],+)++method_registry.register(+ "retrieval",+ "drift",+ retrieve_drift,+ metadata={+ "description": "DRIFT hybrid global-local retrieval engine",+ "parameters": ["query", "knowledge_graph", "reports", "llm"],+ },+ capabilities=["directed_reasoning", "drift_pruning", "dual_attribution"],+)++method_registry.register(+ "retrieval",+ "context",+ retrieve_context,+ metadata={+ "description": "Unified context retriever dispatcher",+ "parameters": ["query", "retriever", "mode", "max_results"],+ },+ capabilities=["multi_mode", "hybrid", "ranking"],+)++method_registry.register(+ "global_retrieval",+ "default",+ retrieve_global,+ metadata={"description": "Default global GraphRAG retrieval"},+ capabilities=["map_reduce", "level_promotion"],+)++method_registry.register(+ "drift_search",+ "default",+ retrieve_drift,+ metadata={"description": "Default DRIFT hybrid search"},+ capabilities=["thematic_framing", "iterative_deepening"],+)diff --git a/semantica/context/registry.py b/semantica/context/registry.pynew file mode 100644index 00000000..5895a1c3--- /dev/null+++ b/semantica/context/registry.py@@ -0,0 +1,89 @@+"""+Method Registry Module for Context Engineering.++Provides a method registry system for registering and dispatching custom+retrieval and context engineering methods.+"""++from typing import Any, Callable, Dict, List, Optional+++class MethodRegistry:+ """Registry for custom context retrieval and engineering methods."""++ _methods: Dict[str, Dict[str, Callable]] = {+ "retrieval": {},+ "global_retrieval": {},+ "drift_search": {},+ "context": {},+ }+ _metadata: Dict[str, Dict[str, Dict[str, Any]]] = {+ "retrieval": {},+ "global_retrieval": {},+ "drift_search": {},+ "context": {},+ }+ _capabilities: Dict[str, Dict[str, List[str]]] = {+ "retrieval": {},+ "global_retrieval": {},+ "drift_search": {},+ "context": {},+ }++ @classmethod+ def register(+ cls,+ task: str,+ name: str,+ method_func: Callable,+ metadata: Optional[Dict[str, Any]] = None,+ capabilities: Optional[List[str]] = None,+ ) -> None:+ """Register a custom context method."""+ if task not in cls._methods:+ cls._methods[task] = {}+ cls._metadata[task] = {}+ cls._capabilities[task] = {}+ cls._methods[task][name] = method_func+ cls._metadata[task][name] = metadata or {}+ cls._capabilities[task][name] = capabilities or []++ @classmethod+ def get(cls, task: str, name: str) -> Optional[Callable]:+ """Get method function by task and name."""+ return cls._methods.get(task, {}).get(name)++ @classmethod+ def list_all(cls, task: Optional[str] = None) -> Dict[str, List[str]]:+ """List registered methods, optionally filtered by task."""+ if task is not None:+ return {task: list(cls._methods.get(task, {}).keys())}+ return {t: list(m.keys()) for t, m in cls._methods.items()}++ @classmethod+ def unregister(cls, task: str, name: str) -> bool:+ """Unregister a method by task and name."""+ if task in cls._methods and name in cls._methods[task]:+ del cls._methods[task][name]+ cls._metadata.get(task, {}).pop(name, None)+ cls._capabilities.get(task, {}).pop(name, None)+ return True+ return False++ @classmethod+ def get_metadata(+ cls, task: str, name: str+ ) -> Optional[Dict[str, Any]]:+ """Get metadata for a registered method."""+ return cls._metadata.get(task, {}).get(name)++ @classmethod+ def has_capability(+ cls, task: str, name: str, capability: str+ ) -> bool:+ """Check if a registered method advertises a specific capability."""+ caps = cls._capabilities.get(task, {}).get(name, [])+ return capability in caps+++method_registry = MethodRegistry()diff --git a/semantica/kg/community_summarizer.py b/semantica/kg/community_summarizer.pyindex 2dbfecc7..99928738 100644--- a/semantica/kg/community_summarizer.py+++ b/semantica/kg/community_summarizer.py@@ -260,10 +260,19 @@ class CommunityReport:norm_findings = []for item in self.findings:if isinstance(item, dict):- norm_findings.append(- {str(k): v for k, v in item.items()}- )- else:+ entry = {str(k): v for k, v in item.items()}+ if "summary" in entry:+ entry["summary"] = (+ "" if entry["summary"] is None else str(entry["summary"])+ )+ if "explanation" in entry:+ entry["explanation"] = (+ ""+ if entry["explanation"] is None+ else str(entry["explanation"])+ )+ norm_findings.append(entry)+ elif item is not None:norm_findings.append({"summary": str(item), "explanation": ""})@@ -309,19 +318,22 @@ class CommunityReport:dict(item) if isinstance(item, dict) else itemfor item in data.get("findings", [])]+ level_val = data.get("level")+ impact_val = data.get("impact_rating")+ rank_val = data.get("rank")return cls(community_id=str(data.get("community_id", "")),- level=int(data.get("level", 0)),+ level=int(level_val) if level_val is not None else 0,title=str(data.get("title", "")),summary=str(data.get("summary", "")),findings=findings,- impact_rating=float(data.get("impact_rating", 5.0)),+ impact_rating=float(impact_val) if impact_val is not None else 5.0,rating_explanation=str(data.get("rating_explanation", "")),member_entities=list(data.get("member_entities", [])),content_hash=str(data.get("content_hash", "")),sub_communities=list(data.get("sub_communities", [])),parent_id=parent_id,- rank=float(data.get("rank", 0.0)),+ rank=float(rank_val) if rank_val is not None else 0.0,embedding=embedding,metadata=dict(data.get("metadata", {})),)diff --git a/semantica/kg/methods.py b/semantica/kg/methods.pyindex 4f2a0606..35f36442 100644--- a/semantica/kg/methods.py+++ b/semantica/kg/methods.py@@ -1095,6 +1095,26 @@ method_registry.register(method_registry.register("community_summary", "hierarchy", summarize_hierarchy)+method_registry.register(+ "global_retrieval", "default", lambda *a, **kw: global_search(*a, **kw)+)+method_registry.register(+ "drift_search", "default", lambda *a, **kw: drift_search(*a, **kw)+)+++def global_search(query: str, **kwargs: Any) -> Any:+ """Execute global hierarchical GraphRAG query search."""+ from ..context.methods import retrieve_global++ return retrieve_global(query, **kwargs)+++def drift_search(query: str, **kwargs: Any) -> Any:+ """Execute DRIFT hybrid global-local search."""+ from ..context.methods import retrieve_drift++ return retrieve_drift(query, **kwargs)# Helper functionsdiff --git a/semantica/kg/registry.py b/semantica/kg/registry.pyindex b726b48e..fd3e1fdf 100644--- a/semantica/kg/registry.py+++ b/semantica/kg/registry.py@@ -61,6 +61,8 @@ class MethodRegistry:"temporal": {},"community_hierarchy": {},"community_summary": {},+ "global_retrieval": {},+ "drift_search": {},}@classmethod@@ -189,6 +191,8 @@ class AlgorithmRegistry:"community_detection": {},"community_hierarchy": {},"community_summary": {},+ "global_retrieval": {},+ "drift_search": {},}self._metadata = {}self._capabilities = {}@@ -234,7 +238,7 @@ class AlgorithmRegistry:if capabilities:self._capabilities[(category, name)] = capabilities- def get(self, category: str, name: str) -> Optional[type]:+ def get(self, category: str, name: str = "default") -> Optional[type]:"""Get algorithm class by category and name.@@ -260,9 +264,23 @@ class AlgorithmRegistry:):from .community_summarizer import CommunitySummarizerreturn CommunitySummarizer+ if (+ algo is None and+ category == "global_retrieval" and+ name in ("default", "global", "map_reduce")+ ):+ from ..context.global_retriever import GlobalGraphRetriever+ return GlobalGraphRetriever+ if (+ algo is None and+ category == "drift_search" and+ name in ("default", "drift", "hybrid")+ ):+ from ..context.drift_search import DriftSearchEngine+ return DriftSearchEnginereturn algo- def create_instance(self, category: str, name: str, **kwargs) -> Any:+ def create_instance(self, category: str, name: str = "default", **kwargs) -> Any:"""Create an instance of an algorithm.@@ -277,10 +295,10 @@ class AlgorithmRegistry:Raises:ValueError: If algorithm not found"""- if name not in self._algorithms.get(category, {}):- raise ValueError(f"Algorithm {name} not found in category {category}")algorithm_class = self.get(category, name)if algorithm_class is None:+ if name not in self._algorithms.get(category, {}):+ raise ValueError(f"Algorithm {name} not found in category {category}")raise TypeError(f"Algorithm {name} has no implementation class registered")if category == "community_hierarchy":@@ -611,6 +629,52 @@ class AlgorithmRegistry:],)+ # Global GraphRAG retrieval+ global_meta = {+ "description": "Global Map-Reduce query retrieval over reports",+ "parameters": ["query", "reports", "hierarchy", "llm"],+ "complexity": "O(C)",+ "quality": "High",+ "use_case": "Macro-level executive query answering",+ }+ global_caps = [+ "map_reduce",+ "level_promotion",+ "token_budgeting",+ "citations",+ ]+ for g_name in ("default", "global", "map_reduce"):+ self.register(+ "global_retrieval",+ g_name,+ None,+ metadata=global_meta,+ capabilities=global_caps,+ )++ # DRIFT hybrid search+ drift_meta = {+ "description": "DRIFT hybrid global-local search engine",+ "parameters": ["query", "knowledge_graph", "reports", "llm"],+ "complexity": "O(K + E)",+ "quality": "High",+ "use_case": "Directed reasoning and drift-pruned traversal",+ }+ drift_caps = [+ "thematic_framing",+ "directed_reasoning",+ "drift_pruning",+ "dual_attribution",+ ]+ for d_name in ("default", "drift", "hybrid"):+ self.register(+ "drift_search",+ d_name,+ None,+ metadata=drift_meta,+ capabilities=drift_caps,+ )+# Global algorithm registryalgorithm_registry = AlgorithmRegistry()diff --git a/semantica/utils/constants.py b/semantica/utils/constants.pyindex 05d03b7b..f06020d7 100644--- a/semantica/utils/constants.py+++ b/semantica/utils/constants.py@@ -106,6 +106,22 @@ DEFAULT_CONFIG = {"access_control_enabled": True,"audit_logging_enabled": True,},+ "graphrag": {+ "global_retrieval": {+ "max_context_tokens": 4000,+ "min_relevance_score": 0.0,+ "max_workers": 4,+ "timeout": 60.0,+ "auto_promote_level": True,+ },+ "drift_search": {+ "max_depth": 2,+ "drift_threshold": 0.35,+ "top_k_reports": 3,+ "max_facets": 3,+ "max_context_tokens": 4000,+ },+ },}# Error Codesdiff --git a/tests/cli/__init__.py b/tests/cli/__init__.pynew file mode 100644index 00000000..6bfb427a--- /dev/null+++ b/tests/cli/__init__.py@@ -0,0 +1 @@+"""CLI test package."""diff --git a/tests/cli/test_cli_graphrag.py b/tests/cli/test_cli_graphrag.pynew file mode 100644index 00000000..acddbb8f--- /dev/null+++ b/tests/cli/test_cli_graphrag.py@@ -0,0 +1,193 @@+"""+Tests for GraphRAG CLI commands: 'semantica kg global' and 'semantica kg drift' (PR #3).+"""++import json+from pathlib import Path+import tempfile++from click.testing import CliRunner+import pytest++import semantica.cli as cli_module+++def runner() -> CliRunner:+ return CliRunner()++[email protected](autouse=True)+def silence_logging(monkeypatch):+ monkeypatch.setattr(cli_module, "setup_logging", lambda *a, **kw: None)+++class TestCliGraphRAG:+ """Tests for CLI subcommands kg global and kg drift."""++ def test_kg_global_help(self, runner: CliRunner):+ result = runner.invoke(cli_module.main, ["kg", "global", "--help"])+ assert result.exit_code == 0+ assert "--reports" in result.output+ assert "--hierarchy" in result.output+ assert "--level" in result.output+ assert "--max-tokens" in result.output+ assert "--json" in result.output++ def test_kg_drift_help(self, runner: CliRunner):+ result = runner.invoke(cli_module.main, ["kg", "drift", "--help"])+ assert result.exit_code == 0+ assert "--reports" in result.output+ assert "--graph" in result.output+ assert "--depth" in result.output+ assert "--drift-threshold" in result.output+ assert "--json" in result.output++ def test_kg_global_with_reports_json(self, runner: CliRunner):+ sample_reports = [+ {+ "community_id": "c_cli_1",+ "level": 0,+ "title": "Quantum Physics Research",+ "summary": "Quantum entanglement and superposition findings.",+ "findings": [{"summary": "Entanglement verified"}],+ "member_entities": ["Photon", "Qubit"],+ }+ ]++ with tempfile.TemporaryDirectory() as tmp_dir:+ rep_path = Path(tmp_dir) / "reports.json"+ with open(rep_path, "w", encoding="utf-8") as f:+ json.dump(sample_reports, f)++ result = runner.invoke(+ cli_module.main,+ [+ "kg",+ "global",+ "quantum entanglement",+ "--reports",+ str(rep_path),+ "--json",+ ],+ )++ assert result.exit_code == 0+ payload = json.loads(result.output)+ assert "response" in payload+ assert payload["level"] == 0+ assert "c_cli_1" in payload["community_reports_used"]+ assert len(payload["key_points"]) >= 1++ def test_kg_global_plain_text(self, runner: CliRunner):+ sample_reports = [+ {+ "community_id": "c_cli_2",+ "level": 0,+ "title": "Autonomous Robotics",+ "summary": "Motion planning, SLAM, and LiDAR sensors.",+ "findings": [{"summary": "LiDAR enables 3D mapping"}],+ "member_entities": ["LiDAR", "Robot"],+ }+ ]++ with tempfile.TemporaryDirectory() as tmp_dir:+ rep_path = Path(tmp_dir) / "reports.json"+ with open(rep_path, "w", encoding="utf-8") as f:+ json.dump(sample_reports, f)++ result = runner.invoke(+ cli_module.main,+ ["kg", "global", "robotics motion", "--reports", str(rep_path)],+ )++ assert result.exit_code == 0+ assert "Global Search Results" in result.output+ assert "c_cli_2" in result.output++ def test_kg_drift_with_graph_and_reports_json(self, runner: CliRunner):+ sample_reports = [+ {+ "community_id": "c_drift_cli",+ "level": 0,+ "title": "Graph Algorithms",+ "summary": "Network traversal and PageRank scoring.",+ "findings": [{"summary": "PageRank scores node influence"}],+ "member_entities": ["PageRank", "Graph"],+ }+ ]+ sample_graph = {+ "nodes": [{"id": "Graph"}, {"id": "PageRank"}],+ "edges": [+ {+ "source": "Graph",+ "target": "PageRank",+ "relation": "EVALUATED_BY",+ "description": "Ranking algorithm",+ }+ ],+ }++ with tempfile.TemporaryDirectory() as tmp_dir:+ rep_path = Path(tmp_dir) / "reports.json"+ with open(rep_path, "w", encoding="utf-8") as f:+ json.dump(sample_reports, f)++ graph_path = Path(tmp_dir) / "graph.json"+ with open(graph_path, "w", encoding="utf-8") as f:+ json.dump(sample_graph, f)++ result = runner.invoke(+ cli_module.main,+ [+ "kg",+ "drift",+ "Graph algorithms PageRank",+ "--reports",+ str(rep_path),+ "--graph",+ str(graph_path),+ "--json",+ ],+ )++ assert result.exit_code == 0+ payload = json.loads(result.output)+ assert "answer" in payload+ assert payload["depth_reached"] >= 1+ assert len(payload["verified_local_contexts"]) >= 1++ def test_kg_drift_plain_text(self, runner: CliRunner):+ result = runner.invoke(cli_module.main, ["kg", "drift", "general question"])+ assert result.exit_code == 0+ assert "DRIFT Hybrid Search Results" in result.output++ def test_kg_global_invalid_json_reports(self, runner: CliRunner):+ with tempfile.TemporaryDirectory() as tmp_dir:+ bad_path = Path(tmp_dir) / "corrupt.json"+ bad_path.write_text("{ this is not valid json }", encoding="utf-8")++ result = runner.invoke(+ cli_module.main,+ ["kg", "global", "query", "--reports", str(bad_path)],+ )+ assert result.exit_code != 0++ def test_kg_drift_invalid_json_graph(self, runner: CliRunner):+ with tempfile.TemporaryDirectory() as tmp_dir:+ bad_path = Path(tmp_dir) / "corrupt_graph.json"+ bad_path.write_text("[ invalid json", encoding="utf-8")++ result = runner.invoke(+ cli_module.main,+ ["kg", "drift", "query", "--graph", str(bad_path)],+ )+ assert result.exit_code != 0++ def test_kg_global_without_reports_raises_error(self, runner: CliRunner):+ result = runner.invoke(+ cli_module.main,+ ["kg", "global", "query"],+ )+ assert result.exit_code != 0+ assert "Global retrieval requires --reports" in result.outputdiff --git a/tests/context/test_context_methods.py b/tests/context/test_context_methods.pynew file mode 100644index 00000000..1f62de57--- /dev/null+++ b/tests/context/test_context_methods.py@@ -0,0 +1,133 @@+"""+Tests for functional methods and registries in semantica.context (PR #3).+"""++from semantica.context import (+ DriftSearchResult,+ GlobalSearchResult,+ MethodRegistry,+ drift_search,+ global_search,+ method_registry,+ retrieve_context,+ retrieve_drift,+ retrieve_global,+)+from semantica.context.context_retriever import RetrievedContext+from semantica.kg.community_summarizer import CommunityReport+from semantica.kg.registry import (+ algorithm_registry as kg_alg_registry,+ method_registry as kg_method_registry,+)+++class TestContextMethodsAndRegistry:+ """Tests for context module functional methods and registry dispatch."""++ def _sample_report(self):+ return [+ CommunityReport(+ community_id="c_test",+ level=0,+ title="Testing Community",+ summary="Methods and registry validation summary.",+ )+ ]++ def test_retrieve_global_functional(self):+ res = retrieve_global("test query", reports=self._sample_report())+ assert isinstance(res, GlobalSearchResult)+ assert "c_test" in res.community_reports_used++ # Verify alias+ res_alias = global_search("test query", reports=self._sample_report())+ assert isinstance(res_alias, GlobalSearchResult)++ def test_retrieve_drift_functional(self):+ graph = {+ "nodes": [{"id": "NodeA"}, {"id": "NodeB"}],+ "edges": [{"source": "NodeA", "target": "NodeB", "relation": "TEST_REL"}],+ }+ res = retrieve_drift(+ "NodeA NodeB",+ knowledge_graph=graph,+ reports=self._sample_report(),+ )+ assert isinstance(res, DriftSearchResult)++ # Verify alias+ res_alias = drift_search(+ "NodeA NodeB",+ knowledge_graph=graph,+ reports=self._sample_report(),+ )+ assert isinstance(res_alias, DriftSearchResult)++ def test_retrieve_context_functional(self):+ contexts = retrieve_context(+ "test query",+ community_reports=self._sample_report(),+ mode="global",+ max_results=2,+ )+ assert isinstance(contexts, list)+ assert len(contexts) >= 1+ assert isinstance(contexts[0], RetrievedContext)++ def test_context_method_registry_lifecycle(self):+ reg = MethodRegistry()+ dummy_func = lambda q: f"Result for {q}" # noqa: E731++ reg.register(+ "custom_task",+ "custom_algo",+ dummy_func,+ metadata={"version": "1.0"},+ capabilities=["fast", "accurate"],+ )++ assert reg.get("custom_task", "custom_algo") is dummy_func+ assert reg.has_capability("custom_task", "custom_algo", "fast")+ assert not reg.has_capability("custom_task", "custom_algo", "slow")+ meta = reg.get_metadata("custom_task", "custom_algo")+ assert meta["version"] == "1.0"++ all_methods = reg.list_all("custom_task")+ assert "custom_algo" in all_methods["custom_task"]++ # Unregister+ assert reg.unregister("custom_task", "custom_algo") is True+ assert reg.get("custom_task", "custom_algo") is None+ assert reg.unregister("custom_task", "custom_algo") is False++ def test_pre_registered_methods_in_context_registry(self):+ global_func = method_registry.get("retrieval", "global")+ assert global_func is not None+ assert global_func is retrieve_global++ drift_func = method_registry.get("retrieval", "drift")+ assert drift_func is not None+ assert drift_func is retrieve_drift++ context_func = method_registry.get("retrieval", "context")+ assert context_func is not None+ assert context_func is retrieve_context++ def test_cross_registration_in_kg_registries(self):+ # Verify registered in kg method_registry+ kg_global = kg_method_registry.get("global_retrieval", "default")+ assert kg_global is not None+ res = kg_global("test", reports=self._sample_report())+ assert isinstance(res, GlobalSearchResult)++ kg_drift = kg_method_registry.get("drift_search", "default")+ assert kg_drift is not None++ # Verify registered in kg algorithm_registry+ alg_global = kg_alg_registry.get("global_retrieval", "default")+ assert alg_global is None or callable(alg_global)+ caps = kg_alg_registry.get_capabilities("global_retrieval", "default")+ assert "map_reduce" in caps++ drift_caps = kg_alg_registry.get_capabilities("drift_search", "default")+ assert "directed_reasoning" in drift_capsdiff --git a/tests/context/test_context_retriever_global_drift.py b/tests/context/test_context_retriever_global_drift.pynew file mode 100644index 00000000..c720de9c--- /dev/null+++ b/tests/context/test_context_retriever_global_drift.py@@ -0,0 +1,187 @@+"""+Integration tests for ContextRetriever global, drift, and hybrid modes (PR #3).+"""++from unittest.mock import MagicMock++import pytest++from semantica.context.context_retriever import ContextRetriever, RetrievedContext+from semantica.context.drift_search import DriftSearchResult+from semantica.context.global_retriever import GlobalSearchResult+from semantica.kg.community_summarizer import CommunityReport+++class TestContextRetrieverGlobalDrift:+ """Tests for ContextRetriever mode dispatch and convenience methods."""++ def _sample_reports(self):+ return [+ CommunityReport(+ community_id="c_1",+ level=0,+ title="Distributed Systems",+ summary="Consensus algorithms, Raft, and Paxos.",+ findings=[{"summary": "Raft is leader-based"}],+ member_entities=["Raft", "Paxos", "Leader"],+ )+ ]++ def _sample_graph(self):+ return {+ "nodes": [{"id": "Raft"}, {"id": "Paxos"}],+ "edges": [+ {+ "source": "Raft",+ "target": "Paxos",+ "relation": "EQUIVALENT_CONSENSUS",+ "description": "Both achieve distributed consensus",+ }+ ],+ }++ def test_backward_compatibility_default_local_mode(self):+ # Mock vector store+ mock_vs = MagicMock()+ mock_vs.search.return_value = [+ {"content": "Local vector memory", "score": 0.9, "metadata": {}}+ ]++ retriever = ContextRetriever(vector_store=mock_vs)+ # Calling retrieve without specifying mode defaults to local+ results = retriever.retrieve("distributed systems", max_results=2)+ assert len(results) >= 1+ assert isinstance(results[0], RetrievedContext)+ mock_vs.search.assert_called_once()++ def test_mode_global_delegation(self):+ reports = self._sample_reports()+ retriever = ContextRetriever(community_reports=reports)++ contexts = retriever.retrieve(+ "consensus algorithms",+ mode="global",+ max_results=3,+ )+ assert len(contexts) >= 1+ assert isinstance(contexts[0], RetrievedContext)+ assert contexts[0].source == "global_search"++ def test_mode_drift_delegation(self):+ reports = self._sample_reports()+ graph = self._sample_graph()+ retriever = ContextRetriever(+ community_reports=reports,+ knowledge_graph=graph,+ )++ contexts = retriever.retrieve(+ "Raft consensus",+ mode="drift",+ max_results=3,+ )+ assert len(contexts) >= 1+ assert isinstance(contexts[0], RetrievedContext)+ assert contexts[0].source == "drift_search"++ def test_mode_hybrid_delegation(self):+ mock_vs = MagicMock()+ mock_vs.search.return_value = [+ {"content": "Local vector text", "score": 0.85, "metadata": {}}+ ]+ reports = self._sample_reports()++ retriever = ContextRetriever(+ vector_store=mock_vs,+ community_reports=reports,+ )++ contexts = retriever.retrieve(+ "consensus algorithms",+ mode="hybrid",+ max_results=4,+ )+ assert len(contexts) >= 1+ sources = {c.source for c in contexts}+ assert any("vector" in s or "global" in s for s in sources)++ def test_unsupported_mode_raises_value_error(self):+ retriever = ContextRetriever()+ with pytest.raises(ValueError, match="Unsupported retrieval mode"):+ retriever.retrieve("test query", mode="quantum_teleportation")++ def test_retrieve_global_convenience_method(self):+ reports = self._sample_reports()+ retriever = ContextRetriever(community_reports=reports)++ # Default returns GlobalSearchResult object+ res_obj = retriever.retrieve_global("distributed consensus")+ assert isinstance(res_obj, GlobalSearchResult)+ assert len(res_obj.community_reports_used) >= 1++ # as_contexts=True returns List[RetrievedContext]+ contexts = retriever.retrieve_global(+ "distributed consensus", as_contexts=True, max_results=2+ )+ assert isinstance(contexts, list)+ assert len(contexts) >= 1+ assert isinstance(contexts[0], RetrievedContext)++ def test_retrieve_drift_convenience_method(self):+ reports = self._sample_reports()+ graph = self._sample_graph()+ retriever = ContextRetriever(+ community_reports=reports,+ knowledge_graph=graph,+ )++ # Default returns DriftSearchResult object+ res_obj = retriever.retrieve_drift("Raft Paxos")+ assert isinstance(res_obj, DriftSearchResult)+ assert res_obj.depth_reached >= 1++ # as_contexts=True returns List[RetrievedContext]+ contexts = retriever.retrieve_drift(+ "Raft Paxos", as_contexts=True, max_results=2+ )+ assert isinstance(contexts, list)+ assert len(contexts) >= 1+ assert isinstance(contexts[0], RetrievedContext)++ def test_options_override_init_parameters(self):+ init_reports = self._sample_reports()+ override_report = [+ CommunityReport(+ community_id="c_override",+ level=0,+ title="Override Community",+ summary="Overridden content",+ )+ ]++ retriever = ContextRetriever(community_reports=init_reports)+ res = retriever.retrieve_global(+ "test",+ community_reports=override_report,+ )+ assert "c_override" in res.community_reports_used++ def test_missing_reports_graceful_handling(self):+ retriever = ContextRetriever()+ res = retriever.retrieve_global("anything")+ assert isinstance(res, GlobalSearchResult)+ assert res.key_points == []+ assert "No community reports" in res.response++ def test_options_override_reports_and_graph_alias(self):+ retriever = ContextRetriever()+ reports = self._sample_reports()+ graph = self._sample_graph()++ res_global = retriever.retrieve_global("test", reports=reports)+ assert isinstance(res_global, GlobalSearchResult)+ assert "c_1" in res_global.community_reports_used++ res_drift = retriever.retrieve_drift("test", reports=reports, graph=graph)+ assert isinstance(res_drift, DriftSearchResult)+ assert "c_1" in res_drift.global_reports_useddiff --git a/tests/context/test_drift_search.py b/tests/context/test_drift_search.pynew file mode 100644index 00000000..3ad7b845--- /dev/null+++ b/tests/context/test_drift_search.py@@ -0,0 +1,473 @@+"""+Unit and integration tests for DriftSearchEngine and DRIFT hybrid retrieval (PR #3).+"""++from unittest.mock import MagicMock++from semantica.context.context_retriever import RetrievedContext+from semantica.context.drift_search import (+ DriftFacet,+ DriftFacetSchema,+ DriftFacetsResponseSchema,+ DriftSearchEngine,+ DriftSearchResult,+)+from semantica.kg.community_summarizer import CommunityReport+++class TestDriftDataModels:+ """Tests for DriftFacet, schemas, and DriftSearchResult."""++ def test_drift_facet_init_and_clamping(self):+ facet = DriftFacet(+ sub_query="What are the scaling limits?",+ target_entities=["GPU", "TPU", "GPU"],+ rationale="Compute bottleneck",+ depth=1,+ relevance_score=1.5, # exceeds 1.0+ )+ assert facet.sub_query == "What are the scaling limits?"+ assert facet.relevance_score == 1.0+ assert facet.target_entities == ["GPU", "TPU"]+ assert facet.depth == 1++ # Test negative score clamp+ f_low = DriftFacet(sub_query="q", relevance_score=-0.5)+ assert f_low.relevance_score == 0.0++ def test_drift_facet_to_dict_and_from_dict(self):+ f = DriftFacet(+ sub_query="Query",+ target_entities=["E1"],+ rationale="Rat",+ depth=2,+ relevance_score=0.8,+ )+ d = f.to_dict()+ reconstructed = DriftFacet.from_dict(d)+ assert reconstructed.sub_query == f.sub_query+ assert reconstructed.target_entities == f.target_entities+ assert reconstructed.relevance_score == f.relevance_score++ def test_drift_facet_schemas_validation(self):+ raw = {+ "facets": [+ {+ "sub_query": "Explore transformer architecture",+ "target_entities": ["Attention", "FeedForward"],+ "rationale": "Key mechanisms",+ "score": 0.95,+ },+ "Direct string facet",+ ]+ }+ schema = DriftFacetsResponseSchema.model_validate(raw)+ assert len(schema.facets) == 2+ assert schema.facets[0].sub_query == "Explore transformer architecture"+ assert schema.facets[0].target_entities == ["Attention", "FeedForward"]+ assert schema.facets[0].relevance_score == 0.95+ assert schema.facets[1].sub_query == "Direct string facet"+ assert schema.facets[1].relevance_score == 1.0++ def test_drift_search_result_to_retrieved_contexts(self):+ result = DriftSearchResult(+ query="Deep learning architectures",+ answer=(+ "Answer: [Community c_1] explains that "+ "(Transformer -[USES]-> Attention)."+ ),+ thematic_framing="Macro context",+ global_reports_used=["c_1"],+ verified_local_contexts=[+ {+ "source": "Transformer",+ "target": "Attention",+ "relation": "USES",+ "description": "Mechanism for long-range dependencies",+ "alignment_score": 0.85,+ "depth": 1,+ "attributes": {"weight": 1.0},+ }+ ],+ facets_explored=[+ DriftFacet(sub_query="Check Attention", target_entities=["Attention"])+ ],+ depth_reached=1,+ pruned_fact_count=2,+ citations=["[Community c_1]", "(Transformer -[USES]-> Attention)"],+ metrics={"time_taken": 0.25},+ )++ contexts = result.to_retrieved_contexts()+ assert len(contexts) == 2++ # Primary executive context+ primary = contexts[0]+ assert isinstance(primary, RetrievedContext)+ assert primary.score == 1.0+ assert primary.source == "drift_search"+ assert primary.content == result.answer++ # Verified local context+ fact_ctx = contexts[1]+ assert isinstance(fact_ctx, RetrievedContext)+ assert fact_ctx.score == 0.85+ assert "(Transformer) -[USES]-> (Attention)" in fact_ctx.content+ assert len(fact_ctx.related_entities) == 2+ assert fact_ctx.related_relationships[0]["type"] == "USES"++ def test_drift_search_result_to_and_from_dict(self):+ res = DriftSearchResult(+ query="q",+ answer="a",+ thematic_framing="tf",+ global_reports_used=["c0"],+ verified_local_contexts=[{"source": "A", "target": "B", "relation": "R"}],+ facets_explored=[DriftFacet(sub_query="sub")],+ depth_reached=1,+ pruned_fact_count=1,+ citations=["c0"],+ metrics={"time_taken": 0.1},+ )+ d = res.to_dict()+ reconstructed = DriftSearchResult.from_dict(d)+ assert reconstructed.query == "q"+ assert reconstructed.answer == "a"+ assert len(reconstructed.facets_explored) == 1+ assert len(reconstructed.verified_local_contexts) == 1+++class TestDriftAdjacencyIndex:+ """Tests for in-memory graph index building across representations."""++ def test_dict_graph_nodes_edges(self):+ graph = {+ "nodes": [{"id": "Python"}, {"id": "Guido"}],+ "edges": [+ {+ "source": "Python",+ "target": "Guido",+ "relation": "CREATED_BY",+ "description": "Creator",+ }+ ],+ }+ engine = DriftSearchEngine(knowledge_graph=graph)+ assert "Python" in engine._adjacency_index+ assert "Guido" in engine._adjacency_index+ # Verify outgoing and inverse incoming edges+ py_edges = engine._adjacency_index["Python"]+ assert len(py_edges) >= 1+ assert py_edges[0]["target"] == "Guido"++ def test_dict_graph_entities_relationships(self):+ graph = {+ "entities": [{"name": "AI"}, {"name": "ML"}],+ "relationships": [+ {+ "from": "AI",+ "to": "ML",+ "type": "INCLUDES",+ "desc": "Subfield",+ }+ ],+ }+ engine = DriftSearchEngine(knowledge_graph=graph)+ assert "AI" in engine._adjacency_index+ assert "ML" in engine._adjacency_index+ ai_edges = engine._adjacency_index["AI"]+ assert ai_edges[0]["relation"] == "INCLUDES"++ def test_tuple_and_object_graph(self):+ class MockEdge:+ def __init__(self, src, tgt, rel, desc):+ self.source = src+ self.target = tgt+ self.type = rel+ self.description = desc+ self.attributes = {}++ class MockGraph:+ def __init__(self):+ self.nodes = ["E1", "E2"]+ self.relationships = [MockEdge("E1", "E2", "LINKS", "Edge info")]++ engine = DriftSearchEngine(knowledge_graph=MockGraph())+ assert "E1" in engine._adjacency_index+ assert engine._adjacency_index["E1"][0]["target"] == "E2"+++class TestDriftSearchPipeline:+ """Tests for end-to-end DRIFT search pipeline stages."""++ def _sample_graph(self):+ return {+ "nodes": [+ {"id": "Semantica"},+ {"id": "GraphRAG"},+ {"id": "HierarchicalLeiden"},+ {"id": "UnrelatedCooking"},+ ],+ "edges": [+ {+ "source": "Semantica",+ "target": "GraphRAG",+ "relation": "IMPLEMENTS",+ "description": "High-performance GraphRAG retrieval framework",+ },+ {+ "source": "GraphRAG",+ "target": "HierarchicalLeiden",+ "relation": "USES_COMMUNITIES",+ "description": "Hierarchical multi-level community clustering",+ },+ {+ "source": "Semantica",+ "target": "UnrelatedCooking",+ "relation": "UNRELATED",+ "description": "Baking bread and pastries",+ },+ ],+ }++ def _sample_reports(self):+ return [+ CommunityReport(+ community_id="c_graphrag",+ level=0,+ title="GraphRAG Architecture",+ summary=(+ "Hierarchical knowledge graph retrieval and community detection."+ ),+ findings=[+ {"summary": "Graph retrieval works well for global reasoning"}+ ],+ member_entities=["Semantica", "GraphRAG"],+ )+ ]++ def test_thematic_framing_stage1(self):+ reports = self._sample_reports()+ engine = DriftSearchEngine(reports=reports, top_k_reports=1)+ framing, rep_ids = engine._extract_thematic_framing("GraphRAG retrieval")+ assert "c_graphrag" in rep_ids+ assert "GraphRAG Architecture" in framing++ def test_directed_facet_generation_stage2(self):+ mock_llm = MagicMock()+ mock_llm.generate_typed.return_value = DriftFacetsResponseSchema(+ facets=[+ DriftFacetSchema(+ sub_query="How does GraphRAG use Leiden?",+ target_entities=["GraphRAG"],+ rationale="Community clustering mechanism",+ score=0.9,+ )+ ]+ )++ engine = DriftSearchEngine(+ reports=self._sample_reports(),+ knowledge_graph=self._sample_graph(),+ llm=mock_llm,+ )++ facets = engine._generate_facets("GraphRAG query", "thematic framing")+ assert len(facets) == 1+ assert facets[0].sub_query == "How does GraphRAG use Leiden?"+ assert facets[0].target_entities == ["GraphRAG"]++ def test_extractive_facets_fallback_when_no_llm(self):+ engine = DriftSearchEngine(+ reports=self._sample_reports(),+ knowledge_graph=self._sample_graph(),+ llm=None,+ )+ facets = engine._generate_facets("Semantica GraphRAG", "thematic framing")+ assert len(facets) >= 1+ target_ents = [ent for f in facets for ent in f.target_entities]+ assert "Semantica" in target_ents or "GraphRAG" in target_ents++ def test_semantic_drift_pruning_stage4(self):+ # The query and framing are focused on GraphRAG and Semantica.+ # "UnrelatedCooking" should be pruned because its alignment score is low!+ engine = DriftSearchEngine(+ reports=self._sample_reports(),+ knowledge_graph=self._sample_graph(),+ drift_threshold=0.30,+ max_depth=2,+ llm=None,+ )++ facets = [+ DriftFacet(+ sub_query="Explore Semantica",+ target_entities=["Semantica"],+ )+ ]++ verified, depth, pruned = engine._traverse_and_prune(+ facets, "Semantica GraphRAG knowledge graph", "Hierarchical GraphRAG"+ )++ verified_relations = [f["relation"] for f in verified]+ assert "IMPLEMENTS" in verified_relations+ assert "UNRELATED" not in verified_relations+ assert pruned >= 1++ def test_iterative_deepening_stage5(self):+ # 1-hop starting at Semantica finds GraphRAG.+ # 2-hop starting at Semantica extends through GraphRAG to HierarchicalLeiden.+ engine = DriftSearchEngine(+ reports=self._sample_reports(),+ knowledge_graph=self._sample_graph(),+ drift_threshold=0.10,+ max_depth=2,+ llm=None,+ )++ facets = [+ DriftFacet(+ sub_query="Explore Semantica",+ target_entities=["Semantica"],+ )+ ]++ verified, depth, pruned = engine._traverse_and_prune(+ facets,+ "Semantica GraphRAG HierarchicalLeiden community",+ "Knowledge graph framework",+ )++ assert depth == 2+ targets = [f["target"] for f in verified]+ assert "HierarchicalLeiden" in targets++ def test_hybrid_synthesis_stage6_with_llm(self):+ mock_llm = MagicMock()+ mock_llm.generate_typed.return_value = DriftFacetsResponseSchema(+ facets=[+ DriftFacetSchema(+ sub_query="Investigate GraphRAG",+ target_entities=["Semantica"],+ )+ ]+ )+ mock_llm.generate.return_value = (+ "Executive summary: [Community c_graphrag] defines the macro model. "+ "Micro evidence confirms (Semantica -[IMPLEMENTS]-> GraphRAG)."+ )++ engine = DriftSearchEngine(+ reports=self._sample_reports(),+ knowledge_graph=self._sample_graph(),+ llm=mock_llm,+ )++ result = engine.search("How does Semantica implement GraphRAG?")+ assert "[Community c_graphrag]" in result.citations+ assert "(Semantica -[IMPLEMENTS]-> GraphRAG)" in result.citations+ assert len(result.verified_local_contexts) >= 1+ assert result.metrics["verified_facts_count"] >= 1++ def test_deterministic_synthesis_without_llm(self):+ engine = DriftSearchEngine(+ reports=self._sample_reports(),+ knowledge_graph=self._sample_graph(),+ llm=None,+ drift_threshold=0.10,+ )++ result = engine.search("Semantica GraphRAG")+ assert "DRIFT Hybrid Response" in result.answer+ assert result.depth_reached >= 1+ assert len(result.global_reports_used) >= 1++ def test_context_graph_and_context_edge_ingestion(self):+ from semantica.context.context_graph import ContextGraph++ cg = ContextGraph()+ cg.add_node("AgentContext", "class", label="Agent Context Engine")+ cg.add_node("MemoryStore", "component", label="Memory Component")+ cg.add_edge(+ "AgentContext",+ "MemoryStore",+ "INTEGRATES_WITH",+ {"description": "Manages conversational memory"},+ )++ engine = DriftSearchEngine(knowledge_graph=cg)+ # Check node info+ assert "AgentContext" in engine._node_meta+ assert engine._node_meta["AgentContext"].get("type") == "class"+ assert not engine._node_meta["AgentContext"]["name"].startswith("ContextNode(")++ # Check edge info+ adj_edges = engine._adjacency_index.get("AgentContext", [])+ assert len(adj_edges) >= 1+ assert adj_edges[0]["relation"] == "INTEGRATES_WITH"+ assert "conversational memory" in adj_edges[0]["description"]++ def test_no_duplicate_inverted_edges_in_traversal(self):+ graph = {+ "nodes": [{"id": "NodeA"}, {"id": "NodeB"}, {"id": "NodeC"}],+ "edges": [+ {+ "source": "NodeA",+ "target": "NodeB",+ "relation": "CONNECTS_TO",+ "description": "Forward link from A to B",+ },+ {+ "source": "NodeB",+ "target": "NodeC",+ "relation": "DEPENDS_ON",+ "description": "Forward link from B to C",+ },+ ],+ }+ engine = DriftSearchEngine(+ knowledge_graph=graph,+ max_depth=2,+ drift_threshold=0.0,+ )+ facets = [DriftFacet(sub_query="Explore NodeA", target_entities=["NodeA"])]+ verified, depth, pruned = engine._traverse_and_prune(+ facets, "NodeA NodeB NodeC", "Network framing"+ )++ # Must have NodeA->NodeB and NodeB->NodeC+ relations = [f["relation"] for f in verified]+ assert "CONNECTS_TO" in relations+ assert "DEPENDS_ON" in relations+ # Must NOT have synthetic INVERSE relations or back-edge duplicates+ assert not any("INVERSE" in r for r in relations)+ assert len(verified) == 2++ def test_drift_to_retrieved_contexts_empty_when_no_data(self):+ result = DriftSearchResult(+ query="unknown query",+ answer="No data available.",+ thematic_framing="",+ global_reports_used=[],+ verified_local_contexts=[],+ )+ assert result.to_retrieved_contexts() == []++ def test_extract_json_multi_item_facets_array(self):+ engine = DriftSearchEngine()+ raw_facets = (+ '[\n'+ ' {"sub_query": "Sub 1", "target_entities": ["E1"], "rationale": "R1"},\n'+ ' {"sub_query": "Sub 2", "target_entities": ["E2"], "rationale": "R2"}\n'+ ']'+ )+ parsed = engine._extract_json(raw_facets)+ assert isinstance(parsed, list)+ assert len(parsed) == 2++ resp = engine._coerce_facets_response(parsed)+ assert resp is not None+ assert len(resp.facets) == 2+ assert resp.facets[0].sub_query == "Sub 1"+ assert resp.facets[1].sub_query == "Sub 2"diff --git a/tests/context/test_global_retriever.py b/tests/context/test_global_retriever.pynew file mode 100644index 00000000..66f1ca13--- /dev/null+++ b/tests/context/test_global_retriever.py@@ -0,0 +1,598 @@+"""+Unit and integration tests for GlobalGraphRetriever and Map-Reduce retrieval (PR #3).+"""++from unittest.mock import MagicMock++import pytest++from semantica.context.context_retriever import RetrievedContext+from semantica.context.global_retriever import (+ GlobalGraphRetriever,+ GlobalSearchResult,+ MapKeyPoint,+ MapPointSchema,+ MapResponseSchema,+ _cosine_similarity,+ _extract_words,+)+from semantica.kg.community_summarizer import CommunityReport+++class TestMapKeyPoint:+ """Tests for MapKeyPoint dataclass and serialization."""++ def test_init_defaults_and_clamping(self):+ kp = MapKeyPoint(+ point="Quantum computing advances",+ description="Qubits scaling faster than predicted",+ relevance_score=15.0, # exceeds 10.0+ community_id="c_1",+ level=1,+ entities=["IBM", "Google", "IBM"], # duplicates+ )+ assert kp.point == "Quantum computing advances"+ assert kp.relevance_score == 10.0+ assert kp.entities == ["Google", "IBM"]+ assert kp.community_id == "c_1"+ assert kp.level == 1++ # Test lower clamp+ kp_low = MapKeyPoint(point="Low", relevance_score=-5.0)+ assert kp_low.relevance_score == 0.0++ # Test NaN / invalid clamp+ kp_nan = MapKeyPoint(point="NaN", relevance_score=float("nan"))+ assert kp_nan.relevance_score == 5.0++ def test_to_dict_and_from_dict(self):+ kp = MapKeyPoint(+ point="Graph algorithms",+ description="Leiden clustering",+ relevance_score=8.5,+ community_id="c_42",+ level=2,+ entities=["Graph", "Node"],+ metadata={"source": "test"},+ )+ d = kp.to_dict()+ assert d["point"] == "Graph algorithms"+ assert d["relevance_score"] == 8.5+ assert d["entities"] == ["Graph", "Node"]++ reconstructed = MapKeyPoint.from_dict(d)+ assert reconstructed.point == kp.point+ assert reconstructed.relevance_score == kp.relevance_score+ assert reconstructed.entities == kp.entities+ assert reconstructed.metadata == kp.metadata+++class TestMapResponseSchema:+ """Tests for MapResponseSchema Pydantic validation and coercion."""++ def test_valid_points(self):+ schema = MapResponseSchema(+ points=[+ MapPointSchema(+ point="AI scaling laws",+ description="Compute dictates capability",+ relevance_score=9.0,+ entities=["GPU", "Compute"],+ )+ ],+ relevance_explanation="Directly answers query",+ )+ assert len(schema.points) == 1+ assert schema.points[0].point == "AI scaling laws"+ assert schema.points[0].relevance_score == 9.0++ def test_normalize_dict_and_string_points(self):+ raw = {+ "points": [+ {+ "finding": "Dict-based finding",+ "explanation": "Derived from summary",+ "score": 7.5,+ "member_entities": ["E1", "E2"],+ },+ "Simple string point",+ ],+ "relevance_explanation": "Normalized successfully",+ }+ schema = MapResponseSchema.model_validate(raw)+ assert len(schema.points) == 2+ assert schema.points[0].point == "Dict-based finding"+ assert schema.points[0].description == "Derived from summary"+ assert schema.points[0].relevance_score == 7.5+ assert schema.points[0].entities == ["E1", "E2"]+ assert schema.points[1].point == "Simple string point"+ assert schema.points[1].relevance_score == 5.0+++class TestGlobalSearchResult:+ """Tests for GlobalSearchResult dataclass and conversion to RetrievedContext."""++ def test_to_retrieved_contexts(self):+ result = GlobalSearchResult(+ query="What are the key tech trends?",+ response="Executive overview: [Community c_1] focuses on AI.",+ level=1,+ key_points=[+ MapKeyPoint(+ point="Neural networks",+ description="Transformer architecture dominates",+ relevance_score=9.0,+ community_id="c_1",+ level=1,+ entities=["Transformers", "Attention"],+ )+ ],+ community_reports_used=["c_1"],+ citations=["c_1"],+ metrics={"time_taken": 0.5},+ )++ contexts = result.to_retrieved_contexts()+ assert len(contexts) == 2++ # Primary executive answer context+ primary = contexts[0]+ assert isinstance(primary, RetrievedContext)+ assert primary.score == 1.0+ assert primary.source == "global_search"+ assert primary.content == result.response+ assert primary.metadata["query"] == result.query+ assert primary.metadata["level"] == 1++ # Key point context+ kp_ctx = contexts[1]+ assert isinstance(kp_ctx, RetrievedContext)+ assert kp_ctx.score == 0.9 # 9.0 / 10.0+ assert kp_ctx.source == "community_c_1"+ assert "Neural networks" in kp_ctx.content+ assert len(kp_ctx.related_entities) == 2+ assert kp_ctx.related_entities[0]["id"] == "Attention"++ def test_to_dict_and_from_dict(self):+ result = GlobalSearchResult(+ query="test",+ response="ans",+ level=0,+ key_points=[MapKeyPoint(point="pt", relevance_score=8.0)],+ community_reports_used=["c0"],+ citations=["c0"],+ metrics={"m": 1},+ )+ d = result.to_dict()+ reconstructed = GlobalSearchResult.from_dict(d)+ assert reconstructed.query == "test"+ assert reconstructed.response == "ans"+ assert len(reconstructed.key_points) == 1+ assert reconstructed.key_points[0].point == "pt"+++class TestGlobalGraphRetrieverLevelSelection:+ """Tests for dynamic level selection and token budgeting."""++ def _create_sample_reports(self):+ # Level 0 reports: 4 reports of ~100 tokens each+ l0_reports = [+ CommunityReport(+ community_id=f"c_0_{i}",+ level=0,+ title=f"Sub-cluster {i} of Machine Learning",+ summary=(+ "Detailed exploration of specific algorithms, gradient descent, "+ "backpropagation, and loss functions in artificial intelligence."+ ),+ findings=[+ {"summary": f"Finding {i}", "explanation": "Detailed analysis"}+ ],+ impact_rating=6.0 + i,+ rank=0.5,+ member_entities=[f"Entity_{i}_A", f"Entity_{i}_B"],+ )+ for i in range(4)+ ]++ # Level 1 reports: 1 coarser report+ l1_report = CommunityReport(+ community_id="c_1_0",+ level=1,+ title="Macro Machine Learning Community",+ summary="Executive synthesis covering all machine learning sub-clusters.",+ findings=[{"summary": "Macro Overview", "explanation": "Unified ML"}],+ impact_rating=8.5,+ rank=0.9,+ member_entities=["MachineLearning", "NeuralNetworks"],+ )++ return l0_reports + [l1_report]++ def test_auto_promote_level_when_budget_exceeded(self):+ reports = self._create_sample_reports()+ # Set max_context_tokens small enough so L0 reports exceed it,+ # but L1 report fits.+ retriever = GlobalGraphRetriever(+ reports=reports,+ max_context_tokens=150, # L0 total is ~250 tokens; L1 is ~70 tokens+ auto_promote_level=True,+ )++ selected_level, selected_reports = retriever.select_level_and_budget(+ query="machine learning"+ )+ assert selected_level == 1+ assert len(selected_reports) == 1+ assert selected_reports[0].community_id == "c_1_0"++ def test_stay_at_level_when_within_budget(self):+ reports = self._create_sample_reports()+ retriever = GlobalGraphRetriever(+ reports=reports,+ max_context_tokens=5000,+ auto_promote_level=True,+ )++ selected_level, selected_reports = retriever.select_level_and_budget(+ query="machine learning", target_level=0+ )+ assert selected_level == 0+ assert len(selected_reports) == 4++ def test_pruning_fallback_when_auto_promote_disabled(self):+ reports = self._create_sample_reports()+ # With auto_promote_level=False, must prune L0 reports to fit budget+ retriever = GlobalGraphRetriever(+ reports=reports,+ max_context_tokens=120,+ auto_promote_level=False,+ )++ selected_level, selected_reports = retriever.select_level_and_budget(+ query="machine learning"+ )+ assert selected_level == 0+ # Should prune from 4 down to fitting number+ assert len(selected_reports) < 4+ assert len(selected_reports) >= 1++ def test_embedding_cosine_pruning(self):+ rep_a = CommunityReport(+ community_id="c_emb_a",+ level=0,+ title="Quantum Physics",+ summary="Study of particles and waves.",+ embedding=[1.0, 0.0, 0.0],+ )+ rep_b = CommunityReport(+ community_id="c_emb_b",+ level=0,+ title="Finance and Banking",+ summary="Investment banking and markets.",+ embedding=[0.0, 1.0, 0.0],+ )++ retriever = GlobalGraphRetriever(+ reports=[rep_a, rep_b],+ max_context_tokens=15, # each report is ~12 tokens, so 15 allows only 1+ auto_promote_level=False,+ )++ # Query aligned with rep_a+ level, selected = retriever.select_level_and_budget(+ query="quantum entanglement",+ query_embedding=[0.9, 0.1, 0.0],+ )+ assert level == 0+ assert len(selected) == 1+ assert selected[0].community_id == "c_emb_a"+++class TestGlobalGraphRetrieverMapReduce:+ """Tests for parallel Map execution, 6-tier LLM unwrap, and Reduce synthesis."""++ def test_parallel_map_with_error_isolation(self):+ rep_good = CommunityReport(+ community_id="c_good",+ level=0,+ title="Success Community",+ summary="Everything functions as expected.",+ member_entities=["Alice", "Bob"],+ )+ rep_fail = CommunityReport(+ community_id="c_fail",+ level=0,+ title="Failing Community",+ summary="Triggers worker exception.",+ member_entities=["ErrorNode"],+ )++ # Mock LLM that raises on rep_fail prompt+ mock_llm = MagicMock()++ def llm_side_effect(prompt, **kwargs):+ if "c_fail" in prompt:+ raise RuntimeError("Simulated worker error in LLM")+ return MapResponseSchema(+ points=[+ MapPointSchema(+ point="Good Point",+ description="From good community",+ relevance_score=8.0,+ )+ ],+ relevance_explanation="Worked",+ )++ mock_llm.generate_typed.side_effect = llm_side_effect++ retriever = GlobalGraphRetriever(+ reports=[rep_good, rep_fail],+ llm=mock_llm,+ max_workers=2,+ )++ result = retriever.search(query="test query")+ assert result is not None+ # Both communities should produce points (c_fail via extractive fallback)+ comm_ids = {kp.community_id for kp in result.key_points}+ assert "c_good" in comm_ids+ assert "c_fail" in comm_ids+ assert result.metrics["reports_evaluated"] == 2++ def test_llm_tier_1_generate_typed(self):+ rep = CommunityReport(+ community_id="c_tier1",+ level=0,+ title="Tier 1 Report",+ summary="Tier 1 evaluation",+ )+ mock_llm = MagicMock()+ mock_llm.generate_typed.return_value = MapResponseSchema(+ points=[+ MapPointSchema(+ point="Tier 1 Point",+ description="Success",+ relevance_score=9.5,+ )+ ]+ )++ retriever = GlobalGraphRetriever(reports=[rep], llm=mock_llm)+ points = retriever._map_report(rep, "query")+ assert len(points) == 1+ assert points[0].point == "Tier 1 Point"+ assert points[0].relevance_score == 9.5+ mock_llm.generate_typed.assert_called_once()++ def test_llm_tier_2_provider_generate_typed(self):+ rep = CommunityReport(+ community_id="c_tier2",+ level=0,+ title="Tier 2 Report",+ summary="Tier 2 evaluation",+ )+ mock_provider = MagicMock()+ mock_provider.generate_typed.return_value = {+ "points": [{"point": "Tier 2 Point", "relevance_score": 8.0}]+ }++ mock_llm = MagicMock(spec=["provider"])+ mock_llm.provider = mock_provider++ retriever = GlobalGraphRetriever(reports=[rep], llm=mock_llm)+ points = retriever._map_report(rep, "query")+ assert len(points) == 1+ assert points[0].point == "Tier 2 Point"+ assert points[0].relevance_score == 8.0++ def test_llm_tier_3_generate_structured(self):+ rep = CommunityReport(+ community_id="c_tier3",+ level=0,+ title="Tier 3 Report",+ summary="Tier 3 evaluation",+ )+ mock_llm = MagicMock(spec=["generate_structured"])+ mock_llm.generate_structured.return_value = {+ "points": [{"point": "Tier 3 Structured", "relevance_score": 7.0}]+ }++ retriever = GlobalGraphRetriever(reports=[rep], llm=mock_llm)+ points = retriever._map_report(rep, "query")+ assert len(points) == 1+ assert points[0].point == "Tier 3 Structured"++ def test_llm_tier_4_generate_with_json(self):+ rep = CommunityReport(+ community_id="c_tier4",+ level=0,+ title="Tier 4 Report",+ summary="Tier 4 evaluation",+ )+ mock_llm = MagicMock(spec=["generate"])+ mock_llm.generate.return_value = (+ "```json\n"+ '{"points": [{"point": "Tier 4 JSON", "relevance_score": 8.2}]}\n'+ "```"+ )++ retriever = GlobalGraphRetriever(reports=[rep], llm=mock_llm)+ points = retriever._map_report(rep, "query")+ assert len(points) == 1+ assert points[0].point == "Tier 4 JSON"+ assert points[0].relevance_score == 8.2++ def test_llm_tier_5_callable(self):+ rep = CommunityReport(+ community_id="c_tier5",+ level=0,+ title="Tier 5 Report",+ summary="Tier 5 evaluation",+ )++ def mock_callable(prompt, **kwargs):+ return '{"points": [{"point": "Tier 5 Callable", "relevance_score": 7.5}]}'++ retriever = GlobalGraphRetriever(reports=[rep], llm=mock_callable)+ points = retriever._map_report(rep, "query")+ assert len(points) == 1+ assert points[0].point == "Tier 5 Callable"++ def test_llm_tier_6_extractive_fallback(self):+ rep = CommunityReport(+ community_id="c_extractive",+ level=0,+ title="Deep Learning Breakthroughs",+ summary="Transformers revolutionized natural language processing.",+ findings=[+ {+ "summary": "Attention Mechanisms",+ "explanation": "Self-attention enables massive context.",+ }+ ],+ member_entities=["BERT", "GPT"],+ )++ retriever = GlobalGraphRetriever(reports=[rep], llm=None)+ points = retriever._map_report(rep, "attention transformers")+ assert len(points) >= 1+ pt_texts = [p.point for p in points]+ assert any("Deep Learning" in pt or "Attention" in pt for pt in pt_texts)++ def test_min_relevance_score_filtering(self):+ rep = CommunityReport(+ community_id="c_filter",+ level=0,+ title="Filtered Report",+ summary="Report testing cutoff",+ )++ mock_llm = MagicMock(spec=["generate_typed"])+ mock_llm.generate_typed.return_value = MapResponseSchema(+ points=[+ MapPointSchema(point="High Relevance", relevance_score=9.0),+ MapPointSchema(point="Low Relevance", relevance_score=2.0),+ ]+ )++ retriever = GlobalGraphRetriever(+ reports=[rep],+ llm=mock_llm,+ min_relevance_score=5.0,+ )++ result = retriever.search(query="test")+ retained = [kp.point for kp in result.key_points]+ assert "High Relevance" in retained+ assert "Low Relevance" not in retained++ def test_executive_synthesis_citations_extraction(self):+ rep = CommunityReport(+ community_id="c_cit",+ level=0,+ title="Citation Source",+ summary="Data for citation",+ )++ mock_llm = MagicMock()+ mock_llm.generate_typed.return_value = MapResponseSchema(+ points=[MapPointSchema(point="Key Finding", relevance_score=8.5)]+ )+ mock_llm.generate.return_value = (+ "According to [Community c_cit], the key finding is verified."+ )++ retriever = GlobalGraphRetriever(reports=[rep], llm=mock_llm)+ result = retriever.search(query="test")+ assert "c_cit" in result.citations+ assert "[Community c_cit]" in result.response++ def test_empty_reports_returns_graceful_result(self):+ retriever = GlobalGraphRetriever(reports=[])+ result = retriever.search(query="empty search")+ assert result.key_points == []+ assert "No community reports" in result.response+ assert result.metrics["reports_evaluated"] == 0+ # Verify to_retrieved_contexts returns empty list to prevent RAG pollution+ assert result.to_retrieved_contexts() == []++ def test_extract_json_multi_item_array_and_markdown(self):+ retriever = GlobalGraphRetriever()+ raw_json_arr = (+ "[\n"+ ' {"point": "Pt A", "description": "D1", "relevance_score": 9.0},\n'+ ' {"point": "Pt B", "description": "D2", "relevance_score": 8.0},\n'+ ' {"point": "Pt C", "description": "D3", "relevance_score": 7.0}\n'+ "]"+ )+ parsed = retriever._extract_json(raw_json_arr)+ assert isinstance(parsed, list)+ assert len(parsed) == 3++ # Test within markdown codeblock+ markdown_text = (+ f"Findings:\n```json\n{raw_json_arr}\n```\nDone."+ )+ parsed_md = retriever._extract_json(markdown_text)+ assert isinstance(parsed_md, list)+ assert len(parsed_md) == 3++ # Test coercion maintains all 3 points+ rep = CommunityReport(community_id="c_arr", level=0, title="T", summary="S")+ schema = retriever._coerce_map_response(parsed, rep)+ assert schema is not None+ assert len(schema.points) == 3+ pts = [p.point for p in schema.points]+ assert pts == ["Pt A", "Pt B", "Pt C"]++ def test_parallel_map_timeout_falls_back_without_failing_batch(self):+ import time++ rep1 = CommunityReport(+ community_id="c_fast",+ level=0,+ title="Fast Community",+ summary="Fast summary",+ findings=[{"summary": "Fast finding"}],+ )+ rep2 = CommunityReport(+ community_id="c_slow",+ level=0,+ title="Slow Community",+ summary="Slow summary",+ findings=[{"summary": "Slow finding"}],+ )++ def mock_llm_with_delay(prompt, **kwargs):+ if "Slow Community" in prompt:+ time.sleep(0.3)+ return (+ '{"points": [{"point": "Finding", "relevance_score": 8.0}]}'+ )++ # Set a short timeout (0.05s) so the slow report times out+ retriever = GlobalGraphRetriever(+ reports=[rep1, rep2],+ llm=mock_llm_with_delay,+ timeout=0.05,+ max_workers=2,+ )++ # Must NOT raise TimeoutError; must return points for both+ points = retriever._execute_parallel_map([rep1, rep2], query="test")+ comm_ids = {p.community_id for p in points}+ assert "c_fast" in comm_ids or "c_slow" in comm_ids+ assert len(points) >= 1++ def test_helper_utilities(self):+ # Cosine similarity+ assert _cosine_similarity([1.0, 0.0], [1.0, 0.0]) == pytest.approx(1.0)+ assert _cosine_similarity([1.0, 0.0], [0.0, 1.0]) == pytest.approx(0.0)+ assert _cosine_similarity([], [1.0]) == 0.0++ # Word extraction+ words = _extract_words("Hello, World! 123_test")+ assert "hello" in words+ assert "world" in wordsdiff --git a/tests/context/test_pr1548_review_fixes.py b/tests/context/test_pr1548_review_fixes.pynew file mode 100644index 00000000..cc3fb0c6--- /dev/null+++ b/tests/context/test_pr1548_review_fixes.py@@ -0,0 +1,959 @@+"""Unit tests covering all 27 PR review fixes (Issues 1-11, Findings A-P)."""++import time+from unittest.mock import MagicMock, patch++from semantica.context.global_retriever import (+ GlobalGraphRetriever,+ GlobalSearchResult,+ MapPointSchema,+ MapKeyPoint,+)+from semantica.context.drift_search import (+ DriftSearchEngine,+ DriftFacetSchema,+ DriftFacet,+)+from semantica.context.context_retriever import ContextRetriever, RetrievedContext+from semantica.kg.community_summarizer import CommunityReport+++# ---------------------------------------------------------------------------+# Issue 1: Concurrency & Timeout Safety in GlobalGraphRetriever+# ---------------------------------------------------------------------------+def test_issue_1_concurrency_timeout():+ """Verify ThreadPoolExecutor timeout cancels futures without blocking."""+ retriever = GlobalGraphRetriever(timeout=0.1, max_workers=2)++ def slow_worker(rep, query):+ time.sleep(2.0)+ return []++ reports = [+ CommunityReport(+ community_id=f"c_{i}",+ level=0,+ title=f"Report {i}",+ summary=f"Summary {i}",+ findings=[],+ member_entities=[f"Ent_{i}"],+ )+ for i in range(3)+ ]+ start_t = time.time()+ with patch.object(retriever, "_map_report", side_effect=slow_worker):+ results = retriever._execute_parallel_map(reports, "test query")+ elapsed = time.time() - start_t+ # Finished within timeout window without waiting for slow workers+ assert elapsed < 2.5+ assert len(results) == 3+++# ---------------------------------------------------------------------------+# Issue 2: Query forwarded to extractive fallback+# ---------------------------------------------------------------------------+def test_issue_2_query_forwarded_to_extractive_fallback():+ retriever = GlobalGraphRetriever()+ report = CommunityReport(+ community_id="c1",+ level=0,+ title="AI",+ summary="Deep learning",+ findings=[],+ member_entities=[],+ )+ with patch.object(+ retriever, "_extractive_map_fallback", return_value=MagicMock(points=[])+ ) as mock_fallback:+ retriever._call_map_llm("prompt text", report, query="machine learning")+ mock_fallback.assert_called_once()+ args, kwargs = mock_fallback.call_args+ assert args[1] == "machine learning"+++# ---------------------------------------------------------------------------+# Issue 3 & Finding G: Tier 1 failure cascades to Tier 2+# ---------------------------------------------------------------------------+def test_issue_3_and_finding_g_tier1_failure_cascades_to_tier2():+ retriever = GlobalGraphRetriever()+ mock_llm = MagicMock()+ mock_provider = MagicMock()+ mock_llm.provider = mock_provider++ # Tier 1 generate_typed fails+ mock_llm.generate_typed.side_effect = RuntimeError("Tier 1 unavailable")+ # Tier 2 provider.generate_typed succeeds+ mock_provider.generate_typed.return_value = [+ MapPointSchema(+ point="Finding from tier 2",+ relevance_score=8.5,+ description="Evidence text",+ )+ ]+ retriever.llm = mock_llm+ report = CommunityReport(+ community_id="c1",+ level=0,+ title="T",+ summary="S",+ findings=[],+ member_entities=[],+ )++ schema = retriever._call_map_llm("prompt", report, query="query")+ assert len(schema.points) == 1+ assert schema.points[0].point == "Finding from tier 2"+ mock_provider.generate_typed.assert_called_once()+++def test_issue_3_and_finding_g_drift_facet_tier1_to_tier2():+ drift = DriftSearchEngine()+ mock_llm = MagicMock()+ mock_provider = MagicMock()+ mock_llm.provider = mock_provider++ mock_llm.generate_typed.side_effect = RuntimeError("Tier 1 fail")+ mock_provider.generate_typed.return_value = [+ DriftFacetSchema(+ sub_query="Facet from tier 2",+ target_entities=["EntityA"],+ rationale="Rationale text",+ relevance_score=0.9,+ )+ ]+ drift.llm = mock_llm++ facets = drift._generate_facets("test query", "thematic framing")+ assert len(facets) == 1+ assert facets[0].sub_query == "Facet from tier 2"+++# ---------------------------------------------------------------------------+# Issue 4: Budget exhaustion and empty lines packing+# ---------------------------------------------------------------------------+def test_issue_4_budget_exhaustion_no_artificial_inflation():+ retriever = GlobalGraphRetriever(+ max_context_tokens=100,+ fixed_overhead=200,+ response_token_budget=100,+ )+ rep = CommunityReport(+ community_id="c1",+ level=0,+ title="Distributed Systems",+ summary="Summary of distributed systems",+ findings=[],+ member_entities=[],+ )+ retriever.set_reports([rep])+ res = retriever.search("consensus")+ assert "No sufficiently relevant community findings were available." in res.response+ assert res.metrics["citations_count"] == 0+++def test_issue_4_empty_packed_lines_handling():+ retriever = GlobalGraphRetriever()+ lines, retained = retriever._pack_reduce_context([], budget=100)+ assert lines == ""+ assert retained == []+++# ---------------------------------------------------------------------------+# Issue 5: Extracted citations intersected with valid_ids+# ---------------------------------------------------------------------------+def test_issue_5_citation_intersection():+ retriever = GlobalGraphRetriever()+ rep1 = CommunityReport(community_id="comm_1", level=0, title="T1", summary="S1")+ rep2 = CommunityReport(community_id="comm_2", level=0, title="T2", summary="S2")+ retriever.set_reports([rep1, rep2])++ points = [+ MapKeyPoint(+ community_id="comm_1",+ point="Point 1",+ relevance_score=8.0,+ description="Evidence 1",+ ),+ MapKeyPoint(+ community_id="comm_2",+ point="Point 2",+ relevance_score=7.0,+ description="Evidence 2",+ ),+ ]++ # LLM hallucinates comm_999 alongside comm_1+ with patch.object(+ retriever, "_execute_parallel_map", return_value=points+ ), patch.object(+ retriever,+ "_synthesize_reduce",+ return_value="Based on [Community comm_1] and [Community comm_999].",+ ):+ res = retriever.search("query")+ assert res.citations == ["comm_1"]++ # When no citations match, fallback to sorted valid_ids+ with patch.object(+ retriever, "_execute_parallel_map", return_value=points+ ), patch.object(+ retriever,+ "_synthesize_reduce",+ return_value="No citations here.",+ ):+ res = retriever.search("query")+ assert res.citations == ["comm_1", "comm_2"]+++# ---------------------------------------------------------------------------+# Issue 6 & Finding H: Schema validation alias for 'score'+# ---------------------------------------------------------------------------+def test_issue_6_and_finding_h_schema_score_alias():+ # MapPointSchema+ p1 = MapPointSchema.model_validate(+ {"point": "Key fact", "score": 8.5, "description": "text"}+ )+ assert p1.relevance_score == 8.5++ p2 = MapPointSchema.model_validate(+ {"point": "Key fact", "relevance_score": 9.2, "description": "text"}+ )+ assert p2.relevance_score == 9.2++ # DriftFacetSchema+ f1 = DriftFacetSchema.model_validate(+ {+ "sub_query": "Query facet",+ "score": 0.8,+ "rationale": "text",+ "target_entities": ["E1"],+ }+ )+ assert f1.relevance_score == 0.8+++# ---------------------------------------------------------------------------+# Issue 7: Drift Search traversal token budget capping+# ---------------------------------------------------------------------------+def test_issue_7_drift_search_token_budget_capping():+ drift = DriftSearchEngine(max_context_tokens=40)+ drift._adjacency_index = {+ "n1": [+ {+ "source": "n1",+ "target": "n2",+ "relation": "relates_to",+ "description": "very long description " * 20,+ },+ {+ "source": "n1",+ "target": "n3",+ "relation": "connects",+ "description": "another long description " * 20,+ },+ {+ "source": "n1",+ "target": "n4",+ "relation": "links",+ "description": "third long description " * 20,+ },+ ]+ }+ drift._node_meta = {+ "n1": {"id": "n1", "name": "n1"},+ "n2": {"id": "n2", "name": "n2"},+ "n3": {"id": "n3", "name": "n3"},+ "n4": {"id": "n4", "name": "n4"},+ }++ facets = [+ DriftFacet(+ sub_query="Explore n1",+ target_entities=["n1"],+ relevance_score=1.0,+ )+ ]+ verified, depth, pruned = drift._traverse_and_prune(+ facets, "test query n1 n2", "framing"+ )+ # Traversal should halt early before adding all edges due to 40 token limit+ assert len(verified) < 3+++# ---------------------------------------------------------------------------+# Issue 8 & Finding M: Citation filtering and regex in Drift Search+# ---------------------------------------------------------------------------+def test_issue_8_and_finding_m_drift_citation_filtering():+ drift = DriftSearchEngine()+ rep = CommunityReport(+ community_id="comm_1",+ level=0,+ title="Title",+ summary="Summary",+ findings=[],+ member_entities=["Node.js", "API/v1"],+ )+ drift.set_reports([rep])+ drift._adjacency_index = {+ "Node.js": [+ {+ "source": "Node.js",+ "target": "API/v1",+ "relation": "exposes",+ "description": "Exposes API",+ }+ ]+ }+ drift._node_meta = {+ "Node.js": {"id": "Node.js", "name": "Node.js"},+ "API/v1": {"id": "API/v1", "name": "API/v1"},+ }++ mock_llm = MagicMock()+ mock_llm.generate.return_value = (+ "Found in [Community comm_1] and [Community comm_999]. "+ "Also (Node.js -[exposes]-> API/v1) and (Fake -[bad]-> Invalid)."+ )+ drift.llm = mock_llm++ result = drift.search("Node.js exposes API/v1")+ assert "[Community comm_1]" in result.citations+ assert "[Community comm_999]" not in result.citations+ assert "(Node.js -[exposes]-> API/v1)" in result.citations+ assert "(Fake -[bad]-> Invalid)" not in result.citations+++# ---------------------------------------------------------------------------+# Issue 9 & Finding D: ContextRetriever threshold scaling & hybrid score preservation+# ---------------------------------------------------------------------------+def test_issue_9_and_finding_d_threshold_scaling():+ retriever = ContextRetriever()+ search_result = GlobalSearchResult(+ query="query",+ response="Answer",+ level=0,+ key_points=[+ MapKeyPoint(+ point="Point 1",+ relevance_score=8.0,+ description="Evidence",+ community_id="c1",+ ),+ MapKeyPoint(+ point="Point 2",+ relevance_score=3.0,+ description="Evidence",+ community_id="c2",+ ),+ ],+ community_reports_used=["c1"],+ citations=["c1"],+ )++ with patch.object(+ GlobalGraphRetriever, "search", return_value=search_result+ ):+ # min_relevance_score=6.0 scales to threshold 0.60+ # Result contains executive answer (score=1.0) and Point 1 (score=0.80)+ contexts = retriever.retrieve_global(+ "query", min_relevance_score=6.0, as_contexts=True+ )+ assert len(contexts) == 2+ assert any(c.score == 0.80 for c in contexts)+ assert all(c.score >= 0.60 for c in contexts)+++def test_issue_9_and_finding_d_hybrid_preserves_weighted_scores():+ retriever = ContextRetriever(hybrid_alpha=0.5)++ c1 = RetrievedContext(+ content="Vector match",+ score=1.0,+ source="vector:1",+ )++ with patch.object(+ retriever, "_retrieve_from_vector", return_value=[c1]+ ), patch.object(+ retriever, "_retrieve_from_graph", return_value=[]+ ), patch.object(+ retriever, "retrieve_global", return_value=[]+ ):+ retriever.knowledge_graph = None+ # In mode="local", c1 score is weighted to 0.5 (>= 0.4).+ # In mode="hybrid", after second merge, score becomes 0.25 (< 0.4).+ # In the old code, a second filter purged it. Now it is preserved.+ results = retriever.retrieve(+ "test query",+ mode="hybrid",+ min_relevance_score=0.4,+ max_results=5,+ )+ assert len(results) == 1+ assert results[0].content == "Vector match"+++# ---------------------------------------------------------------------------+# Issue 10 & Finding K: Early return on no retained points & metrics citations_count+# ---------------------------------------------------------------------------+def test_issue_10_and_finding_k_no_retained_points_metrics():+ retriever = GlobalGraphRetriever()+ retriever.set_reports(+ [+ CommunityReport(+ community_id="c1",+ level=0,+ title="T",+ summary="S",+ findings=[],+ member_entities=[],+ )+ ]+ )++ with patch.object(+ retriever,+ "_execute_parallel_map",+ return_value=[+ MapKeyPoint(+ community_id="c1",+ point="Irrelevant",+ relevance_score=2.0,+ description="e",+ )+ ],+ ):+ result = retriever.search("query", min_relevance_score=8.0)+ assert "No sufficiently relevant community findings" in result.response+ assert result.citations == []+ assert result.community_reports_used == []+ assert result.metrics["citations_count"] == 0+++def test_issue_10_and_finding_k_no_candidate_reports_metrics():+ retriever = GlobalGraphRetriever()+ retriever.set_reports([])+ result = retriever.search("query")+ assert result.metrics["citations_count"] == 0+++# ---------------------------------------------------------------------------+# Issue 11 & Finding A: GraphStore / manager detection and flexible edge keys+# ---------------------------------------------------------------------------+def test_issue_11_and_finding_a_graph_store_detection_and_edge_keys():+ drift = DriftSearchEngine()++ class MockGraphStore:+ def __init__(self):+ self.relationships = MagicMock()+ self.relationships.get.return_value = [+ {+ "start_node_id": "n1",+ "end_node_id": "n2",+ "type": "DEPENDS_ON",+ "properties": {"description": "n1 depends on n2"},+ }+ ]+ self.nodes = MagicMock()+ self.nodes.get.return_value = [+ {"id": "n1", "properties": {"name": "Service A"}},+ {"id": "n2", "properties": {"name": "Service B"}},+ ]++ store = MockGraphStore()+ drift.set_knowledge_graph(store)+ assert "n1" in drift._adjacency_index+ edge = drift._adjacency_index["n1"][0]+ assert edge["source"] == "n1"+ assert edge["target"] == "n2"+ assert edge["relation"] == "DEPENDS_ON"+ assert edge["description"] == "n1 depends on n2"+ assert "n1" in drift._node_meta+ assert drift._node_meta["n1"]["name"] == "Service A"+++# ---------------------------------------------------------------------------+# Finding B: Ingest graph iterables and NetworkX node tuples+# ---------------------------------------------------------------------------+def test_finding_b_ingest_graph_networkx_tuples():+ drift = DriftSearchEngine()++ class MockNetworkXGraph:+ def __init__(self):+ self.nodes = [+ ("node_alpha", {"properties": {"name": "Alpha Node"}}),+ ("node_beta", {"name": "Beta Node"}),+ ]+ self.edges = [("node_alpha", "node_beta", {"relation": "LINKS_TO"})]++ drift.set_knowledge_graph(MockNetworkXGraph())+ assert "node_alpha" in drift._node_meta+ assert drift._node_meta["node_alpha"]["name"] == "Alpha Node"+ assert "node_beta" in drift._node_meta+ assert drift._node_meta["node_beta"]["name"] == "Beta Node"+++# ---------------------------------------------------------------------------+# Finding C: Rank and merge preserves global & drift graph sources+# ---------------------------------------------------------------------------+def test_finding_c_rank_and_merge_preserves_graph_sources():+ retriever = ContextRetriever(hybrid_alpha=0.8)++ contexts = [+ RetrievedContext(content="Global", score=1.0, source="global_search"),+ RetrievedContext(content="DRIFT", score=1.0, source="drift_search"),+ RetrievedContext(content="Comm", score=1.0, source="community_report"),+ RetrievedContext(content="Vector", score=1.0, source="vector:items"),+ ]++ merged = retriever._rank_and_merge(contexts, "query")+ sources = {c.source for c in merged}+ assert "global_search" in sources+ assert "drift_search" in sources+ assert "community_report" in sources+++# ---------------------------------------------------------------------------+# Finding E: Inverse edge canonical direction in traversal+# ---------------------------------------------------------------------------+def test_finding_e_inverse_edge_canonical_direction():+ drift = DriftSearchEngine(drift_threshold=0.0)+ drift.set_knowledge_graph(+ {+ "nodes": [{"id": "client"}, {"id": "server"}],+ "edges": [+ {+ "source": "client",+ "target": "server",+ "relation": "CONNECTS_TO",+ "description": "Client establishes connection to Server",+ }+ ],+ }+ )++ # Query facet matching "server", traversing backward to "client"+ facets = [+ DriftFacet(+ sub_query="Explore server",+ target_entities=["server"],+ relevance_score=1.0,+ )+ ]+ verified, depth, pruned = drift._traverse_and_prune(+ facets, "server client connects", "framing"+ )+ assert len(verified) == 1+ # Fact text should retain canonical (client) -[CONNECTS_TO]-> (server)+ assert verified[0]["source"] == "client"+ assert verified[0]["target"] == "server"+++# ---------------------------------------------------------------------------+# Finding F: Verified facts sorted descending by alignment score+# ---------------------------------------------------------------------------+def test_finding_f_verified_facts_sorted_descending():+ drift = DriftSearchEngine(drift_threshold=0.1)+ rep = CommunityReport(+ community_id="c1",+ level=0,+ title="Title",+ summary="Summary",+ findings=[],+ member_entities=["a", "b", "c"],+ )+ drift.set_reports([rep])+ drift._adjacency_index = {+ "a": [+ {+ "source": "a",+ "target": "b",+ "relation": "r1",+ "description": "fact low",+ },+ {+ "source": "a",+ "target": "c",+ "relation": "r2",+ "description": "fact high",+ },+ ]+ }+ drift._node_meta = {+ "a": {"id": "a", "name": "a"},+ "b": {"id": "b", "name": "b"},+ "c": {"id": "c", "name": "c"},+ }++ with patch.object(+ drift, "_compute_alignment_score", side_effect=[0.3, 0.9]+ ), patch.object(+ drift,+ "_generate_facets",+ return_value=[+ DriftFacet(+ sub_query="Explore a",+ target_entities=["a"],+ relevance_score=1.0,+ )+ ],+ ):+ result = drift.search("a query")+ contexts = result.verified_local_contexts+ assert len(contexts) == 2+ assert contexts[0]["alignment_score"] >= contexts[1]["alignment_score"]+ assert contexts[0]["alignment_score"] == 0.9+++# ---------------------------------------------------------------------------+# Finding I: Guard against None in numeric fields in from_dict+# ---------------------------------------------------------------------------+def test_finding_i_guard_none_in_from_dict():+ # CommunityReport+ cs = CommunityReport.from_dict(+ {+ "community_id": "comm_1",+ "title": "Title",+ "summary": "Summary",+ "level": None,+ "impact_rating": None,+ "rank": None,+ }+ )+ assert cs.level == 0+ assert cs.impact_rating == 5.0+ assert cs.rank == 0.0++ # MapKeyPoint+ kp = MapKeyPoint.from_dict(+ {+ "community_id": "c1",+ "point": "P",+ "relevance_score": None,+ "level": None,+ }+ )+ assert kp.relevance_score == 5.0+ assert kp.level == 0++ # DriftFacet+ df = DriftFacet.from_dict(+ {+ "sub_query": "F",+ "relevance_score": None,+ }+ )+ assert df.relevance_score == 1.0+++# ---------------------------------------------------------------------------+# Finding J: _estimate_report_tokens handles string findings+# ---------------------------------------------------------------------------+def test_finding_j_estimate_report_tokens_string_findings():+ retriever = GlobalGraphRetriever()+ report = CommunityReport(+ community_id="c1",+ level=0,+ title="Report",+ summary="Summary",+ findings=[+ "Simple string finding 1",+ "Simple string finding 2",+ ],+ member_entities=[],+ )+ tokens = retriever._estimate_report_tokens(report)+ assert tokens > 0+++# ---------------------------------------------------------------------------+# Finding N: Unsupported LLM raises TypeError to trigger deterministic fallback+# ---------------------------------------------------------------------------+def test_finding_n_unsupported_llm_raises_typeerror():+ retriever = GlobalGraphRetriever()+ retriever.llm = "unsupported_string_llm"+ rep = CommunityReport(+ community_id="c1",+ level=0,+ title="t",+ summary="sample text",+ findings=[],+ member_entities=[],+ )+ res = retriever._call_map_llm("prompt", rep, query="sample")+ assert isinstance(res.points, list)++ drift = DriftSearchEngine()+ drift.llm = 12345 # unsupported int+ facets = drift._generate_facets("query", "framing")+ assert isinstance(facets, list)+++# ---------------------------------------------------------------------------+# Finding O: set_reports accepts general Iterable+# ---------------------------------------------------------------------------+def test_finding_o_set_reports_accepts_iterable():+ retriever = GlobalGraphRetriever()+ reports_dict = {+ "c1": {"community_id": "c1", "summary": "s1"},+ "c2": {"community_id": "c2", "summary": "s2"},+ }+ # Pass dict_values view+ retriever.set_reports(reports_dict.values())+ assert len(retriever._reports) == 2++ drift = DriftSearchEngine()+ # Pass generator of CommunityReport objects+ rep_objs = (+ CommunityReport(+ community_id=k,+ level=0,+ title=k,+ summary=v["summary"],+ findings=[],+ member_entities=[],+ )+ for k, v in reports_dict.items()+ )+ drift.set_reports(rep_objs)+ assert len(drift._reports) == 2+++# ---------------------------------------------------------------------------+# Finding P: MapPointSchema exported in semantica.context+# ---------------------------------------------------------------------------+def test_finding_p_map_point_schema_exported():+ import semantica.context as ctx+ assert hasattr(ctx, "MapPointSchema")+ assert "MapPointSchema" in ctx.__all__+++# ---------------------------------------------------------------------------+# Deep Verification: Robustness & Edge Cases+# ---------------------------------------------------------------------------+def test_issue_1_duplicate_community_ids_on_timeout():+ """Verify duplicate community IDs do not suppress fallback for timed-out futures."""+ retriever = GlobalGraphRetriever(timeout=0.05, max_workers=2)++ def slow_worker(rep, query):+ time.sleep(2.0)+ return []++ # Both reports share the same community_id+ reports = [+ CommunityReport(+ community_id="shared_comm",+ level=0,+ title="Report 1",+ summary="Summary 1",+ findings=[],+ member_entities=["E1"],+ ),+ CommunityReport(+ community_id="shared_comm",+ level=0,+ title="Report 2",+ summary="Summary 2",+ findings=[],+ member_entities=["E2"],+ ),+ ]+ with patch.object(retriever, "_map_report", side_effect=slow_worker):+ results = retriever._execute_parallel_map(reports, "test query")+ # Both reports produce fallback points despite shared community ID+ assert len(results) == 2+++def test_issue_1_subsecond_timeout_respected():+ retriever = GlobalGraphRetriever(timeout=0.05)+ assert retriever.timeout == 0.05+++def test_issue_4_pack_reduce_context_skips_oversized_points():+ retriever = GlobalGraphRetriever()+ # Create 3 points: kp1 (fits), kp2 (huge, exceeds remaining), kp3 (small, fits)+ kp1 = MapKeyPoint(+ point="Short 1",+ description="d1",+ relevance_score=9.0,+ community_id="c1",+ )+ kp2 = MapKeyPoint(+ point="Huge 2",+ description="long description " * 100,+ relevance_score=8.5,+ community_id="c2",+ )+ kp3 = MapKeyPoint(+ point="Short 3",+ description="d3",+ relevance_score=8.0,+ community_id="c3",+ )++ _, retained = retriever._pack_reduce_context([kp1, kp2, kp3], budget=60)+ assert kp1 in retained+ assert kp2 not in retained+ assert kp3 in retained+++def test_issue_5_integer_and_zero_community_id_citations():+ retriever = GlobalGraphRetriever()+ rep0 = CommunityReport(community_id=0, level=0, title="T0", summary="S0")+ rep1 = CommunityReport(community_id=1, level=0, title="T1", summary="S1")+ retriever.set_reports([rep0, rep1])++ points = [+ MapKeyPoint(+ community_id=0,+ point="Fact 0",+ relevance_score=9.0,+ description="e0",+ ),+ MapKeyPoint(+ community_id=1,+ point="Fact 1",+ relevance_score=8.0,+ description="e1",+ ),+ ]++ with patch.object(+ retriever, "_execute_parallel_map", return_value=points+ ), patch.object(+ retriever,+ "_synthesize_reduce",+ return_value="Assert [Community 0] and [Community 1].",+ ):+ res = retriever.search("query")+ assert "0" in res.citations+ assert "1" in res.citations+++def test_issue_7_unverified_edges_do_not_exhaust_traversal_budget():+ drift = DriftSearchEngine(max_context_tokens=40, drift_threshold=0.5)+ drift._adjacency_index = {+ "n1": [+ # Edge 1: huge description, irrelevant (alignment score = 0.01)+ {+ "source": "n1",+ "target": "n2",+ "relation": "irrelevant_rel",+ "description": "very long irrelevant text " * 50,+ },+ # Edge 2: small, highly relevant (alignment score = 0.99)+ {+ "source": "n1",+ "target": "n3",+ "relation": "relevant_rel",+ "description": "short relevant text",+ },+ ]+ }+ drift._node_meta = {+ "n1": {"id": "n1", "name": "n1"},+ "n2": {"id": "n2", "name": "n2"},+ "n3": {"id": "n3", "name": "n3"},+ }++ facets = [+ DriftFacet(+ sub_query="Explore n1",+ target_entities=["n1"],+ relevance_score=1.0,+ )+ ]++ with patch.object(+ drift, "_compute_alignment_score", side_effect=[0.01, 0.99]+ ):+ verified, depth, pruned = drift._traverse_and_prune(+ facets, "test query", "framing"+ )+ assert pruned == 1+ assert len(verified) == 1+ assert verified[0]["target"] == "n3"+++def test_issue_8_relationship_citation_whitespace_case_and_colon():+ drift = DriftSearchEngine()+ rep = CommunityReport(+ community_id="comm_1",+ level=0,+ title="Title",+ summary="Summary",+ findings=[],+ member_entities=["Node.js", "API/v1"],+ )+ drift.set_reports([rep])+ drift._adjacency_index = {+ "Node.js": [+ {+ "source": "Node.js",+ "target": "API/v1",+ "relation": "exposes",+ "description": "Exposes REST API",+ }+ ]+ }+ drift._node_meta = {+ "Node.js": {"id": "Node.js", "name": "Node.js"},+ "API/v1": {"id": "API/v1", "name": "API/v1"},+ }++ # LLM outputs space around brackets, uppercase relation, and trailing colon+ mock_llm = MagicMock()+ mock_llm.generate.return_value = (+ "Evidence from (Node.js - [EXPOSES] -> API/v1: REST endpoints)."+ )+ drift.llm = mock_llm++ result = drift.search("Node.js exposes API/v1")+ assert "(Node.js -[exposes]-> API/v1)" in result.citations+++def test_issue_11_dict_of_edges_and_neo4j_node_props():+ drift = DriftSearchEngine()+ graph_dict = {+ "nodes": [+ {"id": "n1", "n": {"name": "Neo4j Service A"}},+ {"id": "n2", "properties": {"name": "Service B"}},+ ],+ "edges": {+ "e1": {+ "source": "n1",+ "target": "n2",+ "relation": "CALLS",+ "description": "Service A calls Service B",+ }+ },+ }+ drift.set_knowledge_graph(graph_dict)+ assert "n1" in drift._adjacency_index+ assert drift._adjacency_index["n1"][0]["relation"] == "CALLS"+ assert drift._node_meta["n1"]["name"] == "Neo4j Service A"+++def test_issue_11_networkx_multigraph_4tuple():+ drift = DriftSearchEngine()++ class MockMultiGraph:+ def __init__(self):+ self.nodes = [+ ("srv1", {"name": "Server 1"}),+ ("srv2", {"name": "Server 2"}),+ ]+ self.edges = [+ (+ "srv1",+ "srv2",+ 0,+ {"relation": "REPLICATES_TO", "description": "Replication"},+ )+ ]++ drift.set_knowledge_graph(MockMultiGraph())+ assert "srv1" in drift._adjacency_index+ edge = drift._adjacency_index["srv1"][0]+ assert edge["relation"] == "REPLICATES_TO"+ assert edge["description"] == "Replication"diff --git a/tests/context/test_qodo_review_fixes.py b/tests/context/test_qodo_review_fixes.pynew file mode 100644index 00000000..c6b176a8--- /dev/null+++ b/tests/context/test_qodo_review_fixes.py@@ -0,0 +1,606 @@+"""Unit tests covering all 10 Qodo review fixes.++Issues covered:+1. Global answers evidence links and member entity citations.+2. DRIFT prompts token budgeting and truncation.+3. Named graph nodes alias resolution and readable fact rendering.+4. Zero-valued nodes retaining edges and graph presence.+5. Parallel graph edges and inverse edge identity preservation.+6. AlgorithmRegistry lazy loading and instantiation of retrieval engines.+7. Hybrid retrieval filtering by min_relevance_score without double-weighting.+8. DriftSearchEngine search-level depth/threshold argument immutability.+9. ContextRetriever.retrieve_drift score normalization on 0-10 scale.+10. CommunityReport safe string coercion for findings in global retrieval.+"""++from unittest.mock import MagicMock, patch++from semantica.context.context_retriever import ContextRetriever, RetrievedContext+from semantica.context.drift_search import (+ DriftFacet,+ DriftSearchEngine,+ DriftSearchResult,+ estimate_tokens,+)+from semantica.context.global_retriever import (+ GlobalGraphRetriever,+ MapKeyPoint,+)+from semantica.kg.community_summarizer import CommunityReport+from semantica.kg.registry import AlgorithmRegistry, algorithm_registry+++# ---------------------------------------------------------------------------+# Issue 1: Global answers omit evidence links+# ---------------------------------------------------------------------------+def test_global_retriever_evidence_links_appended_when_missing():+ retriever = GlobalGraphRetriever()+ key_points = [+ MapKeyPoint(+ community_id="c1",+ point="Consensus is required in distributed state machines.",+ description="PBFT and Raft ensure safety under partitions.",+ relevance_score=9.0,+ entities=["Raft", "PBFT"],+ ),+ MapKeyPoint(+ community_id="c2",+ point="Gossip protocols provide eventual consistency.",+ description="Dynamo-style rings use gossip for membership.",+ relevance_score=8.0,+ entities=["Dynamo"],+ ),+ ]++ raw_response = "Distributed systems require consensus algorithms."+ validated = retriever._ensure_evidence_citations(raw_response, key_points)++ assert "Sources / Evidence:" in validated+ assert "[Community c1]" in validated+ assert "[Community c2]" in validated+ assert "Raft" in validated+ assert "PBFT" in validated+ assert "Dynamo" in validated+++def test_global_retriever_evidence_links_preserved_when_already_present():+ retriever = GlobalGraphRetriever()+ key_points = [+ MapKeyPoint(+ community_id="c1",+ point="Consensus ensures safety.",+ description="Desc",+ relevance_score=9.0,+ entities=["Raft"],+ )+ ]++ raw_response = "Safety in [Community c1] is achieved via consensus (Raft)."+ validated = retriever._ensure_evidence_citations(raw_response, key_points)+ assert "Sources / Evidence:" not in validated+ assert validated == raw_response+++def test_global_retriever_deterministic_fallback_cites_entities_and_communities():+ retriever = GlobalGraphRetriever()+ key_points = [+ MapKeyPoint(+ community_id="comm_42",+ point="Primary point",+ description="Detailed evidence",+ relevance_score=9.5,+ entities=["EntityAlpha", "EntityBeta"],+ )+ ]++ fallback = retriever._synthesize_reduce("test query", "context", key_points)+ assert "[Community comm_42]" in fallback+ assert "Entities: EntityAlpha, EntityBeta" in fallback+++# ---------------------------------------------------------------------------+# Issue 2: Drift prompts exceed token limit+# ---------------------------------------------------------------------------+def test_drift_synthesize_hybrid_respects_token_budget():+ engine = DriftSearchEngine(max_context_tokens=300, response_token_budget=50)+ mock_llm = MagicMock()+ mock_llm.generate.return_value = "Synthesized response (NodeA -[rel]-> NodeB)"+ engine.llm = mock_llm++ huge_query = "What is the consensus algorithm? " * 50+ huge_framing = "Global framing overview: " + ("extensive context " * 100)+ huge_facts = [+ {+ "source": f"Node{i}",+ "target": f"Node{i + 1}",+ "relation": "connects_to",+ "description": f"Connection {i} " * 20,+ "alignment_score": 0.9,+ }+ for i in range(100)+ ]++ response = engine._synthesize_hybrid(+ query=huge_query,+ thematic_framing=huge_framing,+ verified_facts=huge_facts,+ )+ assert response == "Synthesized response (NodeA -[rel]-> NodeB)"+ assert mock_llm.generate.called+ prompt_used = mock_llm.generate.call_args[0][0]+ prompt_tokens = estimate_tokens(prompt_used, engine.token_counter)+ # Total prompt tokens must stay within max_context_tokens+ assert prompt_tokens <= 300+++def test_drift_generate_facets_respects_token_budget():+ engine = DriftSearchEngine(max_context_tokens=250, response_token_budget=50)+ mock_llm = MagicMock()+ mock_llm.generate_typed.return_value = []+ engine.llm = mock_llm++ huge_query = "Explore consensus nodes " * 40+ huge_framing = "Thematic context: " + ("deep background " * 100)++ engine._generate_facets(huge_query, huge_framing)+ assert mock_llm.generate_typed.called+ prompt_used = mock_llm.generate_typed.call_args[0][0]+ prompt_tokens = estimate_tokens(prompt_used, engine.token_counter)+ assert prompt_tokens <= 250+++# ---------------------------------------------------------------------------+# Issue 3: Named graph nodes return no facts+# ---------------------------------------------------------------------------+def test_drift_named_graph_nodes_alias_resolution_and_fact_retrieval():+ engine = DriftSearchEngine(drift_threshold=0.0)+ graph_dict = {+ "nodes": [+ {+ "id": "uuid-node-001",+ "name": "PostgreSQL",+ "aliases": ["postgres", "psql"],+ },+ {+ "id": "uuid-node-002",+ "name": "WAL Service",+ "label": "WAL",+ },+ ],+ "edges": [+ {+ "source": "uuid-node-001",+ "target": "uuid-node-002",+ "relation": "writes_to",+ "description": "PostgreSQL streams logs to WAL Service.",+ }+ ],+ }+ engine.set_knowledge_graph(graph_dict)++ assert engine._resolve_node_id("postgres") == "uuid-node-001"+ assert engine._resolve_node_id("psql") == "uuid-node-001"+ assert engine._resolve_node_id("PostgreSQL") == "uuid-node-001"+ assert engine._resolve_node_id("WAL") == "uuid-node-002"++ facets = [+ DriftFacet(+ sub_query="Inspect postgres replication",+ target_entities=["postgres"],+ relevance_score=1.0,+ )+ ]+ verified, depth, pruned = engine._traverse_and_prune(+ facets, "postgres replication", "framing"+ )+ assert len(verified) >= 1+ edge = verified[0]+ assert edge["source"] == "uuid-node-001"+ assert edge["target"] == "uuid-node-002"+ assert edge["source_name"] == "PostgreSQL"+ assert edge["target_name"] == "WAL Service"+++def test_drift_search_result_to_retrieved_contexts_uses_readable_names():+ res = DriftSearchResult(+ query="test query",+ answer="Test answer",+ global_reports_used=["comm_1"],+ verified_local_contexts=[+ {+ "source": "id_1",+ "target": "id_2",+ "relation": "MANAGES",+ "source_name": "Manager Service",+ "target_name": "Worker Node",+ "description": "Manager assigns tasks to Worker Node",+ "alignment_score": 0.85,+ }+ ],+ facets_explored=[],+ )+ contexts = res.to_retrieved_contexts()+ assert len(contexts) == 2 # answer + verified context+ ctx = contexts[1]+ assert "Manager Service" in ctx.content+ assert "Worker Node" in ctx.content+ assert ctx.metadata["source"] == "id_1"+ assert ctx.metadata["target"] == "id_2"+++# ---------------------------------------------------------------------------+# Issue 4: Zero-valued nodes lose their edges+# ---------------------------------------------------------------------------+def test_drift_zero_valued_nodes_preserve_edges():+ engine = DriftSearchEngine(drift_threshold=0.0)+ graph_dict = {+ "nodes": [+ {"id": 0, "name": "Node Zero Int"},+ {"id": 1, "name": "Node One"},+ ],+ "edges": [+ {+ "source": 0,+ "target": 1,+ "relation": "CONNECTS_INT_ZERO",+ "description": "Int 0 to 1",+ },+ ],+ }+ engine.set_knowledge_graph(graph_dict)++ assert "0" in engine._adjacency_index+ assert engine._node_meta.get("0") is not None+ assert engine._resolve_node_id(0) == "0"+ assert engine._resolve_node_id("0") == "0"++ edges = engine._adjacency_index.get("0", [])+ assert len(edges) >= 1+ assert any(e["relation"] == "CONNECTS_INT_ZERO" for e in edges)+++# ---------------------------------------------------------------------------+# Issue 5: Parallel graph facts disappear+# ---------------------------------------------------------------------------+def test_drift_parallel_edges_between_same_endpoints_preserved():+ engine = DriftSearchEngine(drift_threshold=0.0)+ graph_dict = {+ "nodes": [{"id": "svc_a"}, {"id": "svc_b"}],+ "edges": [+ {+ "id": "edge_auth",+ "source": "svc_a",+ "target": "svc_b",+ "relation": "AUTHENTICATES_WITH",+ "description": "Auth protocol",+ },+ {+ "id": "edge_telemetry",+ "source": "svc_a",+ "target": "svc_b",+ "relation": "STREAMS_METRICS_TO",+ "description": "Prometheus scrape",+ },+ ],+ }+ engine.set_knowledge_graph(graph_dict)++ svc_a_edges = [+ e for e in engine._adjacency_index.get("svc_a", [])+ if e.get("target") == "svc_b" and not e.get("is_inverse")+ ]+ assert len(svc_a_edges) == 2+ relations = {e["relation"] for e in svc_a_edges}+ assert relations == {"AUTHENTICATES_WITH", "STREAMS_METRICS_TO"}+++def test_drift_inverse_edge_preserves_canonical_id():+ engine = DriftSearchEngine(drift_threshold=0.0)+ graph_dict = {+ "nodes": [{"id": "node_x"}, {"id": "node_y"}],+ "edges": [+ {+ "id": "unique_edge_123",+ "source": "node_x",+ "target": "node_y",+ "relation": "CALLS",+ "description": "RPC call",+ }+ ],+ }+ engine.set_knowledge_graph(graph_dict)++ fwd_edge = next(+ e for e in engine._adjacency_index["node_x"]+ if e.get("target") == "node_y" and not e.get("is_inverse")+ )+ inv_edge = next(+ e for e in engine._adjacency_index["node_y"]+ if e.get("target") == "node_x" and e.get("is_inverse")+ )++ assert "unique_edge_123" in fwd_edge["canonical_id"]+ assert fwd_edge["canonical_id"] == inv_edge["canonical_id"]+++# ---------------------------------------------------------------------------+# Issue 6: Registered retrieval cannot be created+# ---------------------------------------------------------------------------+def test_algorithm_registry_global_retrieval_and_drift_search():+ reg = AlgorithmRegistry()+ global_cls = reg.get("global_retrieval")+ assert global_cls is GlobalGraphRetriever++ drift_cls = reg.get("drift_search")+ assert drift_cls is DriftSearchEngine++ global_inst = reg.create_instance("global_retrieval")+ assert isinstance(global_inst, GlobalGraphRetriever)++ drift_inst = reg.create_instance("drift_search")+ assert isinstance(drift_inst, DriftSearchEngine)++ # Test global singleton algorithm_registry instance+ assert algorithm_registry.get("global_retrieval") is GlobalGraphRetriever+ assert algorithm_registry.get("drift_search") is DriftSearchEngine+++# ---------------------------------------------------------------------------+# Issue 7: Hybrid results bypass score floor+# ---------------------------------------------------------------------------+def test_hybrid_retrieval_enforces_min_relevance_score_after_weighting():+ retriever = ContextRetriever(hybrid_alpha=0.5)++ # c_high raw score = 1.0 -> weighted score = 0.50 (>= 0.40)+ c_high = RetrievedContext(+ content="High relevance context",+ score=1.0,+ source="vector:high",+ )+ # c_low raw score = 0.60 -> weighted score = 0.30 (< 0.40)+ c_low = RetrievedContext(+ content="Low relevance context",+ score=0.60,+ source="vector:low",+ )++ with patch.object(+ retriever, "_retrieve_from_vector", return_value=[c_high, c_low]+ ), patch.object(+ retriever, "_retrieve_from_graph", return_value=[]+ ), patch.object(+ retriever, "retrieve_global", return_value=[]+ ):+ retriever.knowledge_graph = None+ results = retriever.retrieve(+ "test query",+ mode="hybrid",+ min_relevance_score=0.40,+ max_results=5,+ )++ assert len(results) == 1+ assert results[0].content == "High relevance context"+ assert results[0].score >= 0.40+++# ---------------------------------------------------------------------------+# Issue 8: Concurrent searches corrupt settings+# ---------------------------------------------------------------------------+def test_drift_search_does_not_mutate_engine_settings():+ engine = DriftSearchEngine(max_depth=2, drift_threshold=0.3)+ mock_llm = MagicMock()+ mock_llm.generate_typed.return_value = []+ mock_llm.generate.return_value = "Answer"+ engine.llm = mock_llm++ assert engine.max_depth == 2+ assert engine.drift_threshold == 0.3++ engine.search("query", max_depth=5, drift_threshold=0.85)++ assert engine.max_depth == 2+ assert engine.drift_threshold == 0.3+++# ---------------------------------------------------------------------------+# Issue 9: Valid drift results are filtered out+# ---------------------------------------------------------------------------+def test_context_retriever_retrieve_drift_scales_score_floor():+ retriever = ContextRetriever()+ search_result = DriftSearchResult(+ query="query",+ answer="Answer",+ global_reports_used=["c1"],+ verified_local_contexts=[+ {+ "source": "s1",+ "target": "t1",+ "relation": "REL1",+ "description": "High score fact",+ "alignment_score": 0.80,+ },+ {+ "source": "s2",+ "target": "t2",+ "relation": "REL2",+ "description": "Low score fact",+ "alignment_score": 0.30,+ },+ ],+ facets_explored=[],+ )++ with patch.object(+ DriftSearchEngine, "search", return_value=search_result+ ):+ # min_relevance_score=6.0 should scale to 0.60+ contexts = retriever.retrieve_drift(+ "query", min_relevance_score=6.0, as_contexts=True+ )+ assert len(contexts) >= 1+ assert all(c.score >= 0.60 for c in contexts)+ assert any(c.score == 0.80 for c in contexts)+ assert not any(c.score == 0.30 for c in contexts)+++# ---------------------------------------------------------------------------+# Issue 10: Report loading crashes global search+# ---------------------------------------------------------------------------+def test_community_report_none_and_non_string_findings_safe_handling():+ report = CommunityReport(+ community_id="c_err",+ level=0,+ title="Fault Tolerant",+ summary="Summary text",+ findings=[+ {"summary": None, "explanation": None, "weight": 5.0},+ {"summary": 12345, "explanation": {"detail": "nested"}, "weight": 7.0},+ ],+ member_entities=["NodeA"],+ )++ assert report.findings[0]["summary"] == ""+ assert report.findings[0]["explanation"] == ""+ assert report.findings[1]["summary"] == "12345"++ retriever = GlobalGraphRetriever()+ retriever.set_reports([report])++ tokens = retriever._estimate_report_tokens(report)+ assert tokens > 0++ points = retriever._map_report(report, "test query")+ assert isinstance(points, list)++ fallback_response = retriever._extractive_map_fallback(report, "test query")+ assert hasattr(fallback_response, "points")+ assert isinstance(fallback_response.points, list)+++def test_global_retriever_evidence_word_boundary_and_none_id():+ retriever = GlobalGraphRetriever()+ kp = [+ MapKeyPoint(+ community_id="c1",+ point="",+ description="Algorithm description",+ relevance_score=8.0,+ entities=["Go"],+ ),+ MapKeyPoint(+ community_id=None,+ point="Anonymous point",+ relevance_score=7.0,+ entities=["NodeX"],+ ),+ ]++ resp = "This algorithm executes in linear time."+ validated = retriever._ensure_evidence_citations(resp, kp)+ assert "[Community None]" not in validated+ assert "Sources / Evidence:" in validated+ assert "- [Community c1] (Entities: Go): Algorithm description" in validated+++def test_drift_budgeting_tight_limit_with_huge_query():+ # Facets prompt budgeting+ engine = DriftSearchEngine(max_context_tokens=150, response_token_budget=20)+ mock_llm = MagicMock()+ mock_llm.generate.return_value = "Answer"+ mock_llm.generate_typed.return_value = []+ engine.llm = mock_llm++ huge_query = "What is the consensus algorithm in a distributed system? " * 10+ huge_framing = "Global framing: " * 20++ engine._generate_facets(huge_query, huge_framing)+ prompt = mock_llm.generate_typed.call_args[0][0]+ prompt_tokens = estimate_tokens(prompt, engine.token_counter)+ assert prompt_tokens <= 150++ # Synthesis prompt budgeting+ engine2 = DriftSearchEngine(max_context_tokens=180, response_token_budget=20)+ engine2.llm = mock_llm+ huge_facts = [+ {+ "source": "A",+ "target": "B",+ "relation": "C",+ "description": "D" * 50,+ }+ ]+ engine2._synthesize_hybrid(huge_query, huge_framing, huge_facts)+ prompt2 = mock_llm.generate.call_args[0][0]+ prompt2_tokens = estimate_tokens(prompt2, engine2.token_counter)+ assert prompt2_tokens <= 180+++def test_drift_edge_id_zero_preservation():+ engine = DriftSearchEngine()+ graph = {+ "nodes": [{"id": 0, "name": "ZeroNode"}, {"id": 1, "name": "OneNode"}],+ "edges": [+ {+ "id": 0,+ "source": 0,+ "target": 1,+ "relation": "ZERO_EDGE",+ "description": "Edge 0",+ }+ ],+ }+ engine.set_knowledge_graph(graph)+ edge = engine._adjacency_index["0"][0]+ assert ":0" in edge["canonical_id"]+ assert edge.get("edge_id") == "0"+++def test_algorithm_registry_aliases_and_listing():+ reg = AlgorithmRegistry()+ for name in ("default", "global", "map_reduce"):+ assert reg.get("global_retrieval", name) is GlobalGraphRetriever+ inst = reg.create_instance("global_retrieval", name)+ assert isinstance(inst, GlobalGraphRetriever)++ for name in ("default", "drift", "hybrid"):+ assert reg.get("drift_search", name) is DriftSearchEngine+ inst = reg.create_instance("drift_search", name)+ assert isinstance(inst, DriftSearchEngine)++ global_names = algorithm_registry.list_category("global_retrieval")+ assert "default" in global_names+ assert "global" in global_names+ assert "map_reduce" in global_names++ drift_names = algorithm_registry.list_category("drift_search")+ assert "default" in drift_names+ assert "drift" in drift_names+ assert "hybrid" in drift_names+++def test_local_retrieval_scales_min_relevance_score():+ retriever = ContextRetriever()+ c1 = RetrievedContext(+ content="Context 1",+ score=0.8,+ source="vector:1",+ )+ c2 = RetrievedContext(+ content="Context 2",+ score=0.4,+ source="vector:2",+ )+ with patch.object(+ retriever, "_retrieve_from_vector", return_value=[c1, c2]+ ), patch.object(+ retriever, "_retrieve_from_graph", return_value=[]+ ):+ retriever.knowledge_graph = None+ # min_relevance_score=4.0 should scale to 0.40+ res = retriever.retrieve(+ "query", mode="local", min_relevance_score=4.0, max_results=5+ )+ assert len(res) == 1+ assert res[0].content == "Context 1"+ assert res[0].score >= 0.40