code-finder 0.1.0__py3-none-any.whl

claude_context/explorer.py

@@ -0,0 +1,951 @@
+
+"""anti
+Interactive Explorer for Claude Context
+
+Provides an interactive Q&A interface for exploring codebases with a strict
+evidence-first approach. Questions are classified and routed to appropriate
+handlers based on intent, ensuring grounded, accurate responses.
+
+Philosophy: Facts → Analysis → Reasoning (only with evidence)
+"""
+
+import logging
+import re
+from enum import Enum
+from typing import List, Dict, Any, Optional, Tuple, Set
+from dataclasses import dataclass, field
+from datetime import datetime
+import json
+
+from .search import HybridSearcher, SearchResult, create_hybrid_searcher
+from .config import ClaudeContextConfig, MilvusManager
+from .embeddings import LocalEmbeddings
+from .indexer import RepositoryIndexer
+
+logger = logging.getLogger(__name__)
+
+
+class QuestionType(Enum):
+    """Classification of question types based on required processing"""
+    
+    # Layer 1: Facts only (search)
+    DISCOVERY = "discovery"          # What/Where/List questions
+    DEFINITION = "definition"        # Show me X, Find Y
+    
+    # Layer 2: Analysis required (search + static analysis)
+    RELATIONSHIP = "relationship"    # How X connects to Y
+    FLOW = "flow"                   # Trace data/control flow
+    STRUCTURE = "structure"         # Module/architecture questions
+    
+    # Layer 3: Reasoning required (search + analysis + inference)
+    REASONING = "reasoning"         # Why questions
+    PATTERN = "pattern"            # Design pattern identification
+    EVALUATION = "evaluation"      # Quality/improvement questions
+    
+    # Special types
+    UNKNOWN = "unknown"            # Cannot classify
+    CLARIFICATION = "clarification" # Need more info
+
+
+@dataclass
+class QuestionIntent:
+    """Detailed question intent analysis"""
+    primary_type: QuestionType
+    confidence: float  # 0-1 confidence in classification
+    keywords: List[str]  # Key terms extracted
+    entities: List[str]  # Code entities mentioned (classes, functions, etc.)
+    scope: str  # "specific" or "broad"
+    requires_llm: bool  # Whether LLM would be beneficial
+    suggested_approach: str  # How to handle this question
+
+
+class QuestionClassifier:
+    """
+    Classifies questions to route them to appropriate handlers.
+    No LLM required - uses pattern matching and keyword analysis.
+    """
+    
+    def __init__(self):
+        # Define patterns for each question type
+        self.patterns = {
+            QuestionType.DISCOVERY: {
+                "patterns": [
+                    r"\b(what|which|list|show|find|where|locate)\b.*\b(is|are|all|every|main|primary)\b",
+                    r"\b(what|where)\s+(is|are)\s+(\w+)",
+                    r"\b(show|list|find)\s+(me\s+)?(all\s+)?(\w+)",
+                    r"\b(main|primary|key|core)\s+(components?|modules?|classes?|functions?)\b"
+                ],
+                "keywords": ["what", "where", "which", "list", "show", "find", "locate", "main", "all"],
+                "examples": [
+                    "What are the main components?",
+                    "Where is authentication handled?",
+                    "List all API endpoints",
+                    "Show me the database models"
+                ]
+            },
+            
+            QuestionType.DEFINITION: {
+                "patterns": [
+                    r"\b(show|display|get|find)\s+(me\s+)?(the\s+)?(\w+)\s+(class|function|method|code)\b",
+                    r"\b(definition|implementation)\s+of\s+(\w+)",
+                    r"\bwhat\s+does\s+(\w+)\s+look\s+like\b"
+                ],
+                "keywords": ["show", "display", "definition", "implementation", "code"],
+                "examples": [
+                    "Show me the UserService class",
+                    "Find the login function",
+                    "What does PaymentProcessor look like?"
+                ]
+            },
+            
+            QuestionType.RELATIONSHIP: {
+                "patterns": [
+                    r"\b(how|what|which)\b.*\b(connect|interact|relate|call|use|depend|communicate)\b",
+                    r"\b(relationship|connection|interaction)\s+(between|with|of)\b",
+                    r"\b(what|which)\s+(calls?|uses?|imports?|depends?\s+on)\s+(\w+)",
+                    r"\b(\w+)\s+and\s+(\w+)\s+(interact|connect|relate|work\s+together)"
+                ],
+                "keywords": ["connect", "interact", "relate", "call", "use", "depend", "relationship", "between"],
+                "examples": [
+                    "How do OrderService and PaymentService interact?",
+                    "What calls the authenticate function?",
+                    "Which components depend on Redis?",
+                    "How are User and Profile connected?"
+                ]
+            },
+            
+            QuestionType.FLOW: {
+                "patterns": [
+                    r"\b(trace|follow|track)\b.*\b(flow|path|journey|process)\b",
+                    r"\b(how|what)\b.*\b(flows?|moves?|travels?|processes?|happens?)\b",
+                    r"\b(data|control|execution)\s+(flow|path)\b",
+                    r"\bstep[- ]?by[- ]?step\b"
+                ],
+                "keywords": ["trace", "follow", "flow", "path", "journey", "process", "step"],
+                "examples": [
+                    "Trace the login flow",
+                    "How does data flow from API to database?",
+                    "Follow the order processing path",
+                    "What happens step by step when a user signs up?"
+                ]
+            },
+            
+            QuestionType.STRUCTURE: {
+                "patterns": [
+                    r"\b(architecture|structure|organization|layout)\b",
+                    r"\b(module|package|component)\s+(boundaries?|structure|organization)\b",
+                    r"\b(how\s+is|what\'s\s+the).*\b(organized|structured|architected|laid\s+out)\b"
+                ],
+                "keywords": ["architecture", "structure", "module", "package", "boundaries", "organization"],
+                "examples": [
+                    "What's the architecture of this system?",
+                    "How is the codebase organized?",
+                    "What are the module boundaries?",
+                    "Explain the package structure"
+                ]
+            },
+            
+            QuestionType.REASONING: {
+                "patterns": [
+                    r"\bwhy\b",
+                    r"\b(reason|rationale|purpose|motivation)\b",
+                    r"\b(explain|understand)\s+(the\s+)?(reasoning|thinking|decision)\b",
+                    r"\bwhat\'s\s+the\s+(point|purpose|reason)\b"
+                ],
+                "keywords": ["why", "reason", "rationale", "purpose", "explain", "because"],
+                "examples": [
+                    "Why does this use Redis instead of memory cache?",
+                    "What's the reason for this abstraction?",
+                    "Why is this a separate service?",
+                    "Explain the rationale behind this pattern"
+                ]
+            },
+            
+            QuestionType.PATTERN: {
+                "patterns": [
+                    r"\b(pattern|design|approach|strategy|technique)\b",
+                    r"\b(what|which)\s+(pattern|design|approach)\b",
+                    r"\b(singleton|factory|observer|mvc|repository|strategy)\b"
+                ],
+                "keywords": ["pattern", "design", "approach", "strategy", "technique"],
+                "examples": [
+                    "What design patterns are used?",
+                    "Is this using the repository pattern?",
+                    "What's the caching strategy?",
+                    "Identify the architectural patterns"
+                ]
+            },
+            
+            QuestionType.EVALUATION: {
+                "patterns": [
+                    r"\b(good|bad|better|worse|improve|optimize|refactor)\b",
+                    r"\b(should|could|would)\b.*\b(be|have)\b",
+                    r"\b(quality|performance|security|maintainability)\b",
+                    r"\b(issue|problem|concern|smell|antipattern)\b"
+                ],
+                "keywords": ["good", "bad", "improve", "should", "could", "quality", "issue", "problem"],
+                "examples": [
+                    "How could this be improved?",
+                    "Is this good design?",
+                    "What are potential issues?",
+                    "Should this be refactored?"
+                ]
+            }
+        }
+        
+        # Compile regex patterns for efficiency
+        for qtype in self.patterns:
+            self.patterns[qtype]["compiled"] = [
+                re.compile(pattern, re.IGNORECASE) 
+                for pattern in self.patterns[qtype]["patterns"]
+            ]
+    
+    def classify(self, question: str) -> QuestionIntent:
+        """
+        Classify a question into a type and extract intent details.
+        
+        Args:
+            question: The user's question
+            
+        Returns:
+            QuestionIntent with classification details
+        """
+        # Normalize question
+        normalized = question.lower().strip()
+        
+        # Extract entities (capitalized words, code-like terms)
+        entities = self._extract_entities(question)
+        
+        # Score each question type
+        scores = {}
+        matched_keywords = set()
+        
+        for qtype, config in self.patterns.items():
+            score = 0.0
+            
+            # Check regex patterns
+            for pattern in config["compiled"]:
+                if pattern.search(normalized):
+                    score += 1.0
+            
+            # Check keywords
+            for keyword in config["keywords"]:
+                if keyword in normalized:
+                    score += 0.5
+                    matched_keywords.add(keyword)
+            
+            # Normalize score
+            max_possible = len(config["patterns"]) + (len(config["keywords"]) * 0.5)
+            scores[qtype] = score / max_possible if max_possible > 0 else 0
+        
+        # Find best match
+        if scores:
+            best_type = max(scores, key=scores.get)
+            confidence = scores[best_type]
+        else:
+            best_type = QuestionType.UNKNOWN
+            confidence = 0.0
+        
+        # Determine if we need LLM
+        requires_llm = best_type in [
+            QuestionType.REASONING,
+            QuestionType.PATTERN,
+            QuestionType.EVALUATION
+        ]
+        
+        # Determine scope
+        scope = "specific" if entities else "broad"
+        
+        # Suggest approach
+        approach = self._suggest_approach(best_type, entities, list(matched_keywords))
+        
+        return QuestionIntent(
+            primary_type=best_type,
+            confidence=confidence,
+            keywords=list(matched_keywords),
+            entities=entities,
+            scope=scope,
+            requires_llm=requires_llm,
+            suggested_approach=approach
+        )
+    
+    def _extract_entities(self, question: str) -> List[str]:
+        """Extract potential code entities from question"""
+        entities = []
+        
+        # Question words to exclude
+        question_words = {
+            'what', 'where', 'when', 'why', 'how', 'which', 'who',
+            'is', 'are', 'was', 'were', 'do', 'does', 'did',
+            'can', 'could', 'should', 'would', 'will',
+            'show', 'tell', 'find', 'list', 'get', 'trace', 'explain'
+        }
+        
+        # Find CamelCase words (likely class names)
+        # But exclude common English words that happen to be capitalized
+        camel_case = re.findall(r'\b[A-Z][a-z]+(?:[A-Z][a-z]+)*\b', question)
+        for word in camel_case:
+            if word.lower() not in question_words:
+                entities.append(word)
+        
+        # Find snake_case words (likely function/variable names)
+        snake_case = re.findall(r'\b[a-z]+(?:_[a-z]+)+\b', question)
+        entities.extend(snake_case)
+        
+        # Find code-like terms in backticks or quotes
+        quoted = re.findall(r'[`"\']([^`"\']+)[`"\']', question)
+        entities.extend(quoted)
+        
+        # Find words ending in common code suffixes
+        # These are almost always code entities
+        code_terms = re.findall(r'\b\w+(?:Service|Controller|Model|Handler|Manager|Factory|Repository|Component|Module|Class|Function)\b', question, re.IGNORECASE)
+        for term in code_terms:
+            # Only add if not already in list and not a question word
+            if term not in entities and term.lower() not in question_words:
+                entities.append(term)
+        
+        # Also look for common code terms
+        # Like: API, URL, HTTP, REST, JSON, XML, etc.
+        technical_terms = re.findall(r'\b(?:API|URL|HTTP|REST|JSON|XML|SQL|CSS|HTML|JWT|OAuth|Redis|MongoDB|PostgreSQL)\b', question, re.IGNORECASE)
+        entities.extend(technical_terms)
+        
+        # Remove duplicates while preserving order
+        seen = set()
+        unique_entities = []
+        for entity in entities:
+            if entity not in seen and entity.lower() not in question_words:
+                seen.add(entity)
+                unique_entities.append(entity)
+        
+        return unique_entities
+    
+    def _suggest_approach(self, qtype: QuestionType, entities: List[str], keywords: List[str]) -> str:
+        """Suggest how to approach answering this question"""
+        
+        suggestions = {
+            QuestionType.DISCOVERY: f"Search for {', '.join(entities) if entities else 'relevant components'} and list findings",
+            QuestionType.DEFINITION: f"Locate and display the complete code for {', '.join(entities) if entities else 'the requested item'}",
+            QuestionType.RELATIONSHIP: f"Find connections between {' and '.join(entities) if len(entities) >= 2 else 'components'} using dependency analysis",
+            QuestionType.FLOW: f"Trace the execution path starting from {entities[0] if entities else 'entry point'}",
+            QuestionType.STRUCTURE: "Analyze directory structure and module boundaries",
+            QuestionType.REASONING: f"Search for evidence about {', '.join(entities) if entities else 'the topic'}, then infer purpose from context",
+            QuestionType.PATTERN: "Identify code patterns and match against known design patterns",
+            QuestionType.EVALUATION: f"Analyze {', '.join(entities) if entities else 'code quality'} against best practices",
+            QuestionType.UNKNOWN: "Clarify the question or try a broader search",
+            QuestionType.CLARIFICATION: "Request more specific information"
+        }
+        
+        return suggestions.get(qtype, "Perform general search and analysis")
+    
+    def needs_clarification(self, intent: QuestionIntent) -> bool:
+        """Determine if the question needs clarification"""
+        return (
+            intent.primary_type == QuestionType.UNKNOWN or
+            intent.confidence < 0.3 or
+            (intent.scope == "broad" and not intent.keywords)
+        )
+    
+    def suggest_clarifications(self, question: str, intent: QuestionIntent) -> List[str]:
+        """Suggest clarifying questions"""
+        suggestions = []
+        
+        if intent.primary_type == QuestionType.UNKNOWN:
+            suggestions.append("Could you rephrase your question? I'm not sure what you're looking for.")
+        
+        if intent.scope == "broad" and not intent.entities:
+            suggestions.append("Which specific component or function are you interested in?")
+        
+        if intent.confidence < 0.5:
+            # Suggest example questions based on keywords
+            if "how" in question.lower():
+                suggestions.append("Are you asking about how components interact, or how something is implemented?")
+            elif "what" in question.lower():
+                suggestions.append("Are you looking for a list of items, or the definition of something specific?")
+        
+        if not suggestions:
+            suggestions.append("Could you provide more context or be more specific?")
+        
+        return suggestions
+
+
+@dataclass
+class ExplorationResult:
+    """Result of exploring a question about the codebase"""
+    
+    question: str
+    question_type: QuestionType
+    confidence: float
+    
+    # Core results
+    answer: str  # Natural language answer
+    code_results: List[SearchResult] = field(default_factory=list)
+    
+    # Metadata
+    entities_found: List[str] = field(default_factory=list)
+    search_terms_used: List[str] = field(default_factory=list)
+    
+    # Context for future questions
+    follow_up_suggestions: List[str] = field(default_factory=list)
+    related_files: List[str] = field(default_factory=list)
+    
+    # External context (for future enhancement)
+    external_context: Dict[str, Any] = field(default_factory=dict)
+    
+    # Tracking
+    processing_time: float = 0.0
+    used_llm: bool = False
+    
+    def format_answer(self, include_code: bool = True, max_results: int = 3) -> str:
+        """Format the result for display"""
+        output = []
+        
+        # Question and classification
+        output.append(f"📝 Question: {self.question}")
+        output.append(f"   Type: {self.question_type.value} (confidence: {self.confidence:.2f})")
+        
+        # Answer
+        output.append(f"\n💡 Answer:\n{self.answer}")
+        
+        # Code examples
+        if include_code and self.code_results:
+            output.append(f"\n📂 Relevant Code ({len(self.code_results)} results found):")
+            for i, result in enumerate(self.code_results[:max_results], 1):
+                output.append(f"\n{i}. {result.file_name} ({result.chunk_type})")
+                output.append(f"   Lines {result.start_line}-{result.end_line}")
+                if result.chunk_name:
+                    output.append(f"   Name: {result.chunk_name}")
+                # Show first 3 lines of code
+                lines = result.content.split('\n')[:3]
+                for line in lines:
+                    output.append(f"   {line}")
+                if len(result.content.split('\n')) > 3:
+                    output.append("   ...")
+        
+        # Follow-up suggestions
+        if self.follow_up_suggestions:
+            output.append("\n🔍 You might also want to ask:")
+            for suggestion in self.follow_up_suggestions[:3]:
+                output.append(f"   - {suggestion}")
+        
+        # Processing info
+        output.append(f"\n⏱️  Processed in {self.processing_time:.3f}s")
+        
+        return '\n'.join(output)
+
+
+@dataclass
+class ConversationContext:
+    """Maintains context across multiple questions"""
+    
+    session_id: str
+    started_at: datetime = field(default_factory=datetime.now)
+    
+    # History
+    questions: List[str] = field(default_factory=list)
+    results: List[ExplorationResult] = field(default_factory=list)
+    
+    # Current focus
+    current_entities: Set[str] = field(default_factory=set)
+    current_files: Set[str] = field(default_factory=set)
+    
+    # External context (for future enhancement)
+    external_docs: List[str] = field(default_factory=list)
+    
+    def add_result(self, result: ExplorationResult):
+        """Add a result and update context"""
+        self.questions.append(result.question)
+        self.results.append(result)
+        
+        # Update current focus
+        self.current_entities.update(result.entities_found)
+        self.current_files.update(result.related_files)
+    
+    def get_context_summary(self) -> str:
+        """Get a summary of the conversation context"""
+        return f"""
+Session: {self.session_id}
+Questions asked: {len(self.questions)}
+Entities explored: {', '.join(self.current_entities) if self.current_entities else 'None'}
+Files examined: {len(self.current_files)}
+"""
+
+
+class InteractiveExplorer:
+    """
+    Interactive Q&A explorer for codebases.
+    
+    This is the main interface for exploring code through questions.
+    It uses the question classifier to route questions to appropriate
+    handlers and maintains conversation context.
+    """
+    
+    def __init__(
+        self,
+        config: ClaudeContextConfig,
+        embeddings: LocalEmbeddings,
+        milvus_manager: MilvusManager,
+        llm_client: Optional[Any] = None,  # For future LLM integration
+        external_context: Optional[Dict] = None  # For future context integration
+    ):
+        """
+        Initialize the explorer.
+        
+        Args:
+            config: Configuration
+            embeddings: Embeddings model
+            milvus_manager: Milvus connection manager
+            llm_client: Optional LLM for reasoning questions
+            external_context: Optional external documentation
+        """
+        self.config = config
+        self.classifier = QuestionClassifier()
+        self.searcher = create_hybrid_searcher(config, embeddings, milvus_manager)
+        self.llm_client = llm_client
+        self.external_context = external_context or {}
+        
+        # Session management
+        self.sessions: Dict[str, ConversationContext] = {}
+        
+        logger.info("InteractiveExplorer initialized")
+    
+    def start_session(self, session_id: Optional[str] = None) -> str:
+        """Start a new exploration session"""
+        if not session_id:
+            session_id = f"session_{datetime.now().strftime('%Y%m%d_%H%M%S')}"
+        
+        self.sessions[session_id] = ConversationContext(session_id=session_id)
+        logger.info(f"Started exploration session: {session_id}")
+        return session_id
+    
+    def ask(
+        self,
+        question: str,
+        session_id: Optional[str] = None,
+        include_code: bool = True,
+        max_results: int = 5
+    ) -> ExplorationResult:
+        """
+        Ask a question about the codebase.
+        
+        Args:
+            question: The question to answer
+            session_id: Optional session ID for context
+            include_code: Whether to include code snippets
+            max_results: Maximum number of code results
+            
+        Returns:
+            ExplorationResult with answer and evidence
+        """
+        start_time = datetime.now()
+        
+        # Get or create session
+        if session_id and session_id in self.sessions:
+            context = self.sessions[session_id]
+        else:
+            context = ConversationContext(session_id=session_id or "default")
+        
+        # Classify the question
+        intent = self.classifier.classify(question)
+        
+        # Route to appropriate handler
+        if intent.primary_type in [QuestionType.DISCOVERY, QuestionType.DEFINITION]:
+            result = self._handle_discovery_question(question, intent, max_results)
+        elif intent.primary_type in [QuestionType.RELATIONSHIP, QuestionType.FLOW, QuestionType.STRUCTURE]:
+            result = self._handle_analysis_question(question, intent, max_results)
+        elif intent.primary_type in [QuestionType.REASONING, QuestionType.PATTERN, QuestionType.EVALUATION]:
+            result = self._handle_reasoning_question(question, intent, max_results)
+        else:
+            result = self._handle_unknown_question(question, intent)
+        
+        # Calculate processing time
+        result.processing_time = (datetime.now() - start_time).total_seconds()
+        
+        # Update session context
+        if session_id:
+            context.add_result(result)
+        
+        return result
+    
+    def _handle_discovery_question(
+        self,
+        question: str,
+        intent: QuestionIntent,
+        max_results: int
+    ) -> ExplorationResult:
+        """
+        Handle discovery/definition questions (Layer 1: Facts only).
+        These are "what" and "where" questions that need only search.
+        """
+        # Build search query from entities and keywords
+        search_terms = intent.entities + intent.keywords
+        search_query = ' '.join(search_terms) if search_terms else question
+        
+        # Search for relevant code
+        code_results = self.searcher.search(
+            search_query,
+            limit=max_results
+        )
+        
+        # Build answer from results
+        if code_results:
+            if intent.primary_type == QuestionType.DISCOVERY:
+                answer = self._build_discovery_answer(code_results, intent)
+            else:  # DEFINITION
+                answer = self._build_definition_answer(code_results, intent)
+            
+            # Extract found entities and files
+            entities_found = list(set(
+                r.chunk_name for r in code_results if r.chunk_name
+            ))
+            related_files = list(set(r.file_path for r in code_results))
+            
+            # Suggest follow-ups
+            follow_ups = self._suggest_discovery_followups(code_results, intent)
+        else:
+            answer = f"I couldn't find any code related to: {', '.join(intent.entities) if intent.entities else question}"
+            entities_found = []
+            related_files = []
+            follow_ups = ["Try searching with different terms", "Be more specific about what you're looking for"]
+        
+        return ExplorationResult(
+            question=question,
+            question_type=intent.primary_type,
+            confidence=intent.confidence,
+            answer=answer,
+            code_results=code_results,
+            entities_found=entities_found,
+            search_terms_used=search_terms,
+            follow_up_suggestions=follow_ups,
+            related_files=related_files
+        )
+    
+    def _handle_analysis_question(
+        self,
+        question: str,
+        intent: QuestionIntent,
+        max_results: int
+    ) -> ExplorationResult:
+        """
+        Handle relationship/flow/structure questions (Layer 2: Analysis).
+        These need search plus relationship analysis.
+        """
+        # For now, use search with relationship-focused terms
+        # In future, add actual dependency analysis
+        
+        # Add relationship keywords to search
+        relationship_terms = ["import", "call", "use", "depend", "inherit", "extend"]
+        search_terms = intent.entities + relationship_terms
+        search_query = ' '.join(search_terms) if search_terms else question
+        
+        # Search for relationships
+        code_results = self.searcher.search(
+            search_query,
+            limit=max_results * 2  # Get more results for relationship analysis
+        )
+        
+        # Analyze relationships in results
+        if code_results:
+            answer = self._build_relationship_answer(code_results, intent)
+            entities_found = self._extract_all_entities(code_results)
+            related_files = list(set(r.file_path for r in code_results))
+            follow_ups = self._suggest_relationship_followups(code_results, intent)
+        else:
+            answer = f"I couldn't find relationships for: {', '.join(intent.entities) if intent.entities else 'the specified components'}"
+            entities_found = []
+            related_files = []
+            follow_ups = ["Try specifying the exact component names", "Check if the components exist"]
+        
+        return ExplorationResult(
+            question=question,
+            question_type=intent.primary_type,
+            confidence=intent.confidence,
+            answer=answer,
+            code_results=code_results[:max_results],  # Limit displayed results
+            entities_found=entities_found,
+            search_terms_used=search_terms,
+            follow_up_suggestions=follow_ups,
+            related_files=related_files
+        )
+    
+    def _handle_reasoning_question(
+        self,
+        question: str,
+        intent: QuestionIntent,
+        max_results: int
+    ) -> ExplorationResult:
+        """
+        Handle reasoning/pattern/evaluation questions (Layer 3: Reasoning).
+        These need search, analysis, and potentially LLM inference.
+        """
+        # Search for relevant code
+        search_terms = intent.entities + intent.keywords
+        search_query = ' '.join(search_terms) if search_terms else question
+        
+        code_results = self.searcher.search(
+            search_query,
+            limit=max_results
+        )
+        
+        if self.llm_client:
+            # Use LLM for reasoning (future enhancement)
+            answer = self._build_reasoning_answer_with_llm(code_results, intent, question)
+            used_llm = True
+        else:
+            # Fallback: Provide code evidence without reasoning
+            answer = self._build_reasoning_answer_without_llm(code_results, intent)
+            used_llm = False
+        
+        entities_found = self._extract_all_entities(code_results) if code_results else []
+        related_files = list(set(r.file_path for r in code_results)) if code_results else []
+        follow_ups = self._suggest_reasoning_followups(code_results, intent)
+        
+        return ExplorationResult(
+            question=question,
+            question_type=intent.primary_type,
+            confidence=intent.confidence,
+            answer=answer,
+            code_results=code_results,
+            entities_found=entities_found,
+            search_terms_used=search_terms,
+            follow_up_suggestions=follow_ups,
+            related_files=related_files,
+            used_llm=used_llm
+        )
+    
+    def _handle_unknown_question(
+        self,
+        question: str,
+        intent: QuestionIntent
+    ) -> ExplorationResult:
+        """Handle questions that couldn't be classified"""
+        
+        # Try a general search
+        code_results = self.searcher.search(question, limit=5)
+        
+        if code_results:
+            answer = "I'm not sure what you're asking, but here's what I found:"
+        else:
+            answer = "I couldn't understand your question. Could you please rephrase it?"
+        
+        # Suggest clarifications
+        follow_ups = self.classifier.suggest_clarifications(question, intent)
+        
+        return ExplorationResult(
+            question=question,
+            question_type=QuestionType.UNKNOWN,
+            confidence=0.0,
+            answer=answer,
+            code_results=code_results,
+            follow_up_suggestions=follow_ups
+        )
+    
+    # Answer building methods
+    
+    def _build_discovery_answer(self, results: List[SearchResult], intent: QuestionIntent) -> str:
+        """Build answer for discovery questions"""
+        answer_parts = []
+        
+        if intent.entities:
+            answer_parts.append(f"Here's what I found about {', '.join(intent.entities)}:")
+        else:
+            answer_parts.append("Here's what I found:")
+        
+        # Group by type
+        by_type = {}
+        for r in results:
+            if r.chunk_type not in by_type:
+                by_type[r.chunk_type] = []
+            by_type[r.chunk_type].append(r)
+        
+        for chunk_type, items in by_type.items():
+            answer_parts.append(f"\n{chunk_type.title()}s:")
+            for item in items[:3]:  # Limit to 3 per type
+                if item.chunk_name:
+                    answer_parts.append(f"  • {item.chunk_name} in {item.file_name}")
+                else:
+                    answer_parts.append(f"  • {item.file_name} (lines {item.start_line}-{item.end_line})")
+        
+        return '\n'.join(answer_parts)
+    
+    def _build_definition_answer(self, results: List[SearchResult], intent: QuestionIntent) -> str:
+        """Build answer for definition questions"""
+        if not results:
+            return "Definition not found."
+        
+        best_match = results[0]
+        answer = f"Found {best_match.chunk_type}: {best_match.chunk_name or 'unnamed'}\n"
+        answer += f"Location: {best_match.file_name} (lines {best_match.start_line}-{best_match.end_line})\n"
+        
+        # Add language hint
+        if best_match.language:
+            answer += f"Language: {best_match.language}\n"
+        
+        return answer
+    
+    def _build_relationship_answer(self, results: List[SearchResult], intent: QuestionIntent) -> str:
+        """Build answer for relationship questions"""
+        if len(intent.entities) >= 2:
+            answer = f"Analyzing relationship between {' and '.join(intent.entities)}:\n"
+        else:
+            answer = "Found the following relationships:\n"
+        
+        # Look for imports and calls
+        imports = [r for r in results if r.chunk_type == 'import_block']
+        functions = [r for r in results if r.chunk_type in ['function', 'method']]
+        classes = [r for r in results if r.chunk_type == 'class']
+        
+        if imports:
+            answer += f"\nImports ({len(imports)} found):"
+            for imp in imports[:3]:
+                first_line = imp.content.split('\n')[0][:80]
+                answer += f"\n  • {imp.file_name}: {first_line}"
+        
+        if classes:
+            answer += f"\n\nClasses involved ({len(classes)} found):"
+            for cls in classes[:3]:
+                answer += f"\n  • {cls.chunk_name} in {cls.file_name}"
+        
+        if functions:
+            answer += f"\n\nFunctions/Methods ({len(functions)} found):"
+            for func in functions[:3]:
+                answer += f"\n  • {func.chunk_name} in {func.file_name}"
+        
+        return answer
+    
+    def _build_reasoning_answer_without_llm(self, results: List[SearchResult], intent: QuestionIntent) -> str:
+        """Build reasoning answer without LLM"""
+        answer = "To answer 'why' questions, I need LLM integration. However, here's the relevant code:\n"
+        
+        if results:
+            for r in results[:3]:
+                answer += f"\n• {r.chunk_type} '{r.chunk_name or 'unnamed'}' in {r.file_name}"
+                # Look for comments that might explain why
+                lines = r.content.split('\n')
+                for line in lines:
+                    if '#' in line or '//' in line or '/*' in line:
+                        comment = line.strip()
+                        if len(comment) > 10:  # Non-trivial comment
+                            answer += f"\n  Comment: {comment[:100]}"
+                            break
+        else:
+            answer += "\nNo relevant code found to analyze."
+        
+        answer += "\n\nNote: For deeper reasoning about design decisions, LLM integration would provide better insights."
+        
+        return answer
+    
+    def _build_reasoning_answer_with_llm(self, results: List[SearchResult], intent: QuestionIntent, question: str) -> str:
+        """Build reasoning answer with LLM (future enhancement)"""
+        # This is where we'd use the LLM with grounding
+        # For now, return the non-LLM answer
+        return self._build_reasoning_answer_without_llm(results, intent)
+    
+    # Helper methods
+    
+    def _extract_all_entities(self, results: List[SearchResult]) -> List[str]:
+        """Extract all entities from search results"""
+        entities = set()
+        for r in results:
+            if r.chunk_name:
+                entities.add(r.chunk_name)
+            # Could also extract entities from content
+        return list(entities)
+    
+    def _suggest_discovery_followups(self, results: List[SearchResult], intent: QuestionIntent) -> List[str]:
+        """Suggest follow-up questions for discovery"""
+        suggestions = []
+        
+        if results:
+            # Based on what was found
+            chunk_types = set(r.chunk_type for r in results)
+            if 'class' in chunk_types:
+                suggestions.append("What methods does this class have?")
+            if 'function' in chunk_types:
+                suggestions.append("What calls this function?")
+            if len(set(r.file_name for r in results)) > 1:
+                suggestions.append("How are these files related?")
+        
+        return suggestions
+    
+    def _suggest_relationship_followups(self, results: List[SearchResult], intent: QuestionIntent) -> List[str]:
+        """Suggest follow-up questions for relationships"""
+        suggestions = []
+        
+        if len(intent.entities) >= 2:
+            suggestions.append(f"What's the data flow between {' and '.join(intent.entities[:2])}?")
+        
+        if results:
+            suggestions.append("What are the dependencies of this component?")
+            suggestions.append("Are there any circular dependencies?")
+        
+        return suggestions
+    
+    def _suggest_reasoning_followups(self, results: List[SearchResult], intent: QuestionIntent) -> List[str]:
+        """Suggest follow-up questions for reasoning"""
+        return [
+            "What are the trade-offs of this approach?",
+            "How could this be improved?",
+            "What patterns are being used here?"
+        ]
+
+
+# Example usage and testing
+if __name__ == "__main__":
+    # Test the classifier
+    classifier = QuestionClassifier()
+    
+    test_questions = [
+        # Discovery questions
+        "What are the main components?",
+        "Where is authentication handled?",
+        "List all API endpoints",
+        
+        # Definition questions
+        "Show me the UserService class",
+        "Find the login function implementation",
+        
+        # Relationship questions
+        "How do OrderService and PaymentService interact?",
+        "What calls the authenticate function?",
+        
+        # Flow questions
+        "Trace the login flow",
+        "How does data flow from API to database?",
+        
+        # Structure questions
+        "What's the architecture of this system?",
+        "How is the codebase organized?",
+        
+        # Reasoning questions
+        "Why does this use Redis instead of memory cache?",
+        "What's the reason for separating auth into its own service?",
+        
+        # Pattern questions
+        "What design patterns are used?",
+        "Is this using the repository pattern?",
+        
+        # Evaluation questions
+        "How could the error handling be improved?",
+        "Are there any security concerns?",
+        
+        # Ambiguous questions
+        "How does it work?",
+        "Tell me about the system"
+    ]
+    
+    print("Question Classification Test")
+    print("=" * 60)
+    
+    for question in test_questions:
+        intent = classifier.classify(question)
+        print(f"\nQ: {question}")
+        print(f"   Type: {intent.primary_type.value} (confidence: {intent.confidence:.2f})")
+        print(f"   Entities: {intent.entities}")
+        print(f"   Keywords: {intent.keywords}")
+        print(f"   Needs LLM: {intent.requires_llm}")
+        print(f"   Approach: {intent.suggested_approach}")
+        
+        if classifier.needs_clarification(intent):
+            print("   ⚠️  Needs clarification:")
+            for suggestion in classifier.suggest_clarifications(question, intent):
+                print(f"      - {suggestion}")