import logging
logger = logging.getLogger(__name__)
"""
Retrieval tools for the agentic system
Gap #1: HybridSearchTool — BM25 + Vector with RRF fusion
Gap #2: CommunitySummaryTool — LazyGraphRAG community summaries
Gap #6: Scoring utilities for Graph-of-Thought parallel exploration
"""

from typing import List, Dict, Any, Optional
import json
import asyncio
import hashlib

from ..core.neo4j_store import Neo4jStore
from ..core.llm_factory import UnifiedLLMProvider
from ..core.models import OntologySchema
from ..config import settings


# ── Gap #1: Hybrid Search Tool (BM25 + Vector + RRF) ───────────────────────

class HybridSearchTool:
    """
    Combines dense (vector) and sparse (BM25) retrieval via
    Reciprocal Rank Fusion (RRF) — the 2025 production standard.
    """

    def __init__(self, store: Neo4jStore, llm: UnifiedLLMProvider):
        self.store = store
        self.llm = llm
        self.name = "hybrid_search"
        self.description = (
            "Hybrid BM25 + vector search with RRF fusion. "
            "Best for most queries — handles both semantic and keyword matching."
        )

    async def run(
        self,
        query: str,
        k: int = None,
        filter: Optional[Dict] = None,
        document_id: Optional[str] = None,
        tenant_id: Optional[str] = None
    ) -> List[Dict[str, Any]]:
        """
        Run both BM25 and vector search in parallel, then fuse with RRF.

        Args:
            query: Natural language query
            k: Final number of results after fusion
            filter: Optional metadata filters
            document_id: Optional document scope

        Returns:
            RRF-fused results, highest-scored first
        """
        k = k or settings.default_top_k
        search_k = k * 3  # over-fetch for fusion

        # Run both searches in parallel
        query_embedding = await self.llm.embed(query)

        bm25_task = self.store.bm25_search(query, k=search_k, document_id=document_id, tenant_id=tenant_id)
        vector_task = self.store.search(
            query_vector=query_embedding,
            k=search_k,
            filter=filter or ({"document_id": document_id} if document_id else None),
            tenant_id=tenant_id
        )

        bm25_results, vector_results = await asyncio.gather(
            bm25_task, vector_task, return_exceptions=True
        )

        if isinstance(bm25_results, Exception):
            bm25_results = []
        if isinstance(vector_results, Exception):
            vector_results = []

        # RRF Fusion
        fused = self._rrf_fuse(
            list_a=vector_results,
            list_b=bm25_results,
            rrf_k=settings.rrf_k,
            weight_a=settings.hybrid_vector_weight,
            weight_b=settings.hybrid_bm25_weight
        )

        # Build final result list (top k)
        doc_lookup: Dict[str, Dict] = {}
        for r in vector_results + bm25_results:
            if r.get("id") and r["id"] not in doc_lookup:
                doc_lookup[r["id"]] = r

        final = []
        for chunk_id, score in fused[:k]:
            doc = doc_lookup.get(chunk_id, {})
            doc["hybrid_score"] = score
            doc["retrieval_method"] = "hybrid_rrf"
            final.append(doc)

        return final

    def _rrf_fuse(
        self,
        list_a: List[Dict],
        list_b: List[Dict],
        rrf_k: int = 60,
        weight_a: float = 1.0,
        weight_b: float = 1.0
    ) -> List[tuple]:
        """
        Weighted Reciprocal Rank Fusion.
        Returns sorted list of (id, score) tuples.
        """
        scores: Dict[str, float] = {}

        for rank, doc in enumerate(list_a):
            doc_id = doc.get("id", "")
            if doc_id:
                scores[doc_id] = scores.get(doc_id, 0.0) + weight_a / (rrf_k + rank + 1)

        for rank, doc in enumerate(list_b):
            doc_id = doc.get("id", "")
            if doc_id:
                scores[doc_id] = scores.get(doc_id, 0.0) + weight_b / (rrf_k + rank + 1)

        return sorted(scores.items(), key=lambda x: x[1], reverse=True)


