by-framework-dashboard 0.1.0__tar.gz

by_framework_dashboard-0.1.0/.gitignore

@@ -0,0 +1,73 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.ruff_cache/
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# Environment
+.env
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Node.js
+node_modules/
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+.pnpm-debug.log*
+dist/
+.cache/
+.next/
+out/
+.next-env.d.ts
+
+# IDEs / Editors
+.idea/
+.vscode/
+*.swp
+*.swo
+.DS_Store
+.DS_Store?
+._*
+.Spotlight-V100
+.Trashes
+ehthumbs.db
+Thumbs.db
+
+# Project Specific
+.worktrees/
+*.log
+.gemini/
+/brain/
+.agents/
+.agent/
+*gateway-sdk.log*
+.claude/settings.local.json
+.claude/settings.json
+
+.coderfleet-uploads/
+
+.claude/skills

by_framework_dashboard-0.1.0/Dockerfile

@@ -0,0 +1,40 @@
+# syntax=docker/dockerfile:1
+
+FROM node:22-bookworm-slim AS frontend
+
+WORKDIR /app/libs/by-framework-dashboard/frontend
+COPY libs/by-framework-dashboard/frontend/package*.json ./
+RUN npm ci --no-audit --progress=false
+COPY libs/by-framework-dashboard/frontend/ ./
+RUN npm run build
+
+FROM ghcr.io/astral-sh/uv:python3.12-bookworm-slim AS runtime
+
+ENV PYTHONUNBUFFERED=1 \
+    UV_NO_CACHE=1 \
+    PATH="/opt/venv/bin:${PATH}"
+
+WORKDIR /app
+
+COPY pyproject.toml uv.lock README.md ./
+COPY src ./src
+COPY libs/by-framework-dashboard ./libs/by-framework-dashboard
+COPY libs/by-framework-trace-query ./libs/by-framework-trace-query
+COPY --from=frontend /app/libs/by-framework-dashboard/src/by_framework_dashboard/static/ ./libs/by-framework-dashboard/src/by_framework_dashboard/static/
+
+RUN uv venv /opt/venv \
+    && uv build --wheel --project . --out-dir /tmp/wheels \
+    && uv build --wheel --project libs/by-framework-trace-query --out-dir /tmp/wheels \
+    && uv build --wheel --project libs/by-framework-dashboard --out-dir /tmp/wheels \
+    && uv pip install --python /opt/venv/bin/python \
+        /tmp/wheels/by_framework-*.whl \
+        /tmp/wheels/by_framework_trace_query-*.whl \
+        /tmp/wheels/by_framework_dashboard-*.whl \
+    && rm -rf /tmp/wheels
+
+EXPOSE 8765
+
+HEALTHCHECK --interval=30s --timeout=5s --start-period=10s --retries=3 \
+    CMD python -c "import json, urllib.request; response = urllib.request.urlopen('http://127.0.0.1:8765/api/health', timeout=3); json.load(response)"
+
+CMD ["by-framework-dashboard", "--host", "0.0.0.0", "--port", "8765"]

by_framework_dashboard-0.1.0/PKG-INFO

@@ -0,0 +1,14 @@
+Metadata-Version: 2.4
+Name: by-framework-dashboard
+Version: 0.1.0
+Summary: Dashboard UI and HTTP server for by-framework observability
+Requires-Python: >=3.12
+Requires-Dist: by-framework-trace-query>=0.1.0
+Requires-Dist: by-framework>=0.2.1
+Provides-Extra: dev
+Requires-Dist: isort>=5.13.0; extra == 'dev'
+Requires-Dist: pyink>=24.0.0; extra == 'dev'
+Requires-Dist: pylint>=3.0.0; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.23.0; extra == 'dev'
+Requires-Dist: pytest>=8.0.0; extra == 'dev'
+Requires-Dist: ruff>=0.3.0; extra == 'dev'

by_framework_dashboard-0.1.0/README.md

