mcp-kb 0.3.1__py3-none-any.whl → 0.3.2__py3-none-any.whl

mcp_kb/ui/api.py

@@ -0,0 +1,377 @@
+"""UI API helpers built on top of the knowledge base.
+
+The functions in this module provide reusable primitives for serving the web
+UI. They deliberately separate data shaping from the HTTP layer, which keeps
+the request handler small and easy to test in isolation.
+"""
+
+from __future__ import annotations
+
+import json
+import threading
+from typing import Dict, List, Literal, Optional, TypedDict, Any
+
+from mcp_kb.knowledge.store import KnowledgeBase, FileSegment
+from mcp_kb.knowledge.search import search_text
+from mcp_kb.knowledge.events import KnowledgeBaseSearchListener
+
+
+class TreeNode(TypedDict):
+    """JSON-serializable representation of an entry in the file tree."""
+
+    name: str
+    path: str
+    type: Literal["file", "dir"]
+    children: List["TreeNode"]
+
+
+def build_tree_json(kb: KnowledgeBase) -> TreeNode:
+    """Return a nested dictionary describing the current file tree.
+
+    The result starts at the knowledge base root and includes all active text
+    files, excluding soft-deleted files and the protected documentation folder
+    to align with the server's overview semantics.
+    """
+
+    # Build a nested dict tree keyed by name for deterministic ordering
+    root: Dict[str, Dict] = {}
+    for path in kb.iter_active_files():
+        parts = list(path.relative_to(kb.rules.root).parts)
+        cursor = root
+        for part in parts[:-1]:
+            cursor = cursor.setdefault(part, {})
+        cursor.setdefault(parts[-1], {})
+
+    def _to_node(name: str, subtree: Dict, prefix: str) -> TreeNode:
+        full_path = f"{prefix}/{name}" if prefix else name
+        if subtree:  # directory
+            children: List[TreeNode] = [
+                _to_node(child, subtree[child], full_path)
+                for child in sorted(subtree.keys())
+            ]
+            return TreeNode(name=name, path=full_path, type="dir", children=children)
+        return TreeNode(name=name, path=full_path, type="file", children=[])
+
+    # Convert to the final shape with a synthetic root
+    children = [_to_node(k, v, "") for k, v in sorted(root.items())]
+    return TreeNode(name="", path="", type="dir", children=children)
+
+
+def read_file_json(kb: KnowledgeBase, path: str) -> FileSegment:
+    """Read and return a file as a JSON-compatible dictionary."""
+
+    segment = kb.read_file(path)
+    segment.assert_path(kb.rules)
+    return segment
+
+
+def write_file(kb: KnowledgeBase, path: str, content: str) -> None:
+    """Create or overwrite ``path`` with ``content`` using the knowledge base.
+
+    This operation routes through :meth:`~mcp_kb.knowledge.store.KnowledgeBase.create_file`
+    so that the same validation, locking, and listener notification behavior
+    applies as for MCP tool invocations.
+    """
+
+    kb.create_file(path, content)
+
+
+__all__ = [
+    "TreeNode",
+    "build_tree_json",
+    "read_file_json",
+    "write_file",
+    "search_json",
+    "vector_status_json",
+    "vector_embeddings_json",
+    "vector_query_embedding_json",
+    "vector_reindex_json",
+    "vector_refit_json",
+]
+
+
+def search_json(kb: KnowledgeBase, query: str, *, limit: int | None = None) -> List[Dict[str, Any]]:
+    """Return JSON-compatible search results for ``query``.
+
+    Each result includes the relative ``path`` (string), one-based ``line``
+    number (int) where the match occurs, and ``context`` (list[str]) with
+    surrounding lines.
+    """
+
+    # Reuse the same provider model as the MCP tool: if registered listeners
+    # expose a search capability (e.g., Chroma ingestion), consult them first
+    # before falling back to on-disk scans. This keeps UI and MCP semantics
+    # aligned so results are consistent across entry points.
+    providers: List[KnowledgeBaseSearchListener] = []
+    for listener in getattr(kb, "listeners", ()):  # type: ignore[attr-defined]
+        if isinstance(listener, KnowledgeBaseSearchListener):
+            providers.append(listener)
+
+   
+    all_meta={}
+    matches,meta = search_text(kb, query, providers=providers, n_results=limit)
+    payload: List[Dict[str, Any]] = []
+    for m in matches:
+        payload.append(
+            m.model_dump()
+        )
+    return {"results":payload,"meta":meta}
+
+
+# ----------------------------- Vector Endpoints -----------------------------
+
+def _find_chroma_listener(kb: KnowledgeBase) -> Optional[Any]:
+    """Return the first Chroma-like listener attached to ``kb`` or ``None``.
+
+    The UI exposes additional endpoints when a vector store is available. To
+    avoid introducing a hard dependency on Chroma, the discovery relies on
+    duck-typing: listeners that provide a ``collection`` attribute (Chroma
+    collection) and a ``configuration`` with an ``embedding`` field are treated
+    as vector-capable.
+    """
+
+    for listener in getattr(kb, "listeners", ()):  # type: ignore[attr-defined]
+        if hasattr(listener, "collection"):
+            return listener
+    return None
+
+
+def _to_list(x: Any) -> List[float]:
+    """Return ``x`` as a JSON-serializable list of floats.
+
+    Chroma may return embeddings as NumPy arrays. This helper converts any
+    sequence-like object to a plain Python list of floats using ``tolist`` when
+    available.
+    """
+
+    try:
+        if isinstance(x, str):
+            data = json.loads(x)
+            if isinstance(data, (list, tuple)):
+                return [float(v) for v in data]
+        if hasattr(x, "indices") and hasattr(x, "values"):
+            values = getattr(x, "values")
+            indices = getattr(x, "indices")
+            size = int(getattr(x, "size", len(values)))
+            dense = [0.0] * size
+            for idx, value in zip(indices, values):
+                dense[int(idx)] = float(value)
+            return dense
+        if hasattr(x, "tolist"):
+            return [float(v) for v in x.tolist()]
+    except Exception:
+        pass
+    # Fallback: best-effort cast
+    try:
+        return [float(v) for v in x]
+    except Exception:
+        return []
+
+
+def vector_status_json(kb: KnowledgeBase) -> Dict[str, object]:
+    """Report whether a vector store is available and basic dataset stats.
+
+    Returns a JSON-compatible dictionary with the following keys:
+    - ``available`` (bool): true when a Chroma listener is attached.
+    - ``dimensions`` (int | null): length of the embedding vectors when
+      available; derived from a sample row.
+    - ``count`` (int | null): total number of stored embedding chunks.
+    """
+
+    listener = _find_chroma_listener(kb)
+    if listener is None:
+        return {"available": False, "dimensions": None, "count": None}
+
+    collection = getattr(listener, "collection")
+    # Total count
+    try:
+        total = collection.count()  # type: ignore[no-untyped-call]
+    except Exception:
+        total = None
+
+    # Sample one embedding to infer dimensions
+    dims: Optional[int] = None
+    try:
+        sample = collection.get(limit=1, include=["embeddings"])  # type: ignore[no-untyped-call]
+        embs = sample.get("embeddings") or []
+        # Avoid ambiguous truth checks on NumPy arrays
+        if isinstance(embs, (list, tuple)) and len(embs) > 0:
+            first = _to_list(embs[0])
+            if first:
+                dims = len(first)
+    except Exception:
+        dims = None
+
+    return {"available": True, "dimensions": dims, "count": total}
+
+
+def vector_embeddings_json(
+    kb: KnowledgeBase,
+    *,
+    limit: int = 1000,
+    offset: int = 0,
+    path: Optional[str] = None,
+) -> List[Dict[str, object]]:
+    """Return a page of embeddings with metadata for plotting.
+
+    Parameters
+    ----------
+    limit:
+        Maximum number of items to return (default: 1000).
+    offset:
+        Starting offset into the result set for paging.
+    path:
+        Optional relative path to filter embeddings from a specific file.
+
+    Returns
+    -------
+    list[dict]
+        Each item contains ``id`` (str), ``document_id`` (str|None), ``path``
+        (str), ``chunk`` (int), and ``embedding`` (list[float]). When the
+        backend provides precomputed UMAP projections the dictionaries also
+        surface ``umap2d`` and ``umap3d`` coordinates for downstream
+        visualisations.
+    """
+
+    listener = _find_chroma_listener(kb)
+    if listener is None:
+        return []
+
+    collection = getattr(listener, "collection")
+    where = {"path": path} if path else None
+    # Chroma's `include` only accepts certain fields; `ids` are always returned
+    # and must not be listed in `include`.
+    payload = collection.get(  # type: ignore[no-untyped-call]
+        where=where,
+        include=["embeddings", "metadatas"],
+        limit=limit,
+        offset=offset,
+    )
+
+    ids = payload.get("ids")
+    embs = payload.get("embeddings")
+    metas = payload.get("metadatas")
+    if ids is None:
+        ids = []
+    if embs is None:
+        embs = []
+    if metas is None:
+        metas = []
+
+    results: List[Dict[str, object]] = []
+    for i, emb in enumerate(embs):
+        meta: Dict[str, Any] = metas[i] if i < len(metas) else {}
+        umap2d: List[float] = []
+        umap3d: List[float] = []
+        if isinstance(meta, dict):
+            umap2d = _to_list(meta.get("umap2d", []))
+            umap3d = _to_list(meta.get("umap3d", []))
+        document_id = meta.get("document_id")
+        results.append(
+            {
+                "id": ids[i] if i < len(ids) else str(i),
+                "document_id": document_id if isinstance(document_id, str) else None,
+                "path": meta.get("path", ""),
+                "chunk": int(meta.get("chunk_number", 0)),
+                "embedding": _to_list(emb),
+                "umap2d": umap2d,
+                "umap3d": umap3d,
+            }
+        )
+    return results
+
+
+def vector_query_embedding_json(kb: KnowledgeBase, query: str) -> Dict[str, object]:
+    """Compute and return the embedding vector for ``query``.
+
+    The implementation reuses the Chroma collection's embedding function when
+    available. As a fallback it attempts to reconstruct an embedding function
+    instance based on the ingestor's configuration.
+    """
+
+    listener = _find_chroma_listener(kb)
+    if listener is None:
+        return {"embedding": [], "used_model": None}
+
+    collection = getattr(listener, "collection")
+
+    # Preferred path: use the collection's configured embedding function.
+    func = getattr(collection, "_embedding_function", None)
+    if callable(func):
+        try:
+            vecs = func([query])  # type: ignore[misc]
+            if isinstance(vecs, (list, tuple)) and len(vecs) > 0:
+                return {
+                    "embedding": _to_list(vecs[0]),
+                    "used_model": getattr(func, "__class__", type(func)).__name__,
+                }
+        except Exception:
+            pass
+
+    # Fallback: try to build a new embedding function of the same type.
+    try:
+        deps = getattr(listener, "_deps", None)
+        cfg = getattr(listener, "configuration", None)
+        if deps is not None and cfg is not None:
+            factories: Dict[str, Any] = getattr(deps, "embedding_factories", {})
+            emb_name = getattr(cfg, "embedding", "default")
+            factory = factories.get(emb_name)
+            if factory is not None:
+                inst = factory()
+                vecs = inst([query])
+                if isinstance(vecs, (list, tuple)) and len(vecs) > 0:
+                    return {"embedding": _to_list(vecs[0]), "used_model": inst.__class__.__name__}
+    except Exception:
+        pass
+
+    return {"embedding": [], "used_model": None}
+
+
+def vector_reindex_json(kb: KnowledgeBase) -> Dict[str, object]:
+    """Trigger a background rebuild of the Chroma index and report status."""
+
+    listener = _find_chroma_listener(kb)
+    if listener is None:
+        return {"status": "unavailable"}
+
+    starter = getattr(listener, "start_reindex_async", None)
+    if callable(starter):
+        started = bool(starter(kb))
+        return {"status": "queued" if started else "running"}
+
+    def _run() -> None:
+        try:
+            listener.reindex(kb)  # type: ignore[attr-defined]
+        except Exception:
+            # Fallback should never raise; swallow to keep the API robust.
+            pass
+
+    try:
+        thread = threading.Thread(target=_run, name="kb-reindex", daemon=True)
+        thread.start()
+        return {"status": "queued"}
+    except Exception:
+        return {"status": "error"}
+
+
+def vector_refit_json(kb: KnowledgeBase) -> Dict[str, object]:
+    """Trigger an immediate background UMAP refit when supported."""
+
+    listener = _find_chroma_listener(kb)
+    if listener is None:
+        return {"status": "unavailable"}
+
+    trigger = getattr(listener, "trigger_umap_refit_async", None)
+    if callable(trigger):
+        started = bool(trigger())
+        return {"status": "queued" if started else "error"}
+
+    scheduler = getattr(listener, "_schedule_umap_refit", None)
+    if callable(scheduler):
+        try:
+            scheduler(delay=0.0)
+            return {"status": "queued"}
+        except Exception:
+            return {"status": "error"}
+
+    return {"status": "error"}

