brainpalace-dashboard 26.6.26__tar.gz

brainpalace_dashboard-26.6.26/PKG-INFO

@@ -0,0 +1,21 @@
+Metadata-Version: 2.4
+Name: brainpalace-dashboard
+Version: 26.6.26
+Summary: BrainPalace control-plane web dashboard
+Author: BrainPalace
+Requires-Python: >=3.12,<4.0
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Requires-Dist: brainpalace-cli (==26.6.26)
+Requires-Dist: fastapi (>=0.115,<0.116)
+Requires-Dist: httpx (>=0.28.0,<0.29.0)
+Requires-Dist: sse-starlette (>=2.1,<3.0)
+Requires-Dist: uvicorn (>=0.32.0,<0.33.0)
+Description-Content-Type: text/markdown
+
+# brainpalace-dashboard
+
+Control-plane web dashboard for managing all BrainPalace project servers. See docs/DASHBOARD.md.
+

brainpalace_dashboard-26.6.26/README.md

@@ -0,0 +1,3 @@
+# brainpalace-dashboard
+
+Control-plane web dashboard for managing all BrainPalace project servers. See docs/DASHBOARD.md.

brainpalace_dashboard-26.6.26/brainpalace_dashboard/__init__.py

@@ -0,0 +1,3 @@
+"""BrainPalace control-plane dashboard."""
+
+__version__ = "26.6.26"

brainpalace_dashboard-26.6.26/brainpalace_dashboard/api/routes_config.py

@@ -0,0 +1,65 @@
+"""Config schema + per-instance config GET/PATCH (batched, all-or-nothing)."""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any
+
+from fastapi import APIRouter, HTTPException
+from fastapi.responses import JSONResponse
+from pydantic import BaseModel
+
+from brainpalace_dashboard.services.config_svc import ConfigService, ConfigWriteError
+from brainpalace_dashboard.services.instances import (
+    InstanceNotFound,
+    InstanceService,
+)
+
+router = APIRouter(prefix="/dashboard/api", tags=["config"])
+config_service = ConfigService()
+instance_service = InstanceService()
+
+
+def _state_dir_for(id_: str) -> Path:
+    entry = instance_service._resolve(id_)  # raises InstanceNotFound
+    root = Path(entry["project_root"])
+    return Path(entry["state_dir"]) if entry.get("state_dir") else root / ".brainpalace"
+
+
+class ConfigPatch(BaseModel):
+    values: dict[str, Any]
+    restart: bool = False
+
+
+@router.get("/schema")
+def get_schema() -> dict[str, Any]:
+    return config_service.schema()
+
+
+@router.get("/instances/{id_}/config")
+def get_config(id_: str) -> dict[str, Any]:
+    try:
+        return config_service.read(_state_dir_for(id_))
+    except InstanceNotFound:
+        raise HTTPException(status_code=404, detail="instance not found") from None
+
+
+@router.patch("/instances/{id_}/config")
+def patch_config(id_: str, body: ConfigPatch) -> Any:
+    try:
+        state_dir = _state_dir_for(id_)
+    except InstanceNotFound:
+        raise HTTPException(status_code=404, detail="instance not found") from None
+    try:
+        config_service.write(state_dir, body.values)
+    except ConfigWriteError as e:
+        # Body is exactly {"errors": [...]} so the client reads .errors directly.
+        return JSONResponse(status_code=422, content={"errors": e.errors})
+    restarted = False
+    if body.restart:
+        try:
+            instance_service.restart(id_)
+            restarted = True
+        except Exception as e:  # surface but don't lose the saved config
+            return {"ok": True, "restarted": False, "restart_error": str(e)}
+    return {"ok": True, "restarted": restarted}

brainpalace_dashboard-26.6.26/brainpalace_dashboard/api/routes_data.py

