stache-tools 0.1.0__py3-none-any.whl

stache_tools/__init__.py

@@ -0,0 +1,33 @@
+"""Stache Tools - Client library, CLI, and MCP server for Stache RAG system."""
+
+from stache_tools.client import StacheAPI as StacheClient
+from stache_tools.client.config import StacheConfig
+from stache_tools.client.exceptions import (
+    StacheAPIError,
+    StacheAuthError,
+    StacheConnectionError,
+    StacheError,
+    StacheNotFoundError,
+)
+from stache_tools.loaders import LoaderRegistry
+from stache_tools.loaders.base import DocumentLoader, LoadedDocument
+
+try:
+    from importlib.metadata import version
+    __version__ = version("stache-tools")
+except Exception:
+    __version__ = "0.1.0"  # Fallback for development
+
+__all__ = [
+    "DocumentLoader",
+    "LoadedDocument",
+    "LoaderRegistry",
+    "StacheAPIError",
+    "StacheAuthError",
+    "StacheClient",
+    "StacheConfig",
+    "StacheConnectionError",
+    "StacheError",
+    "StacheNotFoundError",
+    "__version__",
+]

stache_tools/cli/__init__.py

@@ -0,0 +1,5 @@
+"""CLI package for Stache tools."""
+
+from stache_tools.cli.main import main
+
+__all__ = ["main"]

stache_tools/cli/__main__.py

@@ -0,0 +1,6 @@
+"""Allow running as python -m stache_tools.cli."""
+
+from stache_tools.cli import main
+
+if __name__ == "__main__":
+    main()

stache_tools/cli/documents.py

@@ -0,0 +1,120 @@
+"""Document management commands."""
+
+import json
+
+import click
+from rich.console import Console
+from rich.panel import Panel
+from rich.table import Table
+
+from ..client import StacheAPI
+
+console = Console()
+
+
+@click.group()
+def doc():
+    """Manage documents."""
+    pass
+
+
+@doc.command("list")
+@click.option("--namespace", "-n", help="Filter by namespace")
+@click.option("--limit", "-l", default=50, help="Max documents (up to 100)")
+@click.option("--json", "as_json", is_flag=True, help="Output as JSON")
+def list_documents(namespace: str | None, limit: int, as_json: bool):
+    """List documents."""
+    api = StacheAPI()
+
+    try:
+        result = api.list_documents(namespace=namespace, limit=limit)
+
+        if as_json:
+            console.print_json(json.dumps(result))
+            return
+
+        documents = result.get("documents", [])
+
+        if not documents:
+            console.print("[yellow]No documents found.[/yellow]")
+            return
+
+        table = Table(title="Documents")
+        table.add_column("ID", style="cyan", max_width=36)
+        table.add_column("Filename")
+        table.add_column("Namespace")
+        table.add_column("Chunks", justify="right")
+
+        for d in documents:
+            table.add_row(
+                d.get("doc_id", "")[:36],
+                d.get("filename", "")[:30],
+                d.get("namespace", "default"),
+                str(d.get("chunk_count", d.get("total_chunks", "?"))),
+            )
+
+        console.print(table)
+
+        # Show pagination info
+        next_key = result.get("next_key")
+        if next_key:
+            console.print(f"\n[dim]More results available. Use --limit to fetch more.[/dim]")
+    finally:
+        api.close()
+
+
+@doc.command("get")
+@click.argument("doc_id")
+@click.option("--namespace", "-n", default="default", help="Namespace containing the document")
+@click.option("--json", "as_json", is_flag=True, help="Output as JSON")
+def get_document(doc_id: str, namespace: str, as_json: bool):
+    """Get document details and content."""
+    api = StacheAPI()
+
+    try:
+        result = api.get_document(doc_id, namespace)
+
+        if as_json:
+            console.print_json(json.dumps(result))
+            return
+
+        # Document info panel
+        info = (
+            f"[bold]ID:[/bold] {result.get('doc_id', '')}\n"
+            f"[bold]Namespace:[/bold] {result.get('namespace', 'default')}\n"
+            f"[bold]Chunks:[/bold] {result.get('chunk_count', result.get('total_chunks', '?'))}\n"
+            f"[bold]Created:[/bold] {result.get('created_at', '')[:19] if result.get('created_at') else '-'}"
+        )
+        console.print(Panel(info, title=f"[cyan]{result.get('filename', 'Untitled')}[/cyan]"))
+
+        # Document content
+        text = result.get("reconstructed_text", result.get("text", ""))
+        if text:
+            console.print("\n[bold]Content:[/bold]")
+            console.print(text[:2000])
+            if len(text) > 2000:
+                console.print(f"\n[dim]... ({len(text) - 2000} more characters)[/dim]")
+    finally:
+        api.close()
+
+
+@doc.command("delete")
+@click.argument("doc_id")
+@click.option("--namespace", "-n", default="default", help="Namespace containing the document")
+@click.option("--yes", "-y", is_flag=True, help="Skip confirmation")
+def delete_document(doc_id: str, namespace: str, yes: bool):
+    """Delete a document."""
+    if not yes:
+        click.confirm(f"Delete document '{doc_id}'?", abort=True)
+
+    api = StacheAPI()
+
+    try:
+        result = api.delete_document(doc_id, namespace)
+        if result.get("success"):
+            chunks = result.get("chunks_deleted", 0)
+            console.print(f"[green]Deleted document ({chunks} chunks)[/green]")
+        else:
+            console.print(f"[red]Error:[/red] {result.get('error')}")
+    finally:
+        api.close()

