seren-workbench 0.2.0__py3-none-any.whl

seren_workbench/__init__.py

@@ -0,0 +1,32 @@
+"""
+seren_workbench — the MCP server for the Seren stack.
+
+The tool surface that LLMs see. Builtin tools (memory, web, time, cluster, etc.)
+are defined in models/tools/; dynamic tools are loaded from YAML manifests in a
+tools/ directory. This package wires everything into a FastAPI app that serves
+the MCP transport AND an operator dashboard.
+
+Integrates seren_meninges (config/auth/viewer baseplate) and seren_sinew
+(request logging) following the same pattern as seren_loci, seren_memory,
+seren_corpus_callosum, and seren_probe.
+"""
+from __future__ import annotations
+
+# Version flows from the git tag via setuptools-scm (written to _version.py at
+# build time, read here). Fallback only fires in a bare source checkout that was
+# never built. Mirrors the family so every seren_* exposes __version__ alike.
+try:
+    from ._version import version as __version__
+except Exception:  # noqa: BLE001 - source checkout without a build
+    __version__ = "0.0.0+unknown"
+
+from .config import WorkbenchConfig, load_config  # noqa: F401,E402
+from .tool_registry import ToolRegistry, build_registry  # noqa: F401,E402
+
+__all__ = [
+    "__version__",
+    "WorkbenchConfig",
+    "load_config",
+    "ToolRegistry",
+    "build_registry",
+]

seren_workbench/__main__.py

@@ -0,0 +1,56 @@
+"""
+seren_workbench.__main__
+════════════════════════════════════════════════════════════════════════
+
+Entry point for ``python -m seren_workbench`` — starts the uvicorn server.
+
+Usage::
+
+    python -m seren_workbench [--config CONFIG] [--port PORT] [--host HOST]
+
+Config is loaded from ./seren-workbench.yaml by default; override with
+--config or the SEREN_WORKBENCH_CONFIG env var. The resolved path is
+threaded through cfg.source_path so the tools block (McpConfig) loads
+from the SAME file — including when --config is used.
+"""
+from __future__ import annotations
+
+import argparse
+import os
+import sys
+
+
+def main():
+    parser = argparse.ArgumentParser(
+        description="SerenWorkbench — MCP server for the Seren stack")
+    parser.add_argument("--config", "-c", default=None,
+                        help="Path to seren-workbench.yaml (default: "
+                             "./seren-workbench.yaml or $SEREN_WORKBENCH_CONFIG)")
+    parser.add_argument("--port", type=int, default=0,
+                        help="Override the configured port")
+    parser.add_argument("--host", type=str, default=None,
+                        help="Override the configured host")
+    args = parser.parse_args()
+
+    from .app import create_app
+    from .config import load_config
+
+    cfg = load_config(args.config)
+    if args.port:
+        cfg.server.port = args.port
+    if args.host:
+        cfg.server.host = args.host
+
+    app = create_app(cfg)
+
+    import uvicorn
+    uvicorn.run(
+        app,
+        host=cfg.server.host,
+        port=cfg.server.port,
+        log_level=os.environ.get("SEREN_WORKBENCH_LOG_LEVEL", "info").lower(),
+    )
+
+
+if __name__ == "__main__":
+    main()

seren_workbench/_version.py

@@ -0,0 +1,24 @@
+# file generated by vcs-versioning
+# don't change, don't track in version control
+from __future__ import annotations
+
+__all__ = [
+    "__version__",
+    "__version_tuple__",
+    "version",
+    "version_tuple",
+    "__commit_id__",
+    "commit_id",
+]
+
+version: str
+__version__: str
+__version_tuple__: tuple[int | str, ...]
+version_tuple: tuple[int | str, ...]
+commit_id: str | None
+__commit_id__: str | None
+
+__version__ = version = '0.2.0'
+__version_tuple__ = version_tuple = (0, 2, 0)
+
+__commit_id__ = commit_id = 'g42a570fea'

seren_workbench/app.py

