code-finder 0.1.0__py3-none-any.whl

claude_context/context_manager.py

@@ -0,0 +1,627 @@
+"""
+External Context Manager for Claude Context
+
+Manages external documentation, requirements, tickets, and other context
+that helps explain the "why" behind code decisions.
+"""
+
+import logging
+import json
+import re
+from datetime import datetime
+from pathlib import Path
+from typing import List, Dict, Any, Optional, Tuple
+from dataclasses import dataclass, field
+import hashlib
+
+logger = logging.getLogger(__name__)
+
+
+@dataclass
+class ContextItem:
+    """Represents a single piece of external context"""
+    id: str
+    type: str  # requirements, ticket, design_doc, decision, custom
+    content: str
+    metadata: Dict[str, Any] = field(default_factory=dict)
+    source: str = ""  # file path, URL, or API source
+    added_at: datetime = field(default_factory=datetime.now)
+    embedding: Optional[Any] = None  # For future semantic search
+    
+    def get_summary(self, max_length: int = 100) -> str:
+        """Get a brief summary of the context"""
+        if 'title' in self.metadata:
+            return self.metadata['title']
+        # Return first line or N characters
+        first_line = self.content.split('\n')[0]
+        if len(first_line) > max_length:
+            return first_line[:max_length] + "..."
+        return first_line
+
+
+class ExternalContextManager:
+    """
+    Manages all external context (requirements, tickets, docs, etc.)
+    Follows fail-fast principles with clear logging.
+    """
+    
+    def __init__(self):
+        """Initialize the context manager"""
+        self.contexts = {
+            "requirements": [],
+            "tickets": [],
+            "design_docs": [],
+            "decisions": [],
+            "custom": []
+        }
+        self.context_index = {}  # Quick lookup by ID
+        self.total_items = 0
+        logger.info("ExternalContextManager initialized")
+    
+    def add_context(
+        self,
+        context_type: str,
+        content: str,
+        metadata: Optional[Dict[str, Any]] = None,
+        source: str = ""
+    ) -> str:
+        """
+        Add a piece of external context.
+        
+        Args:
+            context_type: Type of context (requirements, tickets, etc.)
+            content: The actual content text
+            metadata: Additional metadata (title, ticket_id, etc.)
+            source: Where this came from (file path, URL, etc.)
+            
+        Returns:
+            Context ID for reference
+            
+        Raises:
+            ValueError: If context_type is invalid or content is empty
+        """
+        # Validate inputs
+        if context_type not in self.contexts:
+            logger.error(f"Invalid context type: {context_type}")
+            raise ValueError(f"Context type must be one of: {list(self.contexts.keys())}")
+        
+        if not content or not content.strip():
+            logger.error("Attempted to add empty context")
+            raise ValueError("Context content cannot be empty")
+        
+        # Generate unique ID
+        content_hash = hashlib.md5(content.encode()).hexdigest()[:8]
+        context_id = f"{context_type}_{self.total_items}_{content_hash}"
+        
+        # Create context item
+        context_item = ContextItem(
+            id=context_id,
+            type=context_type,
+            content=content,
+            metadata=metadata or {},
+            source=source
+        )
+        
+        # Store in both structures
+        self.contexts[context_type].append(context_item)
+        self.context_index[context_id] = context_item
+        self.total_items += 1
+        
+        logger.info(f"Added {context_type}: {context_item.get_summary()}")
+        logger.debug(f"Context ID: {context_id}, Source: {source}")
+        
+        return context_id
+    
+    def add_file(self, file_path: str, context_type: str = "custom") -> str:
+        """
+        Add context from a file.
+        
+        Args:
+            file_path: Path to the file
+            context_type: Type of context
+            
+        Returns:
+            Context ID
+            
+        Raises:
+            FileNotFoundError: If file doesn't exist
+            ValueError: If file is empty
+        """
+        path = Path(file_path)
+        if not path.exists():
+            logger.error(f"File not found: {file_path}")
+            raise FileNotFoundError(f"File not found: {file_path}")
+        
+        try:
+            content = path.read_text(encoding='utf-8')
+        except Exception as e:
+            logger.error(f"Failed to read file {file_path}: {e}")
+            raise RuntimeError(f"Failed to read file: {e}") from e
+        
+        metadata = {
+            "filename": path.name,
+            "file_path": str(path.absolute()),
+            "file_size": path.stat().st_size
+        }
+        
+        # Try to extract title from markdown
+        if path.suffix == '.md':
+            lines = content.split('\n')
+            for line in lines:
+                if line.startswith('# '):
+                    metadata['title'] = line[2:].strip()
+                    break
+        
+        return self.add_context(
+            context_type=context_type,
+            content=content,
+            metadata=metadata,
+            source=str(path)
+        )
+    
+    def add_jira_ticket(
+        self,
+        ticket_id: str,
+        summary: str,
+        description: str,
+        additional_fields: Optional[Dict] = None
+    ) -> str:
+        """
+        Add a Jira ticket as context.
+        
+        Args:
+            ticket_id: Jira ticket ID (e.g., PROJ-123)
+            summary: Ticket summary/title
+            description: Full ticket description
+            additional_fields: Other Jira fields (priority, components, etc.)
+            
+        Returns:
+            Context ID
+        """
+        # Format ticket content
+        content = f"""Jira Ticket: {ticket_id}
+Summary: {summary}
+
+Description:
+{description}"""
+        
+        if additional_fields:
+            if 'acceptance_criteria' in additional_fields:
+                content += f"\n\nAcceptance Criteria:\n{additional_fields['acceptance_criteria']}"
+            if 'components' in additional_fields:
+                content += f"\n\nComponents: {', '.join(additional_fields['components'])}"
+        
+        metadata = {
+            "ticket_id": ticket_id,
+            "title": summary,
+            "type": "jira",
+            **additional_fields
+        } if additional_fields else {
+            "ticket_id": ticket_id,
+            "title": summary,
+            "type": "jira"
+        }
+        
+        return self.add_context(
+            context_type="tickets",
+            content=content,
+            metadata=metadata,
+            source=f"jira:{ticket_id}"
+        )
+    
+    def search_context(
+        self,
+        query: str,
+        context_types: Optional[List[str]] = None,
+        limit: int = 5
+    ) -> List[Tuple[ContextItem, float]]:
+        """
+        Search external context for relevant information.
+        
+        Currently uses simple keyword matching. Future versions
+        will use semantic search with embeddings.
+        
+        Args:
+            query: Search query
+            context_types: Types to search (None = all)
+            limit: Maximum results to return
+            
+        Returns:
+            List of (ContextItem, relevance_score) tuples
+        """
+        results = []
+        types_to_search = context_types or list(self.contexts.keys())
+        
+        query_lower = query.lower()
+        query_words = set(query_lower.split())
+        
+        for context_type in types_to_search:
+            for item in self.contexts[context_type]:
+                # Simple relevance scoring
+                content_lower = item.content.lower()
+                
+                # Exact match scores highest
+                if query_lower in content_lower:
+                    score = 1.0
+                else:
+                    # Word overlap scoring
+                    content_words = set(content_lower.split())
+                    overlap = len(query_words & content_words)
+                    score = overlap / len(query_words) if query_words else 0
+                
+                # Boost score if query matches metadata
+                if item.metadata:
+                    if 'title' in item.metadata and query_lower in item.metadata['title'].lower():
+                        score += 0.5
+                    if 'ticket_id' in item.metadata and query_lower in item.metadata['ticket_id'].lower():
+                        score += 0.3
+                
+                if score > 0:
+                    results.append((item, score))
+        
+        # Sort by relevance and limit
+        results.sort(key=lambda x: x[1], reverse=True)
+        return results[:limit]
+    
+    def get_context_by_id(self, context_id: str) -> Optional[ContextItem]:
+        """Get a specific context item by ID"""
+        return self.context_index.get(context_id)
+    
+    def get_all_context(self, context_type: Optional[str] = None) -> List[ContextItem]:
+        """
+        Get all context items, optionally filtered by type.
+        
+        Args:
+            context_type: Type to filter by (None = all)
+            
+        Returns:
+            List of context items
+        """
+        if context_type:
+            if context_type not in self.contexts:
+                logger.warning(f"Unknown context type: {context_type}")
+                return []
+            return self.contexts[context_type].copy()
+        
+        # Return all contexts
+        all_items = []
+        for items in self.contexts.values():
+            all_items.extend(items)
+        return all_items
+    
+    def get_summary(self) -> Dict[str, Any]:
+        """Get a summary of all loaded context"""
+        summary = {
+            "total_items": self.total_items,
+            "by_type": {}
+        }
+        
+        for context_type, items in self.contexts.items():
+            if items:
+                summary["by_type"][context_type] = {
+                    "count": len(items),
+                    "items": [item.get_summary() for item in items[:3]]  # First 3
+                }
+        
+        return summary
+    
+    def clear(self, context_type: Optional[str] = None):
+        """
+        Clear context, optionally by type.
+        
+        Args:
+            context_type: Type to clear (None = all)
+        """
+        if context_type:
+            if context_type in self.contexts:
+                # Remove from index
+                for item in self.contexts[context_type]:
+                    del self.context_index[item.id]
+                # Clear the list
+                self.contexts[context_type] = []
+                logger.info(f"Cleared {context_type} context")
+        else:
+            # Clear everything
+            for key in self.contexts:
+                self.contexts[key] = []
+            self.context_index = {}
+            self.total_items = 0
+            logger.info("Cleared all context")
+    
+    def save_to_file(self, file_path: str):
+        """
+        Save context to a JSON file for later reuse.
+        
+        Args:
+            file_path: Path to save to
+        """
+        data = {
+            "saved_at": datetime.now().isoformat(),
+            "total_items": self.total_items,
+            "contexts": {}
+        }
+        
+        for context_type, items in self.contexts.items():
+            data["contexts"][context_type] = [
+                {
+                    "id": item.id,
+                    "content": item.content,
+                    "metadata": item.metadata,
+                    "source": item.source,
+                    "added_at": item.added_at.isoformat()
+                }
+                for item in items
+            ]
+        
+        path = Path(file_path)
+        path.parent.mkdir(parents=True, exist_ok=True)
+        
+        with open(path, 'w') as f:
+            json.dump(data, f, indent=2)
+        
+        logger.info(f"Saved context to {file_path}")
+    
+    def load_from_file(self, file_path: str):
+        """
+        Load context from a JSON file.
+        
+        Args:
+            file_path: Path to load from
+            
+        Raises:
+            FileNotFoundError: If file doesn't exist
+            ValueError: If file format is invalid
+        """
+        path = Path(file_path)
+        if not path.exists():
+            raise FileNotFoundError(f"Context file not found: {file_path}")
+        
+        try:
+            with open(path) as f:
+                data = json.load(f)
+        except json.JSONDecodeError as e:
+            raise ValueError(f"Invalid JSON in context file: {e}") from e
+        
+        # Clear existing context
+        self.clear()
+        
+        # Load contexts
+        for context_type, items in data.get("contexts", {}).items():
+            if context_type not in self.contexts:
+                logger.warning(f"Unknown context type in file: {context_type}")
+                continue
+            
+            for item_data in items:
+                self.add_context(
+                    context_type=context_type,
+                    content=item_data["content"],
+                    metadata=item_data.get("metadata", {}),
+                    source=item_data.get("source", "")
+                )
+        
+        logger.info(f"Loaded {self.total_items} context items from {file_path}")
+    
+    def extract_code_blocks(self, source_filter: Optional[str] = None) -> List[Dict[str, str]]:
+        """
+        Extract all code blocks from context items (especially README).
+        
+        Useful for getting exact installation commands, usage examples, etc.
+        
+        Args:
+            source_filter: Optional filter (e.g., "readme" to only get README code)
+            
+        Returns:
+            List of {"language": str, "code": str, "source": str, "context": str}
+        """
+        code_blocks = []
+        items = self.get_all_context()
+        
+        for item in items:
+            # Apply source filter
+            if source_filter and source_filter.lower() not in item.source.lower():
+                continue
+            
+            # Extract markdown code blocks using regex
+            # Pattern: ```language\ncode\n```
+            pattern = r'```(\w+)?\n(.*?)\n```'
+            matches = re.findall(pattern, item.content, re.DOTALL)
+            
+            for lang, code in matches:
+                # Get context around the code block (preceding heading/text)
+                context_text = self._get_code_block_context(item.content, code)
+                
+                code_blocks.append({
+                    "language": lang or "text",
+                    "code": code.strip(),
+                    "source": item.source,
+                    "context": context_text,
+                    "length": len(code.strip().split('\n'))
+                })
+        
+        logger.debug(f"Extracted {len(code_blocks)} code blocks")
+        return code_blocks
+    
+    def _get_code_block_context(self, full_content: str, code_snippet: str, lines_before: int = 3) -> str:
+        """Get text context before a code block (usually a heading or description)."""
+        try:
+            # Find where the code block appears
+            idx = full_content.find(code_snippet)
+            if idx == -1:
+                return ""
+            
+            # Get text before the code block
+            text_before = full_content[:idx]
+            lines = text_before.split('\n')
+            
+            # Get last heading or last few lines
+            context_lines = []
+            for line in reversed(lines[-lines_before:]):
+                if line.strip():
+                    context_lines.insert(0, line.strip())
+                    # Stop at heading
+                    if line.strip().startswith('#'):
+                        break
+            
+            return ' '.join(context_lines)
+        except Exception:
+            return ""
+    
+    def extract_installation_info(self) -> Dict[str, Any]:
+        """
+        Extract installation information from README and config files.
+        
+        Returns:
+            {
+                "commands": ["llama-stack-client", ...],
+                "package_managers": ["pip", ...],
+                "requirements": ["Python 3.7+", ...],
+                "examples": [{"command": "pip install X", "source": "README"}]
+            }
+        """
+        install_info = {
+            "commands": [],
+            "package_managers": [],
+            "requirements": [],
+            "examples": []
+        }
+        
+        items = self.get_all_context()
+        
+        for item in items:
+            content = item.content
+            
+            # Find pip install commands
+            pip_matches = re.findall(r'pip install ([\w\-\[\]\.]+)', content, re.IGNORECASE)
+            for match in pip_matches:
+                install_info["commands"].append(match)
+                install_info["package_managers"].append("pip")
+                install_info["examples"].append({
+                    "command": f"pip install {match}",
+                    "source": item.source,
+                    "type": "pip"
+                })
+            
+            # Find npm install commands
+            npm_matches = re.findall(r'npm install ([\w\-@/\.]+)', content, re.IGNORECASE)
+            for match in npm_matches:
+                install_info["commands"].append(match)
+                install_info["package_managers"].append("npm")
+                install_info["examples"].append({
+                    "command": f"npm install {match}",
+                    "source": item.source,
+                    "type": "npm"
+                })
+            
+            # Find Python version requirements
+            py_version = re.findall(r'Python (\d+\.\d+)\+', content, re.IGNORECASE)
+            if py_version:
+                for version in py_version:
+                    req = f"Python {version}+"
+                    if req not in install_info["requirements"]:
+                        install_info["requirements"].append(req)
+            
+            # Find Node version requirements
+            node_version = re.findall(r'Node(?:\.js)? (\d+\.\d+)\+?', content, re.IGNORECASE)
+            if node_version:
+                for version in node_version:
+                    req = f"Node.js {version}+"
+                    if req not in install_info["requirements"]:
+                        install_info["requirements"].append(req)
+        
+        # Deduplicate
+        install_info["commands"] = list(set(install_info["commands"]))
+        install_info["package_managers"] = list(set(install_info["package_managers"]))
+        
+        logger.debug(f"Extracted installation info: {len(install_info['commands'])} packages")
+        return install_info
+    
+    def extract_quickstart_example(self) -> Optional[Dict[str, str]]:
+        """
+        Extract the main quickstart/usage example from README.
+        
+        Looks for the first substantial code block under Usage, Quickstart, 
+        or Example sections.
+        
+        Returns:
+            {"language": str, "code": str, "section": str, "source": str} or None
+        """
+        items = self.get_all_context()
+        
+        for item in items:
+            # Prioritize README files
+            if "readme" not in item.source.lower():
+                continue
+            
+            # Split into sections
+            content = item.content
+            
+            # Look for Usage, Quickstart, or Example sections
+            section_pattern = r'##\s+(Usage|Quickstart|Quick Start|Example|Getting Started)\s*\n(.*?)(?=\n##|\Z)'
+            sections = re.findall(section_pattern, content, re.DOTALL | re.IGNORECASE)
+            
+            for section_name, section_content in sections:
+                # Find code blocks in this section
+                code_pattern = r'```(\w+)?\n(.*?)\n```'
+                code_matches = re.findall(code_pattern, section_content, re.DOTALL)
+                
+                if code_matches:
+                    # Return the first substantial code block (> 2 lines)
+                    for lang, code in code_matches:
+                        if len(code.strip().split('\n')) > 2:
+                            return {
+                                "language": lang or "text",
+                                "code": code.strip(),
+                                "section": section_name,
+                                "source": item.source
+                            }
+        
+        logger.debug("No quickstart example found in README")
+        return None
+    
+    def has_type(self, context_type: str) -> bool:
+        """Check if context manager has items of a specific type."""
+        return len(self.contexts.get(context_type, [])) > 0
+
+
+if __name__ == "__main__":
+    # Test the context manager
+    print("Testing ExternalContextManager")
+    print("=" * 50)
+    
+    manager = ExternalContextManager()
+    
+    # Add a requirement
+    req_id = manager.add_context(
+        context_type="requirements",
+        content="The system must support horizontal scaling with Redis-based sessions",
+        metadata={"title": "Scaling Requirements"},
+        source="requirements.md"
+    )
+    print(f"Added requirement: {req_id}")
+    
+    # Add a Jira ticket
+    ticket_id = manager.add_jira_ticket(
+        ticket_id="PROJ-123",
+        summary="Implement distributed session management",
+        description="We need to support multiple server instances",
+        additional_fields={
+            "acceptance_criteria": "Sessions work across servers",
+            "priority": "High"
+        }
+    )
+    print(f"Added ticket: {ticket_id}")
+    
+    # Search context
+    print("\nSearching for 'Redis':")
+    results = manager.search_context("Redis")
+    for item, score in results:
+        print(f"  - {item.get_summary()} (score: {score:.2f})")
+    
+    # Get summary
+    print("\nContext Summary:")
+    summary = manager.get_summary()
+    print(f"Total items: {summary['total_items']}")
+    for type_name, info in summary["by_type"].items():
+        print(f"  {type_name}: {info['count']} items")
+    
+    print("\n✅ Context manager test complete!")