stache_tools/cli/health.py

@@ -0,0 +1,67 @@
+"""Health check command."""
+
+import json
+
+import click
+from rich.console import Console
+
+from ..client import StacheAPI, StacheConfig
+
+console = Console()
+
+
+@click.command()
+@click.option("--check-auth", is_flag=True, help="Validate authentication")
+@click.option("--json", "as_json", is_flag=True, help="Output as JSON")
+def health(check_auth: bool, as_json: bool):
+    """Check API connectivity and health."""
+    config = StacheConfig()
+    api = StacheAPI(config)
+
+    if not as_json:
+        transport = "lambda" if config.lambda_function_name else "http"
+        target = config.lambda_function_name or config.api_url
+        console.print(f"[bold]Transport:[/bold] {transport}")
+        console.print(f"[bold]Target:[/bold] {target}")
+        if transport == "http":
+            console.print(f"[bold]OAuth:[/bold] {'enabled' if config.oauth_enabled else 'disabled'}")
+        console.print()
+
+    try:
+        result = api.health(include_auth=check_auth or config.oauth_enabled)
+
+        if as_json:
+            console.print_json(json.dumps(result))
+            return
+
+        status = result.get("status", "unknown")
+        if status == "healthy":
+            console.print(f"[green]Status: {status}[/green]")
+        else:
+            console.print(f"[yellow]Status: {status}[/yellow]")
+
+        if "auth_status" in result:
+            auth = result["auth_status"]
+            if auth == "valid":
+                console.print(f"[green]Auth: {auth}[/green]")
+            else:
+                console.print(f"[red]Auth: {auth}[/red]")
+
+        # Show providers
+        providers = result.get("providers", {})
+        if providers:
+            console.print()
+            console.print("[bold]Providers:[/bold]")
+            console.print(f"  VectorDB: {providers.get('vectordb_provider', 'unknown')}")
+            console.print(f"  Embedding: {providers.get('embedding_provider', 'unknown')}")
+            console.print(f"  LLM: {providers.get('llm_provider', 'unknown')}")
+
+        if api.last_request_id:
+            console.print(f"\n[dim]Request ID: {api.last_request_id}[/dim]")
+
+    except Exception as e:
+        console.print(f"[red]Health check failed:[/red] {e}")
+        raise click.Abort()
+
+    finally:
+        api.close()

stache_tools/cli/ingest.py

