epidash 0.2.0__py3-none-any.whl

epidash/__init__.py

@@ -0,0 +1,3 @@
+"""EpiDash — light MCP-controlled dashboard service."""
+
+__version__ = "0.1.0"

epidash/api/__init__.py

@@ -0,0 +1 @@
+"""Public REST API: published dashboards + the viewer tweak flow."""

epidash/api/routes_public.py

@@ -0,0 +1,284 @@
+"""Public API routes.
+
+- GET /api/dashboards              — published dashboards (listing only)
+- GET /api/dashboards/{slug}       — one published dashboard with charts
+- POST /api/dashboards/{slug}/like — like a published dashboard
+- DELETE /api/dashboards/{slug}/like — undo a like
+- GET  /api/dashboards/{slug}/export — download the dashboard as JSON
+- POST /api/dashboards/{slug}/tweak — forward a viewer request to EpidBot
+- POST /api/dashboards/{slug}/ask  — ask EpidBot a question about a dashboard
+- GET  /api/tweaks/{tweak_id}      — poll a tweak's status
+
+(/healthz lives on the root app, see main.py.)
+
+Draft dashboards are never exposed here; control goes through MCP only.
+"""
+
+import asyncio
+import datetime as _dt
+from typing import Optional
+
+from fastapi import APIRouter, HTTPException, Request
+from fastapi.responses import JSONResponse
+from pydantic import BaseModel, Field
+
+from epidash.config import get_settings
+from epidash.epidbot_client import (
+    EpidBotClient,
+    EpidBotError,
+    build_question_message,
+    build_tweak_message,
+)
+from epidash.logging import get_logger
+from epidash.store import Store
+
+logger = get_logger(__name__)
+
+router = APIRouter(prefix="/api", include_in_schema=True)
+
+_store: Store | None = None
+_epidbot: EpidBotClient | None = None
+
+# Sliding-window rate limiter: slug -> list of submission timestamps.
+_tweak_windows: dict[str, list[float]] = {}
+_ask_windows: dict[str, list[float]] = {}
+_like_windows: dict[str, list[float]] = {}
+
+# Like actions per dashboard per hour (likes + unlikes combined).
+LIKE_RATE_LIMIT_PER_HOUR = 60
+
+
+def set_store(store: Store) -> None:
+    global _store, _epidbot
+    _store = store
+    _epidbot = EpidBotClient()
+
+
+def get_store() -> Store:
+    if _store is None:
+        raise RuntimeError("Store not initialised; app startup did not run")
+    return _store
+
+
+class TweakRequest(BaseModel):
+    """Viewer request to change a dashboard."""
+
+    request: str = Field(min_length=3, max_length=2000)
+
+
+def _rate_limited(slug: str, windows: dict[str, list[float]], limit: int) -> bool:
+    """True when this slug exceeded its hourly budget for `windows`."""
+    now = _dt.datetime.now(_dt.timezone.utc).timestamp()
+    window = [t for t in windows.get(slug, []) if now - t < 3600]
+    if len(window) >= limit:
+        windows[slug] = window
+        return True
+    window.append(now)
+    windows[slug] = window
+    return False
+
+
+def _tweak_rate_limited(slug: str) -> bool:
+    return _rate_limited(slug, _tweak_windows, get_settings().tweak_rate_limit_per_hour)
+
+
+def _get_published(store: Store, slug: str) -> dict:
+    """Published dashboard by slug or 404 (drafts are MCP-only)."""
+    dashboard = store.get_dashboard_by_slug(slug)
+    if dashboard is None or dashboard["status"] != "published":
+        raise HTTPException(status_code=404, detail="Dashboard not found")
+    return dashboard
+
+
+def _public_dashboard(dashboard: dict) -> dict:
+    """Shape of a dashboard exposed publicly (no internal status detail)."""
+    return {
+        "slug": dashboard["slug"],
+        "title": dashboard["title"],
+        "description": dashboard["description"],
+        "created_by": dashboard["created_by"],
+        "layout": dashboard["layout"],
+        "updated_at": dashboard["updated_at"],
+        "published_at": dashboard["published_at"],
+    }
+
+
+@router.get("/dashboards")
+async def list_published_dashboards() -> list[dict]:
+    store = get_store()
+    return [
+        {
+            "slug": d["slug"],
+            "title": d["title"],
+            "description": d["description"],
+            "created_by": d["created_by"],
+            "likes": store.get_likes(d["id"]),
+            "updated_at": d["updated_at"],
+        }
+        for d in store.list_dashboards(include_unpublished=False)
+    ]
+
+
+@router.get("/dashboards/{slug}")
+async def get_published_dashboard(slug: str) -> dict:
+    store = get_store()
+    dashboard = _get_published(store, slug)
+    try:
+        store.record_view(dashboard["id"])
+    except Exception as e:  # noqa: BLE001 — view counting is best effort
+        logger.debug("View count failed for %s: %s", slug, e)
+    return {
+        **_public_dashboard(dashboard),
+        "likes": store.get_likes(dashboard["id"]),
+        "charts": store.list_charts(dashboard["id"]),
+        "tweaks_enabled": get_settings().epidbot_configured,
+    }
+
+
+@router.post("/dashboards/{slug}/like")
+async def like_dashboard(slug: str) -> dict:
+    store = get_store()
+    dashboard = _get_published(store, slug)
+    if _rate_limited(slug, _like_windows, LIKE_RATE_LIMIT_PER_HOUR):
+        raise HTTPException(status_code=429, detail="Too many like actions; try again later")
+    return {"slug": slug, "likes": store.record_like(dashboard["id"])}
+
+
+@router.delete("/dashboards/{slug}/like")
+async def unlike_dashboard(slug: str) -> dict:
+    store = get_store()
+    dashboard = _get_published(store, slug)
+    if _rate_limited(slug, _like_windows, LIKE_RATE_LIMIT_PER_HOUR):
+        raise HTTPException(status_code=429, detail="Too many like actions; try again later")
+    return {"slug": slug, "likes": store.remove_like(dashboard["id"])}
+
+
+@router.get("/dashboards/{slug}/export")
+async def export_dashboard(slug: str) -> JSONResponse:
+    """Download the full dashboard definition (re-importable via MCP)."""
+    store = get_store()
+    dashboard = _get_published(store, slug)
+    payload = {
+        "app": "epidash",
+        "slug": dashboard["slug"],
+        "title": dashboard["title"],
+        "description": dashboard["description"],
+        "created_by": dashboard["created_by"],
+        "layout": dashboard["layout"],
+        "published_at": dashboard["published_at"],
+        "updated_at": dashboard["updated_at"],
+        "likes": store.get_likes(dashboard["id"]),
+        "charts": [
+            {
+                "kind": c["kind"],
+                "title": c["title"],
+                "data": c["data"],
+                "spec": c["spec"],
+                "position": c["position"],
+            }
+            for c in store.list_charts(dashboard["id"])
+        ],
+    }
+    return JSONResponse(
+        payload,
+        headers={
+            "Content-Disposition": f'attachment; filename="{slug}.json"',
+        },
+    )
+
+
+class TweakSubmitted(BaseModel):
+    tweak_id: str
+    status: str = "pending"
+
+
+@router.post("/dashboards/{slug}/tweak", status_code=202)
+async def submit_tweak(slug: str, body: TweakRequest, request: Request) -> TweakSubmitted:
+    store = get_store()
+    dashboard = _get_published(store, slug)
+    settings = get_settings()
+    if not settings.epidbot_configured:
+        raise HTTPException(
+            status_code=503,
+            detail="EpidBot integration is not configured on this server",
+        )
+    if _tweak_rate_limited(slug):
+        raise HTTPException(
+            status_code=429, detail="Too many tweak requests; try again later"
+        )
+
+    tweak = store.create_tweak(dashboard["id"], body.request, kind="tweak")
+    asyncio.create_task(_process_tweak(tweak["id"], dashboard, body.request))
+    return TweakSubmitted(tweak_id=tweak["id"], status=tweak["status"])
+
+
+@router.post("/dashboards/{slug}/ask", status_code=202)
+async def ask_about_dashboard(slug: str, body: TweakRequest, request: Request) -> TweakSubmitted:
+    """Viewer question about a published dashboard — an EpidBot chat turn
+    that answers from the dashboard data without modifying it."""
+    store = get_store()
+    dashboard = _get_published(store, slug)
+    settings = get_settings()
+    if not settings.epidbot_configured:
+        raise HTTPException(
+            status_code=503,
+            detail="EpidBot integration is not configured on this server",
+        )
+    if _rate_limited(slug, _ask_windows, settings.ask_rate_limit_per_hour):
+        raise HTTPException(
+            status_code=429, detail="Too many questions; try again later"
+        )
+
+    tweak = store.create_tweak(dashboard["id"], body.request, kind="question")
+    asyncio.create_task(_process_question(tweak["id"], dashboard, body.request))
+    return TweakSubmitted(tweak_id=tweak["id"], status=tweak["status"])
+
+
+async def _process_epidbot_turn(tweak_id: str, message: str, action: str) -> None:
+    """Background task: run one EpidBot chat turn and record the outcome."""
+    store = get_store()
+    assert _epidbot is not None
+    store.update_tweak(tweak_id, status="processing")
+    try:
+        result = await _epidbot.run_tweak(message)
+        content = result.get("content") or ""
+        store.update_tweak(tweak_id, status="completed", response=content)
+    except EpidBotError as e:
+        logger.warning("%s %s failed: %s", action, tweak_id, e)
+        store.update_tweak(tweak_id, status="failed", error=str(e))
+    except Exception as e:  # noqa: BLE001 — never crash the background task
+        logger.error("%s %s crashed: %s", action, tweak_id, e)
+        store.update_tweak(tweak_id, status="failed", error=f"internal error: {e}")
+
+
+async def _process_tweak(tweak_id: str, dashboard: dict, request_text: str) -> None:
+    """Background task: send the tweak turn to EpidBot and record the result."""
+    message = build_tweak_message(
+        dashboard, get_store().list_charts(dashboard["id"]), request_text
+    )
+    await _process_epidbot_turn(tweak_id, message, "Tweak")
+
+
+async def _process_question(tweak_id: str, dashboard: dict, question: str) -> None:
+    """Background task: send the question turn to EpidBot (read-only)."""
+    message = build_question_message(
+        dashboard, get_store().list_charts(dashboard["id"]), question
+    )
+    await _process_epidbot_turn(tweak_id, message, "Question")
+
+
+@router.get("/tweaks/{tweak_id}")
+async def get_tweak(tweak_id: str) -> dict:
+    tweak = get_store().get_tweak(tweak_id)
+    if tweak is None:
+        raise HTTPException(status_code=404, detail="Tweak not found")
+    return {
+        "tweak_id": tweak["id"],
+        "dashboard_id": tweak["dashboard_id"],
+        "kind": tweak.get("kind", "tweak"),
+        "status": tweak["status"],
+        "response": tweak["response"],
+        "error": tweak["error"],
+        "created_at": tweak["created_at"],
+        "updated_at": tweak["updated_at"],
+    }