@@ -0,0 +1,170 @@
+"""
+seren_workbench.app
+════════════════════════════════════════════════════════════════════════
+
+The FastAPI application for the Seren Workbench MCP server. Wires the
+builtin tools, dynamic tool registry, optional bearer auth, the operator
+dashboard, and the MCP transport for LLMs to connect to.
+
+Serves:
+    GET  /              — service info + tool counts
+    GET  /health        — liveness
+    GET  /tools         — JSON list of all registered tools (for the LLM)
+    GET  /viewer        — the operator dashboard HTML
+    POST /tools/state   — enable/disable a tool or action (viewer toggles)
+    GET  /tools/state   — current enable/disable snapshot
+    GET  /config        — server config JSON
+    GET  /logs          — audit log entries
+    /mcp                — the MCP transport endpoint
+
+Integrates seren_meninges (config/auth/viewer baseplate) and seren_sinew
+(request logging) — following the same pattern as the rest of the Seren family.
+
+DEPENDENCY INJECTION: the lifespan builds one httpx.AsyncClient per Seren
+service (base URLs from cfg.services) and registers them BY PARAMETER NAME
+in app.state.di_registry. The MCP layer injects them into builtin tool
+impls whose params are annotated httpx.AsyncClient / McpConfig. Without
+this the impls' DI defaults are None and every service call explodes —
+the half-cutover state this port started in.
+"""
+from __future__ import annotations
+
+import time
+from contextlib import asynccontextmanager, AsyncExitStack
+from pathlib import Path
+from typing import Optional
+
+import httpx
+from fastapi import FastAPI, Request
+from fastapi.responses import HTMLResponse
+
+from .config import WorkbenchConfig, load_config
+from .tool_registry import build_registry
+from .routes import info as info_routes
+from .routes import tools as tools_routes
+from .routes import config as config_routes
+from .routes import logs as logs_routes
+
+from seren_meninges import get_version
+from seren_meninges.auth import bearer_auth_middleware
+from seren_meninges.viewer import render_from_dir
+from seren_sinew.request_log import RequestLoggingMiddleware
+
+from . import __version__ as _fallback_version
+APP_VERSION = get_version("seren-workbench", fallback=_fallback_version)
+
+
+def create_app(config: Optional[WorkbenchConfig] = None) -> FastAPI:
+    cfg = config or load_config()
+    bearer = cfg.server.resolve_bearer()
+
+    @asynccontextmanager
+    async def lifespan(app: FastAPI):
+        app.state.config = cfg
+
+        # Load McpConfig (tool-level knobs) from the SAME yaml load_config
+        # resolved — no CWD-vs-argv[0] split brain between the server block
+        # and the tools block.
+        from .tool_config.mcp_config import McpConfig as _McpConfig
+        mcp_config = _McpConfig.load(cfg.source_path)
+        app.state.mcp_config = mcp_config
+
+        app.state.tool_registry = build_registry(
+            mcp_config=mcp_config,
+            tools_dir=cfg.dashboard.tools_dir,
+            tools_enabled=cfg.dashboard.tools_enabled,
+            tools_disabled=cfg.dashboard.tools_disabled,
+        )
+
+        # Wire the tool audit log
+        from .dynamic_tools.tool_audit_log import ToolAuditLog
+        app.state.audit_log = ToolAuditLog()
+
+        async with AsyncExitStack() as _stack:
+            # ── DI clients: one AsyncClient per Seren service ───────────
+            svc = cfg.services
+            timeout = httpx.Timeout(svc.timeout_seconds)
+
+            async def _client(base_url: str) -> httpx.AsyncClient:
+                c = httpx.AsyncClient(base_url=base_url, timeout=timeout)
+                await _stack.enter_async_context(c)
+                return c
+
+            # A base_url-less client for fetch_url absolute gets and for
+            # kind=web dynamic tools (their base_url comes from the manifest).
+            _general = await _stack.enter_async_context(
+                httpx.AsyncClient(timeout=timeout))
+
+            app.state.di_registry = {
+                "memory": await _client(svc.memory_url),
+                "runtime_host": await _client(svc.runtime_host_url),
+                "searxng": await _client(svc.searxng_url),
+                "scheduler": await _client(svc.scheduler_url),
+                "config": mcp_config,
+                "_dynamic_web_client": _general,
+            }
+
+            # Mount the MCP surface — conditionally, so a missing `mcp`
+            # package doesn't crash startup.
+            try:
+                from .mcp.server import mount_mcp_routes
+                mcp_server = mount_mcp_routes(app)
+            except ImportError as exc:
+                mcp_server = None
+                print(f"[seren-workbench] MCP surface not available; HTTP-only mode ({exc})")
+            except Exception as exc:
+                mcp_server = None
+                print(f"[seren-workbench] MCP mount failed: {exc!r} — continuing without MCP")
+
+            # The streamable-HTTP transport needs its session manager's task
+            # group entered explicitly.
+            session_manager = getattr(mcp_server, "session_manager", None)
+            if session_manager is not None:
+                await _stack.enter_async_context(session_manager.run())
+                print("[seren-workbench] MCP session manager running")
+            yield
+
+        print("[seren-workbench] shut down")
+
+    app = FastAPI(
+        title="SerenWorkbench",
+        description="MCP (Model Context Protocol) server for the Seren stack — "
+                    "the tool surface LLMs reach through.",
+        version=APP_VERSION,
+        lifespan=lifespan,
+    )
+
+    # ── Auth + logging stack ───────────────────────────────────────────
+    app.add_middleware(bearer_auth_middleware(bearer))
+    app.add_middleware(
+        RequestLoggingMiddleware,
+        service_name="seren-workbench",
+        env_prefix="SEREN_WORKBENCH",
+    )
+
+    viewer_dir = Path(__file__).resolve().parent / "viewer" / "ui"
+
+    # ── The operator dashboard viewer ──────────────────────────────────
+    @app.get("/viewer")
+    async def viewer():
+        """The operator dashboard — carded tool list with enable/disable toggles.
+
+        Renders the shared SerenMeninges baseplate with cool-grey accent and
+        the leaf fragment files from viewer/ui/.
+        """
+        html = render_from_dir(
+            viewer_dir,
+            title="SerenWorkbench",
+            brand="Seren<b>Workbench</b> · Tool Surface",
+            subtitle=f"v{APP_VERSION} · the MCP tool layer",
+            accent="#8e9aaf",  # cool grey — slate with a hint of blue
+        )
+        return HTMLResponse(html)
+
+    # ── Route subpackage mounts ────────────────────────────────────────
+    app.include_router(info_routes.router)
+    app.include_router(tools_routes.router)
+    app.include_router(config_routes.router)
+    app.include_router(logs_routes.router)
+
+    return app