@@ -0,0 +1,215 @@
+"""Ingest command for uploading files to Stache."""
+
+import json
+import os
+import sys
+from pathlib import Path
+
+import click
+from rich.console import Console
+from rich.progress import Progress, SpinnerColumn, TextColumn
+
+from stache_tools.client import StacheAPI
+from stache_tools.client.config import StacheConfig
+from stache_tools.client.exceptions import StacheError
+from stache_tools.loaders import LoaderRegistry
+
+console = Console()
+
+CHUNKING_STRATEGIES = ["auto", "recursive", "markdown", "semantic", "character", "hierarchical", "transcript"]
+
+
+def ingest_file(
+    client: StacheAPI,
+    registry: LoaderRegistry,
+    filepath: Path,
+    namespace: str | None,
+    chunking_strategy: str,
+    metadata: dict | None,
+    prepend_metadata: list[str] | None,
+) -> bool:
+    """Ingest a single file. Returns True on success."""
+    loader = registry.get_loader(filepath.name)
+    if loader is None:
+        console.print(f"[yellow]Skipping {filepath} - no loader available[/yellow]")
+        return False
+
+    try:
+        with open(filepath, "rb") as f:
+            doc = loader.load(f, filepath.name)
+
+        # Merge metadata
+        file_metadata = doc.metadata.copy()
+        file_metadata["source_file"] = str(filepath)
+        if metadata:
+            file_metadata.update(metadata)
+
+        result = client.ingest_text(
+            text=doc.text,
+            namespace=namespace,
+            metadata=file_metadata,
+            chunking_strategy=chunking_strategy,
+            prepend_metadata=prepend_metadata,
+        )
+        chunks = result.get("chunks_created", "?")
+        console.print(f"[green]✓[/green] {filepath.name} → {chunks} chunks")
+        return True
+    except StacheError as e:
+        console.print(f"[red]✗[/red] {filepath.name}: {e}")
+        return False
+    except Exception as e:
+        console.print(f"[red]✗[/red] {filepath.name}: {e}")
+        return False
+
+
+def collect_files(path: Path, recursive: bool) -> list[Path]:
+    """Collect files to ingest."""
+    if path.is_file():
+        return [path]
+
+    if not path.is_dir():
+        return []
+
+    files = []
+    if recursive:
+        for root, _, filenames in os.walk(path):
+            for name in filenames:
+                files.append(Path(root) / name)
+    else:
+        files = [p for p in path.iterdir() if p.is_file()]
+
+    return sorted(files)
+
+
+@click.command("ingest")
+@click.argument("path", type=click.Path(exists=True), required=False)
+@click.option("-n", "--namespace", help="Target namespace")
+@click.option("-r", "--recursive", is_flag=True, help="Recursively process directories")
+@click.option(
+    "-c", "--chunking-strategy",
+    type=click.Choice(CHUNKING_STRATEGIES, case_sensitive=False),
+    default="auto",
+    help="Chunking strategy (default: auto)"
+)
+@click.option("-m", "--metadata", "metadata_json", help="Metadata as JSON (e.g. '{\"author\": \"John\"}')")
+@click.option(
+    "-p", "--prepend-metadata",
+    help="Metadata keys to prepend to chunks (comma-separated, e.g. 'author,topic')"
+)
+@click.option("-t", "--text", "text_input", help="Ingest text directly instead of a file")
+@click.option("--stdin", is_flag=True, help="Read text from stdin")
+def ingest(
+    path: str | None,
+    namespace: str | None,
+    recursive: bool,
+    chunking_strategy: str,
+    metadata_json: str | None,
+    prepend_metadata: str | None,
+    text_input: str | None,
+    stdin: bool,
+) -> None:
+    """Ingest files or text into Stache.
+
+    PATH can be a file or directory. Use -r for recursive directory processing.
+
+    Alternatively, use --text or --stdin to ingest text directly.
+
+    \b
+    Examples:
+      stache ingest document.pdf -n docs
+      stache ingest ./files/ -r -c markdown
+      stache ingest -t "Quick note to remember" -n notes
+      echo "Text from pipe" | stache ingest --stdin -n notes
+      stache ingest sermon.txt -m '{"speaker":"Pastor John"}' -p speaker
+    """
+    config = StacheConfig()
+
+    # Parse metadata
+    metadata = None
+    if metadata_json:
+        try:
+            metadata = json.loads(metadata_json)
+        except json.JSONDecodeError as e:
+            console.print(f"[red]Invalid metadata JSON: {e}[/red]")
+            return
+
+    # Parse prepend_metadata
+    prepend_keys = None
+    if prepend_metadata:
+        prepend_keys = [k.strip() for k in prepend_metadata.split(",") if k.strip()]
+
+    # Handle text input modes
+    if stdin:
+        if not sys.stdin.isatty():
+            text_input = sys.stdin.read()
+        else:
+            console.print("[red]No input on stdin[/red]")
+            return
+
+    if text_input:
+        # Direct text ingestion
+        with StacheAPI(config) as client:
+            try:
+                result = client.ingest_text(
+                    text=text_input,
+                    namespace=namespace,
+                    metadata=metadata,
+                    chunking_strategy=chunking_strategy if chunking_strategy != "auto" else "recursive",
+                    prepend_metadata=prepend_keys,
+                )
+                chunks = result.get("chunks_created", "?")
+                doc_id = result.get("doc_id", result.get("document_id", ""))
+                console.print(f"[green]✓[/green] Ingested text → {chunks} chunks (doc: {doc_id[:8]}...)")
+            except StacheError as e:
+                console.print(f"[red]✗[/red] Failed: {e}")
+        return
+
+    # File/directory ingestion
+    if not path:
+        console.print("[red]Provide a PATH or use --text/--stdin[/red]")
+        return
+
+    registry = LoaderRegistry()
+    target = Path(path)
+    files = collect_files(target, recursive)
+
+    if not files:
+        console.print("[yellow]No files to ingest[/yellow]")
+        return
+
+    console.print(f"Found {len(files)} file(s) to process")
+    if chunking_strategy != "auto":
+        console.print(f"[dim]Chunking strategy: {chunking_strategy}[/dim]")
+
+    success = 0
+    failed = 0
+    skipped = 0
+
+    with StacheAPI(config) as client:
+        with Progress(
+            SpinnerColumn(),
+            TextColumn("[progress.description]{task.description}"),
+            console=console,
+        ) as progress:
+            task = progress.add_task("Ingesting...", total=len(files))
+
+            for filepath in files:
+                progress.update(task, description=f"Processing {filepath.name}")
+
+                loader = registry.get_loader(filepath.name)
+                if loader is None:
+                    skipped += 1
+                elif ingest_file(
+                    client, registry, filepath, namespace,
+                    chunking_strategy if chunking_strategy != "auto" else "recursive",
+                    metadata, prepend_keys
+                ):
+                    success += 1
+                else:
+                    failed += 1
+
+                progress.advance(task)
+
+    # Summary
+    console.print()
+    console.print(f"[bold]Results:[/bold] {success} ingested, {failed} failed, {skipped} skipped")