@@ -0,0 +1,167 @@
+"""Per-instance data reads + action proxies.
+
+Each route is a thin wrapper that forwards to the live project server via
+``ProxyService`` and normalizes any upstream/transport failure to
+``{error, detail, upstream_status}`` (never a blank 500). Upstream paths are the
+*live* server routes confirmed against ``/openapi.json`` — note that cache,
+folders and jobs live under the ``/index/`` prefix on the server.
+"""
+
+from __future__ import annotations
+
+from typing import Annotated, Any
+
+from fastapi import APIRouter, Body
+from fastapi.responses import JSONResponse
+
+from brainpalace_dashboard.services.capabilities import parse_openapi
+from brainpalace_dashboard.services.proxy import ProxyService, UpstreamError
+
+router = APIRouter(prefix="/dashboard/api/instances/{id_}", tags=["data"])
+proxy = ProxyService()
+
+
+async def _call(
+    id_: str,
+    method: str,
+    path: str,
+    json: Any | None = None,
+    params: dict[str, Any] | None = None,
+) -> Any:
+    try:
+        return await proxy.request(id_, method, path, json=json, params=params)
+    except UpstreamError as e:
+        return JSONResponse(
+            status_code=e.upstream_status,
+            content={
+                "error": "upstream",
+                "detail": e.detail,
+                "upstream_status": e.upstream_status,
+            },
+        )
+
+
+# ---- reads ----
+@router.get("/health")
+async def health(id_: str) -> Any:
+    """Liveness + server version/mode (the project server's ``GET /health/``)."""
+    return await _call(id_, "GET", "/health/")
+
+
+@router.get("/status")
+async def status(id_: str) -> Any:
+    return await _call(id_, "GET", "/health/status")
+
+
+@router.get("/providers")
+async def providers(id_: str) -> Any:
+    return await _call(id_, "GET", "/health/providers")
+
+
+@router.get("/postgres")
+async def postgres(id_: str) -> Any:
+    return await _call(id_, "GET", "/health/postgres")
+
+
+@router.get("/folders")
+async def folders(id_: str) -> Any:
+    return await _call(id_, "GET", "/index/folders/")
+
+
+@router.get("/jobs")
+async def jobs(id_: str) -> Any:
+    return await _call(id_, "GET", "/index/jobs/")
+
+
+@router.get("/jobs/{job_id}")
+async def job(id_: str, job_id: str) -> Any:
+    return await _call(id_, "GET", f"/index/jobs/{job_id}")
+
+
+@router.get("/cache")
+async def cache(id_: str) -> Any:
+    return await _call(id_, "GET", "/index/cache/")
+
+
+@router.get("/graph")
+async def graph(id_: str) -> Any:
+    # graph stats live inside /health/status; expose a focused view client-side.
+    return await _call(id_, "GET", "/health/status")
+
+
+@router.get("/memories")
+async def memories(id_: str) -> Any:
+    return await _call(id_, "GET", "/memories/")
+
+
+@router.get("/runtime")
+async def runtime(id_: str) -> Any:
+    return await _call(id_, "GET", "/runtime/")
+
+
+@router.get("/logs")
+async def logs(id_: str, lines: int = 200, level: str | None = None) -> Any:
+    """Tail the server log file (proxy onto the server's ``/health/logs``)."""
+    params: dict[str, Any] = {"lines": lines}
+    if level:
+        params["level"] = level
+    return await _call(id_, "GET", "/health/logs", params=params)
+
+
+@router.get("/capabilities")
+async def capabilities(id_: str) -> Any:
+    doc = await _call(id_, "GET", "/openapi.json")
+    if isinstance(doc, JSONResponse):
+        return doc
+    return parse_openapi(doc)
+
+
+# ---- actions ----
+@router.post("/index")
+async def add_folder(id_: str, body: Annotated[dict[str, Any], Body(...)]) -> Any:
+    return await _call(id_, "POST", "/index/", json=body)
+
+
+@router.delete("/folders")
+async def remove_folder(id_: str, body: Annotated[dict[str, Any], Body(...)]) -> Any:
+    return await _call(id_, "DELETE", "/index/folders/", json=body)
+
+
+@router.delete("/index")
+async def reset_index(id_: str) -> Any:
+    return await _call(id_, "DELETE", "/index/")
+
+
+@router.delete("/cache")
+async def clear_cache(id_: str) -> Any:
+    return await _call(id_, "DELETE", "/index/cache/")
+
+
+@router.delete("/jobs/{job_id}")
+async def cancel_job(id_: str, job_id: str) -> Any:
+    return await _call(id_, "DELETE", f"/index/jobs/{job_id}")
+
+
+@router.post("/git/reindex")
+async def git_reindex(id_: str) -> Any:
+    return await _call(id_, "POST", "/git/reindex")
+
+
+@router.post("/sessions/reindex")
+async def sessions_reindex(id_: str) -> Any:
+    return await _call(id_, "POST", "/sessions/reindex")
+
+
+@router.post("/memories/{memory_id}/obsolete")
+async def memory_obsolete(id_: str, memory_id: str) -> Any:
+    return await _call(id_, "POST", f"/memories/{memory_id}/obsolete")
+
+
+@router.delete("/memories/{memory_id}")
+async def memory_delete(id_: str, memory_id: str) -> Any:
+    return await _call(id_, "DELETE", f"/memories/{memory_id}")
+
+
+@router.post("/memories/rebuild")
+async def memory_rebuild(id_: str) -> Any:
+    return await _call(id_, "POST", "/memories/rebuild")