# ── Legacy vector-only tool (kept for fallback/GoT) ─────────────────────────

class VectorSearchTool:
    """Vector similarity search tool — pure dense retrieval"""

    def __init__(self, store: Neo4jStore, llm: UnifiedLLMProvider):
        self.store = store
        self.llm = llm
        self.name = "vector_search"
        self.description = "Semantic similarity search. Good for conceptual/thematic queries."

    async def run(
        self,
        query: str,
        k: int = None,
        filter: Optional[Dict] = None,
        document_id: Optional[str] = None,
        tenant_id: Optional[str] = None
    ) -> List[Dict[str, Any]]:
        k = k or settings.default_top_k
        query_embedding = await self.llm.embed(query)
        
        final_filter = filter or {}
        if document_id:
            final_filter["document_id"] = document_id
            
        results = await self.store.search(
            query_vector=query_embedding,
            k=k,
            filter=final_filter if final_filter else None,
            tenant_id=tenant_id
        )
        for r in results:
            r["retrieval_method"] = "vector"
        return results


# ── Gap #2: Community Summary Tool (LazyGraphRAG) ───────────────────────────

class CommunitySummaryTool:
    """
    LazyGraphRAG-style community summarization.
    Detects entity clusters, generates LLM summaries at query time.
    Results are cached in Redis with configurable TTL.
    """

    def __init__(self, store: Neo4jStore, llm: UnifiedLLMProvider):
        self.store = store
        self.llm = llm
        self.name = "community_search"
        self.description = (
            "High-level thematic search using entity communities. "
            "Best for: 'What are the main themes?', 'Summarize the landscape', "
            "'What is the overall picture?'"
        )
        self._redis = None

    async def _get_redis(self):
        """Lazily initialize Redis connection for caching"""
        if self._redis is None:
            try:
                import redis.asyncio as aioredis
                self._redis = aioredis.from_url(settings.redis_url)
            except Exception:
                self._redis = None
        return self._redis

    async def run(
        self,
        query: str,
        k: int = None,
        tenant_id: Optional[str] = None
    ) -> List[Dict[str, Any]]:
        """
        Retrieves global community reports using vector search over community_embeddings.
        This provides a high-level thematic overview based on actual community findings.
        """
        k = k or 3  # Top-3 communities

        query_embedding = await self.llm.embed(query)
        if not query_embedding:
            return []

        tenant_filter = "WHERE node.tenant_id = $tenant_id" if tenant_id else ""
        cypher = f"""
        CALL db.index.vector.queryNodes('community_embeddings', $search_k, $query_embedding)
        YIELD node, score
        {tenant_filter}
        RETURN node.id as community_id, node.title as title, node.summary as summary, node.report_json as report_json, node.evidence_chunk_ids as evidence_chunk_ids, score
        LIMIT $k
        """

        params = {"search_k": k * 3, "k": k, "query_embedding": query_embedding}
        if tenant_id:
            params["tenant_id"] = tenant_id

        try:
            rows = await self.store.execute_query(cypher, params)
            results = []
            for row in rows:
                import json
                try:
                    report_data = json.loads(row.get("report_json") or "{}")
                    findings_list = report_data.get("findings", [])
                    findings_text = "; ".join(f.get("text", "") if isinstance(f, dict) else str(f) for f in findings_list)
                except Exception:
                    findings_text = ""
                
                evidence = row.get("evidence_chunk_ids", [])
                evidence_text = f"\nEvidence Chunks: {', '.join(evidence)}" if evidence else ""
                
                text = f"Title: {row.get('title', '')}\nSummary: {row.get('summary', '')}\nFindings: {findings_text}{evidence_text}"
                results.append({
                    "id": f"community_{row.get('community_id')}",
                    "text": text,
                    "community_id": row.get('community_id'),
                    "retrieval_method": "global_community_search",
                    "score": row.get("score", 0.0)
                })
                
            if results:
                return results
        except Exception as e:
            logger.error(f"Global community vector search failed: {e}")
            
        # Fallback to lazy community summarization
        results = []
        try:
            entity_names = await self._find_relevant_entities(query, limit=20, tenant_id=tenant_id)
            if entity_names:
                communities = await self.store.get_communities(entity_names, tenant_id=tenant_id)
                if communities:
                    for community_id, entities in list(communities.items())[:k]:
                        summary = await self._get_community_summary(community_id, entities, query)
                        if summary:
                            results.append({
                                "id": f"community_{community_id}",
                                "text": summary,
                                "community_id": community_id,
                                "entity_count": len(entities),
                                "retrieval_method": "community_summary_fallback",
                                "score": 0.85
                            })
        except Exception as e:
            logger.error(f"Lazy community fallback failed: {e}")
            
        return results

    async def _find_relevant_entities(self, query: str, limit: int = 20, tenant_id: Optional[str] = None) -> List[str]:
        """Find entity names most relevant to the query via BM25"""
        try:
            tenant_filter_node = "WHERE node.tenant_id = $tenant_id" if tenant_id else ""
            tenant_filter_entity = "{tenant_id: $tenant_id}" if tenant_id else ""
            cypher = f"""
            CALL db.index.fulltext.queryNodes('chunk_text_index', $query)
            YIELD node, score
            {tenant_filter_node}
            MATCH (node)-[:MENTIONS]->(e:Entity {tenant_filter_entity})
            RETURN DISTINCT e.name as name
            LIMIT $limit
            """
            params = {"query": query, "limit": limit}
            if tenant_id:
                params["tenant_id"] = tenant_id
            rows = await self.store.execute_query(cypher, params)
            return [r["name"] for r in rows if r.get("name")]
        except Exception:
            return []

    async def _get_community_summary(
        self,
        community_id: int,
        entities: List[Dict],
        query: str
    ) -> Optional[str]:
        """Generate or fetch cached LLM summary for a community"""
        # Build cache key from community entities
        entity_names = sorted([e.get("name", "") for e in entities])
        cache_key = f"community_summary:{hashlib.md5(':'.join(entity_names).encode()).hexdigest()}"

        # Check Redis cache
        redis = await self._get_redis()
        if redis:
            try:
                cached = await redis.get(cache_key)
                if cached:
                    return cached.decode("utf-8")
            except Exception:
                pass

        # Generate summary with LLM
        entity_descriptions = []
        for e in entities[:settings.max_community_entities]:
            desc = f"- {e.get('name', 'Unknown')} ({e.get('type', 'Entity')})"
            entity_descriptions.append(desc)

        prompt = f"""
You are analyzing a community of interconnected entities from a knowledge graph.

Community #{community_id} contains {len(entities)} entities:
{chr(10).join(entity_descriptions)}

User's question: "{query}"

Generate a focused 2-3 sentence summary of what this community represents and
how it relates to the question. Focus on themes, patterns, and key relationships.
Be specific and factual. Do not hallucinate relationships not implied by the entity names.
"""
        try:
            summary = await self.llm.complete(prompt, temperature=0.2)
            summary = summary.strip()

            # Cache the result
            if redis and summary:
                try:
                    await redis.setex(
                        cache_key,
                        settings.community_summary_cache_ttl,
                        summary.encode("utf-8")
                    )
                except Exception:
                    pass

            return summary
        except Exception as e:
            logger.info(f"Community summary generation error: {e}")
            return None