stache_tools/cli/main.py

@@ -0,0 +1,49 @@
+"""Main CLI entry point."""
+
+from pathlib import Path
+
+import click
+from dotenv import load_dotenv
+
+from stache_tools import __version__
+
+# Load .env from cwd
+_env_file = Path.cwd() / ".env"
+if _env_file.exists():
+    load_dotenv(_env_file)
+
+
+@click.group()
+@click.version_option(version=__version__, prog_name="stache")
+def cli():
+    """Stache CLI - Interact with your knowledge base."""
+    pass
+
+
+def setup_cli():
+    """Register all commands."""
+    from .documents import doc
+    from .health import health
+    from .ingest import ingest
+    from .models import models
+    from .namespaces import namespace
+    from .search import search
+
+    cli.add_command(search)
+    cli.add_command(ingest)
+    cli.add_command(namespace)
+    cli.add_command(doc)
+    cli.add_command(health)
+    cli.add_command(models)
+
+
+setup_cli()
+
+
+def main():
+    """Entry point for stache CLI."""
+    cli()
+
+
+if __name__ == "__main__":
+    main()

stache_tools/cli/models.py

@@ -0,0 +1,58 @@
+"""Model listing command."""
+
+import json
+
+import click
+from rich.console import Console
+from rich.table import Table
+
+from ..client import StacheAPI
+
+console = Console()
+
+
+@click.command("models")
+@click.option("--json", "as_json", is_flag=True, help="Output as JSON")
+def models(as_json: bool):
+    """List available LLM models."""
+    api = StacheAPI()
+
+    try:
+        result = api.list_models()
+
+        if as_json:
+            console.print_json(json.dumps(result))
+            return
+
+        provider = result.get("provider", "unknown")
+        default = result.get("default", "")
+        model_list = result.get("models", [])
+
+        console.print(f"[bold]Provider:[/bold] {provider}")
+        console.print(f"[bold]Default:[/bold] {default}")
+        console.print()
+
+        if not model_list:
+            console.print("[yellow]No models available.[/yellow]")
+            return
+
+        table = Table(title="Available Models")
+        table.add_column("ID", style="cyan")
+        table.add_column("Name")
+        table.add_column("Tier")
+        table.add_column("Context", justify="right")
+
+        for model in model_list:
+            model_id = model.get("id", "")
+            is_default = " *" if model_id == default else ""
+            table.add_row(
+                model_id + is_default,
+                model.get("name", ""),
+                model.get("tier", ""),
+                str(model.get("context_window", "-")),
+            )
+
+        console.print(table)
+        console.print("\n[dim]* = default model[/dim]")
+    finally:
+        api.close()