epidash/cli.py

@@ -0,0 +1,76 @@
+"""Control-key management CLI.
+
+Usage (inside the container / on the server):
+
+    python -m epidash.cli add-key "epidbot"
+    python -m epidash.cli list-keys
+    python -m epidash.cli revoke 2
+"""
+
+import argparse
+import secrets
+import sys
+
+from epidash.config import get_settings
+from epidash.logging import get_logger
+from epidash.store import Store
+
+logger = get_logger(__name__)
+
+
+def _store() -> Store:
+    return Store(get_settings().db_path)
+
+
+def _generate_key() -> str:
+    return "dk_" + secrets.token_urlsafe(24)
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(prog="epidash.cli", description=__doc__)
+    sub = parser.add_subparsers(dest="command", required=True)
+
+    p_add = sub.add_parser("add-key", help="create a new control key (raw key shown once)")
+    p_add.add_argument("name", help="human-readable name, e.g. 'epidbot'")
+
+    sub.add_parser("list-keys", help="list control keys (hashes only)")
+
+    p_revoke = sub.add_parser("revoke", help="revoke a key by id")
+    p_revoke.add_argument("key_id", type=int)
+
+    args = parser.parse_args(argv)
+    store = _store()
+
+    if args.command == "add-key":
+        raw = _generate_key()
+        meta = store.add_key(raw, name=args.name)
+        print(f"Key created (id={meta['id']}, name={meta['name']!s},"
+              f" prefix={meta['key_prefix']}...).")
+        print("Store it now — it is shown only once:")
+        print(raw)
+        return 0
+
+    if args.command == "list-keys":
+        keys = store.list_keys()
+        if not keys:
+            print("No control keys.")
+            return 0
+        for k in keys:
+            status = "revoked" if k["revoked"] else "active"
+            last = k["last_used_at"] or "never"
+            print(f"id={k['id']}  {k['key_prefix']}...  {status:<8} "
+                  f"name={k['name']}  last_used={last}")
+        return 0
+
+    if args.command == "revoke":
+        if store.revoke_key(args.key_id):
+            print(f"Key {args.key_id} revoked.")
+            return 0
+        print(f"Key {args.key_id} not found.", file=sys.stderr)
+        return 1
+
+    return 2
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

