crackerjack 0.38.15__py3-none-any.whl → 0.39.0__py3-none-any.whl

crackerjack/agents/semantic_helpers.py

@@ -0,0 +1,356 @@
+"""Semantic enhancement helpers for AI agents.
+
+This module provides shared utilities for integrating semantic search
+capabilities into existing agents, enabling them to discover related
+code patterns and make more informed decisions.
+"""
+
+import typing as t
+from dataclasses import dataclass
+from pathlib import Path
+
+from ..models.semantic_models import SearchQuery, SemanticConfig
+from ..services.vector_store import VectorStore
+
+
+@dataclass
+class SemanticInsight:
+    """Container for semantic analysis results."""
+
+    query: str
+    related_patterns: list[dict[str, t.Any]]
+    similarity_threshold: float
+    total_matches: int
+    high_confidence_matches: int
+    session_id: str | None = None
+    timestamp: str | None = None
+
+    def to_session_data(self) -> dict[str, t.Any]:
+        """Convert insight to session-storable data."""
+        return {
+            "query": self.query,
+            "related_patterns": self.related_patterns[:3],  # Limit for storage
+            "similarity_threshold": self.similarity_threshold,
+            "total_matches": self.total_matches,
+            "high_confidence_matches": self.high_confidence_matches,
+            "session_id": self.session_id,
+            "timestamp": self.timestamp,
+        }
+
+
+class SemanticEnhancer:
+    """Helper class to add semantic capabilities to existing agents."""
+
+    def __init__(self, project_path: Path) -> None:
+        self.project_path = project_path
+        self._vector_store: VectorStore | None = None
+        self._config = self._create_semantic_config()
+        self._session_insights: dict[str, SemanticInsight] = {}
+
+    @staticmethod
+    def _create_semantic_config() -> SemanticConfig:
+        """Create semantic search configuration."""
+        return SemanticConfig(
+            embedding_model="sentence-transformers/all-MiniLM-L6-v2",
+            chunk_size=512,
+            chunk_overlap=50,
+            max_search_results=10,
+            similarity_threshold=0.7,
+            embedding_dimension=384,
+        )
+
+    def _get_vector_store(self) -> VectorStore:
+        """Get or create vector store instance."""
+        if self._vector_store is None:
+            db_path = self._get_persistent_db_path()
+            self._vector_store = VectorStore(self._config, db_path=db_path)
+        return self._vector_store
+
+    def _get_persistent_db_path(self) -> Path:
+        """Get the path to the persistent semantic search database."""
+        db_path = self.project_path / ".crackerjack" / "semantic_index.db"
+        db_path.parent.mkdir(exist_ok=True)
+        return db_path
+
+    async def find_similar_patterns(
+        self,
+        query: str,
+        current_file: Path | None = None,
+        min_similarity: float = 0.6,
+        max_results: int = 5,
+    ) -> SemanticInsight:
+        """Find similar code patterns using semantic search.
+
+        Args:
+            query: Search query (code snippet, function signature, or description)
+            current_file: File to exclude from results (to avoid self-matches)
+            min_similarity: Minimum similarity threshold (0.0-1.0)
+            max_results: Maximum number of results to return
+
+        Returns:
+            SemanticInsight with related patterns and analysis
+        """
+        vector_store = self._get_vector_store()
+
+        search_query = SearchQuery(
+            query=query,
+            max_results=max_results,
+            min_similarity=min_similarity,
+            file_types=["py"],
+        )
+
+        try:
+            results = vector_store.search(search_query)
+
+            # Filter out results from current file if specified
+            if current_file:
+                results = [
+                    result for result in results if result.file_path != current_file
+                ]
+
+            # Categorize results by confidence
+            high_confidence = [
+                result for result in results if result.similarity_score >= 0.8
+            ]
+
+            # Convert to pattern format
+            patterns = [
+                {
+                    "file_path": str(result.file_path),
+                    "content": result.content[:300],  # Truncate for readability
+                    "similarity_score": result.similarity_score,
+                    "lines": f"{result.start_line}-{result.end_line}",
+                    "file_type": result.file_type,
+                    "confidence_level": "high"
+                    if result.similarity_score >= 0.8
+                    else "medium",
+                }
+                for result in results
+            ]
+
+            return SemanticInsight(
+                query=query,
+                related_patterns=patterns,
+                similarity_threshold=min_similarity,
+                total_matches=len(patterns),
+                high_confidence_matches=len(high_confidence),
+            )
+
+        except Exception:
+            # Return empty insight on error
+            return SemanticInsight(
+                query=query,
+                related_patterns=[],
+                similarity_threshold=min_similarity,
+                total_matches=0,
+                high_confidence_matches=0,
+            )
+
+    async def find_duplicate_patterns(
+        self, code_snippet: str, current_file: Path | None = None
+    ) -> SemanticInsight:
+        """Find potential code duplicates using semantic similarity.
+
+        Args:
+            code_snippet: Code snippet to find duplicates for
+            current_file: File to exclude from results
+
+        Returns:
+            SemanticInsight focused on potential duplicates
+        """
+        insight = await self.find_similar_patterns(
+            query=code_snippet,
+            current_file=current_file,
+            min_similarity=0.75,  # Higher threshold for duplicates
+            max_results=8,
+        )
+
+        # Store insight for session continuity
+        await self.store_insight_to_session(insight, "DuplicateDetection")
+        return insight
+
+    async def find_refactoring_opportunities(
+        self, function_signature: str, current_file: Path | None = None
+    ) -> SemanticInsight:
+        """Find similar functions for refactoring opportunities.
+
+        Args:
+            function_signature: Function signature or description
+            current_file: File to exclude from results
+
+        Returns:
+            SemanticInsight focused on refactoring opportunities
+        """
+        return await self.find_similar_patterns(
+            query=function_signature,
+            current_file=current_file,
+            min_similarity=0.6,
+            max_results=6,
+        )
+
+    async def find_implementation_examples(
+        self, pattern_description: str, current_file: Path | None = None
+    ) -> SemanticInsight:
+        """Find implementation examples for a given pattern.
+
+        Args:
+            pattern_description: Description of the pattern to find
+            current_file: File to exclude from results
+
+        Returns:
+            SemanticInsight with implementation examples
+        """
+        return await self.find_similar_patterns(
+            query=pattern_description,
+            current_file=current_file,
+            min_similarity=0.5,  # Lower threshold for broader examples
+            max_results=10,
+        )
+
+    def enhance_recommendations(
+        self,
+        base_recommendations: list[str],
+        semantic_insight: SemanticInsight,
+    ) -> list[str]:
+        """Enhance existing recommendations with semantic insights.
+
+        Args:
+            base_recommendations: Original agent recommendations
+            semantic_insight: Semantic analysis results
+
+        Returns:
+            Enhanced recommendations including semantic insights
+        """
+        enhanced = base_recommendations.copy()
+
+        if semantic_insight.total_matches > 0:
+            # Add semantic-based recommendations
+            if semantic_insight.high_confidence_matches > 0:
+                enhanced.append(
+                    f"Semantic analysis found {semantic_insight.high_confidence_matches} "
+                    f"highly similar patterns - consider consolidation"
+                )
+
+            # Add pattern discovery insights
+            if semantic_insight.total_matches >= 3:
+                enhanced.append(
+                    f"Found {semantic_insight.total_matches} related patterns "
+                    f"across codebase - review for consistency"
+                )
+
+            # Add specific file references for high-confidence matches
+            high_conf_files = {
+                pattern["file_path"]
+                for pattern in semantic_insight.related_patterns
+                if pattern["confidence_level"] == "high"
+            }
+
+            if high_conf_files:
+                file_list = ", ".join(Path(f).name for f in sorted(high_conf_files)[:3])
+                if len(high_conf_files) > 3:
+                    file_list += f" (+{len(high_conf_files) - 3} more)"
+
+                enhanced.append(f"Similar implementations found in: {file_list}")
+
+        return enhanced
+
+    def get_semantic_context_summary(self, insight: SemanticInsight) -> str:
+        """Generate a summary of semantic context for logging.
+
+        Args:
+            insight: Semantic analysis results
+
+        Returns:
+            Human-readable summary string
+        """
+        if insight.total_matches == 0:
+            return "No similar patterns found in semantic analysis"
+
+        high_conf_pct = (
+            insight.high_confidence_matches / insight.total_matches * 100
+            if insight.total_matches > 0
+            else 0
+        )
+
+        return (
+            f"Semantic context: {insight.total_matches} similar patterns found "
+            f"({insight.high_confidence_matches} high-confidence, {high_conf_pct:.0f}%)"
+        )
+
+    async def store_insight_to_session(
+        self, insight: SemanticInsight, agent_type: str
+    ) -> bool:
+        """Store semantic insight to session for continuity.
+
+        Args:
+            insight: Semantic insight to store
+            agent_type: Type of agent storing the insight
+
+        Returns:
+            True if stored successfully, False otherwise
+        """
+        try:
+            # Create a unique session key for this insight
+            session_key = f"{agent_type}_{hash(insight.query)}"
+
+            # Store in local cache
+            self._session_insights[session_key] = insight
+
+            return True
+        except Exception:
+            return False
+
+
+def create_semantic_enhancer(project_path: Path) -> SemanticEnhancer:
+    """Factory function to create a semantic enhancer.
+
+    Args:
+        project_path: Path to the project root
+
+    Returns:
+        Configured SemanticEnhancer instance
+    """
+    return SemanticEnhancer(project_path)
+
+
+async def get_session_enhanced_recommendations(
+    base_recommendations: list[str], agent_type: str, project_path: Path
+) -> list[str]:
+    """Get enhanced recommendations based on session insights.
+
+    Args:
+        base_recommendations: Original recommendations
+        agent_type: Type of agent requesting enhancements
+        project_path: Path to the project root
+
+    Returns:
+        Enhanced recommendations with session context
+    """
+    try:
+        enhancer = create_semantic_enhancer(project_path)
+
+        # Try to find stored insights for this agent type
+        session_insights = [
+            insight
+            for key, insight in enhancer._session_insights.items()
+            if key.startswith(agent_type)
+        ]
+
+        if not session_insights:
+            return base_recommendations
+
+        enhanced = base_recommendations.copy()
+
+        # Add session-based recommendations
+        total_patterns = sum(insight.total_matches for insight in session_insights)
+        if total_patterns > 5:
+            enhanced.append(
+                f"Session context: {total_patterns} similar patterns found "
+                "across recent analyses - consider broader refactoring"
+            )
+
+        return enhanced
+
+    except Exception:
+        # Fallback to original recommendations on error
+        return base_recommendations