# ── Graph Traversal Tool ─────────────────────────────────────────────────────

class GraphTraversalTool:
    """Graph traversal and path finding tool"""

    def __init__(self, store: Neo4jStore, llm: UnifiedLLMProvider):
        self.store = store
        self.llm = llm
        self.name = "graph_traversal"
        self.description = "Traverse knowledge graph to find relationships and paths between entities"

    async def run(
        self,
        query: str,
        source_entity: Optional[str] = None,
        target_entity: Optional[str] = None,
        depth: int = None,
        tenant_id: Optional[str] = None
    ) -> List[Dict[str, Any]]:
        depth = depth or settings.graph_max_depth

        if not source_entity or not target_entity:
            entities = await self._extract_entities_from_query(query)
            if len(entities) >= 2:
                source_entity = source_entity or entities[0]
                target_entity = target_entity or entities[1]
            elif len(entities) == 1:
                source_entity = source_entity or entities[0]

        if source_entity and target_entity:
            results = await self.store.find_path(source_entity, target_entity, depth, tenant_id=tenant_id)
        elif source_entity:
            results = await self.store.get_neighbors(source_entity, depth, tenant_id=tenant_id)
        else:
            results = []

        for r in results:
            r["retrieval_method"] = "graph_traversal"
        return results

    async def _extract_entities_from_query(self, query: str) -> List[str]:
        """Extract entity names from natural language query"""
        prompt = f"""
Extract entity names from this query:
"{query}"

Return only a JSON list of entity names: ["Entity1", "Entity2", ...]
"""
        response = await self.llm.complete(prompt, temperature=0.1)
        try:
            cleaned = response.strip()
            if "```json" in cleaned:
                cleaned = cleaned.split("```json")[1].split("```")[0]
            elif "```" in cleaned:
                cleaned = cleaned.split("```")[1].split("```")[0]
            cleaned = cleaned.strip()
            entities = json.loads(cleaned)
            return entities if isinstance(entities, list) else []
        except Exception:
            return []