mcp_kb/ui/assets/assets/index.css

@@ -0,0 +1 @@
+:root{--bg: #0f1115;--panel: #171a21;--border: #2a2f3a;--text: #e8eaf0;--muted: #a0a7b4;--accent: #5aa3ff;--vec-base: #8a8a8a;--vec-selected: #3d7eff;--vec-result: #ffb02e;--vec-query: #ff4d4f}*{box-sizing:border-box}body{margin:0;font-family:ui-sans-serif,system-ui,-apple-system,Segoe UI,Roboto,Ubuntu,Cantarell,Noto Sans,Helvetica,Arial,"Apple Color Emoji","Segoe UI Emoji";background:var(--bg);color:var(--text)}.menubar{display:flex;justify-content:space-between;align-items:center;padding:10px 14px;background:var(--panel);border-bottom:1px solid var(--border);position:sticky;top:0;z-index:10}.menubar .brand{font-weight:600}.menubar nav button{background:transparent;color:var(--text);border:1px solid var(--border);padding:6px 10px;margin-left:6px;border-radius:6px;cursor:pointer}.menubar nav button.active{border-color:var(--accent);color:var(--accent)}.menubar .searchbar{display:flex;gap:6px;align-items:center;width:50%}.menubar .searchbar input[type=search]{flex:1;min-width:120px;background:#0f1115;color:var(--text);border:1px solid var(--border);border-radius:6px;padding:6px 8px;font-size:13px}.menubar .searchbar input[type=number]{width:64px;background:#0f1115;color:var(--text);border:1px solid var(--border);border-radius:6px;padding:6px 8px;font-size:13px}.menubar .searchbar button{background:transparent;color:var(--text);border:1px solid var(--border);padding:6px 10px;border-radius:6px;cursor:pointer}.layout{display:grid;grid-template-columns:300px 1fr;height:calc(100vh - 50px)}.sidebar{border-right:1px solid var(--border);overflow:auto;background:var(--panel)}.sidebar-header{display:flex;gap:6px;padding:8px;border-bottom:1px solid var(--border);position:sticky;top:0;background:var(--panel);z-index:5}.sidebar-header button{background:transparent;color:var(--text);border:1px solid var(--border);padding:6px 8px;border-radius:6px;cursor:pointer;font-size:13px}.tree{list-style:none;padding:8px;margin:0;font-size:14px}.tree li{margin:2px 0}.tree .dir{color:var(--muted);margin-top:6px}.tree .file{cursor:pointer;padding:2px 6px;border-radius:4px}.tree .file:hover,.tree .file.active{background:#222737}.results{padding:8px;border-top:1px solid var(--border);font-size:13px;color:var(--muted)}.results .result{padding:6px;border:1px solid var(--border);border-radius:6px;margin-top:6px;cursor:pointer;color:var(--text);background:#141822}.results .result:hover{border-color:var(--accent)}.results .path{color:var(--muted);font-size:12px}.results .line{color:var(--accent);font-weight:600;margin-right:6px}.flash{animation:flash-bg 1s ease-out 1}@keyframes flash-bg{0%{background-color:#3b82f620}to{background-color:transparent}}.editor{display:grid;grid-template-rows:auto 1fr auto;height:100%}.path{padding:8px 12px;border-bottom:1px solid var(--border);color:var(--muted);font-size:13px}#editor{width:100%;height:100%;background:transparent;color:var(--text);border:none;resize:none;outline:none;padding:12px;font-family:ui-monospace,SFMono-Regular,Menlo,Monaco,Consolas,Liberation Mono,Courier New,monospace;font-size:14px;line-height:1.5}.actions{display:flex;gap:8px;align-items:center;border-top:1px solid var(--border);padding:8px 12px}.actions button{background:var(--accent);color:#04132b;border:none;padding:8px 12px;border-radius:6px;cursor:pointer;font-weight:600}.actions button#cancel{background:transparent;color:var(--text);border:1px solid var(--border);font-weight:500}.actions button.danger{background:#f87171;color:#2a0b0b}.actions button:disabled{opacity:.5;cursor:not-allowed;filter:grayscale(.2)}.status{margin-left:auto;color:var(--muted);font-size:12px}.hidden{display:none!important}#vectors-view{display:grid;grid-template-rows:auto 1fr auto;height:100%}#vector-canvas-container{position:relative;background:#111;border:1px solid var(--border)}#vector-canvas{width:100%;height:100%;display:block}#vector-legend{font-size:12px;color:var(--muted);padding:6px 12px}

mcp_kb/ui/assets/index.html

@@ -0,0 +1,62 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+    <title>Knowledge Base</title>
+    <link rel="icon" href="data:," />
+    <script type="module" crossorigin src="/static/entries/index.js"></script>
+    <link rel="stylesheet" crossorigin href="/static/assets/index.css">
+  </head>
+  <body>
+    <header class="menubar">
+      <div class="brand">Local Knowledge Base</div>
+      <div class="searchbar">
+        <input id="search-input" type="search" placeholder="Search…" aria-label="Search text" />
+        <input id="search-limit" type="number" min="1" value="10" title="Max results" aria-label="Max results" />
+        <button id="search-clear" title="Clear search">Clear</button>
+      </div>
+      <nav>
+        <button id="menu-browse" class="active" aria-pressed="true">Browse</button>
+        <button id="menu-vectors" class="hidden" aria-pressed="false" title="Embeddings view">
+          Vectors
+        </button>
+        <button id="menu-reindex" class="hidden" aria-pressed="false" title="Reindex Chroma DB">
+          Reindex
+        </button>
+        <button id="menu-umap-refit" class="hidden" aria-pressed="false" title="Refit UMAP (background)">
+          Refit
+        </button>
+      </nav>
+    </header>
+
+    <main class="layout">
+      <aside class="sidebar">
+        <div class="sidebar-header">
+          <button id="new-file">+ New File</button>
+        </div>
+        <ul id="file-tree" class="tree"></ul>
+        <div id="search-results" class="results" aria-live="polite"></div>
+      </aside>
+      <section id="browse-view" class="editor">
+        <div id="current-path" class="path"></div>
+        <textarea id="editor" spellcheck="false"></textarea>
+        <div class="actions">
+          <button id="save" disabled>Save</button>
+          <button id="cancel" disabled>Cancel</button>
+          <button id="delete" disabled class="danger">Delete</button>
+          <span id="status" class="status"></span>
+        </div>
+      </section>
+
+      <section id="vectors-view" class="editor hidden" aria-hidden="true">
+        <div id="vector-legend" class="legend" aria-live="polite"></div>
+        <div id="vector-canvas-container">
+          <canvas id="vector-canvas" aria-label="3D PCA scatter"></canvas>
+        </div>
+        <div id="vector-status" class="status"></div>
+      </section>
+    </main>
+
+  </body>
+</html>