brainpalace-cli 26.5.1__py3-none-any.whl

brainpalace_cli/__init__.py

@@ -0,0 +1,3 @@
+"""Doc-Serve CLI - Command-line interface for managing Doc-Serve server."""
+
+__version__ = "26.5.1"

brainpalace_cli/cli.py

@@ -0,0 +1,131 @@
+"""Main CLI entry point for brainpalace CLI.
+
+This module provides the command-line interface for managing and querying
+the BrainPalace RAG server.
+"""
+
+import click
+
+from . import __version__
+from .commands import (
+    cache_group,
+    config_group,
+    context_command,
+    doctor_command,
+    folders_group,
+    index_command,
+    init_command,
+    inject_command,
+    install_agent_command,
+    jobs_command,
+    list_command,
+    mcp_command,
+    memories_group,
+    query_command,
+    recall_command,
+    remember_command,
+    reset_command,
+    start_command,
+    status_command,
+    stop_command,
+    submit_session_command,
+    types_group,
+    uninstall_command,
+    whoami_command,
+)
+
+
+@click.group()
+@click.version_option(version=__version__, prog_name="brainpalace")
+def cli() -> None:
+    """BrainPalace CLI - Manage and query the BrainPalace RAG server.
+
+    A command-line interface for interacting with the BrainPalace document
+    indexing and semantic search API.
+
+    \b
+    Project Commands:
+      init     Initialize a new brainpalace project
+      start    Start the server for this project
+      stop     Stop the server for this project
+      list     List all running brainpalace instances
+
+    \b
+    Server Commands:
+      status   Check server status
+      query    Search documents
+      index    Index documents from a folder
+      inject   Index documents with content injection
+      jobs     View and manage job queue
+      reset    Clear all indexed documents
+
+    \b
+    Cache Commands:
+      cache    Manage the embedding cache (status, clear)
+
+    \b
+    Folder Commands:
+      folders  Manage indexed folders (list, add, remove)
+
+    \b
+    File Type Commands:
+      types    List available file type presets
+
+    \b
+    MCP (Model Context Protocol):
+      mcp      Serve BrainPalace over stdio for MCP-aware AI clients
+
+    \b
+    Examples:
+      brainpalace init                                # Initialize project
+      brainpalace start                               # Start server
+      brainpalace status                              # Check server status
+      brainpalace query "how to use python"           # Search documents
+      brainpalace index ./docs                        # Index documents
+      brainpalace index ./src --include-type python   # Index with preset
+      brainpalace inject --script enrich.py ./docs   # Index with injection
+      brainpalace folders list                        # List indexed folders
+      brainpalace folders remove ./docs --yes         # Remove folder chunks
+      brainpalace types list                          # Show file type presets
+      brainpalace stop                                # Stop server
+
+    \b
+    Environment Variables:
+      BRAINPALACE_URL  Server URL (default: http://127.0.0.1:8000)
+    """
+    pass
+
+
+# Register project management commands
+cli.add_command(init_command, name="init")
+cli.add_command(start_command, name="start")
+cli.add_command(stop_command, name="stop")
+cli.add_command(list_command, name="list")
+cli.add_command(whoami_command, name="whoami")
+
+# Register server interaction commands
+cli.add_command(doctor_command, name="doctor")
+cli.add_command(status_command, name="status")
+cli.add_command(query_command, name="query")
+cli.add_command(remember_command, name="remember")
+cli.add_command(recall_command, name="recall")
+cli.add_command(memories_group, name="memories")
+cli.add_command(context_command, name="context")
+cli.add_command(submit_session_command, name="submit-session")
+cli.add_command(index_command, name="index")
+cli.add_command(inject_command, name="inject")
+cli.add_command(jobs_command, name="jobs")
+cli.add_command(reset_command, name="reset")
+cli.add_command(config_group, name="config")
+cli.add_command(folders_group, name="folders")
+cli.add_command(types_group, name="types")
+cli.add_command(cache_group, name="cache")
+cli.add_command(uninstall_command, name="uninstall")
+cli.add_command(install_agent_command, name="install-agent")
+
+# Register MCP server (opt-in stdio shim for non-Claude-Code AI clients)
+cli.add_command(mcp_command, name="mcp")
+
+
+if __name__ == "__main__":
+    cli()

