epidash 0.2.0__tar.gz

epidash-0.2.0/.github/workflows/ci.yml

@@ -0,0 +1,26 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+        with:
+          python-version: '3.12'
+
+      - name: Sync dependencies
+        run: uv sync --frozen
+
+      - name: Type check
+        run: uv run ty check epidash/
+
+      - name: Run tests
+        run: uv run pytest -v

epidash-0.2.0/.github/workflows/publish.yml

@@ -0,0 +1,55 @@
+name: Publish to PyPI
+
+on:
+  push:
+    tags: ['v*']
+  workflow_dispatch:
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+        with:
+          python-version: '3.12'
+
+      - name: Sync dependencies
+        run: uv sync --frozen
+
+      - name: Type check
+        run: uv run ty check epidash/
+
+      - name: Run tests
+        run: uv run pytest -v
+
+  publish:
+    needs: test
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write # OIDC trusted publishing — no API token secret needed
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+        with:
+          python-version: '3.12'
+
+      - name: Verify tag matches package version
+        run: |
+          VERSION=$(uv run --no-sync python -c "import tomllib; print(tomllib.load(open('pyproject.toml','rb'))['project']['version'])")
+          if [ "v$VERSION" != "$GITHUB_REF_NAME" ]; then
+            echo "::error::Tag $GITHUB_REF_NAME does not match package version v$VERSION"
+            exit 1
+          fi
+
+      - name: Build package
+        run: uv build
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

epidash-0.2.0/.gitignore

@@ -0,0 +1,23 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+.venv/
+venv/
+dist/
+build/
+
+# Local state
+data/
+*.db
+*.db-wal
+*.db-shm
+
+# Tooling
+.pytest_cache/
+.ty/
+.ruff_cache/
+
+# Secrets
+.env
+.env.local

epidash-0.2.0/Dockerfile

@@ -0,0 +1,27 @@
+FROM python:3.12-slim
+
+COPY --from=ghcr.io/astral-sh/uv:latest /uv /uvx /usr/local/bin/
+
+WORKDIR /app
+
+# Install dependencies first (cached layer), then the app code
+COPY pyproject.toml uv.lock README.md ./
+RUN uv sync --frozen --no-dev --no-install-project
+
+COPY epidash ./epidash
+RUN uv sync --frozen --no-dev
+
+ENV PATH="/app/.venv/bin:$PATH" \
+    EPIDASH_DB_PATH=/data/epidash.db
+
+RUN useradd --system --create-home epidash \
+    && mkdir -p /data \
+    && chown -R epidash:epidash /app /data
+USER epidash
+
+EXPOSE 8000
+
+HEALTHCHECK --interval=30s --timeout=5s --start-period=10s --retries=3 \
+    CMD python -c "import urllib.request; urllib.request.urlopen('http://127.0.0.1:8000/healthz', timeout=4)"
+
+CMD ["uvicorn", "epidash.main:app", "--host", "0.0.0.0", "--port", "8000"]

epidash-0.2.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Deeplearn-PeD
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

epidash-0.2.0/PKG-INFO