seren_workbench/config.py

@@ -0,0 +1,156 @@
+"""
+seren_workbench.config
+════════════════════════════════════════════════════════════════════════
+
+Service-specific config for the Workbench MCP server. Uses seren_meninges
+shared blocks (ServerConfig, TlsConfig) plus its own server-specific sections:
+tools, dashboard, services, and dynamic_tools.
+
+Follows the same pattern as seren_loci.config, seren_memory.config, and
+seren_corpus_callosum.config — the family's lenient-load discipline.
+"""
+from __future__ import annotations
+
+import logging
+import os
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any, Optional
+
+import yaml
+
+from seren_meninges import ServerConfig, TlsConfig
+
+log = logging.getLogger(__name__)
+
+# Port 7425 — family convention: memory 7420, loci-v 7421, loci-nv 7422,
+# scc-nv 7423, scc-v 7424, workbench 7425, probe 7430
+DEFAULT_PORT = 7425
+
+
+@dataclass
+class DashboardConfig:
+    """Operator dashboard knobs.
+
+    tools_enabled / tools_disabled seed the registry's enable state at
+    startup (so an operator's disables survive a restart):
+      - tools_disabled: these tools start DISABLED.
+      - tools_enabled:  if non-empty, it is an ALLOWLIST — every tool NOT
+        named here starts disabled. Empty list = everything enabled.
+    """
+    enabled: bool = True
+    tools_dir: str = "/opt/seren/tools"
+    tools_enabled: list[str] = field(default_factory=lambda: [])
+    tools_disabled: list[str] = field(default_factory=lambda: [])
+
+    @classmethod
+    def from_dict(cls, d: Optional[dict[str, Any]]) -> "DashboardConfig":
+        d = d or {}
+        return cls(
+            enabled=bool(d.get("enabled", True)),
+            tools_dir=str(d.get("tools_dir", "/opt/seren/tools")),
+            tools_enabled=list(d.get("tools_enabled", [])),
+            tools_disabled=list(d.get("tools_disabled", [])),
+        )
+
+
+@dataclass
+class ServicesConfig:
+    """Base URLs for the Seren services the builtin tools reach through.
+
+    These are the DI targets: each builtin tool takes an httpx.AsyncClient
+    named after a service (memory, runtime_host, searxng, scheduler); the
+    app builds one client per URL here and injects it by parameter name.
+
+    Defaults are localhost + the family port convention, so a zero-config
+    run on the cluster head Just Works. Point them across the LAN in yaml
+    for a split deploy.
+    """
+    memory_url: str = "http://127.0.0.1:7420"        # SerenMemory
+    runtime_host_url: str = "http://127.0.0.1:6361"  # SerenRuntimeHost (cluster head)
+    searxng_url: str = "http://127.0.0.1:8080"       # SearXNG metasearch
+    scheduler_url: str = "http://127.0.0.1:6361"     # scheduler surface (RuntimeHost today)
+    timeout_seconds: float = 15.0                    # per-request client timeout
+
+    @classmethod
+    def from_dict(cls, d: Optional[dict[str, Any]]) -> "ServicesConfig":
+        d = d or {}
+        out = cls()
+        out.memory_url = str(d.get("memory_url", out.memory_url))
+        out.runtime_host_url = str(d.get("runtime_host_url", out.runtime_host_url))
+        out.searxng_url = str(d.get("searxng_url", out.searxng_url))
+        out.scheduler_url = str(d.get("scheduler_url", out.scheduler_url))
+        try:
+            out.timeout_seconds = float(d.get("timeout_seconds", out.timeout_seconds))
+        except (TypeError, ValueError):
+            pass  # lenient: unparseable timeout keeps the default
+        return out
+
+
+@dataclass
+class WorkbenchConfig:
+    """The top-level config, composed from shared blocks + service blocks."""
+    server: ServerConfig = field(default_factory=lambda: ServerConfig(port=DEFAULT_PORT))
+    tls: TlsConfig = field(default_factory=TlsConfig)
+    dashboard: DashboardConfig = field(default_factory=DashboardConfig)
+    services: ServicesConfig = field(default_factory=ServicesConfig)
+    # The yaml file this config was loaded from (None = defaults/env only).
+    # Threaded into McpConfig.load() so the server block and the tools block
+    # always come from the SAME file — no CWD-vs-argv[0] split brain.
+    source_path: Optional[str] = None
+
+
+def _apply_env_overrides(cfg: WorkbenchConfig) -> WorkbenchConfig:
+    """SEREN_WORKBENCH_* env wins last."""
+    env = os.environ
+    if v := env.get("SEREN_WORKBENCH_HOST"):
+        cfg.server.host = v
+    if v := env.get("SEREN_WORKBENCH_PORT"):
+        try:
+            cfg.server.port = int(v)
+        except ValueError:
+            log.warning("SEREN_WORKBENCH_PORT=%r is not an int; keeping %s", v, cfg.server.port)
+    if v := env.get("SEREN_WORKBENCH_BEARER_TOKEN"):
+        cfg.server.bearer_token = v
+    if v := env.get("SEREN_WORKBENCH_BEARER_TOKEN_ENV"):
+        cfg.server.bearer_token_env = v
+    if v := env.get("SEREN_WORKBENCH_BEARER_TOKEN_KEYRING"):
+        cfg.server.bearer_token_keyring = v
+    if v := env.get("SEREN_WORKBENCH_TRUST_SYSTEM_STORE"):
+        cfg.tls.trust_system_store = v.lower() in ("1", "true", "yes", "on")
+    if v := env.get("SEREN_WORKBENCH_TOOLS_DIR"):
+        cfg.dashboard.tools_dir = v
+    if v := env.get("SEREN_WORKBENCH_MEMORY_URL"):
+        cfg.services.memory_url = v
+    if v := env.get("SEREN_WORKBENCH_RUNTIME_HOST_URL"):
+        cfg.services.runtime_host_url = v
+    if v := env.get("SEREN_WORKBENCH_SEARXNG_URL"):
+        cfg.services.searxng_url = v
+    if v := env.get("SEREN_WORKBENCH_SCHEDULER_URL"):
+        cfg.services.scheduler_url = v
+    return cfg
+
+
+def load_config(path: Optional[str] = None) -> WorkbenchConfig:
+    """Defaults -> yaml -> env (later wins). A missing file is fine — defaults
+    + env is a valid zero-config run."""
+    data: dict[str, Any] = {}
+    candidate = path or os.environ.get("SEREN_WORKBENCH_CONFIG") or "seren-workbench.yaml"
+    cfg_path = Path(os.path.expanduser(candidate))
+    source_path: Optional[str] = None
+    if cfg_path.is_file():
+        try:
+            with open(cfg_path) as f:
+                data = yaml.safe_load(f) or {}
+            source_path = str(cfg_path)
+        except Exception:  # noqa: BLE001
+            data = {}
+
+    server = ServerConfig.from_dict(data.get("server"), default_port=DEFAULT_PORT)
+    tls = TlsConfig.from_dict(data.get("tls"))
+    dashboard = DashboardConfig.from_dict(data.get("dashboard"))
+    services = ServicesConfig.from_dict(data.get("services"))
+
+    cfg = WorkbenchConfig(server=server, tls=tls, dashboard=dashboard,
+                          services=services, source_path=source_path)
+    return _apply_env_overrides(cfg)

