code-finder 0.1.0__py3-none-any.whl

claude_context/explorer_with_context.py

@@ -0,0 +1,1008 @@
+"""
+Interactive Explorer with External Context Support
+
+Extends the base InteractiveExplorer to integrate external context
+(requirements, tickets, docs) with code exploration.
+"""
+
+import logging
+from typing import List, Dict, Any, Optional, Tuple
+from dataclasses import dataclass, field
+from datetime import datetime
+
+from typing import Any
+from .explorer import (
+    ExplorationResult,
+    ConversationContext,
+    QuestionType,
+    QuestionClassifier
+)
+from .context_manager import ExternalContextManager, ContextItem
+from .search import SearchResult, HybridSearcher
+from .config import ClaudeContextConfig
+from .embeddings import LocalEmbeddings
+from .synthesis.providers import create_generator, TextGenerator
+from .query_metrics import QueryMetrics
+
+logger = logging.getLogger(__name__)
+
+
+@dataclass
+class EnhancedExplorationResult(ExplorationResult):
+    """Extended result that includes external context references"""
+    context_items: List[ContextItem] = field(default_factory=list)
+    context_citations: Dict[str, str] = field(default_factory=dict)
+    rationale_points: List[Dict[str, Any]] = field(default_factory=list)
+    rationale_results: List[SearchResult] = field(default_factory=list)
+    rationale_snippets: List[str] = field(default_factory=list)
+    
+    def format_with_context(self) -> str:
+        """Format the answer with context citations"""
+        formatted = self.answer
+        
+        # Add context citations
+        if self.context_citations:
+            formatted += "\n\n📚 Context References:"
+            for source, citation in self.context_citations.items():
+                formatted += f"\n  • {source}: {citation}"
+        
+        return formatted
+
+
+class InteractiveExplorerWithContext:
+    """
+    Enhanced explorer that combines code exploration with external context.
+    
+    This class composes the base explorer functionality with context management to:
+    1. Search external context (requirements, tickets) alongside code
+    2. Provide richer answers that explain both WHAT and WHY
+    3. Allow dynamic context addition during Q&A
+    """
+    
+    def __init__(
+        self,
+        searcher: HybridSearcher,
+        context_manager: Optional[ExternalContextManager] = None,
+        enable_llm_fallback: bool = True
+    ):
+        """
+        Initialize the context-aware explorer.
+
+        Args:
+            searcher: HybridSearcher instance for code search
+            context_manager: ExternalContextManager for context handling
+            enable_llm_fallback: Enable LLM-based query interpretation for conceptual questions
+        """
+        self.searcher = searcher
+        self.context_manager = context_manager or ExternalContextManager()
+        self.context_enabled = True
+        self.classifier = QuestionClassifier()
+        self.conversation_history = []
+        self.enable_llm_fallback = enable_llm_fallback
+
+        # Initialize LLM generator for query interpretation (lazy init)
+        self._llm_generator: Optional[TextGenerator] = None
+        self._last_concept_type: str = "unknown"  # Track concept type for result ranking
+        
+        # Initialize metrics tracking
+        self.metrics = QueryMetrics()
+
+        logger.info(f"InteractiveExplorerWithContext initialized (LLM fallback: {enable_llm_fallback})")
+    
+    def ask(self, question: str) -> EnhancedExplorationResult:
+        """
+        Enhanced ask method that searches both code and external context.
+
+        Uses a two-stage approach:
+        1. Fast keyword-based search (BM25 + vector)
+        2. If no results, fall back to LLM-based query interpretation
+
+        Args:
+            question: User's question
+
+        Returns:
+            EnhancedExplorationResult with code and context
+        """
+        # Classify the question
+        classification = self.classifier.classify(question)
+
+        candidate_results: List[SearchResult] = []
+
+        # Stage 1: Keyword-based search (fast path)
+        code_results = []
+        search_method = "keyword"
+
+        if classification.entities or classification.keywords:
+            # Search using entities and keywords
+            search_terms = list(classification.entities) + list(classification.keywords)
+            for term in search_terms[:3]:  # Limit searches
+                results = self.searcher.search(term, limit=3)
+                code_results.extend(results)
+
+            # FIX #1: Filter out import-only chunks (low value)
+            # FIX #2: Boost class/function definitions (high value)
+            filtered_results = []
+            for r in code_results:
+                # Skip pure import blocks
+                chunk_type = getattr(r, 'chunk_type', '')
+                if chunk_type == 'import_block':
+                    continue
+
+                # Boost definitions - these are more informative than imports
+                if any(keyword in (r.content or '') for keyword in ['class ', 'def ', 'async def ']):
+                    # Mark as boosted for prioritization
+                    r.boosted = True
+                else:
+                    r.boosted = False
+
+                filtered_results.append(r)
+
+            # Sort: boosted results first, then by original score
+            filtered_results.sort(key=lambda x: (not getattr(x, 'boosted', False), -getattr(x, 'score', 0)))
+
+            # Remove duplicates
+            seen = set()
+            unique_results = []
+            for r in filtered_results:
+                key = (r.file_path, r.start_line)
+                if key not in seen:
+                    seen.add(key)
+                    unique_results.append(r)
+            candidate_results = unique_results
+
+        # Stage 2: LLM-based query interpretation (fallback for conceptual questions)
+        if not candidate_results and self.enable_llm_fallback:
+            logger.info(f"Keyword search returned no results, using LLM interpretation for: '{question}'")
+            try:
+                interpreted_queries = self._llm_interpret_question(question)
+                if interpreted_queries:
+                    search_method = "llm-interpreted"
+                    llm_results: List[SearchResult] = []
+                    for query in interpreted_queries[:5]:  # Top 5 queries
+                        results = self.searcher.search(query, limit=3)
+                        llm_results.extend(results)
+
+                    # Apply same filtering as keyword search
+                    filtered_results = []
+                    for r in llm_results:
+                        chunk_type = getattr(r, 'chunk_type', '')
+                        if chunk_type == 'import_block':
+                            continue
+                        if any(keyword in (r.content or '') for keyword in ['class ', 'def ', 'async def ']):
+                            r.boosted = True
+                        else:
+                            r.boosted = False
+                        filtered_results.append(r)
+
+                    filtered_results.sort(key=lambda x: (not getattr(x, 'boosted', False), -getattr(x, 'score', 0)))
+
+                    # Remove duplicates
+                    seen = set()
+                    unique_results = []
+                    for r in filtered_results:
+                        key = (r.file_path, r.start_line)
+                        if key not in seen:
+                            seen.add(key)
+                            unique_results.append(r)
+                    candidate_results = unique_results
+
+                    logger.info(f"LLM interpretation generated {len(interpreted_queries)} queries, found {len(candidate_results)} results")
+                    
+                    # Rank results by importance if we have concept type
+                    if hasattr(self, '_last_concept_type') and self._last_concept_type != "unknown":
+                        candidate_results = self._rank_by_importance(candidate_results, self._last_concept_type)
+                        logger.info(f"Results re-ranked by importance (concept: {self._last_concept_type})")
+                        
+            except Exception as e:
+                logger.warning(f"LLM interpretation failed: {e}")
+
+        code_results, rationale_results = self._separate_rationale(candidate_results)
+
+        # Build base answer from code
+        base_answer = self._build_code_answer(question, classification, code_results, search_method)
+        base_answer, rationale_points, rationale_snippets = self._augment_with_rationale(base_answer, rationale_results, None)
+
+        # Calculate confidence based on results found
+        # Boost confidence if LLM interpretation found results
+        initial_confidence = classification.confidence
+        if search_method == "llm-interpreted" and candidate_results:
+            # LLM interpretation succeeded - boost confidence significantly
+            initial_confidence = max(0.6, min(0.8, 0.5 + (len(candidate_results) * 0.1)))
+            logger.info(f"LLM interpretation found {len(candidate_results)} results, confidence boosted to {initial_confidence:.0%}")
+        elif candidate_results:
+            # Keyword search succeeded - use higher of classification confidence or result-based
+            result_confidence = min(0.9, 0.5 + (len(candidate_results) * 0.08))
+            initial_confidence = max(classification.confidence, result_confidence)
+
+        combined_rationale_points = list(rationale_points)
+
+        # Create enhanced result
+        enhanced_result = EnhancedExplorationResult(
+            question=question,
+            answer=base_answer,
+            question_type=classification.primary_type,
+            confidence=initial_confidence,
+            code_results=code_results,
+            follow_up_suggestions=[classification.suggested_approach],
+            entities_found=classification.entities,
+            rationale_points=combined_rationale_points,
+            rationale_results=rationale_results,
+            rationale_snippets=rationale_snippets
+        )
+        
+        # Search external context if available
+        if self.context_manager.total_items > 0:
+            context_results = self._search_context(question)
+            if context_results:
+                enhanced_answer, context_rationale = self._enhance_with_context(
+                    enhanced_result,
+                    context_results
+                )
+                enhanced_result.answer = enhanced_answer
+                enhanced_result.context_items = [item for item, _ in context_results]
+                enhanced_result.context_citations = self._extract_citations(context_results)
+                combined_rationale_points.extend(context_rationale)
+                
+                # Boost confidence if we have supporting context
+                if enhanced_result.confidence < 0.9 and context_results:
+                    enhanced_result.confidence = min(0.9, enhanced_result.confidence + 0.2)
+        
+        enhanced_result.rationale_points = combined_rationale_points
+
+        # Update conversation history
+        self.conversation_history.append(enhanced_result)
+        
+        # Log metrics for monitoring
+        self.metrics.log_question(
+            question=question,
+            used_llm=(search_method == "llm-interpreted"),
+            results_count=len(candidate_results),
+            confidence=enhanced_result.confidence
+        )
+        
+        return enhanced_result
+    
+    def _rank_by_importance(self, results: List[SearchResult], concept_type: str) -> List[SearchResult]:
+        """
+        Rank search results by importance to codebase.
+        
+        Generic approach: Prioritizes core functionality over extension points
+        based on file path patterns that work across domains.
+        
+        Args:
+            results: Search results to rank
+            concept_type: Type of concept (core_functionality, extension_point, etc.)
+            
+        Returns:
+            Re-ranked results with core functionality prioritized
+        """
+        if not results:
+            return results
+        
+        ranked = []
+        
+        for result in results:
+            score = getattr(result, 'combined_score', 0.5)
+            
+            # Boost core functionality files (generic patterns)
+            if concept_type == "core_functionality":
+                core_patterns = [
+                    "/models/", "/core/", "/engine/", "/lib/",
+                    "/trainer/", "/inference/", "/quantization/",
+                    "/controllers/", "/operators/", "/api/",
+                    "/src/main/", "/pkg/core/"
+                ]
+                if any(pattern in result.file_path for pattern in core_patterns):
+                    score *= 1.5  # 50% boost for core files
+                    logger.debug(f"Boosted core file: {result.file_path}")
+            
+            # De-prioritize peripheral files
+            peripheral_patterns = [
+                "/examples/", "/tests/", "/test/", 
+                "/plugins/", "/extensions/", "/contrib/",
+                "/demos/", "/samples/", "/benchmarks/"
+            ]
+            if any(pattern in result.file_path for pattern in peripheral_patterns):
+                score *= 0.7  # 30% penalty for peripheral files
+                logger.debug(f"De-prioritized peripheral file: {result.file_path}")
+            
+            # Boost based on chunk type
+            chunk_type = getattr(result, 'chunk_type', '')
+            if chunk_type in ['class', 'function', 'method']:
+                score *= 1.2  # Prefer actual implementation over imports/comments
+            
+            ranked.append((result, score))
+        
+        # Sort by adjusted score
+        ranked.sort(key=lambda x: x[1], reverse=True)
+        
+        return [r for r, _ in ranked]
+    
+    def _llm_interpret_question(self, question: str) -> List[str]:
+        """
+        Use LLM to interpret a conceptual question and generate search queries.
+        
+        ENHANCED: Now uses structured JSON response with domain understanding,
+        concept type detection, and reasoning.
+
+        Args:
+            question: User's conceptual question
+
+        Returns:
+            List of search queries to try
+        """
+        # Lazy init LLM generator
+        if self._llm_generator is None:
+            try:
+                self._llm_generator = create_generator()
+            except Exception as e:
+                logger.warning(f"Could not initialize LLM generator: {e}")
+                return []
+
+        system_prompt = """You are a code search expert who understands diverse technical domains.
+
+Given a user's question, generate targeted search queries by understanding:
+- Domain context (AI/ML, Kubernetes, web frameworks, CLI tools, etc.)
+- Core functionality vs extension points
+- Domain-specific terminology
+- File organization patterns
+
+Return JSON with structured search strategy:
+{
+  "primary_terms": ["most_relevant_terms_for_domain"],
+  "secondary_terms": ["related_concepts"],
+  "file_hints": ["likely_file_patterns"],
+  "concept_type": "core_functionality|extension_point|utility|configuration",
+  "reasoning": "Brief explanation of search strategy"
+}
+
+Examples:
+
+Q: "How does quantization work?"
+A: {
+  "primary_terms": ["quantize", "quantization", "int8"],
+  "secondary_terms": ["precision", "calibration", "weight compression"],
+  "file_hints": ["**/quant*.py", "**/compress*.py"],
+  "concept_type": "core_functionality",
+  "reasoning": "Quantization is core ML optimization, typically in dedicated modules"
+}
+
+Q: "How do I configure the operator?"
+A: {
+  "primary_terms": ["ConfigMap", "configuration", "config"],
+  "secondary_terms": ["environment", "settings", "parameters"],
+  "file_hints": ["config/samples/*.yaml", "**/config*.go"],
+  "concept_type": "configuration",
+  "reasoning": "K8s operators use ConfigMaps for configuration"
+}
+
+Q: "How do I add a custom plugin?"
+A: {
+  "primary_terms": ["register", "plugin", "extension"],
+  "secondary_terms": ["hook", "interface", "registry"],
+  "file_hints": ["**/plugins/*.py", "**/registry.py"],
+  "concept_type": "extension_point",
+  "reasoning": "Plugin systems use registration patterns"
+}
+
+Return ONLY valid JSON, no markdown formatting."""
+
+        user_prompt = f"Question: {question}\n\nGenerate search strategy JSON:"
+
+        try:
+            response = self._llm_generator.generate(
+                system_prompt=system_prompt,
+                user_prompt=user_prompt,
+                temperature=0.3,
+                max_tokens=300  # Increased for JSON response
+            )
+
+            # Try to parse JSON response
+            try:
+                import json
+                # Clean response (remove markdown if present)
+                cleaned = response.strip()
+                if cleaned.startswith("```json"):
+                    cleaned = cleaned[7:]
+                if cleaned.startswith("```"):
+                    cleaned = cleaned[3:]
+                if cleaned.endswith("```"):
+                    cleaned = cleaned[:-3]
+                cleaned = cleaned.strip()
+                
+                parsed = json.loads(cleaned)
+                
+                # Extract queries with priority
+                queries = parsed.get("primary_terms", [])[:3]
+                queries.extend(parsed.get("secondary_terms", [])[:2])
+                
+                # Store metadata for ranking
+                self._last_concept_type = parsed.get("concept_type", "unknown")
+                
+                # Log reasoning for monitoring
+                reasoning = parsed.get("reasoning", "No reasoning provided")
+                logger.info(f"LLM search strategy:")
+                logger.info(f"  Concept type: {self._last_concept_type}")
+                logger.info(f"  Reasoning: {reasoning}")
+                logger.info(f"  Queries: {queries}")
+                
+                return queries[:5]
+                
+            except json.JSONDecodeError as e:
+                # Fallback to comma-separated parsing
+                logger.warning(f"JSON parsing failed, falling back to comma-separated: {e}")
+                queries = [q.strip() for q in response.split(',')]
+                queries = [q for q in queries if q and len(q) > 2]
+                logger.info(f"LLM generated queries (fallback): {queries}")
+                return queries[:5]
+
+        except Exception as e:
+            logger.warning(f"LLM query generation failed: {e}")
+            return []
+
+    def _build_code_answer(self, question: str, classification, code_results: List[SearchResult], search_method: str = "keyword") -> str:
+        """
+        Build an answer based on code search results.
+
+        Args:
+            question: The original question
+            classification: Question classification
+            code_results: Code search results
+            search_method: How results were found ("keyword" or "llm-interpreted")
+
+        Returns:
+            Answer string
+        """
+        if not code_results:
+            suggestion = "Try rephrasing with more specific terms."
+            if search_method == "llm-interpreted":
+                suggestion = "Even with AI interpretation, I couldn't find relevant code. The codebase might not contain this functionality."
+            return f"I couldn't find specific code related to '{question}'. {suggestion}"
+        
+        # Build answer based on question type
+        if classification.primary_type == QuestionType.DISCOVERY:
+            answer = "Based on the codebase:\n\n"
+            for result in code_results[:3]:
+                answer += f"• **{result.file_name}** ({result.language}): "
+                answer += f"Lines {result.start_line}-{result.end_line}\n"
+                if result.chunk_type:
+                    answer += f"  Type: {result.chunk_type}\n"
+        
+        elif classification.primary_type == QuestionType.DEFINITION:
+            answer = f"Here's what I found:\n\n"
+            result = code_results[0]
+            answer += f"**{result.file_name}:{result.start_line}**\n"
+            answer += f"```{result.language}\n{result.content[:200]}...\n```"
+        
+        elif classification.primary_type == QuestionType.RELATIONSHIP:
+            answer = "Code relationships found:\n\n"
+            for result in code_results[:3]:
+                answer += f"• {result.file_name}: {result.chunk_type or 'code'}\n"
+        
+        else:
+            # Generic answer
+            answer = f"Found {len(code_results)} relevant code sections:\n\n"
+            for result in code_results[:3]:
+                answer += f"• {result.file_name}:{result.start_line}\n"
+        
+        return answer
+    
+    def _search_context(self, question: str) -> List[Tuple[ContextItem, float]]:
+        """
+        Search external context for relevant information.
+        
+        Args:
+            question: Search query
+            
+        Returns:
+            List of (ContextItem, relevance_score) tuples
+        """
+        try:
+            return self.context_manager.search_context(question, limit=3)
+        except Exception as e:
+            logger.warning(f"Context search failed: {e}")
+            return []
+    
+    def _enhance_with_context(
+        self,
+        base_result: ExplorationResult,
+        context_results: List[Tuple[ContextItem, float]]
+    ) -> Tuple[str, List[Dict[str, Any]]]:
+        """
+        Enhance the base answer with context information.
+        
+        Args:
+            base_result: Original code-based result
+            context_results: Relevant context items
+            
+        Returns:
+            Tuple of (enhanced answer, rationale points)
+        """
+        enhanced = base_result.answer
+        rationale_points: List[Dict[str, Any]] = []
+
+        if context_results:
+            enhanced, rationale_points = self._restructure_answer_with_context(
+                base_result,
+                context_results
+            )
+
+        return enhanced, rationale_points
+    
+    def _restructure_answer_with_context(
+        self,
+        base_result: ExplorationResult,
+        context_results: List[Tuple[ContextItem, float]]
+    ) -> Tuple[str, List[Dict[str, Any]]]:
+        """
+        Restructure the answer to integrate context naturally.
+        
+        Args:
+            base_result: Original result
+            context_results: Context items to integrate
+            
+        Returns:
+            Tuple of (restructured answer, rationale entries)
+        """
+        question_type = base_result.question_type if hasattr(base_result, 'question_type') else QuestionType.DISCOVERY
+        rationale_points: List[Dict[str, Any]] = []
+        
+        if question_type == QuestionType.REASONING:
+            return self._build_reasoning_answer_with_context(base_result, context_results)
+        elif question_type == QuestionType.DISCOVERY:
+            return self._build_discovery_answer_with_context(base_result, context_results)
+        elif question_type == QuestionType.RELATIONSHIP:
+            return self._build_relationship_answer_with_context(base_result, context_results)
+        else:
+            # For other types, append context at the end
+            return self._append_context_to_answer(base_result, context_results)
+    
+    def _build_reasoning_answer_with_context(
+        self,
+        base_result: ExplorationResult,
+        context_results: List[Tuple[ContextItem, float]]
+    ) -> Tuple[str, List[Dict[str, Any]]]:
+        """Build a reasoning answer that integrates context naturally."""
+
+        lines = ["Based on code analysis and project context:\n"]
+        rationale_points: List[Dict[str, Any]] = []
+
+        for item, score in context_results:
+            if item.type == "requirements":
+                lines.append(f"📄 **Requirement**: {item.get_summary()}")
+                if "acceptance" in item.content.lower():
+                    for line in item.content.split('\n'):
+                        if "acceptance" in line.lower() or "must" in line.lower():
+                            snippet = line.strip()
+                            lines.append(f"   → {snippet}")
+                            rationale_points.append(self._make_rationale_entry(item, snippet))
+                else:
+                    rationale_points.append(self._make_rationale_entry(item, "Requirement informing implementation"))
+
+            elif item.type == "tickets":
+                ticket_id = item.metadata.get("ticket_id", "Ticket")
+                summary = item.get_summary()
+                lines.append(f"🎫 **{ticket_id}**: {summary}")
+                rationale_points.append(self._make_rationale_entry(item, summary))
+                if "decision" in item.content.lower() or "chose" in item.content.lower():
+                    lines.append("   → Decision documented in ticket")
+
+            elif item.type == "design_docs":
+                summary = item.get_summary()
+                lines.append(f"📐 **Design Doc**: {summary}")
+                rationale_points.append(self._make_rationale_entry(item, summary))
+
+            elif item.type == "decisions":
+                summary = item.get_summary()
+                lines.append(f"🤔 **Decision**: {summary}")
+                content_lower = item.content.lower()
+                if "latency" in content_lower:
+                    detail = "Latency requirement referenced"
+                    lines.append(f"   → {detail}")
+                    rationale_points.append(self._make_rationale_entry(item, detail))
+                else:
+                    rationale_points.append(self._make_rationale_entry(item, summary))
+
+        lines.append("\n💻 **Implementation**:")
+        if base_result.code_results:
+            for result in base_result.code_results[:2]:
+                impl_note = f"Implements context in {result.file_name}:{result.start_line}"
+                lines.append(f"   • {result.file_name}:{result.start_line} - implements the requirement")
+                rationale_points.append({
+                    "source": f"{result.file_path}:{result.start_line}",
+                    "note": impl_note
+                })
+
+        if "because" in base_result.answer.lower():
+            lines.append("\n" + base_result.answer)
+
+        augmented, extra_points, _ = self._augment_with_rationale("\n".join(lines), base_result.rationale_results if isinstance(base_result, EnhancedExplorationResult) else [], lines)
+        rationale_points.extend(extra_points)
+        return augmented, rationale_points
+
+    def _build_discovery_answer_with_context(
+        self,
+        base_result: ExplorationResult,
+        context_results: List[Tuple[ContextItem, float]]
+    ) -> Tuple[str, List[Dict[str, Any]]]:
+        """Build a discovery answer enriched with context."""
+
+        lines = [base_result.answer]
+        rationale_points: List[Dict[str, Any]] = []
+
+        context_additions = []
+        for item, score in context_results:
+            if item.type == "requirements" and (
+                "feature" in item.content.lower() or "component" in item.content.lower()
+            ):
+                summary = item.get_summary()
+                context_additions.append(f"📄 Requirements mention: {summary}")
+                rationale_points.append(self._make_rationale_entry(item, summary))
+            elif item.type == "tickets" and "implement" in item.content.lower():
+                ticket_id = item.metadata.get("ticket_id", "Ticket")
+                summary = item.get_summary()
+                context_additions.append(f"🎫 {ticket_id}: {summary}")
+                rationale_points.append(self._make_rationale_entry(item, summary))
+
+        if context_additions:
+            lines.append("\n📚 **Additional Context**:")
+            lines.extend(f"   {addition}" for addition in context_additions)
+
+        augmented, extra_points, _ = self._augment_with_rationale("\n".join(lines), base_result.rationale_results if isinstance(base_result, EnhancedExplorationResult) else [], lines)
+        rationale_points.extend(extra_points)
+        return augmented, rationale_points
+
+    def _build_relationship_answer_with_context(
+        self,
+        base_result: ExplorationResult,
+        context_results: List[Tuple[ContextItem, float]]
+    ) -> Tuple[str, List[Dict[str, Any]]]:
+        """Build a relationship answer with context about why relationships exist."""
+
+        lines = [base_result.answer]
+        rationale_points: List[Dict[str, Any]] = []
+
+        if context_results:
+            lines.append("\n📚 **Context for these relationships**:")
+            for item, score in context_results:
+                if item.type == "design_docs":
+                    summary = item.get_summary()
+                    lines.append(f"   📐 Architecture: {summary}")
+                    rationale_points.append(self._make_rationale_entry(item, summary))
+                elif item.type == "tickets" and (
+                    "integration" in item.content.lower() or "connect" in item.content.lower()
+                ):
+                    ticket_id = item.metadata.get("ticket_id", "Ticket")
+                    summary = item.get_summary()
+                    lines.append(f"   🎫 {ticket_id}: {summary}")
+                    rationale_points.append(self._make_rationale_entry(item, summary))
+
+        augmented, extra_points, _ = self._augment_with_rationale("\n".join(lines), base_result.rationale_results if isinstance(base_result, EnhancedExplorationResult) else [], lines)
+        rationale_points.extend(extra_points)
+        return augmented, rationale_points
+
+    def _augment_with_rationale(
+        self,
+        base_answer: str,
+        rationale_results: List[SearchResult],
+        existing_lines: Optional[List[str]] = None
+    ) -> Tuple[str, List[Dict[str, Any]], List[str]]:
+        """Append rationale evidence from search results to the answer."""
+
+        if not rationale_results:
+            return base_answer, [], []
+
+        lines = (existing_lines[:] if existing_lines is not None else [base_answer.rstrip()])
+        if lines and lines[-1] != "":
+            lines.append("")
+        lines.append("🧠 **Rationale Evidence:**")
+        points: List[Dict[str, Any]] = []
+        snippets: List[str] = []
+
+        for result in rationale_results[:3]:
+            snippet = (result.content or "").strip().split("\n", 1)[0][:220]
+            if not snippet:
+                snippet = getattr(result, "chunk_name", "") or str(getattr(result, "chunk_type", "rationale"))
+            source = result.file_path or "rationale"
+            lines.append(f"• {source}: {snippet}")
+            points.append({
+                "source": f"{result.file_path}:{result.start_line}-{result.end_line}" if result.file_path else source,
+                "note": snippet,
+                "type": getattr(result, "chunk_type", "rationale"),
+            })
+            snippets.append(snippet)
+
+        return "\n".join(lines), points, snippets
+
+    def _separate_rationale(
+        self,
+        results: List[SearchResult]
+    ) -> Tuple[List[SearchResult], List[SearchResult]]:
+        """Split raw search results into code vs rationale buckets."""
+
+        code_results: List[SearchResult] = []
+        rationale_results: List[SearchResult] = []
+
+        for result in results or []:
+            if self._is_rationale_result(result):
+                rationale_results.append(result)
+            else:
+                code_results.append(result)
+
+        return code_results[:5], rationale_results[:3]
+
+    @staticmethod
+    def _is_rationale_result(result: SearchResult) -> bool:
+        chunk_type = str(getattr(result, "chunk_type", "") or "")
+        return chunk_type.startswith("rationale")
+
+    def _append_context_to_answer(
+        self,
+        base_result: ExplorationResult,
+        context_results: List[Tuple[ContextItem, float]]
+    ) -> Tuple[str, List[Dict[str, Any]]]:
+        """Generic method to append context to any answer type."""
+        
+        lines = [base_result.answer]
+        rationale_points: List[Dict[str, Any]] = []
+        
+        if context_results:
+            lines.append("\n📚 **Related Context**:")
+            for item, score in context_results[:2]:
+                source = self._format_context_source(item)
+                summary = item.get_summary()
+                lines.append(f"   • {source}: {summary}")
+                rationale_points.append(self._make_rationale_entry(item, summary))
+        
+        augmented, extra_points, _ = self._augment_with_rationale("\n".join(lines), base_result.rationale_results if isinstance(base_result, EnhancedExplorationResult) else [], lines)
+        rationale_points.extend(extra_points)
+        
+        return augmented, rationale_points
+    
+    def _format_context_source(self, item: ContextItem) -> str:
+        """Format the source of a context item for display."""
+        if item.type == "tickets":
+            return f"🎫 {item.metadata.get('ticket_id', 'Ticket')}"
+        elif item.type == "requirements":
+            return "📄 Requirements"
+        elif item.type == "design_docs":
+            return "📐 Design"
+        elif item.type == "decisions":
+            return "🤔 Decision"
+        else:
+            return "📋 Context"
+    
+    def _extract_citations(self, context_results: List[Tuple[ContextItem, float]]) -> Dict[str, str]:
+        """
+        Extract citations from context results for reference.
+        
+        Args:
+            context_results: Context items with scores
+            
+        Returns:
+            Dictionary of source -> citation
+        """
+        citations = {}
+        for item, score in context_results:
+            source = self._format_context_source(item)
+            
+            # Extract a meaningful citation
+            if item.type == "tickets" and "ticket_id" in item.metadata:
+                citations[item.metadata["ticket_id"]] = item.get_summary()
+            elif item.type == "requirements" and item.source:
+                citations[item.source] = item.get_summary()
+            else:
+                citations[f"{item.type}_{item.id[:8]}"] = item.get_summary()
+        
+        return citations
+
+    def _make_rationale_entry(self, item: ContextItem, note: str) -> Dict[str, Any]:
+        """Create a normalized rationale entry leveraging context metadata."""
+        return {
+            "context_id": item.id,
+            "source": item.source or self._format_context_source(item),
+            "type": item.type,
+            "summary": item.get_summary(),
+            "note": note,
+        }
+    
+    def add_context_interactive(self) -> bool:
+        """
+        Interactive method to add context during Q&A session.
+        
+        Returns:
+            True if context was added, False if cancelled
+        """
+        print("\n📋 Add Context")
+        print("1. Paste text directly")
+        print("2. Add file/document")
+        print("3. Add Jira ticket (manual entry)")
+        print("4. Cancel")
+        
+        choice = input("\nChoice [1-4]: ").strip()
+        
+        if choice == "1":
+            return self._add_text_context()
+        elif choice == "2":
+            return self._add_file_context()
+        elif choice == "3":
+            return self._add_ticket_context()
+        else:
+            return False
+    
+    def _add_text_context(self) -> bool:
+        """Add context by pasting text."""
+        print("\nPaste your text (enter '###' on a new line when done):")
+        lines = []
+        while True:
+            line = input()
+            if line.strip() == "###":
+                break
+            lines.append(line)
+        
+        if not lines:
+            print("No text provided.")
+            return False
+        
+        content = "\n".join(lines)
+        title = input("Brief title for this context: ").strip()
+        
+        context_type = self._select_context_type()
+        
+        try:
+            context_id = self.context_manager.add_context(
+                context_type=context_type,
+                content=content,
+                metadata={"title": title} if title else {},
+                source="manual_entry"
+            )
+            print(f"✅ Added context: {context_id}")
+            return True
+        except Exception as e:
+            print(f"❌ Failed to add context: {e}")
+            return False
+    
+    def _add_file_context(self) -> bool:
+        """Add context from a file."""
+        file_path = input("File path: ").strip()
+        context_type = self._select_context_type()
+        
+        try:
+            context_id = self.context_manager.add_file(file_path, context_type)
+            print(f"✅ Added file context: {context_id}")
+            return True
+        except Exception as e:
+            print(f"❌ Failed to add file: {e}")
+            return False
+    
+    def _add_ticket_context(self) -> bool:
+        """Add a ticket as context."""
+        ticket_id = input("Ticket ID (e.g., PROJ-123): ").strip()
+        summary = input("Summary: ").strip()
+        print("Description (enter '###' on a new line when done):")
+        
+        lines = []
+        while True:
+            line = input()
+            if line.strip() == "###":
+                break
+            lines.append(line)
+        
+        description = "\n".join(lines)
+        
+        try:
+            context_id = self.context_manager.add_jira_ticket(
+                ticket_id=ticket_id,
+                summary=summary,
+                description=description
+            )
+            print(f"✅ Added ticket: {context_id}")
+            return True
+        except Exception as e:
+            print(f"❌ Failed to add ticket: {e}")
+            return False
+    
+    def _select_context_type(self) -> str:
+        """Helper to select context type."""
+        print("\nContext type:")
+        print("1. Requirements")
+        print("2. Design document")
+        print("3. Decision record")
+        print("4. Custom/Other")
+        
+        choice = input("Choice [1-4]: ").strip()
+        
+        type_map = {
+            "1": "requirements",
+            "2": "design_docs",
+            "3": "decisions",
+            "4": "custom"
+        }
+        
+        return type_map.get(choice, "custom")
+    
+    def get_context_summary(self) -> Dict[str, Any]:
+        """Get a summary of loaded context."""
+        return self.context_manager.get_summary()
+    
+    def get_query_metrics(self) -> QueryMetrics:
+        """Get query interpretation metrics for monitoring."""
+        return self.metrics
+    
+    def print_metrics_report(self):
+        """Print query interpretation metrics report."""
+        self.metrics.print_report()
+    
+    def save_session(self, file_path: str):
+        """
+        Save the current session including context.
+        
+        Args:
+            file_path: Path to save session to
+        """
+        # Save context
+        context_file = file_path.replace(".json", "_context.json")
+        self.context_manager.save_to_file(context_file)
+        
+        # Save conversation (could be extended)
+        logger.info(f"Session saved to {file_path} and {context_file}")
+    
+    def load_session(self, file_path: str):
+        """
+        Load a previous session including context.
+        
+        Args:
+            file_path: Path to load session from
+        """
+        # Load context
+        context_file = file_path.replace(".json", "_context.json")
+        try:
+            self.context_manager.load_from_file(context_file)
+            logger.info(f"Session loaded from {file_path} and {context_file}")
+        except FileNotFoundError:
+            logger.warning(f"No saved context found at {context_file}")
+
+
+if __name__ == "__main__":
+    # Test the enhanced explorer
+    print("Testing InteractiveExplorerWithContext")
+    print("=" * 50)
+    
+    # This would normally use real searcher
+    from .search import HybridSearcher
+    
+    # Mock searcher for testing
+    class MockSearcher:
+        def search(self, query, limit=5):
+            return []
+    
+    # Create explorer with context
+    context_manager = ExternalContextManager()
+    explorer = InteractiveExplorerWithContext(MockSearcher(), context_manager)
+    
+    # Add some test context
+    context_manager.add_context(
+        context_type="requirements",
+        content="The system must support 10,000 concurrent users with Redis-based sessions",
+        metadata={"title": "Scaling Requirements"},
+        source="requirements.md"
+    )
+    
+    context_manager.add_jira_ticket(
+        ticket_id="PROJ-123",
+        summary="Implement distributed session management",
+        description="Need to support multiple server instances with shared session state",
+        additional_fields={"priority": "High"}
+    )
+    
+    # Test asking a question
+    result = explorer.ask("Why do we use Redis for sessions?")
+    print(f"\nQuestion: {result.question}")
+    print(f"Answer: {result.format_with_context()}")
+    print(f"Confidence: {result.confidence}")
+    
+    # Show context summary
+    summary = explorer.get_context_summary()
+    print(f"\nContext loaded: {summary['total_items']} items")
+    
+    print("\n✅ Enhanced explorer test complete!")