# ── Cypher Generation Tool ───────────────────────────────────────────────────

class CypherGenerationTool:
    """
    Text-to-Cypher tool with hallucination guards.
    Generates Cypher queries from natural language.
    """

    def __init__(
        self,
        store: Neo4jStore,
        llm: UnifiedLLMProvider,
        ontology: Optional[OntologySchema] = None
    ):
        self.store = store
        self.llm = llm
        self.ontology = ontology
        self.name = "cypher_query"
        self.description = "Generate and execute Cypher queries for complex structured graph queries"

    async def run(self, query: str, tenant_id: Optional[str] = None) -> List[Dict[str, Any]]:

        cypher = await self._generate_cypher(query, tenant_id)
        if not cypher:
            return []

        if tenant_id and tenant_id not in cypher:
            logger.warning("Cypher query rejected: Generated query did not include the required tenant_id filter.")
            return []

        if not self._validate_cypher(cypher):
            cypher = await self._correct_cypher(cypher, query)
            if not self._validate_cypher(cypher) or (tenant_id and tenant_id not in cypher):
                return []

        try:
            results = await self.store.execute_query(cypher)
            for r in results:
                r["retrieval_method"] = "cypher"
            return results
        except Exception as e:
            logger.info(f"Cypher execution error: {e}")
            cypher = await self._correct_cypher_with_error(cypher, query, str(e))
            try:
                results = await self.store.execute_query(cypher)
                for r in results:
                    r["retrieval_method"] = "cypher"
                return results
            except Exception:
                return []

    async def _generate_cypher(self, query: str, tenant_id: Optional[str] = None) -> str:
        schema_info = ""
        if self.ontology:
            schema_info = f"""
Graph Schema:
- Entity Types: {', '.join(self.ontology.entity_types)}
- Relationship Types: {', '.join(self.ontology.relationship_types)}
"""
        tenant_instruction = ""
        if tenant_id:
            tenant_instruction = f"7. ALWAYS filter by tenant_id = '{tenant_id}' on MATCHed nodes (e.g., `WHERE n.tenant_id = '{tenant_id}'`)."

        prompt = f"""
You are a Cypher query generator. Generate a READ-ONLY Cypher query for Neo4j.

Question: {query}
{schema_info}

Rules:
1. Only use entity labels and relationship types from the schema
2. Use MATCH clauses to find patterns
3. Use WHERE clauses for filtering
4. Return relevant data with RETURN clause
5. Add LIMIT 20 to prevent excessive results
6. DO NOT use CALL, CREATE, MERGE, SET, DELETE, DROP, REMOVE, or LOAD CSV. Read-only queries only.
{tenant_instruction}

Return only the Cypher query, no explanation.
"""
        response = await self.llm.complete(
            prompt,
            system_prompt="You generate syntactically correct Cypher queries for Neo4j.",
            temperature=0.1
        )
        cypher = response.strip()
        if "```cypher" in cypher:
            cypher = cypher.split("```cypher")[1].split("```")[0]
        elif "```" in cypher:
            cypher = cypher.split("```")[1].split("```")[0]
        return cypher.strip()

    def _validate_cypher(self, cypher: str) -> bool:
        if not cypher:
            return False
        cypher_upper = cypher.upper()
        if "MATCH" not in cypher_upper and "RETURN" not in cypher_upper:
            return False
        dangerous_keywords = ["CALL", "CREATE", "MERGE", "SET", "DELETE", "DROP", "REMOVE", "LOAD CSV"]
        for keyword in dangerous_keywords:
            # Check for exact word boundaries to prevent matching substring words
            import re
            if re.search(r'\b' + keyword + r'\b', cypher_upper):
                return False
        return True

    async def _correct_cypher(self, cypher: str, query: str) -> str:
        prompt = f"""
This Cypher query may have issues:
{cypher}

Original question: {query}
Fix any syntax errors or schema violations. Return only the corrected Cypher query.
"""
        response = await self.llm.complete(prompt, temperature=0.1)
        corrected = response.strip()
        if "```" in corrected:
            corrected = corrected.split("```")[1]
            if corrected.startswith("cypher"):
                corrected = corrected[6:]
            corrected = corrected.split("```")[0]
        return corrected.strip()

    async def _correct_cypher_with_error(self, cypher: str, query: str, error: str) -> str:
        prompt = f"""
This Cypher query failed with an error:

Query: {cypher}
Error: {error}

Original question: {query}
Fix the query to resolve the error. Return only the corrected Cypher.
"""
        response = await self.llm.complete(prompt, temperature=0.1)
        corrected = response.strip()
        if "```" in corrected:
            corrected = corrected.split("```")[1]
            if corrected.startswith("cypher"):
                corrected = corrected[6:]
            corrected = corrected.split("```")[0]
        return corrected.strip()