epidash/config.py

@@ -0,0 +1,113 @@
+"""Environment-based configuration.
+
+Every setting has a sane local default so the service runs out of the box
+(``uv run uvicorn epidash.main:app``); production values are injected via
+environment variables (see docker-compose.yml / the Ansible role).
+"""
+
+import os
+from dataclasses import dataclass, field
+
+
+def _env_str(name: str, default: str = "") -> str:
+    value = os.environ.get(name)
+    return value.strip() if value is not None else default
+
+
+def _env_bool(name: str, default: bool) -> bool:
+    raw = os.environ.get(name)
+    if raw is None:
+        return default
+    return raw.strip().lower() in ("1", "true", "yes", "on")
+
+
+def _env_int(name: str, default: int) -> int:
+    raw = os.environ.get(name)
+    if raw is None or not raw.strip():
+        return default
+    try:
+        return int(raw.strip())
+    except ValueError:
+        return default
+
+
+@dataclass
+class Settings:
+    """Runtime configuration, read once from the environment."""
+
+    #: SQLite database file (WAL mode).
+    db_path: str = field(default_factory=lambda: _env_str("EPIDASH_DB_PATH", "data/epidash.db"))
+
+    #: Public base URL, used to build share links (published dashboard URLs).
+    base_url: str = field(default_factory=lambda: _env_str("EPIDASH_BASE_URL", "http://localhost:8000"))
+
+    #: Path the MCP streamable-HTTP endpoint is served under.
+    mcp_path: str = field(default_factory=lambda: _env_str("EPIDASH_MCP_PATH", "/mcp"))
+
+    #: Server name advertised during the MCP handshake.
+    server_name: str = field(default_factory=lambda: _env_str("EPIDASH_SERVER_NAME", "epidash"))
+
+    #: Hosts allowed by the MCP DNS-rebinding protection (Host header values).
+    #: The SDK compares the full Host header (port included) and accepts
+    #: ``host:*`` wildcard-port patterns.
+    allowed_hosts: list[str] = field(
+        default_factory=lambda: [
+            h.strip()
+            for h in _env_str("EPIDASH_ALLOWED_HOSTS", "localhost:*,127.0.0.1:*").split(",")
+            if h.strip()
+        ]
+    )
+
+    #: Keep DNS-rebinding protection on in production; tests may disable it.
+    dns_rebinding_protection: bool = field(
+        default_factory=lambda: _env_bool("EPIDASH_DNS_REBINDING_PROTECTION", True)
+    )
+
+    #: Optional pre-shared ``dk_`` control key (seeded at startup, used by
+    #: infra automation so EpidBot and epidash get the same secret).
+    bootstrap_key: str = field(default_factory=lambda: _env_str("EPIDASH_BOOTSTRAP_KEY"))
+
+    #: EpidBot base URL (e.g. https://api.epidbot.kwar-ai.com.br) enabling the
+    #: tweak flow. Empty disables it.
+    epidbot_base_url: str = field(default_factory=lambda: _env_str("EPIDBOT_BASE_URL"))
+
+    #: Shared secret sent as ``X-Internal-Request`` (EpidBot's
+    #: INTERNAL_API_SECRET) or a regular ``ek_`` API key sent as Bearer.
+    epidbot_internal_secret: str = field(
+        default_factory=lambda: _env_str("EPIDBOT_INTERNAL_SECRET")
+    )
+
+    #: Tweak submissions allowed per dashboard slug per hour (LLM cost guard).
+    tweak_rate_limit_per_hour: int = field(
+        default_factory=lambda: _env_int("EPIDASH_TWEAK_RATE_LIMIT_PER_HOUR", 20)
+    )
+
+    #: Viewer questions allowed per dashboard slug per hour (LLM cost guard).
+    ask_rate_limit_per_hour: int = field(
+        default_factory=lambda: _env_int("EPIDASH_ASK_RATE_LIMIT_PER_HOUR", 30)
+    )
+
+    #: How long to wait for EpidBot to finish a tweak (seconds).
+    tweak_timeout_s: int = field(default_factory=lambda: _env_int("EPIDASH_TWEAK_TIMEOUT_S", 300))
+
+    @property
+    def epidbot_configured(self) -> bool:
+        """True when the tweak flow can reach EpidBot."""
+        return bool(self.epidbot_base_url) and bool(self.epidbot_internal_secret)
+
+
+_settings: Settings | None = None
+
+
+def get_settings() -> Settings:
+    """Process-wide settings singleton (tests use ``set_settings``)."""
+    global _settings
+    if _settings is None:
+        _settings = Settings()
+    return _settings
+
+
+def set_settings(settings: Settings | None) -> None:
+    """Replace the settings singleton (mainly for tests)."""
+    global _settings
+    _settings = settings