brainpalace_cli/client/__init__.py

@@ -0,0 +1,20 @@
+"""HTTP client for communicating with BrainPalace server."""
+
+from .api_client import (
+    ConnectionError,
+    DocServeClient,
+    DocServeError,
+    FolderInfo,
+    ServerError,
+)
+from .errors import EXIT_CODE_CONNECTION_ERROR, exit_on_connection_error
+
+__all__ = [
+    "DocServeClient",
+    "DocServeError",
+    "ConnectionError",
+    "EXIT_CODE_CONNECTION_ERROR",
+    "FolderInfo",
+    "ServerError",
+    "exit_on_connection_error",
+]

brainpalace_cli/client/api_client.py

@@ -0,0 +1,552 @@
+"""HTTP client for Doc-Serve API communication."""
+
+from dataclasses import dataclass
+from types import TracebackType
+from typing import Any
+
+import httpx
+
+
+class DocServeError(Exception):
+    """Base exception for Doc-Serve client errors."""
+
+    pass
+
+
+class ConnectionError(DocServeError):
+    """Raised when unable to connect to the server."""
+
+    pass
+
+
+class ServerError(DocServeError):
+    """Raised when server returns an error response."""
+
+    def __init__(self, message: str, status_code: int, detail: str | None = None):
+        super().__init__(message)
+        self.status_code = status_code
+        self.detail = detail
+
+
+@dataclass
+class HealthStatus:
+    """Server health status."""
+
+    status: str
+    message: str | None
+    version: str
+    timestamp: str
+
+
+@dataclass
+class IndexingStatus:
+    """Detailed indexing status."""
+
+    total_documents: int
+    total_chunks: int
+    indexing_in_progress: bool
+    current_job_id: str | None
+    progress_percent: float
+    last_indexed_at: str | None
+    indexed_folders: list[str]
+    file_watcher: dict[str, Any] | None = None
+    embedding_cache: dict[str, Any] | None = None
+    migration: dict[str, Any] | None = None
+
+
+@dataclass
+class QueryResult:
+    """Single query result."""
+
+    text: str
+    source: str
+    score: float
+    chunk_id: str
+    metadata: dict[str, Any]
+    vector_score: float | None = None
+    bm25_score: float | None = None
+
+
+@dataclass
+class QueryResponse:
+    """Query response with results."""
+
+    results: list[QueryResult]
+    query_time_ms: float
+    total_results: int
+
+
+@dataclass
+class FolderInfo:
+    """Indexed folder information."""
+
+    folder_path: str
+    chunk_count: int
+    last_indexed: str
+    watch_mode: str = "off"
+    watch_debounce_seconds: int | None = None
+
+
+@dataclass
+class IndexResponse:
+    """Indexing operation response."""
+
+    job_id: str
+    status: str
+    message: str | None
+
+
+class DocServeClient:
+    """HTTP client for Doc-Serve API."""
+
+    def __init__(
+        self,
+        base_url: str = "http://127.0.0.1:8000",
+        timeout: float = 30.0,
+    ):
+        """
+        Initialize the client.
+
+        Args:
+            base_url: Server base URL.
+            timeout: Request timeout in seconds.
+        """
+        self.base_url = base_url.rstrip("/")
+        self.timeout = timeout
+        self._client = httpx.Client(timeout=timeout)
+
+    def __enter__(self) -> "DocServeClient":
+        return self
+
+    def __exit__(
+        self,
+        exc_type: type[BaseException] | None,
+        exc_val: BaseException | None,
+        exc_tb: TracebackType | None,
+    ) -> None:
+        self.close()
+
+    def close(self) -> None:
+        """Close the HTTP client."""
+        self._client.close()
+
+    def _request(
+        self,
+        method: str,
+        path: str,
+        json: dict[str, Any] | None = None,
+        params: dict[str, Any] | None = None,
+    ) -> dict[str, Any]:
+        """
+        Make an HTTP request to the server.
+
+        Args:
+            method: HTTP method (GET, POST, DELETE).
+            path: API path.
+            json: Optional JSON body.
+            params: Optional query parameters.
+
+        Returns:
+            Response JSON data.
+
+        Raises:
+            ConnectionError: If unable to connect.
+            ServerError: If server returns an error.
+        """
+        url = f"{self.base_url}{path}"
+
+        try:
+            response = self._client.request(method, url, json=json, params=params)
+        except httpx.ConnectError as e:
+            raise ConnectionError(
+                f"Unable to connect to server at {self.base_url}. "
+                f"Is the server running? Error: {e}"
+            ) from e
+        except httpx.TimeoutException as e:
+            raise ConnectionError(
+                f"Request timed out after {self.timeout}s. "
+                "The server may be overloaded or unresponsive."
+            ) from e
+
+        if response.status_code >= 400:
+            detail = None
+            try:
+                error_data = response.json()
+                detail = error_data.get("detail", str(error_data))
+            except Exception:
+                detail = response.text
+
+            raise ServerError(
+                f"Server returned {response.status_code}",
+                status_code=response.status_code,
+                detail=detail,
+            )
+
+        result: dict[str, Any] = response.json()
+        return result
+
+    def health(self) -> HealthStatus:
+        """
+        Get server health status.
+
+        Returns:
+            HealthStatus with current status.
+        """
+        data = self._request("GET", "/health/")
+        return HealthStatus(
+            status=data["status"],
+            message=data.get("message"),
+            version=data.get("version", "unknown"),
+            timestamp=data.get("timestamp", ""),
+        )
+
+    def status(self) -> IndexingStatus:
+        """
+        Get detailed indexing status.
+
+        Returns:
+            IndexingStatus with document counts and progress.
+        """
+        data = self._request("GET", "/health/status")
+        return IndexingStatus(
+            total_documents=data.get("total_documents", 0),
+            total_chunks=data.get("total_chunks", 0),
+            indexing_in_progress=data.get("indexing_in_progress", False),
+            current_job_id=data.get("current_job_id"),
+            progress_percent=data.get("progress_percent", 0.0),
+            last_indexed_at=data.get("last_indexed_at"),
+            indexed_folders=data.get("indexed_folders", []),
+            file_watcher=data.get("file_watcher"),
+            embedding_cache=data.get("embedding_cache"),
+        )
+
+    def query(
+        self,
+        query_text: str,
+        top_k: int = 5,
+        similarity_threshold: float = 0.7,
+        mode: str = "hybrid",
+        alpha: float = 0.5,
+        source_types: list[str] | None = None,
+        languages: list[str] | None = None,
+        file_paths: list[str] | None = None,
+        time_decay: bool = True,
+    ) -> QueryResponse:
+        """
+        Query indexed documents.
+
+        Args:
+            query_text: Search query.
+            top_k: Number of results to return.
+            similarity_threshold: Minimum similarity score.
+            mode: Retrieval mode (vector, bm25, hybrid).
+            alpha: Hybrid search weighting (1.0=vector, 0.0=bm25).
+            source_types: Filter by source types (doc, code, test).
+            languages: Filter by programming languages.
+            file_paths: Filter by file path patterns.
+
+        Returns:
+            QueryResponse with matching results.
+        """
+        request_data = {
+            "query": query_text,
+            "top_k": top_k,
+            "similarity_threshold": similarity_threshold,
+            "mode": mode,
+            "alpha": alpha,
+        }
+        if not time_decay:
+            request_data["time_decay"] = False
+        if source_types is not None:
+            request_data["source_types"] = source_types
+        if languages is not None:
+            request_data["languages"] = languages
+        if file_paths is not None:
+            request_data["file_paths"] = file_paths
+
+        data = self._request("POST", "/query/", json=request_data)
+
+        results = [
+            QueryResult(
+                text=r["text"],
+                source=r["source"],
+                score=r["score"],
+                chunk_id=r["chunk_id"],
+                metadata=r.get("metadata", {}),
+                vector_score=r.get("vector_score"),
+                bm25_score=r.get("bm25_score"),
+            )
+            for r in data.get("results", [])
+        ]
+
+        return QueryResponse(
+            results=results,
+            query_time_ms=data.get("query_time_ms", 0.0),
+            total_results=data.get("total_results", len(results)),
+        )
+
+    def index(
+        self,
+        folder_path: str,
+        chunk_size: int = 512,
+        chunk_overlap: int = 50,
+        recursive: bool = True,
+        include_code: bool = False,
+        supported_languages: list[str] | None = None,
+        code_chunk_strategy: str = "ast_aware",
+        include_patterns: list[str] | None = None,
+        exclude_patterns: list[str] | None = None,
+        include_types: list[str] | None = None,
+        generate_summaries: bool = False,
+        force: bool = False,
+        allow_external: bool = False,
+        injector_script: str | None = None,
+        folder_metadata_file: str | None = None,
+        dry_run: bool = False,
+        watch_mode: str | None = None,
+        watch_debounce_seconds: int | None = None,
+    ) -> IndexResponse:
+        """
+        Enqueue an indexing job for documents and optionally code from a folder.
+
+        Args:
+            folder_path: Path to folder with documents.
+            chunk_size: Target chunk size in tokens.
+            chunk_overlap: Overlap between chunks.
+            recursive: Whether to scan recursively.
+            include_code: Whether to index source code files.
+            supported_languages: Languages to index (defaults to all).
+            code_chunk_strategy: Strategy for code chunking.
+            include_patterns: Additional include patterns.
+            exclude_patterns: Additional exclude patterns.
+            include_types: File type preset names (e.g., ["python", "docs"]).
+            generate_summaries: Generate LLM summaries for code chunks.
+            force: Bypass deduplication and force a new job.
+            allow_external: Allow paths outside the project directory.
+            injector_script: Path to Python script exporting process_chunk().
+            folder_metadata_file: Path to JSON file with static metadata.
+            dry_run: Validate injector against sample chunks without indexing.
+            watch_mode: Watch mode for auto-reindex: 'auto' or 'off'.
+            watch_debounce_seconds: Per-folder debounce in seconds.
+
+        Returns:
+            IndexResponse with job ID and queue status.
+        """
+        body: dict[str, Any] = {
+            "folder_path": folder_path,
+            "chunk_size": chunk_size,
+            "chunk_overlap": chunk_overlap,
+            "recursive": recursive,
+            "include_code": include_code,
+            "supported_languages": supported_languages,
+            "code_chunk_strategy": code_chunk_strategy,
+            "include_patterns": include_patterns,
+            "exclude_patterns": exclude_patterns,
+            "generate_summaries": generate_summaries,
+            "force": force,
+        }
+        if include_types is not None:
+            body["include_types"] = include_types
+        if injector_script is not None:
+            body["injector_script"] = injector_script
+        if folder_metadata_file is not None:
+            body["folder_metadata_file"] = folder_metadata_file
+        if dry_run:
+            body["dry_run"] = True
+        if watch_mode is not None:
+            body["watch_mode"] = watch_mode
+        if watch_debounce_seconds is not None:
+            body["watch_debounce_seconds"] = watch_debounce_seconds
+
+        data = self._request(
+            "POST",
+            "/index/",
+            json=body,
+            params={"force": force, "allow_external": allow_external},
+        )
+
+        return IndexResponse(
+            job_id=data["job_id"],
+            status=data["status"],
+            message=data.get("message"),
+        )
+
+    def list_folders(self) -> list[FolderInfo]:
+        """
+        List all indexed folders.
+
+        Returns:
+            List of FolderInfo objects sorted by folder path.
+        """
+        data = self._request("GET", "/index/folders/")
+        folders: list[FolderInfo] = [
+            FolderInfo(
+                folder_path=f["folder_path"],
+                chunk_count=f["chunk_count"],
+                last_indexed=f["last_indexed"],
+                watch_mode=f.get("watch_mode", "off"),
+                watch_debounce_seconds=f.get("watch_debounce_seconds"),
+            )
+            for f in data.get("folders", [])
+        ]
+        return folders
+
+    def delete_folder(self, folder_path: str) -> dict[str, Any]:
+        """
+        Delete all indexed chunks for a folder.
+
+        Args:
+            folder_path: Absolute path to the folder to remove.
+
+        Returns:
+            Response dict with folder_path, chunks_deleted, and message.
+        """
+        result: dict[str, Any] = self._request(
+            "DELETE",
+            "/index/folders/",
+            json={"folder_path": folder_path},
+        )
+        return result
+
+    def reset(self) -> IndexResponse:
+        """
+        Reset the index by deleting all documents.
+
+        Returns:
+            IndexResponse confirming reset.
+        """
+        data = self._request("DELETE", "/index/")
+
+        return IndexResponse(
+            job_id=data.get("job_id", "reset"),
+            status=data["status"],
+            message=data.get("message"),
+        )
+
+    def list_jobs(self, limit: int = 20) -> list[dict[str, Any]]:
+        """
+        List jobs in the queue.
+
+        Args:
+            limit: Maximum number of jobs to return.
+
+        Returns:
+            List of job dictionaries.
+        """
+        data = self._request("GET", f"/index/jobs/?limit={limit}")
+        jobs: list[dict[str, Any]] = data.get("jobs", [])
+        return jobs
+
+    def get_job(self, job_id: str) -> dict[str, Any]:
+        """
+        Get details for a specific job.
+
+        Args:
+            job_id: The job ID to look up.
+
+        Returns:
+            Job detail dictionary.
+        """
+        return self._request("GET", f"/index/jobs/{job_id}")
+
+    def cancel_job(self, job_id: str) -> dict[str, Any]:
+        """
+        Cancel a specific job.
+
+        Args:
+            job_id: The job ID to cancel.
+
+        Returns:
+            Cancellation result dictionary.
+        """
+        return self._request("DELETE", f"/index/jobs/{job_id}")
+
+    def cache_status(self) -> dict[str, Any]:
+        """
+        Get embedding cache status.
+
+        Returns:
+            Dict with hits, misses, hit_rate, mem_entries, entry_count, size_bytes.
+
+        Raises:
+            ConnectionError: If unable to connect.
+            ServerError: If server returns an error.
+        """
+        return self._request("GET", "/index/cache/")
+
+    def clear_cache(self) -> dict[str, Any]:
+        """
+        Clear the embedding cache.
+
+        Returns:
+            Dict with count, size_bytes, size_mb of cleared entries.
+
+        Raises:
+            ConnectionError: If unable to connect.
+            ServerError: If server returns an error.
+        """
+        return self._request("DELETE", "/index/cache/")
+
+    # ----- Curated memory namespace (Phase 030) -------------------------
+
+    def remember(
+        self,
+        text: str,
+        section: str = "Notes",
+        tags: list[str] | None = None,
+        origin: str = "user",
+    ) -> dict[str, Any]:
+        """Create a curated memory."""
+        return self._request(
+            "POST",
+            "/memories/",
+            json={
+                "text": text,
+                "section": section,
+                "tags": tags or [],
+                "origin": origin,
+            },
+        )
+
+    def recall(self, query: str, top_k: int = 5) -> dict[str, Any]:
+        """Recall from the memory namespace only."""
+        return self._request(
+            "POST", "/memories/recall", json={"query": query, "top_k": top_k}
+        )
+
+    def list_memories(
+        self,
+        tag: str | None = None,
+        section: str | None = None,
+        include_obsolete: bool = False,
+    ) -> dict[str, Any]:
+        """List curated memories."""
+        params: dict[str, Any] = {"include_obsolete": include_obsolete}
+        if tag:
+            params["tag"] = tag
+        if section:
+            params["section"] = section
+        return self._request("GET", "/memories/", params=params)
+
+    def delete_memory(self, memory_id: str) -> dict[str, Any]:
+        """Delete a curated memory by id."""
+        return self._request("DELETE", f"/memories/{memory_id}")
+
+    def obsolete_memory(
+        self, memory_id: str, superseded_by: str | None = None
+    ) -> dict[str, Any]:
+        """Mark a curated memory obsolete."""
+        params = {"superseded_by": superseded_by} if superseded_by else None
+        return self._request(
+            "POST", f"/memories/{memory_id}/obsolete", params=params
+        )
+
+    # ----- Session-start context (Phase 035) ---------------------------
+
+    def session_context(self) -> dict[str, Any]:
+        """Fetch the session-start context block."""
+        return self._request("GET", "/context/session-start")
+
+    def submit_session_extract(self, payload: dict[str, Any]) -> dict[str, Any]:
+        """Persist a session extraction payload (Phase 060)."""
+        return self._request("POST", "/sessions/extract", json=payload)