# ── Metadata Filter Tool ─────────────────────────────────────────────────────

class MetadataFilterTool:
    """Filter-based retrieval using metadata constraints"""

    def __init__(self, store: Neo4jStore):
        self.store = store
        self.name = "metadata_filter"
        self.description = "Filter entities or chunks by metadata attributes (date, type, source, etc.)"

    async def run(
        self,
        filters: Dict[str, Any],
        limit: int = 20
    ) -> List[Dict[str, Any]]:
        import re as _re
        # SECURITY: allowlist property key characters to prevent Cypher injection.
        # Keys must match Neo4j property naming rules: letters, digits, underscores only.
        _SAFE_KEY = _re.compile(r'^[A-Za-z_][A-Za-z0-9_]*$')
        where_clauses = []
        params: Dict[str, Any] = {}

        for i, (key, value) in enumerate(filters.items()):
            if not _SAFE_KEY.match(key):
                # Skip keys that don't match the allowlist — never interpolate them
                continue
            param_name = f"param_{i}"
            if isinstance(value, list):
                where_clauses.append(f"n.{key} IN ${param_name}")
            else:
                where_clauses.append(f"n.{key} = ${param_name}")
            params[param_name] = value

        where_clause = " AND ".join(where_clauses) if where_clauses else "true"

        query = f"""
        MATCH (n)
        WHERE {where_clause}
        RETURN n
        LIMIT $limit
        """
        params["limit"] = limit

        results = await self.store.execute_query(query, params)
        for r in results:
            r["retrieval_method"] = "metadata_filter"
        return results