brainpalace_dashboard-26.6.26/brainpalace_dashboard/api/routes_events.py

@@ -0,0 +1,52 @@
+"""Server-Sent Events stream for live dashboard updates.
+
+A single ``GET /dashboard/api/events`` stream emits an ``instances`` event
+(the current fleet list) every ``poll_s`` seconds. The SPA subscribes once via
+``EventSource`` and feeds each payload into its TanStack Query cache, instead of
+every tab polling ``/instances`` independently.
+
+``max_ticks`` bounds the number of emissions so tests can consume a finite
+stream; in production it defaults to ``None`` (stream until the client
+disconnects).
+"""
+
+from __future__ import annotations
+
+import asyncio
+import json
+from collections.abc import AsyncIterator
+from typing import Any
+
+from fastapi import APIRouter, Query
+from sse_starlette.sse import EventSourceResponse
+
+from brainpalace_dashboard.services.instances import InstanceService
+
+router = APIRouter(prefix="/dashboard/api", tags=["events"])
+service = InstanceService()
+
+
+async def _instance_events(
+    poll_s: float, max_ticks: int | None
+) -> AsyncIterator[dict[str, Any]]:
+    """Yield one ``instances`` SSE event per tick until ``max_ticks`` (if set)."""
+    ticks = 0
+    while max_ticks is None or ticks < max_ticks:
+        try:
+            data = service.list()
+        except Exception:  # never let a transient listing error kill the stream
+            data = []
+        yield {"event": "instances", "data": json.dumps(data)}
+        ticks += 1
+        if max_ticks is not None and ticks >= max_ticks:
+            break
+        await asyncio.sleep(poll_s)
+
+
+@router.get("/events")
+async def events(
+    poll_s: float = Query(5.0, ge=0.0),
+    max_ticks: int | None = Query(None, ge=1),
+) -> EventSourceResponse:
+    """Live SSE stream of the fleet ``instances`` list."""
+    return EventSourceResponse(_instance_events(poll_s, max_ticks))

brainpalace_dashboard-26.6.26/brainpalace_dashboard/api/routes_instances.py