@@ -0,0 +1,174 @@
+# by-framework-dashboard
+
+Dashboard UI and HTTP server for inspecting by-framework workers, queues,
+executions, sessions, traces, and Prometheus metrics.
+
+## Quick Start
+
+From the repository root:
+
+```bash
+uv run --package by-framework-dashboard by-framework-dashboard \
+  --host 127.0.0.1 \
+  --port 8765
+```
+
+Then open:
+
+```text
+http://127.0.0.1:8765
+```
+
+## Container Image
+
+Dashboard release tags also publish a GHCR image:
+
+```text
+ghcr.io/<owner>/by-framework-dashboard:<version>
+```
+
+For example, pushing `by-framework-dashboard-v0.1.0` builds and publishes:
+
+```text
+ghcr.io/<owner>/by-framework-dashboard:0.1.0
+ghcr.io/<owner>/by-framework-dashboard:latest
+```
+
+To run the image:
+
+```bash
+docker run --rm -p 8765:8765 \
+  -e REDIS_HOST=host.docker.internal \
+  ghcr.io/<owner>/by-framework-dashboard:0.1.0
+```
+
+For demo data without a live Redis cluster:
+
+```text
+http://127.0.0.1:8765?demo=1
+```
+
+## Redis Configuration
+
+The dashboard reads live data from the same Redis instance used by workers and
+clients. You can configure Redis with CLI flags:
+
+```bash
+uv run --package by-framework-dashboard by-framework-dashboard \
+  --host 127.0.0.1 \
+  --port 8765 \
+  --redis-host localhost \
+  --redis-port 6379 \
+  --redis-db 0
+```
+
+Or with environment variables:
+
+```bash
+export REDIS_HOST=localhost
+export REDIS_PORT=6379
+export REDIS_DB=0
+export REDIS_USERNAME=
+export REDIS_PASSWORD=
+
+uv run --package by-framework-dashboard by-framework-dashboard
+```
+
+Supported Redis env vars:
+
+- `REDIS_HOST`
+- `REDIS_PORT`
+- `REDIS_DB`
+- `REDIS_USERNAME`
+- `REDIS_PASSWORD`
+- `REDIS_MAX_CONNECTIONS`
+
+## Authentication
+
+When binding to a non-localhost interface, configure a bearer token:
+
+```bash
+export BY_FRAMEWORK_DASHBOARD_TOKEN="change-me"
+uv run --package by-framework-dashboard by-framework-dashboard \
+  --host 0.0.0.0 \
+  --port 8765
+```
+
+API and metrics requests must then include:
+
+```text
+Authorization: Bearer change-me
+```
+
+Static dashboard assets remain public; `/api/*` and `/metrics` are protected.
+
+## Useful Endpoints
+
+- `/` - dashboard UI
+- `/?demo=1` - dashboard UI with demo data
+- `/api/health` - dashboard process health
+- `/api/workers` - worker and agent health snapshot
+- `/api/queues` - Redis stream queue snapshot
+- `/api/executions` - recent execution snapshot
+- `/api/session?session_id=<session_id>` - session execution and event details
+- `/api/traces?session_id=<session_id>` - trace summaries through Trace Read SDK
+- `/api/traces?worker_id=<worker_id>` - trace summaries by worker
+- `/api/traces?agent_type=<agent_type>` - trace summaries by agent type
+- `/api/trace/<trace_id>` - single trace detail through Trace Read SDK
+- `/api/trace/<trace_id>?session_id=<session_id>` - single trace with session hint
+- `/api/trace/<trace_id>/timeline` - trace timeline payload
+- `/metrics` - Prometheus metrics
+
+`/api/traces` in live mode requires at least one of `session_id`, `worker_id`,
+or `agent_type`.
+
+## Trace Data
+
+Trace APIs use `by-framework-trace-query` under the hood. In v1 the read source
+is Redis:
+
+- `by_framework:trace:{trace_id}`
+- `by_framework:trace:spans:{trace_id}`
+- session registry and session data stream fallback
+- trace indexes by session, worker, and agent
+
+If `BYAI_TRACE_FALLBACK_URL` is set, `/api/trace/<trace_id>` can fall back to an
+external HTTP trace source when Redis has no spans for the requested trace.
+
+## Frontend Development
+
+The packaged dashboard serves built static files from:
+
+```text
+libs/by-framework-dashboard/src/by_framework_dashboard/static
+```
+
+The editable React/Vite frontend lives in:
+
+```text
+libs/by-framework-dashboard/frontend
+```
+
+To work on the frontend:
+
+```bash
+cd libs/by-framework-dashboard/frontend
+npm install
+npm run dev
+```
+
+After frontend changes, build and copy the generated assets into the package
+static directory according to the repository release workflow.
+
+## Troubleshooting
+
+If the page loads but live data is empty:
+
+- Confirm workers and clients use the same Redis host, port, and DB.
+- Open `http://127.0.0.1:8765/api/health`.
+- Try demo mode with `http://127.0.0.1:8765?demo=1`.
+- Query a known trace directly with `/api/trace/<trace_id>`.
+- Query trace lists with a filter, for example `/api/traces?session_id=<id>`.
+
+If API requests return `unauthorized`, include the bearer token configured via
+`--auth-token` or `BY_FRAMEWORK_DASHBOARD_TOKEN`.

by_framework_dashboard-0.1.0/frontend/index.html

@@ -0,0 +1,12 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+    <title>by-framework observability</title>
+  </head>
+  <body>
+    <div id="root"></div>
+    <script type="module" src="/src/main.jsx"></script>
+  </body>
+</html>