lukeandClaude Opus 5
9071ed36d3
Seven plan documents covering the website JS infrastructure, show theme, caller quality overhaul, cost dashboard, the Alpine relocation, and caller variety plus Devon's search — the record of why the current architecture looks the way it does. Plus the press release draft. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
108 lines
4.5 KiB
Markdown
108 lines
4.5 KiB
Markdown
# Cost Dashboard Design
|
|
|
|
## Overview
|
|
|
|
A dedicated cost analytics dashboard at `/costs` that visualizes LLM and TTS spending across sessions with time-range filtering, model/category breakdowns, and drill-down into individual sessions and calls.
|
|
|
|
## Architecture
|
|
|
|
- **Route:** `/costs` served by FastAPI, standalone page matching the control panel's dark theme
|
|
- **Database:** SQLite (`data/costs.db`) for cross-session aggregation
|
|
- **Charts:** Chart.js (vanilla JS, no framework)
|
|
- **Data migration:** On first run, import existing `data/cost_reports/*.json` into SQLite
|
|
- **Dual write:** `cost_tracker.py` continues writing JSON reports (backward compat) and also writes to SQLite going forward
|
|
|
|
## Database Schema
|
|
|
|
### `sessions`
|
|
| Column | Type | Description |
|
|
|--------|------|-------------|
|
|
| id | TEXT PK | Session ID |
|
|
| started_at | TIMESTAMP | Session start time |
|
|
| total_cost | REAL | Total cost USD |
|
|
| llm_cost | REAL | LLM cost USD |
|
|
| tts_cost | REAL | TTS cost USD |
|
|
| total_llm_calls | INTEGER | Number of LLM calls |
|
|
| total_tts_calls | INTEGER | Number of TTS calls |
|
|
| total_tokens | INTEGER | Total tokens used |
|
|
| prompt_tokens | INTEGER | Prompt tokens |
|
|
| completion_tokens | INTEGER | Completion tokens |
|
|
|
|
### `llm_calls`
|
|
| Column | Type | Description |
|
|
|--------|------|-------------|
|
|
| id | INTEGER PK | Auto-increment |
|
|
| session_id | TEXT FK | References sessions.id |
|
|
| timestamp | TIMESTAMP | Call time |
|
|
| category | TEXT | background_gen, caller_dialog, devon_monitor, etc. |
|
|
| model | TEXT | Model identifier |
|
|
| prompt_tokens | INTEGER | Prompt tokens |
|
|
| completion_tokens | INTEGER | Completion tokens |
|
|
| cost | REAL | Cost USD |
|
|
| caller_name | TEXT | Caller name (nullable) |
|
|
| latency_ms | REAL | Response latency |
|
|
|
|
### `tts_calls`
|
|
| Column | Type | Description |
|
|
|--------|------|-------------|
|
|
| id | INTEGER PK | Auto-increment |
|
|
| session_id | TEXT FK | References sessions.id |
|
|
| timestamp | TIMESTAMP | Call time |
|
|
| provider | TEXT | Inworld, ElevenLabs, etc. |
|
|
| voice | TEXT | Voice ID |
|
|
| char_count | INTEGER | Characters synthesized |
|
|
| cost | REAL | Cost USD |
|
|
|
|
## API Endpoints
|
|
|
|
All new endpoints under `/api/costs/`:
|
|
|
|
| Endpoint | Description |
|
|
|----------|-------------|
|
|
| `GET /api/costs/summary?period=today\|week\|month\|all` | Aggregated totals: spend, LLM/TTS split, call count, tokens, avg cost/session, % change vs previous period |
|
|
| `GET /api/costs/timeline?period=week\|month\|all&group_by=session\|day` | Time-series for line chart (cost over time) |
|
|
| `GET /api/costs/models?period=week\|month\|all` | Per-model breakdown for pie/bar charts |
|
|
| `GET /api/costs/categories?period=week\|month\|all` | Per-category breakdown (background_gen, caller_dialog, etc.) |
|
|
| `GET /api/costs/sessions?period=week\|month\|all` | Session list with totals, sortable |
|
|
| `GET /api/costs/session/{id}` | Single session detail: per-caller costs, expensive calls, recommendations |
|
|
| `GET /api/costs/expensive?period=week\|month\|all&limit=10` | Top N most expensive individual calls |
|
|
|
|
Existing `/api/costs` (live session) endpoint remains unchanged.
|
|
|
|
## Dashboard Layout
|
|
|
|
### Header
|
|
Time range selector tabs: Today / This Week / This Month / All Time. Clicking any tab refreshes all charts.
|
|
|
|
### Row 1 — Summary Cards (4 across)
|
|
- **Total Spend** with % change vs previous period
|
|
- **LLM / TTS Split** showing both values
|
|
- **Total Sessions** in period
|
|
- **Avg Cost Per Session**
|
|
|
|
### Row 2 — Two charts side by side
|
|
- **Left: Cost Over Time** — line chart, x-axis sessions or days, y-axis dollars. LLM and TTS as separate lines.
|
|
- **Right: Cost by Model** — doughnut chart with legend showing dollar amounts.
|
|
|
|
### Row 3 — Two charts side by side
|
|
- **Left: Cost by Category** — horizontal bar chart (background_gen, caller_dialog, devon_monitor, etc.)
|
|
- **Right: Cost Per Session Trend** — bar chart, each bar a session, colored above/below average.
|
|
|
|
### Row 4 — Tables
|
|
- **Most Expensive Calls** — top 10 LLM calls (model, category, caller, tokens, cost, timestamp)
|
|
- **Session List** — all sessions, sortable by date/cost, clickable for detail view.
|
|
|
|
### Session Detail View (click-through)
|
|
- Per-caller cost breakdown
|
|
- Call-by-call timeline
|
|
- Recommendations from existing `_generate_recommendations()` logic
|
|
|
|
## Visual Style
|
|
Matches the control panel's existing dark theme. Same fonts, colors, card styles.
|
|
|
|
## What's NOT in v1
|
|
- SignalWire cost tracking (future addition)
|
|
- Real-time WebSocket updates (polling on page load is sufficient)
|
|
- Cost alerts/budgets
|
|
- Export to CSV
|