@@ -0,0 +1,70 @@
+"""Instance lifecycle endpoints."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from fastapi import APIRouter, HTTPException, Query
+from pydantic import BaseModel
+
+from brainpalace_dashboard.services.instances import InstanceNotFound, InstanceService
+
+router = APIRouter(prefix="/dashboard/api/instances", tags=["instances"])
+service = InstanceService()
+
+
+class RegisterBody(BaseModel):
+    path: str
+
+
+@router.get("")
+def list_instances() -> list[dict[str, Any]]:
+    return service.list()
+
+
+@router.post("/register")
+def register_instance(body: RegisterBody) -> dict[str, Any]:
+    """Add an existing project dir to the dashboard list."""
+    return service.register(body.path)
+
+
+@router.get("/{id_}")
+def get_instance(id_: str) -> dict[str, Any]:
+    for row in service.list():
+        if row["id"] == id_:
+            return row
+    raise HTTPException(status_code=404, detail="instance not found")
+
+
+@router.post("/{id_}/start")
+def start_instance(id_: str) -> dict[str, Any]:
+    try:
+        return service.start(id_)
+    except InstanceNotFound as exc:
+        raise HTTPException(status_code=404, detail="instance not found") from exc
+    except RuntimeError as exc:
+        raise HTTPException(status_code=502, detail=str(exc)) from exc
+
+
+@router.post("/{id_}/stop")
+def stop_instance(id_: str, force: bool = Query(False)) -> dict[str, Any]:
+    try:
+        return service.stop(id_, force=force)
+    except InstanceNotFound as exc:
+        raise HTTPException(status_code=404, detail="instance not found") from exc
+
+
+@router.post("/{id_}/restart")
+def restart_instance(id_: str) -> dict[str, Any]:
+    try:
+        return service.restart(id_)
+    except InstanceNotFound as exc:
+        raise HTTPException(status_code=404, detail="instance not found") from exc
+    except RuntimeError as exc:
+        raise HTTPException(status_code=502, detail=str(exc)) from exc
+
+
+@router.delete("/{id_}")
+def forget_instance(id_: str) -> dict[str, Any]:
+    """Remove a project from the dashboard list. Does not delete anything on disk."""
+    return service.forget(id_)

brainpalace_dashboard-26.6.26/brainpalace_dashboard/api/routes_queries.py

@@ -0,0 +1,79 @@
+"""Control-plane Queries routes — history list/detail + live replay.
+
+Thin proxies onto the project server's ``/query/history[...]`` reads and a
+``/query/`` replay. Every upstream/transport failure is normalized to
+``{error, detail, upstream_status}`` (never a blank 500), matching the pattern
+in ``routes_data.py``.
+"""
+
+from __future__ import annotations
+
+from typing import Annotated, Any
+
+from fastapi import APIRouter, Body
+from fastapi.responses import JSONResponse
+
+from brainpalace_dashboard.services.proxy import ProxyService, UpstreamError
+
+router = APIRouter(prefix="/dashboard/api/instances/{id_}/queries", tags=["queries"])
+proxy = ProxyService()
+
+
+async def _call(
+    id_: str,
+    method: str,
+    path: str,
+    json: Any | None = None,
+    params: dict[str, Any] | None = None,
+) -> Any:
+    try:
+        return await proxy.request(id_, method, path, json=json, params=params)
+    except UpstreamError as e:
+        return JSONResponse(
+            status_code=e.upstream_status,
+            content={
+                "error": "upstream",
+                "detail": e.detail,
+                "upstream_status": e.upstream_status,
+            },
+        )
+
+
+@router.get("")
+async def history(
+    id_: str,
+    since: float | None = None,
+    mode: str | None = None,
+    contains: str | None = None,
+    limit: int = 100,
+    offset: int = 0,
+) -> Any:
+    params = {
+        k: v
+        for k, v in {
+            "since": since,
+            "mode": mode,
+            "contains": contains,
+            "limit": limit,
+            "offset": offset,
+        }.items()
+        if v is not None
+    }
+    return await _call(id_, "GET", "/query/history", params=params)
+
+
+@router.get("/{qid}")
+async def detail(id_: str, qid: str) -> Any:
+    return await _call(id_, "GET", f"/query/history/{qid}")
+
+
+@router.post("/replay")
+async def replay(id_: str, body: Annotated[dict[str, Any], Body(...)]) -> Any:
+    payload: dict[str, Any] = {
+        "query": body["query"],
+        "mode": body.get("mode", "hybrid"),
+        "top_k": body.get("top_k", 5),
+    }
+    if "alpha" in body:
+        payload["alpha"] = body["alpha"]
+    return await _call(id_, "POST", "/query/", json=payload)

brainpalace_dashboard-26.6.26/brainpalace_dashboard/api/routes_settings.py

@@ -0,0 +1,80 @@
+"""Control-plane (dashboard "server") settings — distinct from per-instance config.
+
+The dashboard's own settings (`dashboard:` block in the XDG config.yaml:
+host/port/poll_s/token) are fleet-wide and govern the control-plane process
+itself, not any single project server. The per-instance Config tab edits each
+project's `config.yaml`; this surface edits the dashboard.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from fastapi import APIRouter
+from fastapi.responses import JSONResponse
+from pydantic import BaseModel
+
+from brainpalace_dashboard import __version__
+from brainpalace_dashboard.config import (
+    TOKEN_MASK,
+    DashboardConfigError,
+    load_dashboard_config,
+    save_dashboard_config,
+)
+from brainpalace_dashboard.server import read_dashboard_runtime
+
+router = APIRouter(prefix="/dashboard/api/settings", tags=["settings"])
+
+# Fields that only take effect when the dashboard process is restarted.
+RESTART_FIELDS = {"host", "port", "token"}
+
+
+@router.get("")
+def get_settings() -> dict[str, Any]:
+    cfg = load_dashboard_config()
+    runtime = read_dashboard_runtime() or {}
+    return {
+        "host": cfg.host,
+        "port": cfg.port,
+        "poll_s": cfg.poll_s,
+        # Never expose the real token; the SPA only learns whether one is set and
+        # echoes back the mask to keep it unchanged.
+        "token_set": cfg.token is not None,
+        "token": TOKEN_MASK if cfg.token is not None else "",
+        "version": __version__,
+        "runtime": {
+            "running": bool(runtime.get("pid")),
+            "port": runtime.get("port"),
+            "base_url": runtime.get("base_url"),
+        },
+    }
+
+
+class SettingsPatch(BaseModel):
+    host: str | None = None
+    port: int | None = None
+    poll_s: int | None = None
+    token: str | None = None
+
+
+@router.patch("", response_model=None)
+def patch_settings(body: SettingsPatch) -> dict[str, Any] | JSONResponse:
+    current = load_dashboard_config()
+    values = body.model_dump(exclude_unset=True)
+
+    # Which submitted fields actually change a restart-sensitive setting?
+    restart_required: list[str] = []
+    if "host" in values and values["host"] != current.host:
+        restart_required.append("host")
+    if "port" in values and values["port"] != current.port:
+        restart_required.append("port")
+    if "token" in values and values["token"] != TOKEN_MASK:
+        new = values["token"] or None
+        if new != current.token:
+            restart_required.append("token")
+
+    try:
+        save_dashboard_config(values)
+    except DashboardConfigError as e:
+        return JSONResponse(status_code=422, content={"errors": e.errors})
+    return {"ok": True, "restart_required": restart_required}

