seren-observatory 0.0.0.dev0__py3-none-any.whl

seren_observatory/__init__.py

@@ -0,0 +1,23 @@
+"""
+seren-observatory - per-Jetson management plane.
+
+HTTP API exposing manifest-driven discovery and lifecycle of locally-installed
+Seren services (llama, kokoro, comfy, whisper, coral). Consumed by:
+    - SerenRuntimeHost (C#) for chat-app workflows
+    - SerenCommandCenter (SCC, future) for cluster orchestration
+    - The NUC dashboard for monitoring
+
+Routes are versioned under /api/v1/. See service_routes.py and system_routes.py.
+"""
+from __future__ import annotations
+
+from importlib.metadata import PackageNotFoundError, version
+
+try:
+    __version__: str = version("seren-observatory")
+except PackageNotFoundError:
+    # Running from a source checkout without an editable install.
+    # Set SETUPTOOLS_SCM_PRETEND_VERSION=0.0.0 and run:
+    #   pip install -e ".[dev]"
+    # to resolve this.
+    __version__ = "0.0.0.dev"

seren_observatory/__main__.py

@@ -0,0 +1,37 @@
+"""Entry point for `python -m seren_observatory`.
+
+Accepts --config / -c to match the SerenMemory convention (Memory leads, the
+rest follow). Host/port come from the resolved config (which itself layers
+defaults < yaml < env). The bearer token is NOT a config concern - it's loaded
+separately from ~/.seren/secrets.json by auth.load_token(). See config.py.
+"""
+from __future__ import annotations
+
+import argparse
+
+import uvicorn
+
+from .app import create_app
+from .config import load_config
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(
+        prog="seren_observatory",
+        description="seren-observatory - per-node management plane.")
+    parser.add_argument(
+        "--config", "-c", default=None,
+        help="Path to seren-observatory.yaml (default: $SEREN_AGENT_CONFIG, then "
+             "~/seren-observatory/seren-observatory.yaml, falling back to built-in "
+             "defaults of 0.0.0.0:7777).")
+    args = parser.parse_args()
+
+    cfg = load_config(args.config)
+    app = create_app(cfg)
+
+    print(f"[seren-observatory] listening on {cfg.host}:{cfg.port}")
+    uvicorn.run(app, host=cfg.host, port=cfg.port, log_level="info")
+
+
+if __name__ == "__main__":
+    main()

seren_observatory/_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.0.0.dev0'
+__version_tuple__ = version_tuple = (0, 0, 0, 'dev0')
+
+__commit_id__ = commit_id = None

seren_observatory/app.py

