Embedded DuckDB Observability Dashboard

[QueryPlanner]

What

Implement an embedded observability dashboard directly into the existing FastAPI server to visualize local DuckDB telemetry and trace data.

Why

We recently transitioned to local JSON file logging and tracing. To keep the infrastructure footprint minimal (avoiding standalone tools like Grafana), we want to embed an interactive, lightweight dashboard using DuckDB's Python client and an interactive charting library (e.g., Chart.js or ECharts) served directly by FastAPI.

How

1. Install duckdb via uv.
2. Write a Python wrapper class to execute queries against the blacki-traces.log and blacki-telemetry.log files.
3. Add a new FastAPI endpoint (e.g., /api/telemetry/stats) that returns aggregated JSON data (like token usage over time).
4. Add a FastAPI route (e.g., /dashboard) that serves a simple HTML page containing interactive frontend graphs.
5. Provide a foundation to easily add an ADK tool for Telegram querying later.

Priority

Medium

Level of Effort

Medium (1-2 days)

Sources

• FastAPI Integration point: src/blacki/server.py
• DuckDB Python API: DuckDB Docs
• Charting libraries: ECharts or Chart.js

Passing Criteria

• The duckdb Python package is successfully added to the pyproject.toml and installed via uv.
• FastAPI serves a /dashboard endpoint returning an HTML page.
• FastAPI serves an /api/telemetry/stats endpoint returning aggregated JSON metrics queried from the local logs.
• The HTML dashboard correctly fetches the metrics and renders an interactive chart (e.g., plotting token usage).
• Automated tests pass asserting that the API endpoint returns valid JSON and the dashboard endpoint returns HTML.