brainpalace_dashboard-26.6.26/brainpalace_dashboard/app.py

@@ -0,0 +1,144 @@
+"""FastAPI application factory for the control-plane dashboard."""
+
+from __future__ import annotations
+
+import os
+from collections.abc import AsyncIterator
+from contextlib import asynccontextmanager
+from pathlib import Path
+from typing import Any
+
+from fastapi import FastAPI, Request
+from fastapi.responses import FileResponse, JSONResponse
+from fastapi.staticfiles import StaticFiles
+from starlette.middleware.base import BaseHTTPMiddleware
+from starlette.responses import Response
+
+from brainpalace_dashboard import __version__
+from brainpalace_dashboard.api import (
+    routes_config,
+    routes_data,
+    routes_events,
+    routes_instances,
+    routes_queries,
+    routes_settings,
+)
+from brainpalace_dashboard.config import load_dashboard_config
+
+
+def _static_dir() -> Path:
+    """Directory holding the built SPA (``index.html`` + ``assets/``).
+
+    Overridable via ``BRAINPALACE_DASHBOARD_STATIC`` (used by tests and by
+    deployments that ship the build separately). Defaults to the package-local
+    ``static/`` directory populated by ``npm run build``.
+    """
+    override = os.environ.get("BRAINPALACE_DASHBOARD_STATIC")
+    if override:
+        return Path(override)
+    return Path(__file__).parent / "static"
+
+
+def _mount_spa(app: FastAPI) -> None:
+    """Serve the built SPA under ``/dashboard/`` with client-side-routing
+    fallback.
+
+    Registered AFTER the API routers so that the ``/dashboard/{path:path}``
+    catch-all never shadows ``/dashboard/api/...`` endpoints. If no build is
+    present (e.g. a source checkout without ``npm run build``) this is a no-op,
+    leaving the API fully functional.
+    """
+    static = _static_dir()
+    if not (static / "index.html").exists():
+        return
+
+    assets = static / "assets"
+    if assets.is_dir():
+        app.mount(
+            "/dashboard/assets",
+            StaticFiles(directory=assets),
+            name="dashboard-assets",
+        )
+
+    @app.get("/dashboard/{path:path}", include_in_schema=False)
+    def spa(path: str) -> FileResponse:
+        candidate = (static / path).resolve()
+        # Guard against path traversal escaping the static root.
+        if path and static.resolve() in candidate.parents and candidate.is_file():
+            return FileResponse(candidate)
+        return FileResponse(static / "index.html")
+
+
+#: API paths exempt from the bearer-token guard even when a token is set.
+_AUTH_EXEMPT_PATHS = frozenset({"/dashboard/api/health"})
+
+
+def _resolve_token() -> str | None:
+    """Resolve the configured dashboard token.
+
+    Precedence: the ``BRAINPALACE_DASHBOARD_TOKEN`` env var, then the
+    ``dashboard.token`` config value. Returns ``None`` when no token is set
+    (meaning the dashboard is unguarded — the default for localhost use).
+    """
+    env_token = os.environ.get("BRAINPALACE_DASHBOARD_TOKEN")
+    if env_token:
+        return env_token
+    return load_dashboard_config().token
+
+
+class BearerTokenMiddleware(BaseHTTPMiddleware):
+    """Guard ``/dashboard/api/**`` with a static bearer token when configured.
+
+    Only API paths are guarded; static/SPA routes and ``/dashboard/api/health``
+    are always open. When no token is configured the middleware is a pass-through
+    (enabling the guard is intended for shared machines, not localhost).
+    """
+
+    def __init__(self, app: Any, token: str) -> None:
+        super().__init__(app)
+        self._token = token
+
+    async def dispatch(self, request: Request, call_next: Any) -> Response:
+        path = request.url.path
+        if path.startswith("/dashboard/api/") and path not in _AUTH_EXEMPT_PATHS:
+            header = request.headers.get("Authorization", "")
+            expected = f"Bearer {self._token}"
+            if header != expected:
+                return JSONResponse(
+                    {"detail": "Unauthorized"},
+                    status_code=401,
+                )
+        response: Response = await call_next(request)
+        return response
+
+
+@asynccontextmanager
+async def lifespan(app: FastAPI) -> AsyncIterator[None]:
+    yield
+    # Close the shared proxy httpx clients on shutdown.
+    await routes_data.proxy.aclose()
+    await routes_queries.proxy.aclose()
+
+
+def create_app() -> FastAPI:
+    app = FastAPI(title="BrainPalace Dashboard", version=__version__, lifespan=lifespan)
+
+    token = _resolve_token()
+    if token:
+        app.add_middleware(BearerTokenMiddleware, token=token)
+
+    @app.get("/dashboard/api/health")
+    def health() -> dict[str, str]:
+        return {"status": "ok", "version": __version__}
+
+    app.include_router(routes_instances.router)
+    app.include_router(routes_config.router)
+    app.include_router(routes_data.router)
+    app.include_router(routes_queries.router)
+    app.include_router(routes_events.router)
+    app.include_router(routes_settings.router)
+
+    # SPA catch-all is registered last so API routers win.
+    _mount_spa(app)
+
+    return app