agent-brain-cli 9.6.0__tar.gz → 10.0.1__tar.gz

{agent_brain_cli-9.6.0 → agent_brain_cli-10.0.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: agent-brain-cli
-Version: 9.6.0
+Version: 10.0.1
 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,7 @@ 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 (>=9.6.0,<10.0.0)
+Requires-Dist: agent-brain-rag (>=10.0.1,<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-9.6.0 → agent_brain_cli-10.0.1}/agent_brain_cli/__init__.py

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

{agent_brain_cli-9.6.0 → agent_brain_cli-10.0.1}/agent_brain_cli/cli.py

@@ -10,6 +10,7 @@ from . import __version__
 from .commands import (
     cache_group,
     config_group,
+    doctor_command,
     folders_group,
     index_command,
     init_command,
@@ -50,6 +51,7 @@ def cli() -> None:
       inject   Index documents with content injection
       jobs     View and manage job queue
       reset    Clear all indexed documents
+      doctor   Diagnose installation, configuration, and server state
 
     \b
     Cache Commands:
@@ -103,6 +105,7 @@ 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")
+cli.add_command(doctor_command, name="doctor")
 
 
 if __name__ == "__main__":

{agent_brain_cli-9.6.0 → agent_brain_cli-10.0.1}/agent_brain_cli/commands/__init__.py

@@ -2,6 +2,7 @@
 
 from .cache import cache_group
 from .config import config_group
+from .doctor import doctor_command
 from .folders import folders_group
 from .index import index_command
 from .init import init_command
@@ -20,6 +21,7 @@ from .uninstall import uninstall_command
 __all__ = [
     "cache_group",
     "config_group",
+    "doctor_command",
     "folders_group",
     "index_command",
     "inject_command",

agent_brain_cli-10.0.1/agent_brain_cli/commands/doctor.py

@@ -0,0 +1,86 @@
+"""``agent-brain doctor`` — diagnose installation, configuration and server state."""
+
+from __future__ import annotations
+
+import click
+from rich.console import Console
+from rich.panel import Panel
+from rich.table import Table
+
+from agent_brain_cli.diagnostics import (
+    SEVERITY_FAIL,
+    SEVERITY_OK,
+    SEVERITY_WARN,
+    report_to_json,
+    run_doctor,
+)
+
+console = Console()
+
+
+_STATUS_STYLE = {
+    SEVERITY_OK: ("green", "OK"),
+    SEVERITY_WARN: ("yellow", "WARN"),
+    SEVERITY_FAIL: ("red", "FAIL"),
+}
+
+
+@click.command("doctor")
+@click.option(
+    "--url",
+    envvar="AGENT_BRAIN_URL",
+    default=None,
+    help="Server URL to probe (default: resolved from runtime.json or config).",
+)
+@click.option("--json", "json_output", is_flag=True, help="Emit machine-readable JSON.")
+def doctor_command(url: str | None, json_output: bool) -> None:
+    """Diagnose your Agent Brain setup.
+
+    Inspects Python version, project init state, provider config, required
+    API keys, optional dependencies, .gitignore hygiene, and whether the
+    server is reachable. Exits non-zero on any critical failure so it can
+    be used in scripts (``agent-brain doctor || agent-brain init``).
+    """
+    report = run_doctor(server_url_override=url)
+
+    if json_output:
+        click.echo(report_to_json(report))
+        raise SystemExit(report.exit_code)
+
+    header_color = "green" if report.exit_code == 0 else "red"
+    console.print(
+        Panel(
+            (
+                f"[bold]Project root:[/] {report.project_root}\n"
+                f"[bold]State dir:[/]    {report.state_dir} "
+                f"({'present' if report.state_dir_exists else 'missing'})\n"
+                f"[bold]Server URL:[/]   {report.server_url}"
+            ),
+            title="Agent Brain Doctor",
+            border_style=header_color,
+        )
+    )
+
+    table = Table(show_header=True, header_style="bold cyan")
+    table.add_column("Check", style="dim")
+    table.add_column("Status")
+    table.add_column("Details", overflow="fold")
+
+    for check in report.checks:
+        style, label = _STATUS_STYLE.get(check.status, ("white", check.status.upper()))
+        body = check.message
+        if check.fix:
+            body = f"{body}\n[dim]→ {check.fix}[/]"
+        table.add_row(check.name, f"[{style}]{label}[/]", body)
+
+    console.print(table)
+
+    if report.exit_code != 0:
+        console.print(
+            "\n[red]Doctor reported critical issues.[/] "
+            "Fix the items above and re-run.",
+        )
+    else:
+        console.print("\n[green]All critical checks passed.[/]")
+
+    raise SystemExit(report.exit_code)

{agent_brain_cli-9.6.0 → agent_brain_cli-10.0.1}/agent_brain_cli/commands/index.py

@@ -7,6 +7,7 @@ from rich.console import Console
 
 from ..client import ConnectionError, DocServeClient, ServerError
 from ..config import get_server_url
+from ..diagnostics import doctor_hint_message
 
 console = Console()
 
@@ -184,6 +185,7 @@ def index_command(
             click.echo(json.dumps({"error": str(e)}))
         else:
             console.print(f"[red]Connection Error:[/] {e}")
+            console.print(f"[dim]{doctor_hint_message()}[/]")
         raise SystemExit(1) from e
 
     except ServerError as e:

{agent_brain_cli-9.6.0 → agent_brain_cli-10.0.1}/agent_brain_cli/commands/init.py

@@ -7,6 +7,7 @@ import click
 from rich.console import Console
 from rich.panel import Panel
 
+from agent_brain_cli.config import resolve_project_root
 from agent_brain_cli.migration import migrate_state_dir
 from agent_brain_cli.xdg_paths import migrate_legacy_paths
 
@@ -37,53 +38,6 @@ DEFAULT_CONFIG = {
 STATE_DIR_NAME = ".agent-brain"
 
 
-def resolve_project_root(start_path: Path | None = None) -> Path:
-    """Resolve the canonical project root directory.
-
-    Resolution order:
-    1. Git repository root (git rev-parse --show-toplevel)
-    2. Walk up looking for .claude/ directory
-    3. Walk up looking for pyproject.toml
-    4. Fall back to cwd
-
-    Args:
-        start_path: Starting path for resolution. Defaults to cwd.
-
-    Returns:
-        Resolved project root path.
-    """
-    import subprocess
-
-    start = (start_path or Path.cwd()).resolve()
-
-    # Try git root first
-    try:
-        result = subprocess.run(
-            ["git", "rev-parse", "--show-toplevel"],
-            capture_output=True,
-            text=True,
-            timeout=5,
-            cwd=str(start),
-        )
-        if result.returncode == 0:
-            return Path(result.stdout.strip()).resolve()
-    except (subprocess.TimeoutExpired, FileNotFoundError, OSError):
-        pass
-
-    # Walk up looking for markers
-    current = start
-    while current != current.parent:
-        if (current / ".agent-brain").is_dir():
-            return current
-        if (current / ".claude").is_dir():
-            return current
-        if (current / "pyproject.toml").is_file():
-            return current
-        current = current.parent
-
-    return start
-
-
 @click.command("init")
 @click.option(
     "--path",

{agent_brain_cli-9.6.0 → agent_brain_cli-10.0.1}/agent_brain_cli/commands/jobs.py

@@ -10,6 +10,7 @@ from rich.table import Table
 
 from ..client import ConnectionError, DocServeClient, ServerError
 from ..config import get_server_url
+from ..diagnostics import doctor_hint_message
 
 console = Console()
 
@@ -310,6 +311,7 @@ def jobs_command(
             click.echo(json.dumps({"error": str(e)}))
         else:
             console.print(f"[red]Connection Error:[/] {e}")
+            console.print(f"[dim]{doctor_hint_message()}[/]")
         raise SystemExit(1) from e
 
     except ServerError as e:

{agent_brain_cli-9.6.0 → agent_brain_cli-10.0.1}/agent_brain_cli/commands/query.py

@@ -7,6 +7,7 @@ from rich.text import Text
 
 from ..client import ConnectionError, DocServeClient, ServerError
 from ..config import get_server_url
+from ..diagnostics import doctor_hint_message
 
 console = Console()
 
@@ -208,6 +209,7 @@ def query_command(
             click.echo(json.dumps({"error": str(e)}))
         else:
             console.print(f"[red]Connection Error:[/] {e}")
+            console.print(f"[dim]{doctor_hint_message()}[/]")
         raise SystemExit(1) from e
 
     except ServerError as e:

{agent_brain_cli-9.6.0 → agent_brain_cli-10.0.1}/agent_brain_cli/commands/reset.py

@@ -6,6 +6,7 @@ from rich.prompt import Confirm
 
 from ..client import ConnectionError, DocServeClient, ServerError
 from ..config import get_server_url
+from ..diagnostics import doctor_hint_message
 
 console = Console()
 
@@ -67,6 +68,7 @@ def reset_command(url: str | None, yes: bool, json_output: bool) -> None:
             click.echo(json.dumps({"error": str(e)}))
         else:
             console.print(f"[red]Connection Error:[/] {e}")
+            console.print(f"[dim]{doctor_hint_message()}[/]")
         raise SystemExit(1) from e
 
     except ServerError as e:

{agent_brain_cli-9.6.0 → agent_brain_cli-10.0.1}/agent_brain_cli/commands/start.py

@@ -15,6 +15,7 @@ import click
 from rich.console import Console
 from rich.panel import Panel
 
+from agent_brain_cli.config import resolve_project_root
 from agent_brain_cli.migration import resolve_state_dir_with_fallback
 from agent_brain_cli.xdg_paths import get_xdg_state_dir, migrate_legacy_paths
 
@@ -26,38 +27,6 @@ PID_FILE = "agent-brain.pid"
 RUNTIME_FILE = "runtime.json"
 
 
-def resolve_project_root(start_path: Path | None = None) -> Path:
-    """Resolve the canonical project root directory."""
-    start = (start_path or Path.cwd()).resolve()
-
-    # Try git root first
-    try:
-        result = subprocess.run(
-            ["git", "rev-parse", "--show-toplevel"],
-            capture_output=True,
-            text=True,
-            timeout=5,
-            cwd=str(start),
-        )
-        if result.returncode == 0:
-            return Path(result.stdout.strip()).resolve()
-    except (subprocess.TimeoutExpired, FileNotFoundError, OSError):
-        pass
-
-    # Walk up looking for markers
-    current = start
-    while current != current.parent:
-        if (current / ".agent-brain").is_dir():
-            return current
-        if (current / ".claude").is_dir():
-            return current
-        if (current / "pyproject.toml").is_file():
-            return current
-        current = current.parent
-
-    return start
-
-
 def read_config(state_dir: Path) -> dict[str, Any]:
     """Read configuration from state directory."""
     config_path = state_dir / "config.json"

{agent_brain_cli-9.6.0 → agent_brain_cli-10.0.1}/agent_brain_cli/commands/status.py

@@ -7,6 +7,7 @@ from rich.table import Table
 
 from ..client import ConnectionError, DocServeClient, ServerError
 from ..config import get_server_url
+from ..diagnostics import doctor_hint_message
 
 console = Console()
 
@@ -151,6 +152,7 @@ def status_command(url: str | None, json_output: bool, verbose: bool) -> None:
             click.echo(json.dumps({"error": str(e)}))
         else:
             console.print(f"[red]Connection Error:[/] {e}")
+            console.print(f"[dim]{doctor_hint_message()}[/]")
         raise SystemExit(1) from e
 
     except ServerError as e:

{agent_brain_cli-9.6.0 → agent_brain_cli-10.0.1}/agent_brain_cli/config.py

@@ -251,25 +251,38 @@ def load_config(start_path: Path | None = None) -> AgentBrainConfig:
     return config
 
 
-def _find_project_root(start_path: Path | None = None) -> Path:
+def resolve_project_root(start_path: Path | None = None) -> Path:
     """Find the project root by looking for markers.
 
-    Walks up from start_path looking for:
-    1. Git repository root
-    2. .claude/ directory
-    3. pyproject.toml file
+    Resolution order (first match wins):
+    1. Walk up from ``start_path`` looking for ``.agent-brain/`` — this lets a
+       sub-project inside a mono-repo keep its own state dir and not get
+       pulled to the git top-level (issues #124, #128).
+    2. Walk up looking for legacy ``.claude/agent-brain/``.
+    3. Git repository root (``git rev-parse --show-toplevel``).
+    4. Walk up looking for ``.claude/`` or ``pyproject.toml``.
+    5. Fall back to ``start_path``.
 
     Args:
         start_path: Starting directory. Defaults to cwd.
 
     Returns:
-        Project root path or start_path if no markers found.
+        Project root path.
     """
     import subprocess
 
     start = (start_path or Path.cwd()).resolve()
 
-    # Try git root first
+    # 1 & 2. Prefer a local state dir over git root so nested projects work.
+    current = start
+    while current != current.parent:
+        if (current / STATE_DIR_NAME).is_dir():
+            return current
+        if (current / LEGACY_STATE_DIR_NAME).is_dir():
+            return current
+        current = current.parent
+
+    # 3. Git root next — useful when this is the first time the user runs init.
     try:
         result = subprocess.run(
             ["git", "rev-parse", "--show-toplevel"],
@@ -283,11 +296,9 @@ def _find_project_root(start_path: Path | None = None) -> Path:
     except (subprocess.TimeoutExpired, FileNotFoundError, OSError):
         pass
 
-    # Walk up looking for markers
+    # 4. Other markers.
     current = start
     while current != current.parent:
-        if (current / ".agent-brain").is_dir():
-            return current
         if (current / ".claude").is_dir():
             return current
         if (current / "pyproject.toml").is_file():
@@ -297,6 +308,10 @@ def _find_project_root(start_path: Path | None = None) -> Path:
     return start
 
 
+# Backwards-compatible alias for any external callers.
+_find_project_root = resolve_project_root
+
+
 def get_state_dir(
     config: AgentBrainConfig | None = None,
     project_root: Path | None = None,
@@ -318,7 +333,7 @@ def get_state_dir(
     """
     # 1. Auto-detect project root and check for existing state dir
     if project_root is None:
-        project_root = _find_project_root()
+        project_root = resolve_project_root()
 
     # Check new path first, then legacy
     new_state_dir = project_root / STATE_DIR_NAME

agent_brain_cli-10.0.1/agent_brain_cli/diagnostics.py

@@ -0,0 +1,384 @@
+"""Shared diagnostics helpers for the Agent Brain CLI.
+
+The functions here power both the ``agent-brain doctor`` command and the
+"tip: run doctor" hint that appears when a command can't reach the server.
+Keeping the logic in one place means the hint and the diagnosis can never
+drift out of sync.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import platform
+import shutil
+import socket
+import sys
+from dataclasses import asdict, dataclass, field
+from pathlib import Path
+from typing import Any
+from urllib.error import URLError
+from urllib.request import Request, urlopen
+
+from agent_brain_cli.config import (
+    LEGACY_STATE_DIR_NAME,
+    STATE_DIR_NAME,
+    get_server_url,
+    load_config,
+    resolve_project_root,
+)
+
+#: Severity returned by every diagnostic check.
+SEVERITY_OK = "ok"
+SEVERITY_WARN = "warn"
+SEVERITY_FAIL = "fail"
+
+DOCTOR_HINT = "Tip: run `agent-brain doctor` to diagnose your setup."
+
+
+@dataclass
+class CheckResult:
+    """One row in the doctor output."""
+
+    name: str
+    status: str  # ok | warn | fail
+    message: str
+    fix: str | None = None
+    details: dict[str, Any] = field(default_factory=dict)
+
+
+@dataclass
+class DoctorReport:
+    """The full diagnostic snapshot."""
+
+    project_root: str
+    state_dir: str
+    state_dir_exists: bool
+    runtime_file: str | None
+    server_url: str
+    checks: list[CheckResult]
+
+    @property
+    def exit_code(self) -> int:
+        """Non-zero when any critical check failed."""
+        return 1 if any(c.status == SEVERITY_FAIL for c in self.checks) else 0
+
+    def to_dict(self) -> dict[str, Any]:
+        data = asdict(self)
+        data["exit_code"] = self.exit_code
+        return data
+
+
+def _check_python() -> CheckResult:
+    major, minor = sys.version_info[:2]
+    version = f"{major}.{minor}.{sys.version_info.micro}"
+    if (major, minor) >= (3, 10):
+        return CheckResult(
+            "python_version",
+            SEVERITY_OK,
+            f"Python {version}",
+            details={"version": version},
+        )
+    return CheckResult(
+        "python_version",
+        SEVERITY_FAIL,
+        f"Python {version} — Agent Brain requires 3.10+",
+        fix="Upgrade to Python 3.10 or newer.",
+        details={"version": version},
+    )
+
+
+def _check_project_init(project_root: Path, state_dir: Path) -> CheckResult:
+    config_path = state_dir / "config.json"
+    if config_path.exists():
+        return CheckResult(
+            "project_initialized",
+            SEVERITY_OK,
+            f"Project initialized at {state_dir}",
+            details={"state_dir": str(state_dir)},
+        )
+    return CheckResult(
+        "project_initialized",
+        SEVERITY_FAIL,
+        f"No {STATE_DIR_NAME}/config.json under {project_root}",
+        fix="Run `agent-brain init` in your project directory.",
+        details={
+            "project_root": str(project_root),
+            "expected_path": str(config_path),
+        },
+    )
+
+
+def _check_provider_config(state_dir: Path) -> CheckResult:
+    yaml_path = state_dir / "config.yaml"
+    try:
+        cfg = load_config()
+    except Exception as exc:  # pragma: no cover — pydantic noise
+        return CheckResult(
+            "provider_config",
+            SEVERITY_FAIL,
+            f"Failed to load config.yaml: {exc}",
+            fix=f"Fix or delete {yaml_path} and re-run `agent-brain doctor`.",
+        )
+
+    return CheckResult(
+        "provider_config",
+        SEVERITY_OK,
+        (
+            f"embedding={cfg.embedding.provider}:{cfg.embedding.model}, "
+            f"summarization={cfg.summarization.provider}:{cfg.summarization.model}"
+        ),
+        details={
+            "config_path": str(yaml_path) if yaml_path.exists() else None,
+            "embedding_provider": cfg.embedding.provider,
+            "embedding_model": cfg.embedding.model,
+            "summarization_provider": cfg.summarization.provider,
+            "summarization_model": cfg.summarization.model,
+        },
+    )
+
+
+_PROVIDER_KEY_ENV: dict[str, str] = {
+    "openai": "OPENAI_API_KEY",
+    "anthropic": "ANTHROPIC_API_KEY",
+    "claude": "ANTHROPIC_API_KEY",
+    "cohere": "COHERE_API_KEY",
+    "gemini": "GEMINI_API_KEY",
+    "google": "GEMINI_API_KEY",
+    "grok": "XAI_API_KEY",
+}
+
+
+def _check_api_keys() -> list[CheckResult]:
+    try:
+        cfg = load_config()
+    except Exception:  # pragma: no cover
+        return []
+
+    results: list[CheckResult] = []
+    for label, provider, model in (
+        ("embedding", cfg.embedding.provider, cfg.embedding.model),
+        ("summarization", cfg.summarization.provider, cfg.summarization.model),
+    ):
+        if provider == "ollama":
+            continue
+        env_name = (
+            cfg.embedding.api_key_env
+            if label == "embedding"
+            else cfg.summarization.api_key_env
+        ) or _PROVIDER_KEY_ENV.get(provider.lower())
+        if not env_name:
+            continue
+        present = bool(os.environ.get(env_name))
+        results.append(
+            CheckResult(
+                f"api_key_{label}",
+                SEVERITY_OK if present else SEVERITY_FAIL,
+                (
+                    f"{env_name} is set"
+                    if present
+                    else f"{env_name} is not set (required by {provider})"
+                ),
+                fix=(
+                    None
+                    if present
+                    else f"export {env_name}=… then re-run `agent-brain doctor`."
+                ),
+                details={
+                    "provider": provider,
+                    "model": model,
+                    "env_var": env_name,
+                    "present": present,
+                },
+            )
+        )
+    return results
+
+
+def _is_listening(host: str, port: int, timeout: float = 0.5) -> bool:
+    try:
+        with socket.create_connection((host, port), timeout=timeout):
+            return True
+    except (OSError, ConnectionRefusedError):
+        return False
+
+
+def _check_server(server_url: str, runtime_file: Path | None) -> CheckResult:
+    if runtime_file and not runtime_file.exists():
+        return CheckResult(
+            "server_reachable",
+            SEVERITY_WARN,
+            (
+                f"No runtime.json at {runtime_file} — server is probably not "
+                "running for this project."
+            ),
+            fix="Run `agent-brain start` to launch the server.",
+            details={
+                "runtime_file": str(runtime_file),
+                "server_url": server_url,
+            },
+        )
+
+    try:
+        req = Request(server_url.rstrip("/") + "/health")
+        with urlopen(req, timeout=3) as resp:  # noqa: S310 — local URL
+            body = resp.read().decode("utf-8", errors="replace")
+        return CheckResult(
+            "server_reachable",
+            SEVERITY_OK,
+            f"Server responded at {server_url}",
+            details={"server_url": server_url, "response_preview": body[:120]},
+        )
+    except URLError as exc:
+        return CheckResult(
+            "server_reachable",
+            SEVERITY_FAIL,
+            f"Cannot reach server at {server_url}: {exc.reason}",
+            fix="Start it with `agent-brain start` (or pass --url).",
+            details={"server_url": server_url, "error": str(exc.reason)},
+        )
+    except Exception as exc:  # noqa: BLE001
+        return CheckResult(
+            "server_reachable",
+            SEVERITY_FAIL,
+            f"Error contacting server at {server_url}: {exc}",
+            fix="Start it with `agent-brain start` (or pass --url).",
+            details={"server_url": server_url, "error": str(exc)},
+        )
+
+
+def _check_optional_dep(provider: str, module_name: str, extra: str) -> CheckResult:
+    """Report on an optional Python package that a chosen provider needs."""
+    if shutil.which("python3"):
+        # We import in-process so test mocks of installed packages work.
+        try:
+            __import__(module_name)
+            return CheckResult(
+                f"optional_dep_{module_name}",
+                SEVERITY_OK,
+                f"{module_name} is installed ({provider} provider)",
+                details={"module": module_name, "provider": provider},
+            )
+        except ImportError:
+            return CheckResult(
+                f"optional_dep_{module_name}",
+                SEVERITY_FAIL,
+                (
+                    f"{provider} provider selected but {module_name} is not "
+                    "installed."
+                ),
+                fix=f"pip install 'agent-brain-rag[{extra}]'",
+                details={
+                    "module": module_name,
+                    "provider": provider,
+                    "extras_install": extra,
+                },
+            )
+    return CheckResult(
+        f"optional_dep_{module_name}",
+        SEVERITY_WARN,
+        "Could not run Python interpreter to verify imports.",
+    )
+
+
+def _check_gitignore(project_root: Path) -> CheckResult:
+    gi = project_root / ".gitignore"
+    if not gi.exists():
+        return CheckResult(
+            "gitignore_state_dir",
+            SEVERITY_WARN,
+            f"No .gitignore at {project_root} — {STATE_DIR_NAME}/ may get committed.",
+            fix=f"Add `{STATE_DIR_NAME}/` to .gitignore.",
+        )
+    try:
+        lines = {line.strip() for line in gi.read_text().splitlines()}
+    except OSError:
+        return CheckResult(
+            "gitignore_state_dir",
+            SEVERITY_WARN,
+            f"Could not read {gi}.",
+        )
+    if any(entry in lines for entry in (STATE_DIR_NAME, f"{STATE_DIR_NAME}/")):
+        return CheckResult(
+            "gitignore_state_dir",
+            SEVERITY_OK,
+            f"{STATE_DIR_NAME}/ is in .gitignore",
+        )
+    return CheckResult(
+        "gitignore_state_dir",
+        SEVERITY_WARN,
+        f"{STATE_DIR_NAME}/ is not in .gitignore — index data may get committed.",
+        fix=f"Add `{STATE_DIR_NAME}/` to .gitignore.",
+    )
+
+
+def run_doctor(server_url_override: str | None = None) -> DoctorReport:
+    """Run every check and return a structured report."""
+    project_root = resolve_project_root()
+    state_dir = project_root / STATE_DIR_NAME
+    runtime_file: Path | None
+    if state_dir.exists():
+        runtime_file = state_dir / "runtime.json"
+    else:
+        legacy = project_root / LEGACY_STATE_DIR_NAME
+        runtime_file = legacy / "runtime.json" if legacy.exists() else None
+
+    server_url = server_url_override or get_server_url()
+
+    checks: list[CheckResult] = []
+    checks.append(_check_python())
+    checks.append(_check_project_init(project_root, state_dir))
+    checks.append(_check_provider_config(state_dir))
+    checks.extend(_check_api_keys())
+
+    # Optional deps that surface common install failures (issues #122/#125/#129).
+    try:
+        cfg = load_config()
+    except Exception:  # pragma: no cover
+        cfg = None
+    if cfg and cfg.embedding.provider.lower() == "cohere":
+        checks.append(_check_optional_dep("cohere", "cohere", "cohere"))
+    checks.append(_check_gitignore(project_root))
+
+    checks.append(_check_server(server_url, runtime_file))
+
+    return DoctorReport(
+        project_root=str(project_root),
+        state_dir=str(state_dir),
+        state_dir_exists=state_dir.exists(),
+        runtime_file=str(runtime_file) if runtime_file else None,
+        server_url=server_url,
+        checks=checks,
+    )
+
+
+def doctor_hint_message(project_root: Path | None = None) -> str:
+    """Suggest the doctor command — and call out the most likely setup issue.
+
+    When ``runtime.json`` is missing, the user almost certainly hasn't run
+    ``agent-brain init && agent-brain start`` in this directory. Saying so
+    is more useful than the generic "connection refused".
+    """
+    root = project_root or resolve_project_root()
+    state_dir = root / STATE_DIR_NAME
+    runtime_file = state_dir / "runtime.json"
+    if not runtime_file.exists():
+        return (
+            "Tip: no `.agent-brain/runtime.json` found under "
+            f"{root}. Run `agent-brain init` and `agent-brain start` here "
+            "first, or run `agent-brain doctor` to diagnose."
+        )
+    return DOCTOR_HINT
+
+
+def report_to_json(report: DoctorReport) -> str:
+    return json.dumps(report.to_dict(), indent=2)
+
+
+def env_snapshot() -> dict[str, Any]:
+    """Lightweight environment summary used in JSON output."""
+    return {
+        "platform": platform.platform(),
+        "python": platform.python_version(),
+        "cwd": str(Path.cwd()),
+    }

{agent_brain_cli-9.6.0 → agent_brain_cli-10.0.1}/pyproject.toml

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