epidash/epidbot_client.py

@@ -0,0 +1,152 @@
+"""Client for EpidBot's chat API — powers the viewer "tweak" flow.
+
+Authentication uses the internal-service pattern already established by
+EpidBot's file-upload endpoint: the shared ``INTERNAL_API_SECRET`` sent as
+an ``X-Internal-Request`` header. An ``ek_`` API key sent as a Bearer
+token is supported as a fallback for local experiments.
+
+Flow: submit the tweak as a chat job (POST /api/v1/chat), then poll
+GET /api/v1/chat/{job_id} until the agent finishes. The agent is expected
+to mutate the dashboard through its EpiDash MCP tools during that turn.
+"""
+
+import asyncio
+from typing import Any, Optional
+
+import httpx
+
+from epidash.config import get_settings
+from epidash.logging import get_logger
+
+logger = get_logger(__name__)
+
+POLL_INTERVAL_S = 2.0
+
+
+class EpidBotError(RuntimeError):
+    """A tweak round-trip against EpidBot failed."""
+
+
+def _compact_charts(charts: list[dict]) -> list[dict]:
+    return [
+        {
+            "id": c["id"],
+            "kind": c["kind"],
+            "title": c["title"],
+            "data": c["data"],
+            "spec": c["spec"],
+            "position": c["position"],
+        }
+        for c in charts
+    ]
+
+
+def build_tweak_message(dashboard: dict, charts: list[dict], request: str) -> str:
+    """Prompt sent to the EpidBot agent for one tweak turn."""
+    compact = _compact_charts(charts)
+    return (
+        f"A viewer of the EpiDash dashboard '{dashboard.get('title', '')}' "
+        f"(dashboard_id={dashboard['id']}, slug={dashboard['slug']}) requests "
+        f"changes to it.\n\n"
+        f"Current charts (JSON):\n{compact}\n\n"
+        f"Viewer request: {request}\n\n"
+        "Use your EpiDash MCP tools to apply the requested changes to this "
+        "dashboard (update_chart / add_chart / remove_chart as needed). Keep "
+        "the existing visual style unless asked otherwise, keep data "
+        "envelopes consistent with each chart kind, and reply with a one or "
+        "two sentence summary of what you changed."
+    )
+
+
+def build_question_message(dashboard: dict, charts: list[dict], question: str) -> str:
+    """Prompt sent to the EpidBot agent when a viewer asks a question.
+
+    Same chat pipeline as tweaks, but the agent must answer from the
+    dashboard data and leave the dashboard untouched.
+    """
+    compact = _compact_charts(charts)
+    return (
+        f"A viewer of the EpiDash dashboard '{dashboard.get('title', '')}' "
+        f"(dashboard_id={dashboard['id']}, slug={dashboard['slug']}) is asking "
+        f"a QUESTION about it.\n\n"
+        f"Current charts (JSON):\n{compact}\n\n"
+        f"Viewer question: {question}\n\n"
+        "Answer the question based on the dashboard's data. This is a "
+        "read-only turn: do NOT use your EpiDash MCP tools to modify the "
+        "dashboard. Reply with a concise, self-contained answer (a short "
+        "paragraph at most); cite the specific numbers or charts you used."
+    )
+
+
+class EpidBotClient:
+    """Submits tweak turns to EpidBot and waits for completion."""
+
+    def __init__(
+        self,
+        base_url: Optional[str] = None,
+        internal_secret: Optional[str] = None,
+        timeout_s: Optional[int] = None,
+    ):
+        settings = get_settings()
+        self.base_url = (base_url or settings.epidbot_base_url).rstrip("/")
+        self.internal_secret = internal_secret or settings.epidbot_internal_secret
+        self.timeout_s = timeout_s or settings.tweak_timeout_s
+
+    def _headers(self) -> dict[str, str]:
+        headers = {"Content-Type": "application/json"}
+        if self.internal_secret.startswith("ek_"):
+            headers["Authorization"] = f"Bearer {self.internal_secret}"
+        else:
+            headers["X-Internal-Request"] = self.internal_secret
+        return headers
+
+    async def _submit(self, client: httpx.AsyncClient, message: str) -> tuple[str, Optional[int]]:
+        response = await client.post(
+            f"{self.base_url}/api/v1/chat",
+            json={"message": message, "locale": "en"},
+            headers=self._headers(),
+            timeout=30,
+        )
+        if response.status_code != 200:
+            raise EpidBotError(
+                f"EpidBot chat submit failed: HTTP {response.status_code}: "
+                f"{response.text[:200]}"
+            )
+        payload = response.json()
+        return payload["job_id"], payload.get("session_id")
+
+    async def _poll(
+        self, client: httpx.AsyncClient, job_id: str
+    ) -> dict[str, Any]:
+        deadline = asyncio.get_event_loop().time() + self.timeout_s
+        while True:
+            response = await client.get(
+                f"{self.base_url}/api/v1/chat/{job_id}",
+                headers=self._headers(),
+                timeout=15,
+            )
+            if response.status_code != 200:
+                raise EpidBotError(
+                    f"EpidBot chat poll failed: HTTP {response.status_code}"
+                )
+            payload = response.json()
+            status = payload.get("status")
+            if status == "completed":
+                return payload
+            if status == "failed":
+                raise EpidBotError(
+                    f"EpidBot chat job failed: {payload.get('error') or 'unknown error'}"
+                )
+            if asyncio.get_event_loop().time() > deadline:
+                raise EpidBotError(
+                    f"EpidBot chat job {job_id} timed out after {self.timeout_s}s"
+                )
+            await asyncio.sleep(POLL_INTERVAL_S)
+
+    async def run_tweak(self, message: str) -> dict[str, Any]:
+        """Submit the tweak turn and wait for the agent to finish."""
+        async with httpx.AsyncClient() as client:
+            job_id, _session_id = await self._submit(client, message)
+            logger.info("EpiDash tweak submitted to EpidBot (job_id=%s)", job_id)
+            result = await self._poll(client, job_id)
+        return result

epidash/logging.py

@@ -0,0 +1,22 @@
+"""Minimal logging setup for EpiDash (keeps epidash self-contained)."""
+
+import logging
+import os
+import sys
+
+_FORMAT = "%(asctime)s %(levelname)s %(name)s: %(message)s"
+
+
+def _level() -> str:
+    return os.environ.get("EPIDASH_LOG_LEVEL", "INFO").upper()
+
+
+def get_logger(name: str) -> logging.Logger:
+    logger = logging.getLogger(name)
+    if not logging.getLogger("epidash").handlers:
+        handler = logging.StreamHandler(sys.stdout)
+        handler.setFormatter(logging.Formatter(_FORMAT))
+        root = logging.getLogger("epidash")
+        root.addHandler(handler)
+        root.setLevel(_level())
+    return logger