Skip to content

Graph-Native Infrastructure for Context and Accountable AI Systems

Feat/pr 1548 global drift retrieval (#1628)

Zohaib Hassnaina7420916c083
diff --git a/semantica/cli.py b/semantica/cli.py
index 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]("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]("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__.py
index 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 AgentContext
from .agent_memory import AgentMemory, MemoryItem
from .context_graph import ContextEdge, ContextGraph, ContextNode
-from .context_retriever import ContextRetriever, RetrievedContext, TemporalGraphRetriever
+from .context_retriever import (
+ ContextRetriever,
+ RetrievedContext,
+ TemporalGraphRetriever,
+)
from .decision_context import DecisionContext
from .entity_linker import EntityLink, EntityLinker, LinkedEntity
from .erasure import ErasureCoordinator, ErasureReceipt
# Decision tracking imports
from .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 alias
diff --git a/semantica/context/context_graph.py b/semantica/context/context_graph.py
index 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.py
index 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 components
self.hybrid_calculator = HybridSimilarityCalculator()
self.decision_pipeline: Optional[DecisionEmbeddingPipeline] = None
-
+
# Initialize KG algorithms if knowledge graph available
if self.knowledge_graph:
self.path_finder = PathFinder()
@@ -170,7 +196,7 @@ class ContextRetriever:
self.centrality_calculator = None
self.community_detector = None
self.similarity_calculator = None
-
+
# Initialize decision pipeline if vector store available
if 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 results
use_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 retrieval
tracking_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_results
min_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=balanced
alpha = self.hybrid_alpha
for 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"] = True
for 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"] = True
for 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 -> result
seen_content = {} # content_hash -> result
- all_results = vector_results + graph_results + memory_results
+ all_results = vector_results + graph_results + memory_results + other_results
for 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 content
content_key = result.content[:100] if result.content else ""
@@ -830,8 +1086,11 @@ class ContextRetriever:
# Combine deduplicated results
merged_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 boost
diff --git a/semantica/context/drift_search.py b/semantica/context/drift_search.py
new file mode 100644
index 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.py
new file mode 100644
index 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.py
new file mode 100644
index 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.py
new file mode 100644
index 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.py
index 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 item
for 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.py
index 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 functions
diff --git a/semantica/kg/registry.py b/semantica/kg/registry.py
index 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 CommunitySummarizer
return 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 DriftSearchEngine
return 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 registry
algorithm_registry = AlgorithmRegistry()
diff --git a/semantica/utils/constants.py b/semantica/utils/constants.py
index 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 Codes
diff --git a/tests/cli/__init__.py b/tests/cli/__init__.py
new file mode 100644
index 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.py
new file mode 100644
index 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.output
diff --git a/tests/context/test_context_methods.py b/tests/context/test_context_methods.py
new file mode 100644
index 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_caps
diff --git a/tests/context/test_context_retriever_global_drift.py b/tests/context/test_context_retriever_global_drift.py
new file mode 100644
index 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_used
diff --git a/tests/context/test_drift_search.py b/tests/context/test_drift_search.py
new file mode 100644
index 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.py
new file mode 100644
index 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 words
diff --git a/tests/context/test_pr1548_review_fixes.py b/tests/context/test_pr1548_review_fixes.py
new file mode 100644
index 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.py
new file mode 100644
index 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