crackerjack/cli/options.py

@@ -137,6 +137,12 @@ class Options(BaseModel):
     quick: bool = False
     thorough: bool = False
     clear_cache: bool = False
+
+    # Semantic search options
+    index: str | None = None
+    search: str | None = None
+    semantic_stats: bool = False
+    remove_from_index: str | None = None
     cache_stats: bool = False
 
     # Semantic field names (new primary interface)
@@ -924,6 +930,27 @@ CLI_OPTIONS = {
         "--refresh-cache",
         help="Refresh pre-commit cache to ensure fresh environment.",
     ),
+    # Semantic search options
+    "index": typer.Option(
+        None,
+        "--index",
+        help="Index a file or directory for semantic search (e.g., --index path/to/file.py).",
+    ),
+    "search": typer.Option(
+        None,
+        "--search",
+        help="Perform semantic search across indexed files (e.g., --search 'similarity calculation').",
+    ),
+    "semantic_stats": typer.Option(
+        False,
+        "--semantic-stats",
+        help="Display statistics about the semantic search index.",
+    ),
+    "remove_from_index": typer.Option(
+        None,
+        "--remove-from-index",
+        help="Remove a file from the semantic search index (e.g., --remove-from-index path/to/file.py).",
+    ),
 }
 
 

crackerjack/cli/semantic_handlers.py