# ── Gap #4: LLM-as-a-Judge Scorer ────────────────────────────────────────────

class LLMJudge:
    """
    LLM-as-a-Judge for real confidence scoring.
    Replaces the fake len(contexts)/top_k formula.
    """

    def __init__(self, llm: UnifiedLLMProvider):
        self.llm = llm

    async def score(
        self,
        query: str,
        answer: str,
        contexts: List[Dict[str, Any]]
    ) -> Dict[str, Any]:
        """
        Evaluate how well the answer is grounded in the retrieved contexts.

        Returns:
            {
                "score": float (0.0-1.0),
                "reasoning": str,
                "grounded_claims": int,
                "ungrounded_claims": int,
                "hallucination_risk": "low" | "medium" | "high"
            }
        """
        if not contexts or not answer:
            return {
                "score": 0.0,
                "reasoning": "No contexts or empty answer",
                "grounded_claims": 0,
                "ungrounded_claims": 0,
                "hallucination_risk": "high"
            }

        context_text = "\n\n".join([
            f"[Context {i+1}]: {ctx.get('text', str(ctx))[:400]}"
            for i, ctx in enumerate(contexts[:6])
        ])

        prompt = f"""You are an expert fact-checker evaluating whether an AI answer is grounded in source documents.

Question: {query}

AI Answer:
{answer[:600]}

Source Contexts:
{context_text}

Evaluate the answer. For each claim in the answer, check if it is directly supported by at least one context.

Rate the answer:
- 0.9-1.0: Every claim is clearly stated in the contexts (no hallucination)
- 0.7-0.9: Most claims supported, minor paraphrasing only
- 0.5-0.7: Some claims supported, some come from model training/inference
- 0.3-0.5: Many claims not traceable to contexts
- 0.0-0.3: Answer largely contradicts or ignores provided contexts

Return ONLY valid JSON (no markdown, no extra text):
{{"score": 0.85, "reasoning": "brief explanation", "grounded_claims": 4, "ungrounded_claims": 1}}"""

        try:
            response = await self.llm.complete(
                prompt,
                system_prompt="You are a strict factuality evaluator. Return only valid JSON.",
                temperature=settings.judge_temperature
            )
            cleaned = response.strip()
            # Strip any markdown code fences
            if "```" in cleaned:
                cleaned = cleaned.split("```")[1]
                if cleaned.startswith("json"):
                    cleaned = cleaned[4:]
                cleaned = cleaned.split("```")[0]
            data = json.loads(cleaned.strip())

            score = float(data.get("score", 0.5))
            grounded = int(data.get("grounded_claims", 0))
            ungrounded = int(data.get("ungrounded_claims", 0))

            if score >= 0.75:
                risk = "low"
            elif score >= 0.5:
                risk = "medium"
            else:
                risk = "high"

            return {
                "score": score,
                "reasoning": data.get("reasoning", ""),
                "grounded_claims": grounded,
                "ungrounded_claims": ungrounded,
                "hallucination_risk": risk
            }
        except Exception as e:
            logger.info(f"LLM Judge error: {e}")
            # Fallback: use a simple heuristic
            base_score = min(1.0, len(contexts) / max(settings.default_top_k, 1))
            return {
                "score": base_score,
                "reasoning": f"Heuristic score (judge unavailable: {e})",
                "grounded_claims": len(contexts),
                "ungrounded_claims": 0,
                "hallucination_risk": "medium" if base_score < 0.7 else "low"
            }


# ── Gap #8: RAG Evaluator ────────────────────────────────────────────────────

