agent-brain-cli 1.1.0__tar.gz

agent_brain_cli-1.1.0/PKG-INFO

@@ -0,0 +1,95 @@
+Metadata-Version: 2.3
+Name: agent-brain-cli
+Version: 1.1.0
+Summary: CLI management tool for agent-brain-rag server
+License: MIT
+Keywords: rag,cli,documentation,semantic-search,ai-agent,brain
+Author: Spillwave Solutions
+Requires-Python: >=3.10,<4.0
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Requires-Dist: click (>=8.1.0,<9.0.0)
+Requires-Dist: httpx (>=0.28.0,<0.29.0)
+Requires-Dist: rich (>=13.9.0,<14.0.0)
+Project-URL: Homepage, https://github.com/SpillwaveSolutions/doc-serve
+Project-URL: Repository, https://github.com/SpillwaveSolutions/doc-serve
+Description-Content-Type: text/markdown
+
+# doc-svr-ctl
+
+Command-line interface for managing the Doc-Serve document indexing and search server.
+
+## Installation
+
+```bash
+pip install doc-serve-cli
+```
+
+## Quick Start
+
+```bash
+doc-svr-ctl init          # Initialize project
+doc-svr-ctl start         # Start server
+doc-svr-ctl index ./docs  # Index documents
+doc-svr-ctl query "search term"
+```
+
+## Development Installation
+
+```bash
+cd doc-svr-ctl
+poetry install
+```
+
+## Usage
+
+```bash
+# Check server status
+doc-svr-ctl status
+
+# Search documents
+doc-svr-ctl query "how to use python"
+
+# Index documents from a folder
+doc-svr-ctl index ./docs
+
+# Reset/clear the index
+doc-svr-ctl reset --yes
+```
+
+## Configuration
+
+Set the server URL via environment variable:
+
+```bash
+export DOC_SERVE_URL=http://localhost:8000
+```
+
+Or use the `--url` flag:
+
+```bash
+doc-svr-ctl --url http://localhost:8000 status
+```
+
+## Commands
+
+| Command | Description |
+|---------|-------------|
+| `status` | Check server health and indexing status |
+| `query` | Search indexed documents |
+| `index` | Start indexing documents from a folder |
+| `reset` | Clear all indexed documents |
+
+## Options
+
+All commands support:
+- `--url` - Server URL (or `DOC_SERVE_URL` env var)
+- `--json` - Output as JSON for scripting
+

agent_brain_cli-1.1.0/README.md

@@ -0,0 +1,70 @@
+# doc-svr-ctl
+
+Command-line interface for managing the Doc-Serve document indexing and search server.
+
+## Installation
+
+```bash
+pip install doc-serve-cli
+```
+
+## Quick Start
+
+```bash
+doc-svr-ctl init          # Initialize project
+doc-svr-ctl start         # Start server
+doc-svr-ctl index ./docs  # Index documents
+doc-svr-ctl query "search term"
+```
+
+## Development Installation
+
+```bash
+cd doc-svr-ctl
+poetry install
+```
+
+## Usage
+
+```bash
+# Check server status
+doc-svr-ctl status
+
+# Search documents
+doc-svr-ctl query "how to use python"
+
+# Index documents from a folder
+doc-svr-ctl index ./docs
+
+# Reset/clear the index
+doc-svr-ctl reset --yes
+```
+
+## Configuration
+
+Set the server URL via environment variable:
+
+```bash
+export DOC_SERVE_URL=http://localhost:8000
+```
+
+Or use the `--url` flag:
+
+```bash
+doc-svr-ctl --url http://localhost:8000 status
+```
+
+## Commands
+
+| Command | Description |
+|---------|-------------|
+| `status` | Check server health and indexing status |
+| `query` | Search indexed documents |
+| `index` | Start indexing documents from a folder |
+| `reset` | Clear all indexed documents |
+
+## Options
+
+All commands support:
+- `--url` - Server URL (or `DOC_SERVE_URL` env var)
+- `--json` - Output as JSON for scripting

agent_brain_cli-1.1.0/doc_svr_ctl/__init__.py

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

agent_brain_cli-1.1.0/doc_svr_ctl/cli.py