@@ -0,0 +1,290 @@
+"""CLI handlers for semantic search operations."""
+
+from pathlib import Path
+from textwrap import dedent
+
+from rich.console import Console
+from rich.panel import Panel
+from rich.table import Table
+
+from crackerjack.models.semantic_models import SearchQuery, SemanticConfig
+from crackerjack.services.vector_store import VectorStore
+
+console = Console()
+
+
+def handle_semantic_index(file_path: str) -> None:
+    """Handle indexing a file for semantic search.
+
+    Args:
+        file_path: Path to the file or directory to index
+    """
+    try:
+        console.print(f"[cyan]Indexing file for semantic search:[/cyan] {file_path}")
+
+        # Validate path
+        path_obj = Path(file_path)
+        if not path_obj.exists():
+            console.print(f"[red]Error:[/red] File does not exist: {file_path}")
+            return
+
+        # Create default configuration
+        config = SemanticConfig(
+            embedding_model="sentence-transformers/all-MiniLM-L6-v2",
+            chunk_size=512,
+            chunk_overlap=50,
+            max_search_results=10,
+            similarity_threshold=0.7,
+            embedding_dimension=384,
+        )
+
+        # Initialize vector store with persistent database
+        db_path = Path.cwd() / ".crackerjack" / "semantic_index.db"
+        db_path.parent.mkdir(exist_ok=True)
+        vector_store = VectorStore(config, db_path=db_path)
+
+        if path_obj.is_file():
+            # Index single file
+            embeddings = vector_store.index_file(path_obj)
+            console.print(
+                f"[green]✅ Successfully indexed {len(embeddings)} chunks from {path_obj.name}[/green]"
+            )
+        else:
+            # Index directory (recursively)
+            total_files = 0
+            total_chunks = 0
+
+            for file in path_obj.rglob("*.py"):  # Index Python files
+                try:
+                    embeddings = vector_store.index_file(file)
+                    total_files += 1
+                    total_chunks += len(embeddings)
+                    console.print(
+                        f"[dim]Indexed {len(embeddings)} chunks from {file.relative_to(path_obj)}[/dim]"
+                    )
+                except Exception as e:
+                    console.print(
+                        f"[yellow]Warning:[/yellow] Failed to index {file}: {e}"
+                    )
+
+            console.print(
+                f"[green]✅ Successfully indexed {total_files} files with {total_chunks} total chunks[/green]"
+            )
+
+        # Show index stats
+        stats = vector_store.get_stats()
+        console.print(
+            f"[cyan]Index now contains:[/cyan] {stats.total_files} files, {stats.total_chunks} chunks"
+        )
+
+    except Exception as e:
+        console.print(
+            f"[red]Error indexing file:[/red] {str(e).replace('[', '\\[').replace(']', '\\]')}"
+        )
+
+
+def handle_semantic_search(query: str) -> None:
+    """Handle semantic search across indexed files.
+
+    Args:
+        query: The search query text
+    """
+    try:
+        console.print(f"[cyan]Performing semantic search for:[/cyan] {query}")
+
+        # Create default configuration
+        config = SemanticConfig(
+            embedding_model="sentence-transformers/all-MiniLM-L6-v2",
+            chunk_size=512,
+            chunk_overlap=50,
+            max_search_results=10,
+            similarity_threshold=0.7,
+            embedding_dimension=384,
+        )
+
+        # Create search query
+        search_query = SearchQuery(
+            query=query,
+            max_results=10,
+            min_similarity=0.3,  # Lower threshold for CLI to show more results
+        )
+
+        # Initialize vector store with persistent database
+        db_path = Path.cwd() / ".crackerjack" / "semantic_index.db"
+        db_path.parent.mkdir(exist_ok=True)
+        vector_store = VectorStore(config, db_path=db_path)
+        results = vector_store.search(search_query)
+
+        if not results:
+            console.print(
+                "[yellow]No results found. Try a different search term or index more files.[/yellow]"
+            )
+            return
+
+        # Display results in a table
+        table = Table(title=f"Semantic Search Results for: '{query}'")
+        table.add_column("File", style="cyan", no_wrap=True)
+        table.add_column("Lines", style="magenta", justify="center")
+        table.add_column("Score", style="green", justify="center")
+        table.add_column("Content Preview", style="white")
+
+        for result in results:
+            # Truncate content for display
+            content_preview = (
+                result.content[:80] + "..."
+                if len(result.content) > 80
+                else result.content
+            )
+            content_preview = content_preview.replace("\n", " ").strip()
+
+            # Escape Rich markup in content to prevent rendering issues
+            content_preview = content_preview.replace("[", "\\[").replace("]", "\\]")
+
+            table.add_row(
+                str(result.file_path.name),
+                f"{result.start_line}-{result.end_line}",
+                f"{result.similarity_score:.3f}",
+                content_preview,
+            )
+
+        console.print(table)
+
+        # Show detailed content for top result
+        if results:
+            top_result = results[0]
+            # Escape Rich markup in the detailed content
+            escaped_content = (
+                top_result.content.strip().replace("[", "\\[").replace("]", "\\]")
+            )
+            console.print(
+                Panel(
+                    dedent(f"""
+                [cyan]Top Result Details:[/cyan]
+                [bold]File:[/bold] {top_result.file_path}
+                [bold]Lines:[/bold] {top_result.start_line}-{top_result.end_line}
+                [bold]Similarity Score:[/bold] {top_result.similarity_score:.4f}
+
+                [bold]Content:[/bold]
+                {escaped_content}
+                """).strip(),
+                    title="🎯 Best Match",
+                    border_style="green",
+                )
+            )
+
+    except Exception as e:
+        console.print(
+            f"[red]Error performing search:[/red] {str(e).replace('[', '\\[').replace(']', '\\]')}"
+        )
+
+
+def handle_semantic_stats() -> None:
+    """Handle displaying semantic search index statistics."""
+    try:
+        console.print("[cyan]Retrieving semantic search index statistics...[/cyan]")
+
+        # Create default configuration
+        config = SemanticConfig(
+            embedding_model="sentence-transformers/all-MiniLM-L6-v2",
+            chunk_size=512,
+            chunk_overlap=50,
+            max_search_results=10,
+            similarity_threshold=0.7,
+            embedding_dimension=384,
+        )
+
+        # Initialize vector store with persistent database
+        db_path = Path.cwd() / ".crackerjack" / "semantic_index.db"
+        db_path.parent.mkdir(exist_ok=True)
+        vector_store = VectorStore(config, db_path=db_path)
+        stats = vector_store.get_stats()
+
+        # Create stats table
+        table = Table(title="Semantic Search Index Statistics")
+        table.add_column("Metric", style="cyan", no_wrap=True)
+        table.add_column("Value", style="green")
+
+        table.add_row("Total Files", str(stats.total_files))
+        table.add_row("Total Chunks", str(stats.total_chunks))
+        table.add_row("Index Size", f"{stats.index_size_mb:.2f} MB")
+
+        # Calculate average chunks per file
+        avg_chunks = (
+            stats.total_chunks / stats.total_files if stats.total_files > 0 else 0.0
+        )
+        table.add_row("Average Chunks per File", f"{avg_chunks:.1f}")
+
+        table.add_row("Embedding Model", config.embedding_model)
+        table.add_row("Embedding Dimension", "384")  # ONNX fallback uses 384 dimensions
+
+        if stats.last_updated:
+            table.add_row(
+                "Last Updated", stats.last_updated.strftime("%Y-%m-%d %H:%M:%S")
+            )
+
+        console.print(table)
+
+        if stats.total_files == 0:
+            console.print(
+                Panel(
+                    "[yellow]The semantic search index is empty. Use [bold]--index[/bold] to add files.[/yellow]",
+                    title="💡 Tip",
+                    border_style="yellow",
+                )
+            )
+
+    except Exception as e:
+        console.print(
+            f"[red]Error retrieving stats:[/red] {str(e).replace('[', '\\[').replace(']', '\\]')}"
+        )
+
+
+def handle_remove_from_semantic_index(file_path: str) -> None:
+    """Handle removing a file from the semantic search index.
+
+    Args:
+        file_path: Path to the file to remove
+    """
+    try:
+        console.print(
+            f"[cyan]Removing file from semantic search index:[/cyan] {file_path}"
+        )
+
+        # Validate path
+        path_obj = Path(file_path)
+
+        # Create default configuration
+        config = SemanticConfig(
+            embedding_model="sentence-transformers/all-MiniLM-L6-v2",
+            chunk_size=512,
+            chunk_overlap=50,
+            max_search_results=10,
+            similarity_threshold=0.7,
+            embedding_dimension=384,
+        )
+
+        # Initialize vector store with persistent database
+        db_path = Path.cwd() / ".crackerjack" / "semantic_index.db"
+        db_path.parent.mkdir(exist_ok=True)
+        vector_store = VectorStore(config, db_path=db_path)
+        success = vector_store.remove_file(path_obj)
+
+        if success:
+            console.print(
+                f"[green]✅ Successfully removed {path_obj.name} from index[/green]"
+            )
+        else:
+            console.print(
+                f"[yellow]Warning:[/yellow] File {path_obj.name} was not found in index"
+            )
+
+        # Show updated stats
+        stats = vector_store.get_stats()
+        console.print(
+            f"[cyan]Index now contains:[/cyan] {stats.total_files} files, {stats.total_chunks} chunks"
+        )
+
+    except Exception as e:
+        console.print(
+            f"[red]Error removing file:[/red] {str(e).replace('[', '\\[').replace(']', '\\]')}"
+        )