class RAGEvaluator:
    """
    RAGAS-style evaluation metrics for the quality dashboard.
    Computes faithfulness, answer_relevancy, context_precision.
    """

    def __init__(self, llm: UnifiedLLMProvider):
        self.llm = llm

    async def evaluate(
        self,
        question: str,
        answer: str,
        contexts: List[str],
        ground_truth: Optional[str] = None
    ) -> Dict[str, float]:
        """
        Run all evaluation metrics in parallel.
        Returns dict with metric scores.
        """
        tasks = [
            self._faithfulness(answer, contexts),
            self._answer_relevancy(question, answer),
            self._context_precision(question, contexts),
        ]

        results = await asyncio.gather(*tasks, return_exceptions=True)

        faithfulness = results[0] if not isinstance(results[0], Exception) else 0.5
        relevancy = results[1] if not isinstance(results[1], Exception) else 0.5
        precision = results[2] if not isinstance(results[2], Exception) else 0.5

        overall = (faithfulness * 0.4 + relevancy * 0.35 + precision * 0.25)

        return {
            "faithfulness": faithfulness,
            "answer_relevancy": relevancy,
            "context_precision": precision,
            "overall_score": overall,
            "hallucination_detected": faithfulness < 0.5
        }

    async def _faithfulness(self, answer: str, contexts: List[str]) -> float:
        """
        Measure: Are all claims in the answer supported by the contexts?
        """
        ctx_text = "\n".join([f"- {c[:300]}" for c in contexts[:5]])
        prompt = f"""Given these source contexts:
{ctx_text}

And this answer:
{answer[:400]}

Score from 0.0 to 1.0 how faithfully the answer is grounded in the contexts.
1.0 = every statement is supported. 0.0 = answer contradicts or ignores contexts.
Return ONLY a float number like: 0.82"""
        try:
            resp = await self.llm.complete(prompt, temperature=0.0)
            return float(resp.strip().split()[0])
        except Exception:
            return 0.5

    async def _answer_relevancy(self, question: str, answer: str) -> float:
        """
        Measure: Does the answer actually address the question?
        """
        prompt = f"""Question: {question}
Answer: {answer[:400]}

Score from 0.0 to 1.0 how relevant and complete the answer is for the question.
1.0 = fully answers the question. 0.0 = completely off-topic.
Return ONLY a float number like: 0.91"""
        try:
            resp = await self.llm.complete(prompt, temperature=0.0)
            return float(resp.strip().split()[0])
        except Exception:
            return 0.5

    async def _context_precision(self, question: str, contexts: List[str]) -> float:
        """
        Measure: Are the retrieved contexts useful for answering the question?
        """
        if not contexts:
            return 0.0
        ctx_text = "\n".join([f"[{i+1}]: {c[:200]}" for i, c in enumerate(contexts[:5])])
        prompt = f"""Question: {question}

Retrieved contexts:
{ctx_text}

Score from 0.0 to 1.0 how relevant and useful these contexts are for answering the question.
1.0 = all contexts are highly relevant. 0.0 = all contexts are irrelevant.
Return ONLY a float number like: 0.75"""
        try:
            resp = await self.llm.complete(prompt, temperature=0.0)
            return float(resp.strip().split()[0])
        except Exception:
            return 0.5


# ── MiroFish EntityEnricher: Entity Summary Search Tool ─────────────────────