seren_workbench/dynamic_tools/__init__.py

@@ -0,0 +1,10 @@
+"""
+seren_workbench.dynamic_tools — YAML-defined plug-and-play tool dispatchers.
+
+Dynamic tools are loaded from YAML manifests in a tools/ directory and
+dispatched via web_dispatcher (HTTP calls) or process_dispatcher (subprocess
+calls). This module mirrors the original dynamic_tools/ package at the
+project root, now moved inside the seren_workbench package for family
+alignment.
+"""
+from __future__ import annotations

seren_workbench/dynamic_tools/dynamic_tool_registry.py

@@ -0,0 +1,139 @@
+# ════════════════════════════════════════════════════════════════════════
+#  DynamicToolRegistry - state tracker for plug-and-play YAML tools.
+#
+#  ARCHITECTURAL NOTE (the v1 reality)
+#
+#  In v1, the actual live tool surface is FIXED at app startup. This
+#  registry holds the LoadResult captured at startup and provides
+#  RescanDiskAsync() that re-reads tools/ and updates the "current disk
+#  state" snapshot. /reload calls this - it does NOT change the live
+#  tool surface; that needs a restart.
+# ════════════════════════════════════════════════════════════════════════
+
+from __future__ import annotations
+
+import asyncio
+import os
+import sys
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import List
+
+from .manifest_loader import LoadResult, ManifestLoader
+
+
+@dataclass
+class LoadedToolInfo:
+    name: str = ""
+    source: str = ""
+
+
+@dataclass
+class SkipInfo:
+    name: str = ""
+    reason: str = ""
+
+
+@dataclass
+class FileFailureInfo:
+    file: str = ""
+    error: str = ""
+
+
+@dataclass
+class RegistrySnapshot:
+    tools_dir: str = ""
+    live: List[LoadedToolInfo] = field(default_factory=list)
+    on_disk: List[LoadedToolInfo] = field(default_factory=list)
+    skipped: List[SkipInfo] = field(default_factory=list)
+    failed_files: List[FileFailureInfo] = field(default_factory=list)
+    warnings: List[str] = field(default_factory=list)
+    restart_pending: bool = False
+    would_add_on_restart: List[str] = field(default_factory=list)
+    would_remove_on_restart: List[str] = field(default_factory=list)
+
+
+class DynamicToolRegistry:
+    def __init__(self, tools_dir: str, initial_load: LoadResult) -> None:
+        self._tools_dir = tools_dir
+        self._loader = ManifestLoader()
+        self._initial_load = initial_load
+        self._current_disk_state = initial_load
+        self._lock = asyncio.Lock()
+        self._log_startup_summary(initial_load)
+
+    async def rescan_disk_async(self) -> RegistrySnapshot:
+        async with self._lock:
+            self._current_disk_state = self._loader.load_directory(self._tools_dir)
+            print(
+                f"[mcp-registry] disk rescan: "
+                f"parsed={len(self._current_disk_state.resolved_inline_tools)} "
+                f"skipped={len(self._current_disk_state.skipped_tools)} "
+                f"failed_files={len(self._current_disk_state.failed_files)}",
+                file=sys.stderr,
+            )
+            return self._build_snapshot()
+
+    def current_snapshot(self) -> RegistrySnapshot:
+        return self._build_snapshot()
+
+    # -- Helpers --
+
+    def _log_startup_summary(self, result: LoadResult) -> None:
+        print(
+            f"[mcp-registry] startup: loaded={len(result.resolved_inline_tools)} "
+            f"from {self._tools_dir} "
+            f"(skipped={len(result.skipped_tools)}, "
+            f"failed_files={len(result.failed_files)})",
+            file=sys.stderr,
+        )
+        for name, reason in result.skipped_tools:
+            print(f"[mcp-registry]   skipped: {reason}", file=sys.stderr)
+        for path, err in result.failed_files:
+            print(f"[mcp-registry]   failed:  {Path(path).name}: {err}", file=sys.stderr)
+        for warning in result.warnings:
+            print(f"[mcp-registry]   warning: {warning}", file=sys.stderr)
+
+    def _build_snapshot(self) -> RegistrySnapshot:
+        live_names = set(
+            t.name or "(unnamed)"
+            for t, _, _ in self._initial_load.resolved_inline_tools
+        )
+        disk_names = set(
+            t.name or "(unnamed)"
+            for t, _, _ in self._current_disk_state.resolved_inline_tools
+        )
+
+        would_add = sorted(disk_names - live_names)
+        would_remove = sorted(live_names - disk_names)
+
+        def to_info(t: tuple) -> LoadedToolInfo:
+            entry, _, source = t
+            return LoadedToolInfo(
+                name=entry.name or "(unnamed)",
+                source=Path(source).name,
+            )
+
+        return RegistrySnapshot(
+            tools_dir=self._tools_dir,
+            live=sorted(
+                [to_info(t) for t in self._initial_load.resolved_inline_tools],
+                key=lambda x: x.name,
+            ),
+            on_disk=sorted(
+                [to_info(t) for t in self._current_disk_state.resolved_inline_tools],
+                key=lambda x: x.name,
+            ),
+            skipped=[
+                SkipInfo(name=n, reason=r)
+                for n, r in self._current_disk_state.skipped_tools
+            ],
+            failed_files=[
+                FileFailureInfo(file=Path(p).name, error=e)
+                for p, e in self._current_disk_state.failed_files
+            ],
+            warnings=list(self._current_disk_state.warnings),
+            restart_pending=bool(would_add or would_remove),
+            would_add_on_restart=would_add,
+            would_remove_on_restart=would_remove,
+        )