@@ -0,0 +1,172 @@
+"""
+seren-observatory - main FastAPI app.
+
+Run with:
+    seren-observatory                          # via the installed console script
+    python -m seren_observatory                # config-aware entry (--config/-c)
+    python -m seren_observatory.app            # directly from the source tree
+    uvicorn seren_observatory.app:app          # ASGI server pointing at module app
+
+or via systemd / a launcher. Listens on 0.0.0.0:7777 by default.
+
+Config: host/port resolve via config.load_config() (defaults < yaml's server:
+block < env vars). The bearer token is loaded SEPARATELY from
+~/.seren/secrets.json by auth.load_token() - it's a safety interlock, not a
+config field. See config.py for why.
+"""
+from __future__ import annotations
+
+import os
+
+from pathlib import Path
+
+from fastapi import FastAPI
+from fastapi.responses import HTMLResponse
+
+from . import __version__, manifests
+from .auth import BearerAuthMiddleware, load_token
+from .config import ObservatoryConfig, load_config
+from .request_log import RequestLoggingMiddleware
+from .service_routes import register_all_services
+from .system_routes import router as system_router
+
+from seren_meninges import get_version
+from seren_meninges.viewer import render_from_dir
+
+# Version via the shared SerenMeninges helper: the installed wheel's
+# setuptools-scm metadata, falling back to the package __version__ for an
+# editable/dev checkout where dist metadata may be absent. get_version never
+# raises - the same one-liner the rest of the family uses, replacing the old
+# hand-rolled importlib.metadata block that drifted from the others.
+APP_VERSION = get_version("seren-observatory", fallback=__version__)
+
+
+def create_app(cfg: ObservatoryConfig | None = None) -> FastAPI:
+    # cfg is accepted so the config-aware entry points (python -m seren_observatory)
+    # can pass a resolved config. When called with no arg (e.g. the
+    # module-level `app` below, or `uvicorn seren_observatory.app:app`), fall back to
+    # load_config() so behaviour is identical either way. cfg currently carries
+    # host/port; those are consumed by the caller that runs uvicorn, so the app
+    # body doesn't need them - but we resolve it anyway so a future need (e.g.
+    # surfacing the bind in the root page) has it on hand without another load.
+    cfg = cfg or load_config()
+
+    app = FastAPI(
+        title="seren-observatory",
+        version=APP_VERSION,
+        description="Per-Jetson management plane. Manifest-driven service "
+                    "lifecycle, status, and orchestration. Bearer token auth "
+                    "on everything except /api/v1/system/{ping,version}.",
+    )
+
+    # Request logging - wraps every request, captures timing + status +
+    # 500 tracebacks. Logs go to BOTH stderr (journalctl) AND a rotating
+    # file at ~/seren-logs/observatory-requests.log (no sudo needed to read).
+    #
+    # MUST be added BEFORE auth so we log auth-rejected requests too -
+    # that's actually one of the most useful debug signals ("dashboard
+    # is failing - is the bearer token wrong, or is the route 500ing?")
+    #
+    # Starlette/FastAPI middleware order: LIFO at request time. So adding
+    # RequestLoggingMiddleware FIRST means it runs LAST on the way in
+    # (closest to the route), and FIRST on the way out - wrapping the
+    # entire chain. Adding auth SECOND means auth runs BEFORE logging on
+    # request, which is wrong. We want logging OUTERMOST.
+    #
+    # Correct stack (request flow top→bottom):
+    #     RequestLoggingMiddleware  (logs everything, including 401s)
+    #       BearerAuthMiddleware    (rejects unauthed, logging sees the rejection)
+    #         <route handler>
+    #
+    # FastAPI add_middleware adds in REVERSE order at runtime, so we add
+    # auth FIRST (will run inner) and logging SECOND (will run outer).
+    token = load_token()
+    app.add_middleware(BearerAuthMiddleware, expected_token=token)
+    app.add_middleware(RequestLoggingMiddleware)
+
+    # Root info page - no service data, just links + auth status indicator
+    @app.get("/", response_class=HTMLResponse)
+    async def root() -> str:
+        node = manifests.load_node()
+        host = (node or {}).get("hostname", "unknown")
+        auth_state = "configured" if token else "DISABLED (no token in ~/.seren/secrets.json)"
+        return f"""<!doctype html>
+<html><head><title>seren-observatory - {host}</title></head>
+<body style="font-family: system-ui; max-width: 720px; margin: 2rem auto; padding: 0 1rem;">
+<h1>seren-observatory</h1>
+<p>Per-Jetson management plane for the Seren cluster.</p>
+<dl>
+  <dt>Hostname:</dt> <dd>{host}</dd>
+  <dt>Observatory version:</dt> <dd>{APP_VERSION}</dd>
+  <dt>Auth:</dt> <dd>{auth_state}</dd>
+</dl>
+<h2>Endpoints</h2>
+<ul>
+  <li><a href="/docs">/docs</a> - interactive API docs (Swagger)</li>
+  <li><a href="/api/v1/system/ping">/api/v1/system/ping</a> - public liveness</li>
+  <li><a href="/api/v1/system/version">/api/v1/system/version</a> - public version</li>
+  <li>/api/v1/system/{{node, services, health, reclaim}} - auth required</li>
+  <li>/api/v1/service/{{name}}/{{start, stop, restart, health, status, logs, manifest}} - auth required</li>
+</ul>
+<p>Source of truth: ~/.seren/services/*.json + ~/.seren/node.json</p>
+</body></html>"""
+
+    # The Observatory glance - on the shared SerenMeninges baseplate.
+    @app.get("/viewer", response_class=HTMLResponse)
+    async def viewer() -> str:
+        # Node vitals, thermals, health rollup, and the service roster with
+        # lifecycle controls. PUBLIC route (the HTML shell needs no auth - see
+        # auth.PUBLIC_PATHS); its /api/v1/* fetches carry the token from the
+        # shell's key modal. With no token provisioned the read-only glance
+        # still works (safe GETs stay open); the action buttons fail closed
+        # (503) until ~/.seren/secrets.json exists - the deliberate interlock,
+        # surfaced in the UI instead of hidden.
+        return render_from_dir(
+            Path(__file__).resolve().parent / "viewer" / "ui",
+            title="seren-observatory",
+            brand="Seren<b>Observatory</b>",
+            subtitle=f"v{APP_VERSION} · per-node watch plane",
+            accent="#6eff70",
+        )
+
+    # System routes (ping, version, node, services, health, reclaim)
+    app.include_router(system_router)
+
+    # Per-service routes - one router per installed service
+    mounted = register_all_services(app)
+    print(f"[seren-observatory] mounted services: {mounted}")
+
+    return app
+
+
+# Module-level app for `uvicorn seren_observatory.app:app`
+app = create_app()
+
+
+if __name__ == "__main__":
+    import uvicorn
+
+    # Direct `python -m seren_observatory.app` path. Resolve config the same way the
+    # console script does so host/port behave identically. (`python -m
+    # seren_observatory` -> __main__.py is the preferred, --config-aware entry.)
+    _cfg = load_config()
+    uvicorn.run(app, host=_cfg.host, port=_cfg.port, log_level="info")
+
+
+def main() -> None:
+    """Console-script entry point: `seren-observatory` (declared in pyproject.toml).
+
+    Resolves config (defaults < yaml < env) and runs uvicorn. The CLI --config
+    flag is handled by __main__.py (`python -m seren_observatory`); the bare
+    console-script reads $SEREN_AGENT_CONFIG / the conventional path / defaults.
+    """
+    import uvicorn
+
+    cfg = load_config()
+    uvicorn.run(
+        "seren_observatory.app:app",
+        host=cfg.host,
+        port=cfg.port,
+        log_level="info",
+        reload=False,
+    )

