agent-brain-cli 10.0.7__tar.gz → 10.2.0__tar.gz

{agent_brain_cli-10.0.7 → agent_brain_cli-10.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: agent-brain-cli
-Version: 10.0.7
+Version: 10.2.0
 Summary: Agent Brain CLI - Command-line interface for managing AI agent memory and knowledge retrieval
 Home-page: https://github.com/SpillwaveSolutions/agent-brain
 License: MIT
@@ -15,7 +15,8 @@ Classifier: Programming Language :: Python :: 3
 Classifier: Programming Language :: Python :: 3.10
 Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
-Requires-Dist: agent-brain-rag (>=10.0.7,<11.0.0)
+Requires-Dist: agent-brain-rag (>=10.2.0,<11.0.0)
+Requires-Dist: agent-brain-uds (>=10.2.0,<11.0.0)
 Requires-Dist: click (>=8.1.0,<9.0.0)
 Requires-Dist: httpx (>=0.28.0,<0.29.0)
 Requires-Dist: pydantic (>=2.10.0,<3.0.0)

{agent_brain_cli-10.0.7 → agent_brain_cli-10.2.0}/agent_brain_cli/__init__.py

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

{agent_brain_cli-10.0.7 → agent_brain_cli-10.2.0}/agent_brain_cli/cli.py

@@ -30,7 +30,41 @@ from .commands import (
 
 @click.group()
 @click.version_option(version=__version__, prog_name="agent-brain")
-def cli() -> None:
+@click.option(
+    "--transport",
+    "transport",
+    type=click.Choice(["auto", "http", "uds"], case_sensitive=False),
+    default=None,
+    help=(
+        "Transport to use: auto (default — UDS if available, HTTP "
+        "otherwise), http, or uds. Honors AGENT_BRAIN_TRANSPORT env."
+    ),
+)
+@click.option(
+    "--socket-path",
+    type=click.Path(),
+    default=None,
+    help="Override UDS socket path (only used with --transport=uds|auto).",
+)
+@click.option(
+    "--base-url",
+    default=None,
+    help="Override server base URL (only used with --transport=http|auto).",
+)
+@click.option(
+    "--debug-transport",
+    is_flag=True,
+    default=False,
+    help="Log the resolved transport (http or uds) and target to stderr.",
+)
+@click.pass_context
+def cli(
+    ctx: click.Context,
+    transport: str | None,
+    socket_path: str | None,
+    base_url: str | None,
+    debug_transport: bool,
+) -> None:
     """Agent Brain CLI - Manage and query the Agent Brain RAG server.
 
     A command-line interface for interacting with the Agent Brain document
@@ -81,9 +115,15 @@ def cli() -> None:
 
     \b
     Environment Variables:
-      AGENT_BRAIN_URL  Server URL (default: http://127.0.0.1:8000)
+      AGENT_BRAIN_URL        Server URL (default: http://127.0.0.1:8000)
+      AGENT_BRAIN_TRANSPORT  Transport hint: auto, http, or uds
+      AGENT_BRAIN_UDS_PATH   Override UDS socket path
     """
-    pass
+    ctx.ensure_object(dict)
+    ctx.obj["transport_hint"] = transport
+    ctx.obj["base_url_override"] = base_url
+    ctx.obj["socket_path_override"] = socket_path
+    ctx.obj["debug_transport"] = debug_transport
 
 
 # Register project management commands

{agent_brain_cli-10.0.7 → agent_brain_cli-10.2.0}/agent_brain_cli/client/api_client.py

@@ -53,6 +53,22 @@ class IndexingStatus:
     embedding_cache: dict[str, Any] | None = None
 
 
+@dataclass
+class ResultExplanation:
+    """Structured per-result explanation (issue #159).
+
+    Populated only when the request set `explain=true`. All fields are
+    optional because their relevance depends on retrieval mode.
+    """
+
+    reason: str
+    matched_terms: list[str] | None = None
+    fusion: dict[str, float] | None = None
+    graph_path: list[str] | None = None
+    rerank_movement: int | None = None
+    graph_fallback: bool | None = None
+
+
 @dataclass
 class QueryResult:
     """Single query result."""
@@ -64,6 +80,14 @@ class QueryResult:
     metadata: dict[str, Any]
     vector_score: float | None = None
     bm25_score: float | None = None
+    graph_score: float | None = None
+    rerank_score: float | None = None
+    original_rank: int | None = None
+    relationship_path: list[str] | None = None
+    related_entities: list[str] | None = None
+    source_type: str = "doc"
+    language: str | None = None
+    explanation: ResultExplanation | None = None
 
 
 @dataclass
@@ -95,6 +119,39 @@ class IndexResponse:
     message: str | None
 
 
+def _parse_query_result(payload: dict[str, Any]) -> QueryResult:
+    """Build a QueryResult from a server response dict, including optional
+    explanation block (issue #159)."""
+    explanation_data = payload.get("explanation")
+    explanation: ResultExplanation | None = None
+    if explanation_data is not None:
+        explanation = ResultExplanation(
+            reason=explanation_data.get("reason", ""),
+            matched_terms=explanation_data.get("matched_terms"),
+            fusion=explanation_data.get("fusion"),
+            graph_path=explanation_data.get("graph_path"),
+            rerank_movement=explanation_data.get("rerank_movement"),
+            graph_fallback=explanation_data.get("graph_fallback"),
+        )
+    return QueryResult(
+        text=payload["text"],
+        source=payload["source"],
+        score=payload["score"],
+        chunk_id=payload["chunk_id"],
+        metadata=payload.get("metadata", {}),
+        vector_score=payload.get("vector_score"),
+        bm25_score=payload.get("bm25_score"),
+        graph_score=payload.get("graph_score"),
+        rerank_score=payload.get("rerank_score"),
+        original_rank=payload.get("original_rank"),
+        relationship_path=payload.get("relationship_path"),
+        related_entities=payload.get("related_entities"),
+        source_type=payload.get("source_type", "doc"),
+        language=payload.get("language"),
+        explanation=explanation,
+    )
+
+
 class DocServeClient:
     """HTTP client for Doc-Serve API."""
 
@@ -114,6 +171,29 @@ class DocServeClient:
         self.timeout = timeout
         self._client = httpx.Client(timeout=timeout)
 
+    @classmethod
+    def from_httpx(cls, client: httpx.Client) -> "DocServeClient":
+        """Build a DocServeClient that uses a pre-constructed httpx.Client.
+
+        Used by the transport selector to inject a UDS-backed client
+        (see ``agent_brain_cli.client.transport.open_client``). The
+        inner client's ``base_url`` is preserved; this wrapper sends
+        relative paths only.
+
+        Args:
+            client: An already-configured ``httpx.Client``. The wrapper
+                takes ownership and will close it on ``__exit__``.
+
+        Returns:
+            A DocServeClient backed by ``client``.
+        """
+        instance = cls.__new__(cls)
+        instance.base_url = ""  # inner client carries the real base_url
+        timeout = client.timeout
+        instance.timeout = timeout.read or 30.0
+        instance._client = client
+        return instance
+
     def __enter__(self) -> "DocServeClient":
         return self
 
@@ -229,6 +309,7 @@ class DocServeClient:
         source_types: list[str] | None = None,
         languages: list[str] | None = None,
         file_paths: list[str] | None = None,
+        explain: bool = False,
     ) -> QueryResponse:
         """
         Query indexed documents.
@@ -242,11 +323,14 @@ class DocServeClient:
             source_types: Filter by source types (doc, code, test).
             languages: Filter by programming languages.
             file_paths: Filter by file path patterns.
+            explain: When True, include structured per-result explanations
+                (matched terms, fusion breakdown, graph path, rerank movement,
+                and a 'why this rank' summary). See issue #159.
 
         Returns:
             QueryResponse with matching results.
         """
-        request_data = {
+        request_data: dict[str, Any] = {
             "query": query_text,
             "top_k": top_k,
             "similarity_threshold": similarity_threshold,
@@ -259,21 +343,12 @@ class DocServeClient:
             request_data["languages"] = languages
         if file_paths is not None:
             request_data["file_paths"] = file_paths
+        if explain:
+            request_data["explain"] = True
 
         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", [])
-        ]
+        results = [_parse_query_result(r) for r in data.get("results", [])]
 
         return QueryResponse(
             results=results,
@@ -295,7 +370,6 @@ class DocServeClient:
         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,
@@ -318,7 +392,6 @@ class DocServeClient:
             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.
@@ -358,7 +431,7 @@ class DocServeClient:
             "POST",
             "/index/",
             json=body,
-            params={"force": force, "allow_external": allow_external},
+            params={"force": force},
         )
 
         return IndexResponse(

agent_brain_cli-10.2.0/agent_brain_cli/client/transport.py

@@ -0,0 +1,54 @@
+"""Transport selector — builds a DocServeClient over HTTP or UDS.
+
+Plan §4.4: every CLI command should call ``open_client(ctx)`` instead of
+``DocServeClient(base_url=resolved_url)`` directly. The selector reads
+transport-related state off the Click context, calls
+:func:`agent_brain_cli.config.resolve_transport`, then constructs the
+appropriate wrapper.
+
+The selector is intentionally tiny — three branches and one
+``from_httpx`` call. Resolution logic stays in ``config.py`` so it is
+testable without a live ``httpx.Client``.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+import click
+
+from ..config import resolve_transport
+from .api_client import DocServeClient
+
+
+def open_client(ctx: click.Context, *, timeout: float = 30.0) -> DocServeClient:
+    """Construct a ``DocServeClient`` over the transport selected by ``ctx``.
+
+    Args:
+        ctx: Click context. Reads optional keys from ``ctx.obj``:
+            ``transport_hint`` (``"http"`` / ``"uds"`` / ``"auto"`` /
+            ``None``), ``base_url_override``, ``socket_path_override``,
+            and ``debug_transport``.
+        timeout: HTTP request timeout in seconds. Defaults to 30.
+
+    Returns:
+        A live ``DocServeClient``. The caller is responsible for closing
+        it (use as a context manager).
+    """
+    obj = ctx.obj or {}
+    transport, target = resolve_transport(
+        transport_hint=obj.get("transport_hint"),
+        base_url_override=obj.get("base_url_override"),
+        socket_path_override=obj.get("socket_path_override"),
+    )
+    if obj.get("debug_transport"):
+        click.echo(f"[debug-transport] {transport} -> {target}", err=True)
+
+    if transport == "http":
+        return DocServeClient(base_url=target, timeout=timeout)
+
+    # UDS: import lazily so HTTP-only invocations don't pay the cost.
+    from agent_brain_uds import make_client
+
+    inner = make_client(socket_path=Path(target), timeout=timeout)
+    return DocServeClient.from_httpx(inner)

{agent_brain_cli-10.0.7 → agent_brain_cli-10.2.0}/agent_brain_cli/commands/cache.py

@@ -5,8 +5,8 @@ from rich.console import Console
 from rich.prompt import Confirm
 from rich.table import Table
 
-from ..client import ConnectionError, DocServeClient, ServerError
-from ..config import get_server_url
+from ..client import ConnectionError, ServerError
+from ..client.transport import open_client
 
 console = Console()
 
@@ -25,11 +25,15 @@ def cache_group() -> None:
     help="Agent Brain server URL (default: from config or http://127.0.0.1:8000)",
 )
 @click.option("--json", "json_output", is_flag=True, help="Output as JSON")
-def cache_status(url: str | None, json_output: bool) -> None:
+@click.pass_context
+def cache_status(ctx: click.Context, url: str | None, json_output: bool) -> None:
     """Show embedding cache statistics."""
-    resolved_url = url or get_server_url()
+    if url:
+        ctx.ensure_object(dict)
+        ctx.obj["base_url_override"] = url
+        ctx.obj["transport_hint"] = "http"
     try:
-        with DocServeClient(base_url=resolved_url) as client:
+        with open_client(ctx) as client:
             data = client.cache_status()
 
             if json_output:
@@ -91,14 +95,18 @@ def cache_status(url: str | None, json_output: bool) -> None:
     is_flag=True,
     help="Skip confirmation prompt",
 )
-def cache_clear(url: str | None, yes: bool) -> None:
+@click.pass_context
+def cache_clear(ctx: click.Context, url: str | None, yes: bool) -> None:
     """Clear all cached embeddings from the cache.
 
     Without --yes, shows the current entry count and prompts for confirmation.
     """
-    resolved_url = url or get_server_url()
+    if url:
+        ctx.ensure_object(dict)
+        ctx.obj["base_url_override"] = url
+        ctx.obj["transport_hint"] = "http"
     try:
-        with DocServeClient(base_url=resolved_url) as client:
+        with open_client(ctx) as client:
             if not yes:
                 # Get current count before asking
                 try:

{agent_brain_cli-10.0.7 → agent_brain_cli-10.2.0}/agent_brain_cli/commands/folders.py

@@ -7,8 +7,8 @@ import click
 from rich.console import Console
 from rich.table import Table
 
-from ..client import ConnectionError, DocServeClient, ServerError
-from ..config import get_server_url
+from ..client import ConnectionError, ServerError
+from ..client.transport import open_client
 
 console = Console()
 
@@ -34,7 +34,8 @@ def folders_group() -> None:
     help="Agent Brain server URL (default: from config or http://127.0.0.1:8000)",
 )
 @click.option("--json", "json_output", is_flag=True, help="Output as JSON")
-def list_folders_cmd(url: str | None, json_output: bool) -> None:
+@click.pass_context
+def list_folders_cmd(ctx: click.Context, url: str | None, json_output: bool) -> None:
     """List all indexed folders with chunk counts and last indexed time.
 
     \b
@@ -42,10 +43,13 @@ def list_folders_cmd(url: str | None, json_output: bool) -> None:
       agent-brain folders list
       agent-brain folders list --json
     """
-    resolved_url = url or get_server_url()
+    if url:
+        ctx.ensure_object(dict)
+        ctx.obj["base_url_override"] = url
+        ctx.obj["transport_hint"] = "http"
 
     try:
-        with DocServeClient(base_url=resolved_url) as client:
+        with open_client(ctx) as client:
             folders = client.list_folders()
 
             if json_output:
@@ -139,7 +143,9 @@ def list_folders_cmd(url: str | None, json_output: bool) -> None:
     help="Debounce interval in seconds for file watching (default: 30)",
 )
 @click.option("--json", "json_output", is_flag=True, help="Output as JSON")
+@click.pass_context
 def add_folder_cmd(
+    ctx: click.Context,
     folder_path: str,
     url: str | None,
     include_code: bool,
@@ -157,11 +163,14 @@ def add_folder_cmd(
       agent-brain folders add ./src --include-code
       agent-brain folders add ./src --watch auto --debounce 10
     """
-    resolved_url = url or get_server_url()
+    if url:
+        ctx.ensure_object(dict)
+        ctx.obj["base_url_override"] = url
+        ctx.obj["transport_hint"] = "http"
     folder = Path(folder_path).resolve()
 
     try:
-        with DocServeClient(base_url=resolved_url) as client:
+        with open_client(ctx) as client:
             response = client.index(
                 folder_path=str(folder),
                 include_code=include_code,
@@ -218,7 +227,9 @@ def add_folder_cmd(
     help="Skip confirmation prompt",
 )
 @click.option("--json", "json_output", is_flag=True, help="Output as JSON")
+@click.pass_context
 def remove_folder_cmd(
+    ctx: click.Context,
     folder_path: str,
     url: str | None,
     yes: bool,
@@ -234,7 +245,10 @@ def remove_folder_cmd(
       agent-brain folders remove ./docs --yes
       agent-brain folders remove /absolute/path/to/docs
     """
-    resolved_url = url or get_server_url()
+    if url:
+        ctx.ensure_object(dict)
+        ctx.obj["base_url_override"] = url
+        ctx.obj["transport_hint"] = "http"
     resolved_path = str(Path(folder_path).resolve())
 
     if not yes:
@@ -244,7 +258,7 @@ def remove_folder_cmd(
         )
 
     try:
-        with DocServeClient(base_url=resolved_url) as client:
+        with open_client(ctx) as client:
             result = client.delete_folder(folder_path=resolved_path)
 
             chunks_deleted = result.get("chunks_deleted", 0)

{agent_brain_cli-10.0.7 → agent_brain_cli-10.2.0}/agent_brain_cli/commands/index.py

@@ -5,8 +5,8 @@ from pathlib import Path
 import click
 from rich.console import Console
 
-from ..client import ConnectionError, DocServeClient, ServerError
-from ..config import get_server_url
+from ..client import ConnectionError, ServerError
+from ..client.transport import open_client
 from ..diagnostics import doctor_hint_message
 
 console = Console()
@@ -79,13 +79,10 @@ console = Console()
     is_flag=True,
     help="Force re-indexing even if embedding provider has changed",
 )
-@click.option(
-    "--allow-external",
-    is_flag=True,
-    help="Allow indexing paths outside the project directory",
-)
 @click.option("--json", "json_output", is_flag=True, help="Output as JSON")
+@click.pass_context
 def index_command(
+    ctx: click.Context,
     folder_path: str,
     url: str | None,
     chunk_size: int,
@@ -99,15 +96,16 @@ def index_command(
     exclude_patterns: str | None,
     generate_summaries: bool,
     force: bool,
-    allow_external: bool,
     json_output: bool,
 ) -> None:
     """Index documents from a folder.
 
     FOLDER_PATH: Path to the folder containing documents to index.
     """
-    # Get URL from config if not specified
-    resolved_url = url or get_server_url()
+    if url:
+        ctx.ensure_object(dict)
+        ctx.obj["base_url_override"] = url
+        ctx.obj["transport_hint"] = "http"
 
     # Resolve to absolute path
     folder = Path(folder_path).resolve()
@@ -131,7 +129,7 @@ def index_command(
     )
 
     try:
-        with DocServeClient(base_url=resolved_url) as client:
+        with open_client(ctx) as client:
             response = client.index(
                 folder_path=str(folder),
                 chunk_size=chunk_size,
@@ -145,7 +143,6 @@ def index_command(
                 exclude_patterns=exclude_patterns_list,
                 generate_summaries=generate_summaries,
                 force=force,
-                allow_external=allow_external,
             )
 
             if json_output:

{agent_brain_cli-10.0.7 → agent_brain_cli-10.2.0}/agent_brain_cli/commands/inject.py

@@ -5,8 +5,8 @@ from pathlib import Path
 import click
 from rich.console import Console
 
-from ..client import ConnectionError, DocServeClient, ServerError
-from ..config import get_server_url
+from ..client import ConnectionError, ServerError
+from ..client.transport import open_client
 
 console = Console()
 
@@ -98,13 +98,10 @@ console = Console()
     is_flag=True,
     help="Force re-indexing even if embedding provider has changed",
 )
-@click.option(
-    "--allow-external",
-    is_flag=True,
-    help="Allow indexing paths outside the project directory",
-)
 @click.option("--json", "json_output", is_flag=True, help="Output as JSON")
+@click.pass_context
 def inject_command(
+    ctx: click.Context,
     folder_path: str,
     injector_script: str | None,
     folder_metadata: str | None,
@@ -121,7 +118,6 @@ def inject_command(
     exclude_patterns: str | None,
     generate_summaries: bool,
     force: bool,
-    allow_external: bool,
     json_output: bool,
 ) -> None:
     """Index documents from a folder with content injection.
@@ -152,8 +148,10 @@ def inject_command(
             )
         raise SystemExit(2)
 
-    # Get URL from config if not specified
-    resolved_url = url or get_server_url()
+    if url:
+        ctx.ensure_object(dict)
+        ctx.obj["base_url_override"] = url
+        ctx.obj["transport_hint"] = "http"
 
     # Resolve to absolute paths
     folder = Path(folder_path).resolve()
@@ -181,7 +179,7 @@ def inject_command(
     )
 
     try:
-        with DocServeClient(base_url=resolved_url) as client:
+        with open_client(ctx) as client:
             response = client.index(
                 folder_path=str(folder),
                 chunk_size=chunk_size,
@@ -195,7 +193,6 @@ def inject_command(
                 exclude_patterns=exclude_patterns_list,
                 generate_summaries=generate_summaries,
                 force=force,
-                allow_external=allow_external,
                 injector_script=resolved_script,
                 folder_metadata_file=resolved_metadata,
                 dry_run=dry_run,
@@ -268,4 +265,15 @@ def inject_command(
                     "\n[dim]A conflict occurred. "
                     "Check 'agent-brain jobs' for queue status.[/]"
                 )
+            elif e.status_code == 403:
+                # Injector allowlist rejected the script (issue #181).
+                console.print(
+                    "\n[dim]Injector scripts must be allowlisted in "
+                    "[bold].agent-brain/config.yaml[/] before they can run on "
+                    "the server. Add an entry under [bold]injector_scripts:[/] "
+                    "with the script's path and the sha256 of its contents "
+                    "(run [bold]sha256sum <script>[/] to get the hash). "
+                    "See docs/USER_GUIDE.md 'Content Injection' for the full "
+                    "schema.[/]"
+                )
         raise SystemExit(1) from e

{agent_brain_cli-10.0.7 → agent_brain_cli-10.2.0}/agent_brain_cli/commands/jobs.py

@@ -9,7 +9,7 @@ from rich.panel import Panel
 from rich.table import Table
 
 from ..client import ConnectionError, DocServeClient, ServerError
-from ..config import get_server_url
+from ..client.transport import open_client
 from ..diagnostics import doctor_hint_message
 
 console = Console()
@@ -285,7 +285,9 @@ def _watch_jobs(client: DocServeClient, limit: int) -> None:
     help="Agent Brain server URL (default: from config or http://127.0.0.1:8000)",
 )
 @click.option("--json", "json_output", is_flag=True, help="Output as JSON")
+@click.pass_context
 def jobs_command(
+    ctx: click.Context,
     job_id: str | None,
     watch: bool,
     cancel: bool,
@@ -305,7 +307,10 @@ def jobs_command(
       agent-brain jobs JOB_ID       # Show job details
       agent-brain jobs JOB_ID --cancel  # Cancel a job
     """
-    resolved_url = url or get_server_url()
+    if url:
+        ctx.ensure_object(dict)
+        ctx.obj["base_url_override"] = url
+        ctx.obj["transport_hint"] = "http"
 
     # Validate options
     if cancel and not job_id:
@@ -318,7 +323,7 @@ def jobs_command(
         raise click.UsageError("--watch cannot be used with --json")
 
     try:
-        with DocServeClient(base_url=resolved_url) as client:
+        with open_client(ctx) as client:
             if cancel and job_id:
                 _cancel_job(client, job_id, json_output)
             elif watch:

{agent_brain_cli-10.0.7 → agent_brain_cli-10.2.0}/agent_brain_cli/commands/query.py

@@ -3,18 +3,59 @@
 import click
 from rich.console import Console
 from rich.panel import Panel
+from rich.table import Table
 from rich.text import Text
 
-from ..client import ConnectionError, DocServeClient, ServerError
-from ..config import get_server_url
+from ..client import ConnectionError, ServerError
+from ..client.api_client import ResultExplanation
+from ..client.transport import open_client
 from ..diagnostics import doctor_hint_message
 
 console = Console()
 
 
-def _get_default_url() -> str:
-    """Get default server URL from config."""
-    return get_server_url()
+def _render_explanation(explanation: ResultExplanation) -> None:
+    """Render a ResultExplanation as a sub-panel below the main result.
+
+    Layout (only rows that have data are emitted):
+        Why:      <reason string>
+        Matched:  term1, term2, ...
+        Fusion:   key=value | key=value | ...
+        Graph:    subject -> predicate -> object
+        Rerank:   moved up/down N places (if any)
+        Fallback: graph -> vector
+    """
+    table = Table(show_header=False, box=None, padding=(0, 1), expand=False)
+    table.add_column("label", style="cyan", no_wrap=True)
+    table.add_column("value", style="dim")
+
+    table.add_row("Why:", explanation.reason)
+
+    if explanation.matched_terms:
+        highlighted = Text(", ".join(explanation.matched_terms))
+        highlighted.highlight_words(explanation.matched_terms, style="bold yellow")
+        table.add_row("Matched:", highlighted)
+
+    if explanation.fusion:
+        parts = [f"{k}={v:.4f}" for k, v in explanation.fusion.items()]
+        table.add_row("Fusion:", " | ".join(parts))
+
+    if explanation.graph_path:
+        table.add_row("Graph:", " -> ".join(explanation.graph_path))
+
+    if explanation.rerank_movement is not None:
+        if explanation.rerank_movement > 0:
+            arrow = f"+{explanation.rerank_movement} (moved up)"
+        elif explanation.rerank_movement < 0:
+            arrow = f"{explanation.rerank_movement} (moved down)"
+        else:
+            arrow = "0 (held position)"
+        table.add_row("Rerank:", arrow)
+
+    if explanation.graph_fallback:
+        table.add_row("Fallback:", "graph returned no hits -> vector")
+
+    console.print(table)
 
 
 @click.command("query")
@@ -63,6 +104,15 @@ def _get_default_url() -> str:
 @click.option("--json", "json_output", is_flag=True, help="Output as JSON")
 @click.option("--full", is_flag=True, help="Show full text content")
 @click.option("--scores", is_flag=True, help="Show individual vector/BM25 scores")
+@click.option(
+    "--explain",
+    is_flag=True,
+    help=(
+        "Show structured 'why this rank' explanations under each result: "
+        "matched terms, fusion breakdown, graph path, and rerank movement "
+        "(issue #159)."
+    ),
+)
 @click.option(
     "--source-types",
     help="Comma-separated source types to filter by (doc,code,test)",
@@ -75,7 +125,9 @@ def _get_default_url() -> str:
     "--file-paths",
     help="Comma-separated file path patterns to filter by (wildcards supported)",
 )
+@click.pass_context
 def query_command(
+    ctx: click.Context,
     query_text: str,
     url: str | None,
     top_k: int,
@@ -85,13 +137,16 @@ def query_command(
     json_output: bool,
     full: bool,
     scores: bool,
+    explain: bool,
     source_types: str | None,
     languages: str | None,
     file_paths: str | None,
 ) -> None:
     """Search indexed documents with natural language or keyword query."""
-    # Get URL from config if not specified
-    resolved_url = url or _get_default_url()
+    if url:
+        ctx.ensure_object(dict)
+        ctx.obj["base_url_override"] = url
+        ctx.obj["transport_hint"] = "http"
 
     # Parse comma-separated lists
     source_types_list = (
@@ -105,7 +160,7 @@ def query_command(
     )
 
     try:
-        with DocServeClient(base_url=resolved_url) as client:
+        with open_client(ctx) as client:
             response = client.query(
                 query_text=query_text,
                 top_k=top_k,
@@ -115,6 +170,7 @@ def query_command(
                 source_types=source_types_list,
                 languages=languages_list,
                 file_paths=file_paths_list,
+                explain=explain,
             )
 
             if json_output:
@@ -202,6 +258,10 @@ def query_command(
                     )
                 )
 
+                # Issue #159: optional structured explanation block.
+                if explain and result.explanation is not None:
+                    _render_explanation(result.explanation)
+
     except ConnectionError as e:
         if json_output:
             import json

{agent_brain_cli-10.0.7 → agent_brain_cli-10.2.0}/agent_brain_cli/commands/reset.py

@@ -4,8 +4,8 @@ import click
 from rich.console import Console
 from rich.prompt import Confirm
 
-from ..client import ConnectionError, DocServeClient, ServerError
-from ..config import get_server_url
+from ..client import ConnectionError, ServerError
+from ..client.transport import open_client
 from ..diagnostics import doctor_hint_message
 
 console = Console()
@@ -25,13 +25,18 @@ console = Console()
     help="Skip confirmation prompt",
 )
 @click.option("--json", "json_output", is_flag=True, help="Output as JSON")
-def reset_command(url: str | None, yes: bool, json_output: bool) -> None:
+@click.pass_context
+def reset_command(
+    ctx: click.Context, url: str | None, yes: bool, json_output: bool
+) -> None:
     """Reset the index by deleting all indexed documents.
 
     WARNING: This permanently removes all indexed content.
     """
-    # Get URL from config if not specified
-    resolved_url = url or get_server_url()
+    if url:
+        ctx.ensure_object(dict)
+        ctx.obj["base_url_override"] = url
+        ctx.obj["transport_hint"] = "http"
 
     # Confirm unless --yes flag provided
     if not yes and not json_output:
@@ -43,7 +48,7 @@ def reset_command(url: str | None, yes: bool, json_output: bool) -> None:
             return
 
     try:
-        with DocServeClient(base_url=resolved_url) as client:
+        with open_client(ctx) as client:
             response = client.reset()
 
             if json_output:

{agent_brain_cli-10.0.7 → agent_brain_cli-10.2.0}/agent_brain_cli/commands/start.py

@@ -25,6 +25,7 @@ STATE_DIR_NAME = ".agent-brain"
 LOCK_FILE = "agent-brain.lock"
 PID_FILE = "agent-brain.pid"
 RUNTIME_FILE = "runtime.json"
+SOCKET_FILE_NAME = "agent-brain.sock"
 
 
 def read_config(state_dir: Path) -> dict[str, Any]:
@@ -105,6 +106,31 @@ def check_health(base_url: str, timeout: float = 3.0) -> bool:
         return False
 
 
+def _probe_uds(socket_path: str, *, timeout_s: float = 2.0) -> bool:
+    """Probe ``socket_path`` with a UDS GET /health/ — True if 200.
+
+    Used by ``start --uds`` after the HTTP readiness probe to confirm
+    the UDS transport is actually live before advertising it in
+    runtime.json (Phase 7 reviewer #4). Local import keeps httpx out of
+    the start command's hot path when UDS isn't requested.
+    """
+    try:
+        import httpx
+    except ImportError:
+        return False
+    try:
+        transport = httpx.HTTPTransport(uds=str(socket_path))
+        with httpx.Client(
+            transport=transport,
+            base_url="http://agent-brain",
+            timeout=timeout_s,
+        ) as client:
+            response = client.get("/health/")
+            return bool(response.status_code == 200)
+    except Exception:
+        return False
+
+
 def find_available_port(host: str, start_port: int, end_port: int) -> int | None:
     """Find an available port in the given range."""
     for port in range(start_port, end_port + 1):
@@ -174,6 +200,16 @@ def update_registry(project_root: Path, state_dir: Path) -> None:
     is_flag=True,
     help="Enable strict mode: fail on critical provider configuration errors",
 )
+@click.option(
+    "--uds",
+    is_flag=True,
+    help="Also bind a Unix Domain Socket alongside the HTTP listener.",
+)
+@click.option(
+    "--uds-only",
+    is_flag=True,
+    help="Bind only the Unix Domain Socket (no TCP listener). Implies --uds.",
+)
 def start_command(
     path: str | None,
     host: str | None,
@@ -182,6 +218,8 @@ def start_command(
     timeout: int,
     json_output: bool,
     strict: bool,
+    uds: bool,
+    uds_only: bool,
 ) -> None:
     """Start an Agent Brain server for this project.
 
@@ -305,24 +343,39 @@ def start_command(
         if not json_output:
             console.print(f"[dim]Starting server on {base_url}...[/]")
 
-        # Build server command
+        # Build server command. We invoke `agent_brain_server.api.main`'s
+        # Click CLI (not raw `python -m uvicorn`) so the server's `run()`
+        # function actually fires — it's the only place that branches on
+        # AGENT_BRAIN_UDS / _UDS_ONLY env vars to delegate to uds_bind
+        # (Phase 7 fix for reviewer finding A1). Behaviour for HTTP-only
+        # users is identical because run() ends up calling uvicorn.run()
+        # with the same args.
         server_cmd = [
             sys.executable,
             "-m",
-            "uvicorn",
-            "agent_brain_server.api.main:app",
+            "agent_brain_server.api.main",
             "--host",
             bind_host,
             "--port",
             str(bind_port),
         ]
 
+        # --uds-only implies --uds (plan §7)
+        enable_uds = uds or uds_only
+        socket_path = str(state_dir / SOCKET_FILE_NAME) if enable_uds else None
+
         # Set environment variables for server
         env = os.environ.copy()
         env["AGENT_BRAIN_PROJECT_ROOT"] = str(project_root)
         env["AGENT_BRAIN_STATE_DIR"] = str(state_dir)
         if strict:
             env["AGENT_BRAIN_STRICT_MODE"] = "true"
+        if enable_uds:
+            env["AGENT_BRAIN_UDS"] = "1"
+            assert socket_path is not None  # for mypy
+            env["AGENT_BRAIN_UDS_PATH"] = socket_path
+        if uds_only:
+            env["AGENT_BRAIN_UDS_ONLY"] = "1"
 
         if foreground:
             # Write runtime state even in foreground mode so CLI can discover the URL
@@ -340,6 +393,7 @@ def start_command(
                 "pid": os.getpid(),  # Current PID (will be replaced by exec)
                 "started_at": datetime.now(timezone.utc).isoformat(),
                 "foreground": True,  # Mark as foreground for cleanup detection
+                "socket_path": socket_path,
             }
             write_runtime(state_dir, runtime_state)
 
@@ -391,6 +445,7 @@ def start_command(
                 "port": bind_port,
                 "pid": process.pid,
                 "started_at": datetime.now(timezone.utc).isoformat(),
+                "socket_path": socket_path,
             }
             write_runtime(state_dir, runtime_state)
 
@@ -409,6 +464,22 @@ def start_command(
                     break
                 time.sleep(0.5)
 
+            # If UDS was requested, probe the socket too and unset the
+            # runtime.json::socket_path field if it isn't actually live.
+            # Otherwise a runtime.json entry for socket_path misleads any
+            # client (MCP, CLI auto-mode) that prefers UDS (Phase 7
+            # reviewer #4).
+            if ready and enable_uds and socket_path:
+                if not _probe_uds(socket_path, timeout_s=2.0):
+                    runtime_state["socket_path"] = None
+                    write_runtime(state_dir, runtime_state)
+                    if not json_output:
+                        console.print(
+                            "[yellow]UDS socket probe failed — "
+                            "runtime.json::socket_path cleared. "
+                            "Clients will use HTTP.[/]"
+                        )
+
             if ready:
                 if json_output:
                     click.echo(
@@ -419,6 +490,7 @@ def start_command(
                                 "pid": process.pid,
                                 "project_root": str(project_root),
                                 "log_file": str(stdout_log),
+                                "socket_path": runtime_state.get("socket_path"),
                             },
                             indent=2,
                         )

{agent_brain_cli-10.0.7 → agent_brain_cli-10.2.0}/agent_brain_cli/commands/status.py

@@ -5,8 +5,8 @@ from rich.console import Console
 from rich.panel import Panel
 from rich.table import Table
 
-from ..client import ConnectionError, DocServeClient, ServerError
-from ..config import get_server_url
+from ..client import ConnectionError, ServerError
+from ..client.transport import open_client
 from ..diagnostics import doctor_hint_message
 
 console = Console()
@@ -21,11 +21,19 @@ console = Console()
 )
 @click.option("--json", "json_output", is_flag=True, help="Output as JSON")
 @click.option("--verbose", "-v", is_flag=True, help="Show additional detail")
-def status_command(url: str | None, json_output: bool, verbose: bool) -> None:
+@click.pass_context
+def status_command(
+    ctx: click.Context, url: str | None, json_output: bool, verbose: bool
+) -> None:
     """Check Agent Brain server status and health."""
-    resolved_url = url or get_server_url()
+    # ``--url`` is a per-command HTTP override — promote it to the
+    # transport-selector context so ``open_client`` honors it.
+    if url:
+        ctx.ensure_object(dict)
+        ctx.obj["base_url_override"] = url
+        ctx.obj["transport_hint"] = "http"
     try:
-        with DocServeClient(base_url=resolved_url) as client:
+        with open_client(ctx) as client:
             health = client.health()
             indexing = client.status()
 

{agent_brain_cli-10.0.7 → agent_brain_cli-10.2.0}/agent_brain_cli/config.py

@@ -8,7 +8,7 @@ import logging
 import os
 import sys
 from pathlib import Path
-from typing import Any
+from typing import Any, Literal
 
 import yaml
 from pydantic import BaseModel, Field
@@ -412,3 +412,75 @@ def get_server_url(config: AgentBrainConfig | None = None) -> str:
         config = load_config()
 
     return config.server.url
+
+
+def resolve_transport(
+    *,
+    transport_hint: str | None = None,
+    base_url_override: str | None = None,
+    socket_path_override: Path | None = None,
+    config: AgentBrainConfig | None = None,
+) -> tuple[Literal["http", "uds"], str]:
+    """Resolve the active transport and its connection target.
+
+    Sibling to :func:`get_server_url` — shares the same precedence chain
+    for HTTP, layers UDS detection on top. See plan §4.4 and §12.3 #6.
+
+    Precedence:
+      1. ``transport_hint`` argument (from CLI ``--transport`` flag)
+      2. ``AGENT_BRAIN_TRANSPORT`` environment variable
+      3. ``"auto"`` (try UDS first, fall back to HTTP)
+
+    For ``"uds"``: uses ``socket_path_override`` → ``AGENT_BRAIN_UDS_PATH``
+    env → ``agent_brain_uds.resolve_socket_path``. Validates with
+    :func:`agent_brain_uds.validate_socket` and raises on failure (so
+    an explicit ``--transport uds`` without a valid socket exits loudly,
+    per plan §12.3 #7).
+
+    For ``"http"``: uses ``base_url_override`` → :func:`get_server_url`.
+
+    For ``"auto"``: tries UDS; on any validation failure, falls back to
+    HTTP transparently.
+
+    Returns:
+        A ``(transport, target)`` tuple where ``transport`` is
+        ``"http"`` or ``"uds"`` and ``target`` is the URL or socket path
+        (as a string).
+    """
+    chosen = (
+        transport_hint or os.environ.get("AGENT_BRAIN_TRANSPORT") or "auto"
+    ).lower()
+
+    def _resolve_uds_target() -> str:
+        from agent_brain_uds import resolve_socket_path, validate_socket
+
+        if socket_path_override is not None:
+            path = Path(socket_path_override).expanduser()
+        elif env_path := os.environ.get("AGENT_BRAIN_UDS_PATH"):
+            path = Path(env_path).expanduser()
+        else:
+            path = resolve_socket_path(None)
+        validate_socket(path)
+        return str(path)
+
+    def _resolve_http_target() -> str:
+        if base_url_override:
+            return base_url_override
+        return get_server_url(config)
+
+    if chosen == "uds":
+        return ("uds", _resolve_uds_target())
+    if chosen == "http":
+        return ("http", _resolve_http_target())
+
+    # "auto" — try UDS, fall back to HTTP on any validation failure.
+    try:
+        from agent_brain_uds import AgentBrainUdsError
+
+        try:
+            return ("uds", _resolve_uds_target())
+        except (AgentBrainUdsError, OSError, FileNotFoundError):
+            return ("http", _resolve_http_target())
+    except ImportError:
+        # agent_brain_uds not installed — HTTP is the only option.
+        return ("http", _resolve_http_target())

{agent_brain_cli-10.0.7 → agent_brain_cli-10.2.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [tool.poetry]
 name = "agent-brain-cli"
-version = "10.0.7"
+version = "10.2.0"
 description = "Agent Brain CLI - Command-line interface for managing AI agent memory and knowledge retrieval"
 authors = ["Spillwave Solutions"]
 readme = "README.md"
@@ -27,7 +27,8 @@ httpx = "^0.28.0"
 rich = "^13.9.0"
 pyyaml = "^6.0.0"
 pydantic = "^2.10.0"
-agent-brain-rag = "^10.0.7"
+agent-brain-rag = "^10.2.0"
+agent-brain-uds = "^10.2.0"
 
 [tool.poetry.group.dev.dependencies]
 pytest = "^8.3.0"