contextual-engine 0.1.0__py3-none-any.whl

contextual/__init__.py

@@ -0,0 +1,18 @@
+"""Contextual: Temporal-first local AI context engine.
+
+A tool-agnostic semantic code memory system that eliminates AI hallucinations
+through bi-temporal fact tracking and deterministic retrieval.
+"""
+from __future__ import annotations
+
+
+__version__ = "0.1.0"
+__author__ = "Contextual Team"
+__license__ = "BSL-1.1"
+
+# Public API exports will be added as modules are built
+__all__ = [
+    "__author__",
+    "__license__",
+    "__version__",
+]

contextual/__main__.py

@@ -0,0 +1,11 @@
+"""Entry point for `python -m contextual` invocation.
+
+Delegates to the Typer CLI defined in cli.py.
+"""
+from __future__ import annotations
+
+from contextual.cli import app
+
+
+if __name__ == "__main__":
+    app()

contextual/cli.py

@@ -0,0 +1,339 @@
+"""CLI for Contextual - Temporal-first local code memory.
+
+Main commands:
+- init: Initialize configuration
+- index: Index a code repository
+- search: Search indexed code
+- stats: Show index statistics
+"""
+
+from __future__ import annotations
+
+import sys
+from pathlib import Path
+from typing import Annotated, Optional
+
+import typer
+from rich.console import Console
+from rich.table import Table
+
+from contextual.embedding import embed_query_simple
+from contextual.indexing.pipeline import IndexingPipeline
+from contextual.observability.logging import get_logger
+from contextual.retrieval.search import hybrid_search, SearchResult
+from contextual.storage.sqlite_pool import SQLitePool
+
+
+logger = get_logger(__name__)
+console = Console()
+app = typer.Typer(
+    name="contextual",
+    help="Temporal-first local code memory for AI tools",
+    add_completion=False,
+)
+
+
+@app.command()
+def init(
+    path: Annotated[
+        Optional[Path],
+        typer.Argument(help="Repository path to initialize (default: current directory)"),
+    ] = None,
+) -> None:
+    """Initialize Contextual configuration for a repository.
+    
+    Creates .contextual/ directory with database and config.
+    """
+    repo_path = (path or Path.cwd()).resolve()
+    
+    if not repo_path.exists():
+        console.print(f"[red]Error:[/red] Path does not exist: {repo_path}")
+        raise typer.Exit(1)
+    
+    # Create .contextual directory
+    contextual_dir = repo_path / ".contextual"
+    contextual_dir.mkdir(exist_ok=True)
+    
+    # Initialize database
+    db_path = contextual_dir / "contextual.db"
+    
+    console.print(f"[bold]Initializing Contextual in:[/bold] {repo_path}")
+    
+    try:
+        # Create pool and run migrations
+        from contextual.storage.migrations import run_migrations
+        
+        pool = SQLitePool(db_path)
+        with pool.writer() as conn:
+            run_migrations(conn)
+        pool.close()
+        
+        console.print(f"[green]✓[/green] Created database: {db_path}")
+        console.print(f"[green]✓[/green] Initialization complete")
+        console.print(f"\n[dim]Next steps:[/dim]")
+        console.print(f"  contextual index {repo_path}")
+        console.print(f"  contextual search 'your query'")
+        
+    except Exception as e:
+        console.print(f"[red]Error:[/red] Initialization failed: {e}")
+        logger.exception("Initialization failed")
+        raise typer.Exit(1)
+
+
+@app.command()
+def index(
+    path: Annotated[
+        Optional[Path],
+        typer.Argument(help="Repository path to index (default: current directory)"),
+    ] = None,
+    force: Annotated[
+        bool,
+        typer.Option("--force", "-f", help="Force re-index even if up-to-date"),
+    ] = False,
+) -> None:
+    """Index a code repository for semantic search.
+    
+    Discovers source files, extracts symbols, generates embeddings,
+    and builds search index (BM25 + vector).
+    """
+    repo_path = (path or Path.cwd()).resolve()
+    
+    if not repo_path.exists():
+        console.print(f"[red]Error:[/red] Path does not exist: {repo_path}")
+        raise typer.Exit(1)
+    
+    # Check for .contextual directory
+    contextual_dir = repo_path / ".contextual"
+    if not contextual_dir.exists():
+        console.print(f"[yellow]Warning:[/yellow] Not initialized. Running init first...")
+        init(repo_path)
+    
+    db_path = contextual_dir / "contextual.db"
+    
+    console.print(f"[bold]Indexing:[/bold] {repo_path}")
+    
+    try:
+        # Initialize pipeline
+        pool = SQLitePool(db_path)
+        pipeline = IndexingPipeline(repo_root=repo_path, db_pool=pool)
+        
+        # Run indexing
+        with console.status("[bold green]Indexing files..."):
+            result = pipeline.index_repository()
+        
+        # Display results
+        console.print(f"\n[green]✓[/green] Indexing complete")
+        
+        # Results table
+        table = Table(show_header=True, header_style="bold cyan")
+        table.add_column("Metric", style="dim")
+        table.add_column("Value", justify="right")
+        
+        table.add_row("Files indexed", str(result.get("files", 0)))
+        table.add_row("Chunks created", str(result.get("chunks", 0)))
+        table.add_row("Embeddings generated", str(result.get("embeddings", 0)))
+        table.add_row("Symbols extracted", str(result.get("symbols", 0)))
+        table.add_row("Duration", f"{result.get('duration_ms', 0) / 1000:.2f}s")
+        
+        console.print(table)
+        
+        pool.close()
+        
+    except Exception as e:
+        console.print(f"[red]Error:[/red] Indexing failed: {e}")
+        logger.exception("Indexing failed")
+        raise typer.Exit(1)
+
+
+@app.command()
+def search(
+    query: Annotated[str, typer.Argument(help="Search query")],
+    path: Annotated[
+        Optional[Path],
+        typer.Option("--path", "-p", help="Repository path (default: current directory)"),
+    ] = None,
+    limit: Annotated[
+        int,
+        typer.Option("--limit", "-n", help="Number of results", min=1, max=50),
+    ] = 10,
+    language: Annotated[
+        Optional[str],
+        typer.Option("--language", "-l", help="Filter by language (py, ts, js, rs, go)"),
+    ] = None,
+) -> None:
+    """Search indexed code semantically.
+    
+    Uses hybrid search (BM25 + vector embeddings) with RRF fusion.
+    """
+    repo_path = (path or Path.cwd()).resolve()
+    contextual_dir = repo_path / ".contextual"
+    
+    if not contextual_dir.exists():
+        console.print(f"[red]Error:[/red] Repository not indexed. Run 'contextual index' first.")
+        raise typer.Exit(1)
+    
+    db_path = contextual_dir / "contextual.db"
+    
+    console.print(f"[bold]Searching:[/bold] {query}\n")
+    
+    try:
+        # Initialize database
+        pool = SQLitePool(db_path)
+        
+        # Embed query
+        query_embedding = embed_query_simple(query)
+        
+        # Execute search
+        with pool.reader() as conn:
+            results: list[SearchResult] = hybrid_search(
+                conn=conn,
+                query=query,
+                query_embedding=query_embedding,
+                top_k=limit,
+                language=language,
+            )
+        
+        if not results:
+            console.print("[yellow]No results found[/yellow]")
+            pool.close()
+            return
+        
+        # Display results
+        for i, result in enumerate(results, 1):
+            console.print(f"[bold cyan]{i}. {result.path}[/bold cyan]")
+            console.print(f"   Lines {result.start_line}-{result.end_line} | Score: {result.score:.3f}")
+            
+            if result.symbol_name:
+                console.print(f"   Symbol: [green]{result.symbol_name}[/green] ({result.chunk_type})")
+            
+            # Show snippet
+            console.print(f"   [dim]{result.snippet}[/dim]\n")
+        
+        pool.close()
+        
+    except Exception as e:
+        console.print(f"[red]Error:[/red] Search failed: {e}")
+        logger.exception("Search failed")
+        raise typer.Exit(1)
+
+
+@app.command()
+def stats(
+    path: Annotated[
+        Optional[Path],
+        typer.Argument(help="Repository path (default: current directory)"),
+    ] = None,
+) -> None:
+    """Show index statistics for a repository."""
+    repo_path = (path or Path.cwd()).resolve()
+    contextual_dir = repo_path / ".contextual"
+    
+    if not contextual_dir.exists():
+        console.print(f"[red]Error:[/red] Repository not indexed. Run 'contextual index' first.")
+        raise typer.Exit(1)
+    
+    db_path = contextual_dir / "contextual.db"
+    
+    try:
+        pool = SQLitePool(db_path)
+        
+        # Query statistics
+        with pool.reader() as conn:
+            # File count
+            cursor = conn.execute("SELECT COUNT(*) FROM files")
+            file_count = cursor.fetchone()[0]
+            
+            # Chunk count
+            cursor = conn.execute("SELECT COUNT(*) FROM chunks")
+            chunk_count = cursor.fetchone()[0]
+            
+            # Symbol count
+            cursor = conn.execute("SELECT COUNT(*) FROM code_symbols")
+            symbol_count = cursor.fetchone()[0]
+            
+            # Language distribution
+            cursor = conn.execute("""
+                SELECT language, COUNT(*) as count
+                FROM files
+                GROUP BY language
+                ORDER BY count DESC
+            """)
+            languages = cursor.fetchall()
+            
+            # Indexing state
+            cursor = conn.execute("""
+                SELECT last_full_index_at, total_files, total_chunks
+                FROM indexing_state
+                LIMIT 1
+            """)
+            state = cursor.fetchone()
+        
+        # Display statistics
+        console.print(f"[bold]Statistics for:[/bold] {repo_path}\n")
+        
+        table = Table(show_header=True, header_style="bold cyan")
+        table.add_column("Metric", style="dim")
+        table.add_column("Value", justify="right")
+        
+        table.add_row("Files indexed", str(file_count))
+        table.add_row("Chunks created", str(chunk_count))
+        table.add_row("Symbols extracted", str(symbol_count))
+        
+        if state:
+            table.add_row("Last indexed", str(state[0]))
+        
+        console.print(table)
+        
+        # Language distribution
+        if languages:
+            console.print("\n[bold]Languages:[/bold]")
+            lang_table = Table(show_header=False)
+            lang_table.add_column("Language", style="cyan")
+            lang_table.add_column("Files", justify="right")
+            
+            for lang, count in languages:
+                lang_table.add_row(lang or "unknown", str(count))
+            
+            console.print(lang_table)
+        
+        # Database stats
+        db_stats = pool.get_db_stats()
+        console.print(f"\n[dim]Database size: {db_stats.get('db_size_bytes', 0) / 1024 / 1024:.2f} MB[/dim]")
+        
+        pool.close()
+        
+    except Exception as e:
+        console.print(f"[red]Error:[/red] Failed to get statistics: {e}")
+        logger.exception("Stats failed")
+        raise typer.Exit(1)
+
+
+@app.command()
+def version() -> None:
+    """Show Contextual version."""
+    try:
+        from contextual import __version__
+        console.print(f"Contextual version {__version__}")
+    except ImportError:
+        console.print("Contextual version 0.1.0")
+
+
+def main() -> None:
+    """Entry point for CLI."""
+    try:
+        app()
+    except KeyboardInterrupt:
+        console.print("\n[yellow]Interrupted[/yellow]")
+        sys.exit(130)
+    except Exception as e:
+        console.print(f"[red]Fatal error:[/red] {e}")
+        logger.exception("Fatal error")
+        sys.exit(1)
+
+from contextual.cli_docs import docs_app, setup_app
+app.add_typer(docs_app,  name="docs",  help="Index and search documentation.")
+app.add_typer(setup_app, name="setup", help="Configure Contextual in your IDE/AI client.")
+
+
+if __name__ == "__main__":
+    main()