@@ -0,0 +1,153 @@
+Metadata-Version: 2.5
+Name: epidash
+Version: 0.2.0
+Summary: EpiDash — light MCP-controlled dashboard service: EpidBot publishes and controls dashboards via MCP
+License: MIT
+License-File: LICENSE
+Requires-Python: >=3.12
+Requires-Dist: fastapi>=0.115.0
+Requires-Dist: httpx>=0.28.0
+Requires-Dist: mcp<2,>=1.10
+Requires-Dist: pydantic>=2.9
+Requires-Dist: uvicorn[standard]>=0.32.0
+Provides-Extra: dev
+Requires-Dist: pytest-asyncio>=0.24; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: ty>=0.0.1a5; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# EpiDash
+
+[![CI](https://github.com/Deeplearn-PeD/epidash/actions/workflows/ci.yml/badge.svg)](https://github.com/Deeplearn-PeD/epidash/actions/workflows/ci.yml)
+[![Python 3.12+](https://img.shields.io/badge/python-3.12+-blue.svg)](https://www.python.org/downloads/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+[![Managed with uv](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/uv/main/assets/badge/v1.json)](https://docs.astral.sh/uv/)
+
+A light, MCP-controlled dashboard service. [EpidBot](https://github.com/Deeplearn-PeD/EpiDBot)
+(and any MCP client holding a control key) builds, updates, publishes and
+unpublishes dashboards through an MCP tool surface; anyone with a dashboard
+link views it in a minimal web UI. Viewers can ask EpidBot to tweak a
+dashboard from the browser.
+
+```
+EpidBot agent ──(MCP client, dk_ key)──▶ EpiDash /mcp (FastMCP tools)
+                                            │
+                       SQLite ◀─────────────┤ (dashboards, charts, keys, audit)
+                                            │
+Viewer browser ──(public link)──▶ EpiDash / (vanilla JS + Plotly)
+      │                                 │
+      └── tweak request ──▶ POST /api/dashboards/{slug}/tweak
+                                 │  (X-Internal-Request: shared secret)
+                                 ▼
+                           EpidBot /api/v1/chat ──agent──▶ EpiDash MCP tools
+```
+
+## Quick start
+
+```bash
+uv sync
+uv run uvicorn epidash.main:app --port 8000
+```
+
+Then issue a control key and talk to the MCP endpoint:
+
+```bash
+uv run python -m epidash.cli add-key "local"
+# → dk_...  (shown once)
+```
+
+```bash
+# The MCP endpoint is stateless: one POST per call, no handshake needed.
+curl -s -X POST http://localhost:8000/mcp \
+  -H "X-API-Key: dk_..." -H "Content-Type: application/json" \
+  -H "Accept: application/json, text/event-stream" \
+  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'
+```
+
+In an MCP client (e.g. Claude Desktop, Cursor, EpidBot):
+
+```json
+{
+  "mcpServers": {
+    "epidash": {
+      "url": "http://localhost:8000/mcp",
+      "headers": { "X-API-Key": "dk_..." }
+    }
+  }
+}
+```
+
+## Configuration (environment variables)
+
+| Variable | Default | Purpose |
+|---|---|---|
+| `EPIDASH_DB_PATH` | `data/epidash.db` | SQLite file (WAL) |
+| `EPIDASH_BASE_URL` | `http://localhost:8000` | Public base URL for share links |
+| `EPIDASH_MCP_PATH` | `/mcp` | Mount path of the MCP endpoint |
+| `EPIDASH_ALLOWED_HOSTS` | `localhost,127.0.0.1` | Host header allowlist (DNS-rebinding protection) |
+| `EPIDASH_BOOTSTRAP_KEY` | — | Pre-shared `dk_` key seeded at startup (infra automation) |
+| `EPIDBOT_BASE_URL` | — | EpidBot base URL; enables the tweak flow |
+| `EPIDBOT_INTERNAL_SECRET` | — | Shared secret (EpidBot `INTERNAL_API_SECRET`) or `ek_` API key |
+| `EPIDASH_TWEAK_RATE_LIMIT_PER_HOUR` | `20` | Per-dashboard viewer tweak budget |
+| `EPIDASH_ASK_RATE_LIMIT_PER_HOUR` | `30` | Per-dashboard viewer question budget |
+| `EPIDASH_TWEAK_TIMEOUT_S` | `300` | Max wait for an EpidBot tweak turn |
+
+## MCP tools
+
+Read-only: `list_dashboards`, `get_dashboard`, `get_view_stats`, `get_audit_log`.
+
+Mutations (audited): `create_dashboard`, `update_dashboard`,
+`publish_dashboard` (confirm), `unpublish_dashboard` (confirm),
+`add_chart`, `update_chart`, `remove_chart` (confirm).
+
+### Chart data envelopes
+
+| kind | data |
+|---|---|
+| `line`, `bar`, `pie`, `table` | `{"columns": ["month", "cases"], "rows": [["Jan", 120], ...]}` |
+| `kpi` | `{"value": 1234, "label": "Cases", "unit": "", "delta": "+12%"}` |
+| `choropleth` | `{"values": {"SP": 120, "RJ": 90}, "region_level": "uf", "label": "cases"}` |
+
+`spec` accepts style overrides (`{"color": "#4ade80"}`, `{"y_label": "cases"}`) and
+`position` controls ordering/width (`{"order": 1, "width": "half"}`).
+
+## Viewer tweak flow
+
+A viewer types a request ("show only the Southeast after 2020") into the
+dashboard's chat box. EpiDash forwards it as an EpidBot chat turn with the
+dashboard context; the EpidBot agent uses its EpiDash MCP tools to update
+the charts; the viewer's browser picks up the change on its next poll.
+
+Viewers can also **ask questions** ("why did cases spike in March?") via
+the Ask button — the same chat pipeline, but the prompt instructs EpidBot
+to answer from the dashboard data without modifying it. No authentication
+is required for either; questions are recorded in the `tweaks` table with
+`kind='question'` and rate-limited separately from tweaks.
+
+Requires `EPIDBOT_BASE_URL` + `EPIDBOT_INTERNAL_SECRET` (EpidBot must accept
+`X-Internal-Request` on its chat endpoint — see the EpidBot-side integration
+docs) or an `ek_` API key.
+
+## Deployment
+
+Single container, single volume:
+
+```bash
+docker compose up -d --build
+```
+
+Production (KwarAI) deploys this via the Ansible `epidash` role behind
+nginx at `dash.kwar-ai.com.br` — see the
+[infrastructure repo](https://github.com/Deeplearn-PeD/infrastructure).
+
+## Development
+
+```bash
+uv sync                  # deps
+uv run pytest -v         # tests
+uv run ty check epidash/ # type check
+```
+
+## License
+
+MIT

epidash-0.2.0/README.md

@@ -0,0 +1,135 @@
+# EpiDash
+
+[![CI](https://github.com/Deeplearn-PeD/epidash/actions/workflows/ci.yml/badge.svg)](https://github.com/Deeplearn-PeD/epidash/actions/workflows/ci.yml)
+[![Python 3.12+](https://img.shields.io/badge/python-3.12+-blue.svg)](https://www.python.org/downloads/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+[![Managed with uv](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/uv/main/assets/badge/v1.json)](https://docs.astral.sh/uv/)
+
+A light, MCP-controlled dashboard service. [EpidBot](https://github.com/Deeplearn-PeD/EpiDBot)
+(and any MCP client holding a control key) builds, updates, publishes and
+unpublishes dashboards through an MCP tool surface; anyone with a dashboard
+link views it in a minimal web UI. Viewers can ask EpidBot to tweak a
+dashboard from the browser.
+
+```
+EpidBot agent ──(MCP client, dk_ key)──▶ EpiDash /mcp (FastMCP tools)
+                                            │
+                       SQLite ◀─────────────┤ (dashboards, charts, keys, audit)
+                                            │
+Viewer browser ──(public link)──▶ EpiDash / (vanilla JS + Plotly)
+      │                                 │
+      └── tweak request ──▶ POST /api/dashboards/{slug}/tweak
+                                 │  (X-Internal-Request: shared secret)
+                                 ▼
+                           EpidBot /api/v1/chat ──agent──▶ EpiDash MCP tools
+```
+
+## Quick start
+
+```bash
+uv sync
+uv run uvicorn epidash.main:app --port 8000
+```
+
+Then issue a control key and talk to the MCP endpoint:
+
+```bash
+uv run python -m epidash.cli add-key "local"
+# → dk_...  (shown once)
+```
+
+```bash
+# The MCP endpoint is stateless: one POST per call, no handshake needed.
+curl -s -X POST http://localhost:8000/mcp \
+  -H "X-API-Key: dk_..." -H "Content-Type: application/json" \
+  -H "Accept: application/json, text/event-stream" \
+  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'
+```
+
+In an MCP client (e.g. Claude Desktop, Cursor, EpidBot):
+
+```json
+{
+  "mcpServers": {
+    "epidash": {
+      "url": "http://localhost:8000/mcp",
+      "headers": { "X-API-Key": "dk_..." }
+    }
+  }
+}
+```
+
+## Configuration (environment variables)
+
+| Variable | Default | Purpose |
+|---|---|---|
+| `EPIDASH_DB_PATH` | `data/epidash.db` | SQLite file (WAL) |
+| `EPIDASH_BASE_URL` | `http://localhost:8000` | Public base URL for share links |
+| `EPIDASH_MCP_PATH` | `/mcp` | Mount path of the MCP endpoint |
+| `EPIDASH_ALLOWED_HOSTS` | `localhost,127.0.0.1` | Host header allowlist (DNS-rebinding protection) |
+| `EPIDASH_BOOTSTRAP_KEY` | — | Pre-shared `dk_` key seeded at startup (infra automation) |
+| `EPIDBOT_BASE_URL` | — | EpidBot base URL; enables the tweak flow |
+| `EPIDBOT_INTERNAL_SECRET` | — | Shared secret (EpidBot `INTERNAL_API_SECRET`) or `ek_` API key |
+| `EPIDASH_TWEAK_RATE_LIMIT_PER_HOUR` | `20` | Per-dashboard viewer tweak budget |
+| `EPIDASH_ASK_RATE_LIMIT_PER_HOUR` | `30` | Per-dashboard viewer question budget |
+| `EPIDASH_TWEAK_TIMEOUT_S` | `300` | Max wait for an EpidBot tweak turn |
+
+## MCP tools
+
+Read-only: `list_dashboards`, `get_dashboard`, `get_view_stats`, `get_audit_log`.
+
+Mutations (audited): `create_dashboard`, `update_dashboard`,
+`publish_dashboard` (confirm), `unpublish_dashboard` (confirm),
+`add_chart`, `update_chart`, `remove_chart` (confirm).
+
+### Chart data envelopes
+
+| kind | data |
+|---|---|
+| `line`, `bar`, `pie`, `table` | `{"columns": ["month", "cases"], "rows": [["Jan", 120], ...]}` |
+| `kpi` | `{"value": 1234, "label": "Cases", "unit": "", "delta": "+12%"}` |
+| `choropleth` | `{"values": {"SP": 120, "RJ": 90}, "region_level": "uf", "label": "cases"}` |
+
+`spec` accepts style overrides (`{"color": "#4ade80"}`, `{"y_label": "cases"}`) and
+`position` controls ordering/width (`{"order": 1, "width": "half"}`).
+
+## Viewer tweak flow
+
+A viewer types a request ("show only the Southeast after 2020") into the
+dashboard's chat box. EpiDash forwards it as an EpidBot chat turn with the
+dashboard context; the EpidBot agent uses its EpiDash MCP tools to update
+the charts; the viewer's browser picks up the change on its next poll.
+
+Viewers can also **ask questions** ("why did cases spike in March?") via
+the Ask button — the same chat pipeline, but the prompt instructs EpidBot
+to answer from the dashboard data without modifying it. No authentication
+is required for either; questions are recorded in the `tweaks` table with
+`kind='question'` and rate-limited separately from tweaks.
+
+Requires `EPIDBOT_BASE_URL` + `EPIDBOT_INTERNAL_SECRET` (EpidBot must accept
+`X-Internal-Request` on its chat endpoint — see the EpidBot-side integration
+docs) or an `ek_` API key.
+
+## Deployment
+
+Single container, single volume:
+
+```bash
+docker compose up -d --build
+```
+
+Production (KwarAI) deploys this via the Ansible `epidash` role behind
+nginx at `dash.kwar-ai.com.br` — see the
+[infrastructure repo](https://github.com/Deeplearn-PeD/infrastructure).
+
+## Development
+
+```bash
+uv sync                  # deps
+uv run pytest -v         # tests
+uv run ty check epidash/ # type check
+```
+
+## License
+
+MIT

epidash-0.2.0/docker-compose.yml

@@ -0,0 +1,27 @@
+services:
+  epidash:
+    build: .
+    image: epidash:latest
+    container_name: epidash
+    ports:
+      - '127.0.0.1:8310:8000'
+    volumes:
+      - ./data:/data
+    environment:
+      - EPIDASH_DB_PATH=/data/epidash.db
+      - EPIDASH_BASE_URL=${EPIDASH_BASE_URL:-http://localhost:8310}
+      - EPIDASH_ALLOWED_HOSTS=${EPIDASH_ALLOWED_HOSTS:-localhost,127.0.0.1}
+      - EPIDASH_BOOTSTRAP_KEY=${EPIDASH_BOOTSTRAP_KEY:-}
+      - EPIDBOT_BASE_URL=${EPIDBOT_BASE_URL:-}
+      - EPIDBOT_INTERNAL_SECRET=${EPIDBOT_INTERNAL_SECRET:-}
+    restart: unless-stopped
+    healthcheck:
+      test:
+        - CMD
+        - python
+        - -c
+        - "import urllib.request; urllib.request.urlopen('http://127.0.0.1:8000/healthz', timeout=4)"
+      interval: 30s
+      timeout: 5s
+      retries: 3
+      start_period: 10s

epidash-0.2.0/epidash/__init__.py

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

epidash-0.2.0/epidash/api/__init__.py

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