seren_observatory/auth.py

@@ -0,0 +1,134 @@
+"""
+Bearer-token auth middleware.
+
+Token lives at ~/.seren/secrets.json with {"observatory_token": "..."}, chmod 600.
+Generated by `seren-secrets.sh` which is invoked by foundation Phase 1
+(or manually if missing).
+
+Skipped paths:
+    /                              - root info page (links only, no service data)
+    /api/v1/system/ping            - liveness probe
+    /api/v1/system/version         - observatory version (no sensitive info)
+
+Everything else requires `Authorization: Bearer <token>`.
+
+When NO token is configured (fresh install before seren-secrets.sh runs),
+the observatory stays reachable for safe, read-only requests (GET/HEAD/OPTIONS) so
+monitoring and bootstrap work - but it FAILS CLOSED on any state-changing
+method (POST/PUT/PATCH/DELETE). This plane can restart services and trigger a
+sudoers-backed reboot; an unprovisioned observatory on 0.0.0.0 must never be an open
+remote-reboot button. Provision the token to unlock mutating endpoints.
+
+Threat model: this is a Jetson on your home LAN. The token protects against
+casual LAN-mate snooping and prevents drive-by RCE if you ever expose the
+observatory port outside your trusted network. It is NOT designed for multi-user
+or untrusted-attacker scenarios. Use a VPN or firewall if those apply.
+"""
+from __future__ import annotations
+
+import hmac
+import json
+import os
+from pathlib import Path
+
+from fastapi import Request, Response
+from fastapi.responses import JSONResponse
+from starlette.middleware.base import BaseHTTPMiddleware
+from starlette.types import ASGIApp
+
+SECRETS_PATH = Path(os.path.expanduser("~")) / ".seren" / "secrets.json"
+
+# HTTP methods that don't change state. When no token is configured these
+# stay open (read-only introspection for monitoring/bootstrap); everything
+# else is refused until a token exists.
+_SAFE_METHODS = frozenset({"GET", "HEAD", "OPTIONS"})
+
+# Paths that bypass auth. Keep this list MINIMAL - every entry here is an
+# information disclosure or attack-surface concern.
+PUBLIC_PATHS = frozenset({
+    "/",
+    "/viewer",                      # the glance HTML shell - public like /, but
+                                    # its /api/v1/* fetches still carry the token,
+                                    # and mutations still fail closed without one.
+    "/api/v1/system/ping",
+    "/api/v1/system/version",
+})
+
+
+def load_token() -> str | None:
+    """Load the observatory token from ~/.seren/secrets.json, or None if missing.
+
+    None means "auth is disabled" - the observatory will accept all requests. This
+    is meant as a fallback for fresh installs before seren-secrets.sh runs;
+    in production all installs should have a token.
+    """
+    if not SECRETS_PATH.is_file():
+        return None
+    try:
+        with open(SECRETS_PATH) as f:
+            data = json.load(f)
+        token = data.get("observatory_token")
+        if isinstance(token, str) and token:
+            return token
+    except (json.JSONDecodeError, OSError):
+        pass
+    return None
+
+
+class BearerAuthMiddleware(BaseHTTPMiddleware):
+    """ASGI middleware that requires `Authorization: Bearer <token>` on
+    every request EXCEPT those listed in PUBLIC_PATHS."""
+
+    def __init__(self, app: ASGIApp, *, expected_token: str | None) -> None:
+        super().__init__(app)
+        self._expected = expected_token
+
+    async def dispatch(self, request: Request, call_next) -> Response:
+        path = request.url.path
+
+        # If no token configured, stay reachable for safe reads but refuse
+        # anything that changes state. The fresh-install convenience must not
+        # extend to remote service restarts or a sudoers-backed reboot.
+        if self._expected is None:
+            if request.method not in _SAFE_METHODS:
+                return JSONResponse(
+                    {"error": "unauthorized",
+                     "detail": "no observatory token configured; service-management "
+                               "endpoints are disabled until ~/.seren/secrets.json "
+                               "exists (run seren-secrets.sh)"},
+                    status_code=503,
+                )
+            response = await call_next(request)
+            response.headers["X-Seren-Auth"] = "disabled-no-token-configured"
+            return response
+
+        if path in PUBLIC_PATHS:
+            return await call_next(request)
+
+        auth_header = request.headers.get("authorization", "")
+        if not auth_header.startswith("Bearer "):
+            return JSONResponse(
+                {"error": "unauthorized", "detail": "missing bearer token"},
+                status_code=401,
+            )
+
+        provided = auth_header[len("Bearer "):].strip()
+        # Constant-time compare to avoid timing leaks on token prefix
+        if not _constant_time_eq(provided, self._expected):
+            return JSONResponse(
+                {"error": "unauthorized", "detail": "invalid token"},
+                status_code=401,
+            )
+
+        return await call_next(request)
+
+
+def _constant_time_eq(a: str, b: str) -> bool:
+    """Constant-time comparison via the stdlib's audited hmac.compare_digest.
+
+    Encodes to bytes so non-ASCII input can't raise (compare_digest rejects
+    non-ASCII str). Different-length inputs return False without raising, so
+    this is a drop-in for the previous hand-rolled version - and it means we
+    don't pull in the `cryptography` package just to compare two tokens.
+    """
+    return hmac.compare_digest(a.encode("utf-8"), b.encode("utf-8"))

