getbased-dashboard 0.5.0__tar.gz

getbased_dashboard-0.5.0/LICENSE

@@ -0,0 +1,22 @@
+                    GNU GENERAL PUBLIC LICENSE
+                       Version 3, 29 June 2007
+
+ Copyright (C) 2007 Free Software Foundation, Inc. <https://fsf.org/>
+ Everyone is permitted to copy and distribute verbatim copies
+ of this license document, but changing it is not allowed.
+
+                            Preamble
+
+  The GNU General Public License is a free, copyleft license for
+software and other kinds of works.
+
+  The licenses for most software and other practical works are designed
+to take away your freedom to share and change the works.  By contrast,
+the GNU General Public License is intended to guarantee your freedom to
+share and change all versions of a program--to make sure it remains free
+software for all its users.  We, the Free Software Foundation, use the
+GNU General Public License for most of our software; it applies also to
+any other work released this way by its authors.  You can apply it to
+your programs, too.
+
+  For the full license text, see <https://www.gnu.org/licenses/gpl-3.0.txt>

getbased_dashboard-0.5.0/PKG-INFO

@@ -0,0 +1,125 @@
+Metadata-Version: 2.4
+Name: getbased-dashboard
+Version: 0.5.0
+Summary: Web dashboard for getbased-agents — manage knowledge libraries, generate MCP client configs, inspect agent activity
+License-Expression: GPL-3.0-only
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: fastapi>=0.110
+Requires-Dist: uvicorn[standard]>=0.29
+Requires-Dist: httpx>=0.27
+Requires-Dist: typer>=0.12
+Requires-Dist: python-multipart>=0.0.6
+Requires-Dist: getbased-mcp>=0.2.2
+Provides-Extra: test
+Requires-Dist: pytest>=8.0; extra == "test"
+Requires-Dist: pytest-asyncio>=0.23; extra == "test"
+Requires-Dist: respx>=0.21; extra == "test"
+Requires-Dist: httpx>=0.27; extra == "test"
+Dynamic: license-file
+
+# getbased-dashboard
+
+Web dashboard for [getbased-agents](https://github.com/elkimek/getbased-agents) — one page that covers knowledge library management, MCP client setup, and agent-activity inspection. Matches the getbased PWA's browser-local lens UX for users running the external-server backend.
+
+---
+
+## What it looks like
+
+Three tabs, single auth gate, one pill for ingest progress that lives outside the tab DOM so it survives navigation.
+
+### Knowledge tab
+- Engine badge strip at the top: `ONNX · CPU · MiniLM-L6-v2 · 384d · floor 0.55 · ready`
+- Library list with per-row model chip, live chunk count (`12,758 chunks`), relative last-ingested (`indexed 2h ago`), activate/rename/delete
+- Create-library form with a model dropdown (MiniLM-L6-v2 · BGE-small/base/large-en · BGE-M3) — dimension + download size shown per option
+- Drag-drop ingest with a bottom-right pill: HTML5 `<progress>`, `12,500 / 16,000 · 3.2/s` chunks/sec rate, Cancel (partial commit) + Dismiss (×). 3s auto-dismiss on completion.
+- Search preview with score per result
+- Sources panel sorted by chunk count desc, Delete-all + per-source delete
+
+### MCP tab
+- Env viewer showing what a spawned MCP would see (`LENS_URL`, `LENS_API_KEY_FILE` + present/missing, `GETBASED_TOKEN` set/not set, module path). Tooltips explain the difference between "dashboard's env" and "client's MCP env block"
+- Config generator — emits paste-ready blocks for **Claude Desktop**, **Claude Code**, **Cursor**, **Cline**, **Hermes**. JSON for the first four, YAML with `enabled_tools` allowlist for Hermes. Copy-to-clipboard button.
+- "Test MCP" — spawns the real `getbased-mcp` binary via stdio, runs `initialize` + `tools/list`, returns elapsed ms + tool names
+
+### Activity tab
+- Top-line stat cards (total calls, errors, error rate, tools in use)
+- Per-tool table with P50/P95 latency
+- Newest-first feed of recent calls, polls every 10s
+- Clear log button
+
+---
+
+## Install and run
+
+```bash
+pipx install getbased-dashboard
+getbased-dashboard serve          # http://127.0.0.1:8323
+```
+
+The dashboard expects a [getbased-rag](https://github.com/elkimek/getbased-agents/tree/main/packages/rag) server at `http://127.0.0.1:8322` and reuses rag's API key. On first visit the UI prompts for the bearer key; it's stored in `localStorage` on your machine.
+
+Or as part of the full stack:
+
+```bash
+pipx install "getbased-agent-stack[full]"
+lens serve                       # in one terminal — the RAG backend
+getbased-dashboard serve         # in another — the UI
+```
+
+---
+
+## Architecture
+
+```
+  Browser                 Dashboard               Rag server            MCP subprocess
+  localhost        ↔      localhost         ↔     localhost             on-demand stdio
+                          /api/* proxy            /query, /ingest,      tools/list
+                          + MCP test spawn        /libraries, /info,    (for Test button)
+                          + activity tail         /models, /stats
+```
+
+The dashboard holds no data. Delete it and your knowledge base is untouched.
+
+- All `/api/*` routes bearer-auth'd with the same key rag + MCP use (`secrets.compare_digest`, constant-time)
+- Error envelope normalised to `{"error": "<string>"}` for both HTTPException and Pydantic validation errors — frontend has one shape to parse
+- Upload path streams chunk-by-chunk to a temp file with a byte cap enforced before buffering (no OOM-via-multi-GB-upload)
+- Client disconnect propagates: browser aborts fetch → dashboard drops upstream → rag sees disconnect → ingest stops at next batch boundary
+
+---
+
+## Config
+
+| Variable | Default | Description |
+|---|---|---|
+| `DASHBOARD_HOST` | `127.0.0.1` | Bind host. Loopback-only by default — expose to LAN at your own risk |
+| `DASHBOARD_PORT` | `8323` | Bind port |
+| `LENS_URL` | `http://127.0.0.1:8322` | Where the rag server lives |
+| `LENS_API_KEY_FILE` | `$XDG_DATA_HOME/getbased/lens/api_key` (with legacy fallback to `~/.hermes/rag/lens_api_key`) | Shared bearer token — same one MCP reads |
+| `DASHBOARD_ACTIVITY_LOG` | `$XDG_STATE_HOME/getbased/mcp/activity.jsonl` | JSONL path the MCP writes to; dashboard tails it |
+| `DASHBOARD_MAX_INGEST_BYTES` | `268435456` (256 MB) | Cap on a single upload's total size |
+| `GETBASED_TOKEN` | (from env) | Optional. When set, the MCP tab's env viewer reads "set" and the config generator bakes it into the env blocks. Typically you leave it unset locally and set it in your AI client's MCP config |
+
+---
+
+## CLI
+
+```
+getbased-dashboard serve      Start the web server
+getbased-dashboard info       Show resolved config + whether the rag key is on disk
+```
+
+---
+
+## Security notes
+
+- Dashboard binds loopback by default. Exposing via `DASHBOARD_HOST=0.0.0.0` means anyone on the LAN can drive your rag with the bearer key
+- The bearer key is read fresh from disk on every authed request — rotating the key (rewrite the file) takes effect without a dashboard restart
+- Multipart upload filenames are basename-sanitised before forwarding to rag (defence in depth; rag also sanitises)
+- Subprocess spawn for the MCP test button reaps the child on timeout, exception, or cancellation — no orphaned processes
+
+---
+
+## License
+
+GPL-3.0-only, matching the rest of the monorepo.

getbased_dashboard-0.5.0/README.md

@@ -0,0 +1,104 @@
+# getbased-dashboard
+
+Web dashboard for [getbased-agents](https://github.com/elkimek/getbased-agents) — one page that covers knowledge library management, MCP client setup, and agent-activity inspection. Matches the getbased PWA's browser-local lens UX for users running the external-server backend.
+
+---
+
+## What it looks like
+
+Three tabs, single auth gate, one pill for ingest progress that lives outside the tab DOM so it survives navigation.
+
+### Knowledge tab
+- Engine badge strip at the top: `ONNX · CPU · MiniLM-L6-v2 · 384d · floor 0.55 · ready`
+- Library list with per-row model chip, live chunk count (`12,758 chunks`), relative last-ingested (`indexed 2h ago`), activate/rename/delete
+- Create-library form with a model dropdown (MiniLM-L6-v2 · BGE-small/base/large-en · BGE-M3) — dimension + download size shown per option
+- Drag-drop ingest with a bottom-right pill: HTML5 `<progress>`, `12,500 / 16,000 · 3.2/s` chunks/sec rate, Cancel (partial commit) + Dismiss (×). 3s auto-dismiss on completion.
+- Search preview with score per result
+- Sources panel sorted by chunk count desc, Delete-all + per-source delete
+
+### MCP tab
+- Env viewer showing what a spawned MCP would see (`LENS_URL`, `LENS_API_KEY_FILE` + present/missing, `GETBASED_TOKEN` set/not set, module path). Tooltips explain the difference between "dashboard's env" and "client's MCP env block"
+- Config generator — emits paste-ready blocks for **Claude Desktop**, **Claude Code**, **Cursor**, **Cline**, **Hermes**. JSON for the first four, YAML with `enabled_tools` allowlist for Hermes. Copy-to-clipboard button.
+- "Test MCP" — spawns the real `getbased-mcp` binary via stdio, runs `initialize` + `tools/list`, returns elapsed ms + tool names
+
+### Activity tab
+- Top-line stat cards (total calls, errors, error rate, tools in use)
+- Per-tool table with P50/P95 latency
+- Newest-first feed of recent calls, polls every 10s
+- Clear log button
+
+---
+
+## Install and run
+
+```bash
+pipx install getbased-dashboard
+getbased-dashboard serve          # http://127.0.0.1:8323
+```
+
+The dashboard expects a [getbased-rag](https://github.com/elkimek/getbased-agents/tree/main/packages/rag) server at `http://127.0.0.1:8322` and reuses rag's API key. On first visit the UI prompts for the bearer key; it's stored in `localStorage` on your machine.
+
+Or as part of the full stack:
+
+```bash
+pipx install "getbased-agent-stack[full]"
+lens serve                       # in one terminal — the RAG backend
+getbased-dashboard serve         # in another — the UI
+```
+
+---
+
+## Architecture
+
+```
+  Browser                 Dashboard               Rag server            MCP subprocess
+  localhost        ↔      localhost         ↔     localhost             on-demand stdio
+                          /api/* proxy            /query, /ingest,      tools/list
+                          + MCP test spawn        /libraries, /info,    (for Test button)
+                          + activity tail         /models, /stats
+```
+
+The dashboard holds no data. Delete it and your knowledge base is untouched.
+
+- All `/api/*` routes bearer-auth'd with the same key rag + MCP use (`secrets.compare_digest`, constant-time)
+- Error envelope normalised to `{"error": "<string>"}` for both HTTPException and Pydantic validation errors — frontend has one shape to parse
+- Upload path streams chunk-by-chunk to a temp file with a byte cap enforced before buffering (no OOM-via-multi-GB-upload)
+- Client disconnect propagates: browser aborts fetch → dashboard drops upstream → rag sees disconnect → ingest stops at next batch boundary
+
+---
+
+## Config
+
+| Variable | Default | Description |
+|---|---|---|
+| `DASHBOARD_HOST` | `127.0.0.1` | Bind host. Loopback-only by default — expose to LAN at your own risk |
+| `DASHBOARD_PORT` | `8323` | Bind port |
+| `LENS_URL` | `http://127.0.0.1:8322` | Where the rag server lives |
+| `LENS_API_KEY_FILE` | `$XDG_DATA_HOME/getbased/lens/api_key` (with legacy fallback to `~/.hermes/rag/lens_api_key`) | Shared bearer token — same one MCP reads |
+| `DASHBOARD_ACTIVITY_LOG` | `$XDG_STATE_HOME/getbased/mcp/activity.jsonl` | JSONL path the MCP writes to; dashboard tails it |
+| `DASHBOARD_MAX_INGEST_BYTES` | `268435456` (256 MB) | Cap on a single upload's total size |
+| `GETBASED_TOKEN` | (from env) | Optional. When set, the MCP tab's env viewer reads "set" and the config generator bakes it into the env blocks. Typically you leave it unset locally and set it in your AI client's MCP config |
+
+---
+
+## CLI
+
+```
+getbased-dashboard serve      Start the web server
+getbased-dashboard info       Show resolved config + whether the rag key is on disk
+```
+
+---
+
+## Security notes
+
+- Dashboard binds loopback by default. Exposing via `DASHBOARD_HOST=0.0.0.0` means anyone on the LAN can drive your rag with the bearer key
+- The bearer key is read fresh from disk on every authed request — rotating the key (rewrite the file) takes effect without a dashboard restart
+- Multipart upload filenames are basename-sanitised before forwarding to rag (defence in depth; rag also sanitises)
+- Subprocess spawn for the MCP test button reaps the child on timeout, exception, or cancellation — no orphaned processes
+
+---
+
+## License
+
+GPL-3.0-only, matching the rest of the monorepo.

getbased_dashboard-0.5.0/pyproject.toml

@@ -0,0 +1,36 @@
+[build-system]
+requires = ["setuptools>=68.0", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "getbased-dashboard"
+version = "0.5.0"
+description = "Web dashboard for getbased-agents — manage knowledge libraries, generate MCP client configs, inspect agent activity"
+readme = "README.md"
+license = "GPL-3.0-only"
+requires-python = ">=3.10"
+dependencies = [
+    "fastapi>=0.110",
+    "uvicorn[standard]>=0.29",
+    "httpx>=0.27",
+    "typer>=0.12",
+    "python-multipart>=0.0.6",
+    "getbased-mcp>=0.2.2",
+]
+
+[project.optional-dependencies]
+test = ["pytest>=8.0", "pytest-asyncio>=0.23", "respx>=0.21", "httpx>=0.27"]
+
+[project.scripts]
+getbased-dashboard = "getbased_dashboard.cli:app"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+getbased_dashboard = ["web/**/*"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+addopts = "-ra -q"
+asyncio_mode = "auto"

getbased_dashboard-0.5.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

getbased_dashboard-0.5.0/src/getbased_dashboard/__init__.py

@@ -0,0 +1,9 @@
+"""getbased-dashboard — web UI for getbased-agents.
+
+Orchestration layer that sits between the browser and the rag + mcp
+packages. Holds no data of its own: proxies knowledge-base operations
+to rag, spawns the mcp stdio process on demand for tool discovery and
+config generation, reads the mcp's activity log for the dashboard feed.
+"""
+
+__version__ = "0.1.0"

getbased_dashboard-0.5.0/src/getbased_dashboard/api/__init__.py

@@ -0,0 +1,6 @@
+"""Dashboard HTTP API.
+
+Each submodule registers its routes onto a FastAPI app via a `register()`
+function. Keeps the server.py entry point readable and lets each concern
+(knowledge, mcp, activity) own its own dependencies.
+"""

getbased_dashboard-0.5.0/src/getbased_dashboard/api/activity.py

@@ -0,0 +1,153 @@
+"""Activity API — tail the MCP's JSONL activity log and surface the
+recent records + simple aggregations.
+
+The log is written by getbased-mcp at `$XDG_STATE_HOME/getbased/mcp/
+activity.jsonl` (configurable via LENS_MCP_ACTIVITY_LOG). One record
+per tool call: tool name, timestamp, duration, ok flag, error class on
+failure. Args are never logged upstream so we don't have to strip them.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+from collections import defaultdict
+from pathlib import Path
+
+from fastapi import APIRouter, FastAPI, Request
+
+from ..config import DashboardConfig
+from ..server import _require_auth
+
+
+def _cfg(request: Request) -> DashboardConfig:
+    return request.app.state.config
+
+
+# Cap on how much of the log we read per request. Users with heavy agent
+# usage can accumulate megabytes quickly — loading the entire file on
+# every poll is wasteful. Tailing from the end keeps the endpoint O(cap)
+# regardless of how long the log has been running.
+_TAIL_BYTES = 512 * 1024
+
+
+def _read_records(path: Path, limit: int) -> list[dict]:
+    """Return up to `limit` most-recent records. If the file is under
+    _TAIL_BYTES read the whole thing; otherwise seek from the end. Malformed
+    lines (partial last write, corrupt records) are silently skipped so
+    one bad line can't hide the rest."""
+    if not path.exists():
+        return []
+    size = path.stat().st_size
+    try:
+        if size <= _TAIL_BYTES:
+            text = path.read_text(encoding="utf-8", errors="replace")
+        else:
+            with path.open("rb") as f:
+                f.seek(size - _TAIL_BYTES)
+                # Drop the first (likely partial) line so we don't parse
+                # garbage. There will always be a complete line after the
+                # first newline we find, assuming writers use line-atomic
+                # append — which Python's text-mode write does.
+                f.readline()
+                text = f.read().decode("utf-8", errors="replace")
+    except OSError:
+        return []
+
+    records: list[dict] = []
+    for line in text.splitlines():
+        line = line.strip()
+        if not line:
+            continue
+        try:
+            rec = json.loads(line)
+            if isinstance(rec, dict):
+                records.append(rec)
+        except json.JSONDecodeError:
+            continue
+
+    return records[-limit:]
+
+
+def _aggregate(records: list[dict]) -> dict:
+    """Per-tool counts, success rate, and P50/P95 latency. O(N log N) —
+    fine up to the ~thousand records our tail window holds."""
+    by_tool: dict[str, list[dict]] = defaultdict(list)
+    for r in records:
+        t = r.get("tool")
+        if isinstance(t, str):
+            by_tool[t].append(r)
+
+    def _percentile(sorted_vals: list[int], p: float) -> int | None:
+        if not sorted_vals:
+            return None
+        idx = int(p * (len(sorted_vals) - 1))
+        return sorted_vals[idx]
+
+    tools: list[dict] = []
+    for name, group in sorted(by_tool.items()):
+        durations = sorted(
+            int(r.get("duration_ms", 0)) for r in group if isinstance(r.get("duration_ms"), (int, float))
+        )
+        errors = sum(1 for r in group if not r.get("ok", True))
+        tools.append(
+            {
+                "tool": name,
+                "calls": len(group),
+                "errors": errors,
+                "error_rate": (errors / len(group)) if group else 0.0,
+                "p50_ms": _percentile(durations, 0.5),
+                "p95_ms": _percentile(durations, 0.95),
+            }
+        )
+
+    total_errors = sum(1 for r in records if not r.get("ok", True))
+    return {
+        "total_calls": len(records),
+        "total_errors": total_errors,
+        "overall_error_rate": (total_errors / len(records)) if records else 0.0,
+        "tools": tools,
+    }
+
+
+def register(app: FastAPI) -> None:
+    router = APIRouter(prefix="/api/activity", tags=["activity"])
+
+    @router.get("")
+    async def activity_feed(request: Request, limit: int = 200):
+        cfg = _cfg(request)
+        _require_auth(request, cfg)
+        # Bound limit so a client can't ask us to return 10 million records
+        # in one payload. 1000 is plenty for a dashboard tick.
+        limit = max(1, min(1000, int(limit)))
+        records = _read_records(cfg.activity_log, limit)
+        stats = _aggregate(records)
+        return {
+            "log_path": str(cfg.activity_log),
+            "log_exists": cfg.activity_log.exists(),
+            "records": records,
+            "stats": stats,
+        }
+
+    @router.delete("")
+    async def clear_activity(request: Request):
+        """Wipe the log. Useful for resetting the dashboard's view after
+        a period of testing. Returns the new (empty) state so the UI can
+        refresh in one round-trip."""
+        cfg = _cfg(request)
+        _require_auth(request, cfg)
+        try:
+            if cfg.activity_log.exists():
+                os.unlink(cfg.activity_log)
+        except OSError:
+            # File may have been created by another process or removed in
+            # a race; either way we want to return "nothing here" state.
+            pass
+        return {
+            "log_path": str(cfg.activity_log),
+            "log_exists": False,
+            "records": [],
+            "stats": _aggregate([]),
+        }
+
+    app.include_router(router)