class EntitySummarySearchTool:
    """
    Searches entity-level LLM summaries (from EntityEnricher) as a second
    retrieval layer alongside chunk-level vector/BM25 search.

    When entity summaries exist (e.summary IS NOT NULL), this tool embeds
    the query and searches against them via BM25 text fallback or filters.
    Complements HybridSearchTool which searches raw chunk text.
    """

    def __init__(self, store: Neo4jStore, llm: UnifiedLLMProvider) -> None:
        self.store = store
        self.llm = llm
        self.name = "entity_summary_search"
        self.description = (
            "Searches enriched entity profile summaries. "
            "Best for 'what is X?', 'tell me about Y', named-entity questions."
        )

    async def run(
        self,
        query: str,
        k: int = None,
        entity_type: Optional[str] = None,
        tenant_id: Optional[str] = None
    ) -> List[Dict[str, Any]]:
        """
        Find entities whose summaries are relevant to the query.

        Uses fulltext search on the chunk index to surface entity names,
        then fetches their summaries. Falls back to a simple CONTAINS match
        if fulltext gives no results.

        Args:
            query:       Natural language query
            k:           Max results (default from settings)
            entity_type: Optional filter by entity type

        Returns:
            List of context dicts with entity name, type, summary text
        """
        k = k or settings.default_top_k
        type_filter = "AND e.type = $entity_type" if entity_type else ""
        params: Dict[str, Any] = {"limit": k}
        if entity_type:
            params["entity_type"] = entity_type

        tenant_filter_bm25 = "WHERE node.tenant_id = $tenant_id" if tenant_id else ""
        tenant_filter_entity = "AND e.tenant_id = $tenant_id" if tenant_id else ""

        # Strategy 1: Use BM25 index to find relevant entities via chunk→entity links
        results: List[Dict[str, Any]] = []
        try:
            bm25_cypher = f"""
            CALL db.index.fulltext.queryNodes('chunk_text_index', $query)
            YIELD node, score
            {tenant_filter_bm25}
            MATCH (node)-[:MENTIONS]->(e:Entity)
            WHERE e.summary IS NOT NULL AND e.summary <> '' {tenant_filter_entity}
            {type_filter}
            RETURN DISTINCT e.name as name, e.type as type, e.summary as summary,
                   score
            ORDER BY score DESC
            LIMIT $limit
            """
            params["query"] = query
            if tenant_id:
                params["tenant_id"] = tenant_id
            rows = await self.store.execute_query(bm25_cypher, params)
            for r in rows:
                results.append({
                    "id": f"entity_summary:{r['name']}",
                    "text": f"[Entity: {r['name']} ({r['type']})] {r['summary']}",
                    "entity_name": r["name"],
                    "entity_type": r.get("type", "Entity"),
                    "summary": r["summary"],
                    "score": r.get("score", 0.8),
                    "retrieval_method": "entity_summary",
                })
        except Exception as exc:
            logger.info(f"[EntitySummarySearch BM25] {exc}")

        # Strategy 2: Fallback — keyword match on entity names in graph
        if not results:
            try:
                import re as _re
                # SECURITY: sanitize each word before string-interpolating into Cypher.
                # Allow basic punctuation to support terms like C++, Node.js, O'Connor.
                _safe_word = _re.compile(r"^[\w\s\-\.\+\'\"]+$")
                words = [
                    w for w in query.split()
                    if len(w) > 3 and _safe_word.match(w)
                ][:5]
                if words:
                    # Use parameterised toLower comparison — one param per word
                    conditions_parts = []
                    for j, w in enumerate(words):
                        p = f"word_{j}"
                        conditions_parts.append(f"toLower(e.name) CONTAINS ${p}")
                        params[p] = w.lower()
                    conditions = " OR ".join(conditions_parts)
                    tenant_filter_fallback = "AND e.tenant_id = $tenant_id" if tenant_id else ""
                    fallback_cypher = f"""
                    MATCH (e:Entity)
                    WHERE ({conditions}) AND e.summary IS NOT NULL AND e.summary <> '' {tenant_filter_fallback}
                    {type_filter}
                    RETURN e.name as name, e.type as type, e.summary as summary
                    LIMIT $limit
                    """
                    rows = await self.store.execute_query(fallback_cypher, params)
                    for r in rows:
                        results.append({
                            "id": f"entity_summary:{r['name']}",
                            "text": f"[Entity: {r['name']} ({r['type']})] {r['summary']}",
                            "entity_name": r["name"],
                            "entity_type": r.get("type", "Entity"),
                            "summary": r["summary"],
                            "score": 0.6,
                            "retrieval_method": "entity_summary_fallback",
                        })
            except Exception as exc:
                logger.info(f"[EntitySummarySearch fallback] {exc}")

        return results[:k]