seren_observatory/config.py

@@ -0,0 +1,153 @@
+"""Config for seren-observatory.
+
+Follows the SerenMemory convention (Memory leads, the rest follow) so a buddy
+who set up one service already knows how to set up this one:
+
+    * network settings live under a ``server:`` block (host/port)
+    * config resolves: --config  ->  $SEREN_AGENT_CONFIG  ->
+      ~/seren-observatory/seren-observatory.yaml  ->  built-in defaults
+    * the file is named seren-observatory.yaml
+
+DELIBERATE EXCEPTION - the bearer token is NOT here. Unlike SerenMemory, the
+observatory's token is a SAFETY INTERLOCK, not a config knob: this plane can restart
+services and trigger a sudoers-backed reboot, so the token lives in
+~/.seren/secrets.json (chmod 600, written by seren-secrets.sh) and is loaded
+by auth.load_token(). The observatory fails CLOSED on mutating methods when no token
+exists. Putting the token in a yaml field would add a second, lower-security
+path (yaml may be 644, may be committed) next to the deliberate secrets.json
+one - a security regression dressed as consistency. Follow-the-leader on
+STRUCTURE (--config, server: block, resolution order); NOT on collapsing auth
+into config. (Same spirit as Margin keeping 127.0.0.1 instead of inheriting
+Memory's 0.0.0.0.)
+
+Precedence (highest wins):
+    1. Env vars  (AGENT_HOST/AGENT_PORT, and the SEREN_AGENT_* aliases)
+    2. YAML file (operator's standing config)
+    3. Defaults  (0.0.0.0:7777 - the Seren cluster convention)
+
+Lenient parse (Postel-as-kindness): missing file or malformed YAML -> log and
+fall back to defaults; a bad single value -> that key falls back, others apply.
+"""
+from __future__ import annotations
+
+import os
+from pathlib import Path
+from typing import Any, Optional
+
+from pydantic import BaseModel
+
+try:
+    import yaml  # type: ignore[import-untyped]
+    _HAS_YAML = True
+except ImportError:  # pragma: no cover - pyyaml is a hard dep, but be lenient
+    _HAS_YAML = False
+
+
+class ObservatoryConfig(BaseModel):
+    """seren-observatory network config. Defaults match the cluster convention:
+    bind all interfaces (trusted LAN) on 7777.
+
+    NOTE: no token field here, on purpose - see module docstring.
+    """
+
+    # Bind all interfaces by default - the observatory is a cluster plane meant to be
+    # reached from the NUC/RuntimeHost across the trusted LAN. (Contrast Margin,
+    # which is private and binds 127.0.0.1.) The auth interlock, not the bind
+    # address, is what protects the mutating endpoints.
+    host: str = "0.0.0.0"
+    port: int = 7777
+
+
+_DEFAULT_CONFIG_PATH = Path.home() / "seren-observatory" / "seren-observatory.yaml"
+
+
+def _resolve_config_path(explicit_path: Optional[str] = None) -> Optional[Path]:
+    """--config -> $SEREN_AGENT_CONFIG -> ~/seren-observatory/seren-observatory.yaml -> None."""
+    if explicit_path:
+        return Path(explicit_path).expanduser()
+    env = os.getenv("SEREN_AGENT_CONFIG")
+    if env:
+        return Path(env).expanduser()
+    if _DEFAULT_CONFIG_PATH.exists():
+        return _DEFAULT_CONFIG_PATH
+    return None
+
+
+def _load_yaml_lenient(path: Path) -> dict[str, Any]:
+    if not path.exists():
+        return {}
+    if not _HAS_YAML:
+        print(f"[seren-observatory] config: pyyaml not installed; ignoring {path}")
+        return {}
+    try:
+        with open(path, "r", encoding="utf-8") as f:
+            data = yaml.safe_load(f)
+    except Exception as e:
+        print(f"[seren-observatory] config: failed to parse {path}: {e} (using defaults)")
+        return {}
+    if data is None:
+        return {}
+    if not isinstance(data, dict):
+        print(f"[seren-observatory] config: {path} top-level must be a mapping; got "
+              f"{type(data).__name__} (using defaults)")
+        return {}
+    return data
+
+
+def _apply_server_overrides(cfg: ObservatoryConfig, server: dict[str, Any], *, source: str) -> None:
+    """Apply per-key overrides; each key try/except'd so one bad value doesn't
+    sink the others. Only host/port are known - anything else is ignored with
+    a note (notably 'bearer_token', which is intentionally NOT honored here)."""
+    known = {"host", "port"}
+    for key, raw in server.items():
+        if key == "bearer_token":
+            # Loud, specific note: the token is not a config field by design.
+            print("[seren-observatory] config: 'bearer_token' in the yaml is ignored "
+                  "by design - the observatory token lives in ~/.seren/secrets.json "
+                  "(run seren-secrets.sh). See config.py for why.")
+            continue
+        if key not in known:
+            print(f"[seren-observatory] config: ignoring unknown server key '{key}' from {source}")
+            continue
+        try:
+            current = cfg.model_dump()
+            current[key] = raw
+            cfg.__dict__.update(ObservatoryConfig.model_validate(current).__dict__)
+        except Exception as e:
+            print(f"[seren-observatory] config: ignored bad value for '{key}' from {source}: {e}")
+
+
+def load_config(path: Optional[str] = None) -> ObservatoryConfig:
+    """Defaults -> YAML (server: block) -> env vars. Never raises on bad input.
+
+    ``path`` is the --config flag value (highest-priority config location).
+    """
+    cfg = ObservatoryConfig()
+
+    # Layer 2: YAML
+    yaml_path = _resolve_config_path(path)
+    if yaml_path is not None:
+        data = _load_yaml_lenient(yaml_path)
+        server = data.get("server")
+        if isinstance(server, dict):
+            _apply_server_overrides(cfg, server, source=str(yaml_path))
+        elif server is not None:
+            print(f"[seren-observatory] config: 'server' in {yaml_path} must be a mapping; ignoring")
+
+    # Layer 3: env vars (highest precedence). Honor BOTH the original
+    # AGENT_HOST/AGENT_PORT (what app.py historically read, and what the old
+    # launcher exported) AND the SEREN_AGENT_* aliases the yaml sample
+    # documents. The SEREN_AGENT_* form wins if both are somehow set, since
+    # it's the documented, namespaced one.
+    env_overrides: dict[str, Any] = {}
+    for env_key, attr in (("AGENT_HOST", "host"),
+                          ("AGENT_PORT", "port"),
+                          ("SEREN_AGENT_HOST", "host"),
+                          ("SEREN_AGENT_PORT", "port")):
+        v = os.getenv(env_key)
+        if v is not None:
+            env_overrides[attr] = v
+    if env_overrides:
+        _apply_server_overrides(cfg, env_overrides, source="environment")
+
+    return cfg