@@ -0,0 +1,70 @@
+"""Main CLI entry point for doc-svr-ctl."""
+
+import click
+
+from . import __version__
+from .commands import (
+    index_command,
+    init_command,
+    list_command,
+    query_command,
+    reset_command,
+    start_command,
+    status_command,
+    stop_command,
+)
+
+
+@click.group()
+@click.version_option(version=__version__, prog_name="doc-svr-ctl")
+def cli() -> None:
+    """Doc-Serve CLI - Manage and query the Doc-Serve server.
+
+    A command-line interface for interacting with the Doc-Serve document
+    indexing and semantic search API.
+
+    \b
+    Project Commands:
+      init     Initialize a new doc-serve project
+      start    Start the server for this project
+      stop     Stop the server for this project
+      list     List all running doc-serve instances
+
+    \b
+    Server Commands:
+      status   Check server status
+      query    Search documents
+      index    Index documents from a folder
+      reset    Clear all indexed documents
+
+    \b
+    Examples:
+      doc-svr-ctl init                      # Initialize project
+      doc-svr-ctl start                     # Start server
+      doc-svr-ctl status                    # Check server status
+      doc-svr-ctl query "how to use python" # Search documents
+      doc-svr-ctl index ./docs              # Index documents
+      doc-svr-ctl stop                      # Stop server
+
+    \b
+    Environment Variables:
+      DOC_SERVE_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")
+
+# Register server interaction commands
+cli.add_command(status_command, name="status")
+cli.add_command(query_command, name="query")
+cli.add_command(index_command, name="index")
+cli.add_command(reset_command, name="reset")
+
+
+if __name__ == "__main__":
+    cli()

agent_brain_cli-1.1.0/doc_svr_ctl/client/__init__.py

@@ -0,0 +1,5 @@
+"""HTTP client for communicating with Doc-Serve server."""
+
+from .api_client import ConnectionError, DocServeClient, DocServeError, ServerError
+
+__all__ = ["DocServeClient", "DocServeError", "ConnectionError", "ServerError"]

agent_brain_cli-1.1.0/doc_svr_ctl/client/api_client.py

@@ -0,0 +1,334 @@
+"""HTTP client for Doc-Serve API communication."""
+
+from dataclasses import dataclass
+from types import TracebackType
+from typing import Any, Optional
+
+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: Optional[str] = None):
+        super().__init__(message)
+        self.status_code = status_code
+        self.detail = detail
+
+
+@dataclass
+class HealthStatus:
+    """Server health status."""
+
+    status: str
+    message: Optional[str]
+    version: str
+    timestamp: str
+
+
+@dataclass
+class IndexingStatus:
+    """Detailed indexing status."""
+
+    total_documents: int
+    total_chunks: int
+    indexing_in_progress: bool
+    current_job_id: Optional[str]
+    progress_percent: float
+    last_indexed_at: Optional[str]
+    indexed_folders: list[str]
+
+
+@dataclass
+class QueryResult:
+    """Single query result."""
+
+    text: str
+    source: str
+    score: float
+    chunk_id: str
+    metadata: dict[str, Any]
+    vector_score: Optional[float] = None
+    bm25_score: Optional[float] = None
+
+
+@dataclass
+class QueryResponse:
+    """Query response with results."""
+
+    results: list[QueryResult]
+    query_time_ms: float
+    total_results: int
+
+
+@dataclass
+class IndexResponse:
+    """Indexing operation response."""
+
+    job_id: str
+    status: str
+    message: Optional[str]
+
+
+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: Optional[type[BaseException]],
+        exc_val: Optional[BaseException],
+        exc_tb: Optional[TracebackType],
+    ) -> None:
+        self.close()
+
+    def close(self) -> None:
+        """Close the HTTP client."""
+        self._client.close()
+
+    def _request(
+        self,
+        method: str,
+        path: str,
+        json: Optional[dict[str, Any]] = 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.
+
+        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)
+        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", []),
+        )
+
+    def query(
+        self,
+        query_text: str,
+        top_k: int = 5,
+        similarity_threshold: float = 0.7,
+        mode: str = "hybrid",
+        alpha: float = 0.5,
+        source_types: Optional[list[str]] = None,
+        languages: Optional[list[str]] = None,
+        file_paths: Optional[list[str]] = None,
+    ) -> 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 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: Optional[list[str]] = None,
+        code_chunk_strategy: str = "ast_aware",
+        include_patterns: Optional[list[str]] = None,
+        exclude_patterns: Optional[list[str]] = None,
+        generate_summaries: bool = False,
+    ) -> IndexResponse:
+        """
+        Start indexing 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.
+            generate_summaries: Generate LLM summaries for code chunks.
+
+        Returns:
+            IndexResponse with job ID.
+        """
+        data = self._request(
+            "POST",
+            "/index/",
+            json={
+                "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,
+            },
+        )
+
+        return IndexResponse(
+            job_id=data["job_id"],
+            status=data["status"],
+            message=data.get("message"),
+        )
+
+    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"),
+        )

agent_brain_cli-1.1.0/doc_svr_ctl/commands/__init__.py

@@ -0,0 +1,21 @@
+"""CLI commands for doc-svr-ctl."""
+
+from .index import index_command
+from .init import init_command
+from .list_cmd import list_command
+from .query import query_command
+from .reset import reset_command
+from .start import start_command
+from .status import status_command
+from .stop import stop_command
+
+__all__ = [
+    "index_command",
+    "init_command",
+    "list_command",
+    "query_command",
+    "reset_command",
+    "start_command",
+    "status_command",
+    "stop_command",
+]