Skip to content

armgit / AiSOC

Public Imported from GitHub
0

Open-source AI Security Operations Center: alert fusion, LLM-agent triage, MITRE ATT&CK investigation, and a replayable decision ledger for every agent step. Self-hostable, runs with no API keys, MIT licensed. Ships an MCP server for Claude, Cursor and Continue.

WS-H1: cost dashboard — LLM spend, BYOK savings, action counts

Beenu Aroraae04e6987d52
diff --git a/apps/web/src/app/(admin)/costs/page.tsx b/apps/web/src/app/(admin)/costs/page.tsx
new file mode 100644
index 000000000..8fe65c4f9
--- /dev/null
+++ b/apps/web/src/app/(admin)/costs/page.tsx
@@ -0,0 +1,7 @@
+import { CostDashboardView } from '@/components/admin/CostDashboardView';
+
+export const metadata = { title: 'Cost Dashboard — AiSOC' };
+
+export default function CostDashboardPage() {
+ return <CostDashboardView />;
+}
diff --git a/apps/web/src/app/(admin)/layout.tsx b/apps/web/src/app/(admin)/layout.tsx
new file mode 100644
index 000000000..560775659
--- /dev/null
+++ b/apps/web/src/app/(admin)/layout.tsx
@@ -0,0 +1,15 @@
+import { AppShell } from '@/components/layout/AppShell';
+
+/**
+ * Admin route group layout — WS-H1.
+ *
+ * Holds tenant-administrator surfaces (cost dashboard, future billing
+ * controls, BYOK key rotation, etc.) inside the same `AppShell` chrome the
+ * rest of the console uses, so navigation, command palette, and SWR config
+ * all behave identically. Pages under this group remain server-rendered by
+ * default; individual `*View` components opt into `'use client'` when they
+ * need hooks.
+ */
+export default function AdminLayout({ children }: { children: React.ReactNode }) {
+ return <AppShell>{children}</AppShell>;
+}
diff --git a/apps/web/src/components/admin/CostDashboardView.test.tsx b/apps/web/src/components/admin/CostDashboardView.test.tsx
new file mode 100644
index 000000000..4b1152093
--- /dev/null
+++ b/apps/web/src/components/admin/CostDashboardView.test.tsx
@@ -0,0 +1,229 @@
+import { describe, expect, it, vi, beforeEach } from 'vitest';
+import { render, screen, within, waitFor } from '@testing-library/react';
+import userEvent from '@testing-library/user-event';
+
+// WS-H1 — verify the cost dashboard wires:
+// 1. SWR fixture → headline / daily / by_model / top_cases / actions
+// 2. window-days <select> drives a fresh costsApi.dashboard call
+// 3. BYOK panel toggles its "active" / "neutral" branding from the payload
+// 4. Empty branches render their dedicated copy without crashing
+//
+// We mock SWR so we control the data the view receives, and mock costsApi to
+// observe the param wiring. SWR is keyed on `['cost-dashboard', days]`, so
+// the cache map below mirrors the component's keying scheme exactly.
+
+const swrCalls = vi.hoisted(() => new Map<string, unknown>());
+vi.mock('swr', () => ({
+ __esModule: true,
+ default: (key: unknown) => {
+ const cacheKey = JSON.stringify(key);
+ const data = swrCalls.get(cacheKey);
+ return {
+ data,
+ error: undefined,
+ isLoading: false,
+ mutate: vi.fn(async () => undefined),
+ };
+ },
+}));
+
+const dashboardMock = vi.hoisted(() => vi.fn());
+vi.mock('@/lib/api', () => ({
+ __esModule: true,
+ costsApi: {
+ dashboard: dashboardMock,
+ },
+}));
+
+import { CostDashboardView } from './CostDashboardView';
+import type { CostDashboard } from '@/lib/api';
+
+function fixture(overrides: Partial<CostDashboard> = {}): CostDashboard {
+ return {
+ tenant_id: 't1',
+ period: {
+ start: '2026-04-09T00:00:00Z',
+ end: '2026-05-09T00:00:00Z',
+ window_days: 30,
+ label: 'Apr 9 – May 9, 2026',
+ },
+ headline: {
+ total_cost_usd: 142.37,
+ total_tokens: 4_321_000,
+ total_calls: 1287,
+ total_runs: 312,
+ avg_cost_per_run_usd: 0.456,
+ },
+ daily_costs: [
+ { day: '2026-05-07', total_cost_usd: 12.5, total_tokens: 320_000, call_count: 80 },
+ { day: '2026-05-08', total_cost_usd: 18.2, total_tokens: 410_000, call_count: 95 },
+ { day: '2026-05-09', total_cost_usd: 9.7, total_tokens: 280_000, call_count: 65 },
+ ],
+ by_model: [
+ {
+ model: 'gpt-4o-mini',
+ runs: 200,
+ calls: 800,
+ total_prompt_tokens: 1_200_000,
+ total_completion_tokens: 600_000,
+ total_cost_usd: 65.4,
+ imputed_public_cost_usd: 65.4,
+ avg_latency_ms: 1240,
+ },
+ {
+ model: 'claude-3-5-sonnet-20241022',
+ runs: 112,
+ calls: 487,
+ total_prompt_tokens: 900_000,
+ total_completion_tokens: 410_000,
+ total_cost_usd: 76.97,
+ imputed_public_cost_usd: 76.97,
+ avg_latency_ms: 2100,
+ },
+ ],
+ top_cases: [
+ { case_id: 'CASE-2026-0042', runs: 6, total_cost_usd: 18.4, total_tokens: 420_000 },
+ { case_id: 'CASE-2026-0044', runs: 4, total_cost_usd: 12.1, total_tokens: 280_000 },
+ ],
+ action_counts: [
+ { action: 'cases:read', count: 482 },
+ { action: 'alerts:write', count: 219 },
+ ],
+ byok_savings: {
+ is_byok_active: false,
+ provider: 'openai',
+ recorded_cost_usd: 142.37,
+ imputed_public_cost_usd: 142.37,
+ savings_usd: 0,
+ },
+ ...overrides,
+ };
+}
+
+function seed(days: number, payload: CostDashboard) {
+ swrCalls.set(JSON.stringify(['cost-dashboard', days]), payload);
+}
+
+beforeEach(() => {
+ swrCalls.clear();
+ dashboardMock.mockReset();
+});
+
+describe('CostDashboardView', () => {
+ it('renders headline KPIs and the period hero from the SWR payload', () => {
+ seed(30, fixture());
+ render(<CostDashboardView />);
+
+ expect(screen.getByRole('heading', { name: 'Cost Dashboard', level: 1 })).toBeInTheDocument();
+ expect(screen.getByText('Apr 9 – May 9, 2026')).toBeInTheDocument();
+
+ const headline = screen.getByTestId('cost-headline');
+ // Total LLM spend → "$142.37"
+ expect(within(headline).getByText('$142.37')).toBeInTheDocument();
+ // Tokens consumed → "4.32M" (4,321,000 tokens)
+ expect(within(headline).getByText('4.32M')).toBeInTheDocument();
+ // Avg cost / run → "$0.46" (0.456 → toFixed(2))
+ expect(within(headline).getByText('$0.46')).toBeInTheDocument();
+ });
+
+ it('renders the by-model table with recorded + imputed costs', () => {
+ seed(30, fixture());
+ render(<CostDashboardView />);
+
+ const table = screen.getByTestId('model-table');
+ expect(within(table).getByText('gpt-4o-mini')).toBeInTheDocument();
+ expect(within(table).getByText('claude-3-5-sonnet-20241022')).toBeInTheDocument();
+ // $65.40 appears in both recorded and imputed columns when BYOK is inactive,
+ // so we just assert the value shows up in the table at least once.
+ expect(within(table).getAllByText('$65.40').length).toBeGreaterThan(0);
+ expect(within(table).getAllByText('$76.97').length).toBeGreaterThan(0);
+ });
+
+ it('renders top-cost cases and action counts', () => {
+ seed(30, fixture());
+ render(<CostDashboardView />);
+
+ const cases = screen.getByTestId('top-cases');
+ expect(within(cases).getByText('CASE-2026-0042')).toBeInTheDocument();
+ expect(within(cases).getByText('$18.40')).toBeInTheDocument();
+
+ const actions = screen.getByTestId('action-counts');
+ expect(within(actions).getByText('cases:read')).toBeInTheDocument();
+ expect(within(actions).getByText('482')).toBeInTheDocument();
+ });
+
+ it('marks the BYOK panel "neutral" when the provider is hosted', () => {
+ seed(30, fixture());
+ render(<CostDashboardView />);
+
+ const panel = screen.getByTestId('byok-panel');
+ expect(panel).toHaveAttribute('data-byok', 'inactive');
+ expect(within(panel).getByText('Hosted provider')).toBeInTheDocument();
+ });
+
+ it('marks the BYOK panel "active" and surfaces savings when BYOK is on', () => {
+ seed(
+ 30,
+ fixture({
+ byok_savings: {
+ is_byok_active: true,
+ provider: 'local-ollama',
+ recorded_cost_usd: 0,
+ imputed_public_cost_usd: 142.37,
+ savings_usd: 142.37,
+ },
+ }),
+ );
+ render(<CostDashboardView />);
+
+ const panel = screen.getByTestId('byok-panel');
+ expect(panel).toHaveAttribute('data-byok', 'active');
+ expect(within(panel).getByText('BYOK active')).toBeInTheDocument();
+ expect(
+ within(panel).getByText('~$142.37 saved by running your own model'),
+ ).toBeInTheDocument();
+ });
+
+ it('switches the SWR key when the operator changes the window', async () => {
+ seed(30, fixture());
+ seed(7, fixture({ headline: { ...fixture().headline, total_cost_usd: 12.5 } }));
+
+ render(<CostDashboardView />);
+ // "$142.37" appears in headline + BYOK panel — narrow to the headline.
+ expect(within(screen.getByTestId('cost-headline')).getByText('$142.37')).toBeInTheDocument();
+
+ await userEvent.selectOptions(screen.getByLabelText('Reporting window'), '7');
+
+ await waitFor(() => {
+ expect(within(screen.getByTestId('cost-headline')).getByText('$12.50')).toBeInTheDocument();
+ });
+ });
+
+ it('renders empty states when the window has no activity', () => {
+ seed(
+ 30,
+ fixture({
+ headline: {
+ total_cost_usd: 0,
+ total_tokens: 0,
+ total_calls: 0,
+ total_runs: 0,
+ avg_cost_per_run_usd: null,
+ },
+ daily_costs: [],
+ by_model: [],
+ top_cases: [],
+ action_counts: [],
+ }),
+ );
+ render(<CostDashboardView />);
+
+ expect(screen.getByText('No LLM calls recorded in this window.')).toBeInTheDocument();
+ expect(screen.getByText('No LLM activity recorded for this window.')).toBeInTheDocument();
+ expect(screen.getByText('No per-model rows recorded for this window.')).toBeInTheDocument();
+ expect(
+ screen.getByText('No case-attributed runs recorded for this window.'),
+ ).toBeInTheDocument();
+ expect(screen.getByText('No audit events recorded for this window.')).toBeInTheDocument();
+ });
+});
diff --git a/apps/web/src/components/admin/CostDashboardView.tsx b/apps/web/src/components/admin/CostDashboardView.tsx
new file mode 100644
index 000000000..b9e0f7579
--- /dev/null
+++ b/apps/web/src/components/admin/CostDashboardView.tsx
@@ -0,0 +1,433 @@
+'use client';
+
+/**
+ * Cost dashboard — WS-H1.
+ *
+ * Renders the deterministic snapshot returned by
+ * ``GET /api/v1/costs/dashboard?window_days=N`` as an admin-facing page that
+ * answers four questions at a glance:
+ *
+ * 1. Where is the LLM money going? (headline KPIs + daily sparkline)
+ * 2. Which models are eating the budget? (per-model breakdown table)
+ * 3. Which investigations are the most expensive? (top-cost cases)
+ * 4. How much SOC activity am I getting for that money? (action counts)
+ *
+ * A dedicated BYOK savings panel labels itself as "active" or "neutral"
+ * based on the runtime LLM provider, so operators running a local model see
+ * imputed savings vs a hosted alternative without us claiming billing-grade
+ * accuracy.
+ *
+ * Styling intentionally mirrors `components/reports/ExecutiveDigest.tsx` so
+ * the two admin reports feel like siblings (same Card, KpiCard, Stat
+ * primitives, same dark-on-violet hero band).
+ */
+
+import { useMemo, useState } from 'react';
+import useSWR from 'swr';
+
+import { costsApi, type CostDashboard } from '@/lib/api';
+
+const WINDOW_PRESETS: { label: string; days: number }[] = [
+ { label: 'Last 7 days', days: 7 },
+ { label: 'Last 14 days', days: 14 },
+ { label: 'Last 30 days', days: 30 },
+ { label: 'Last 90 days', days: 90 },
+];
+
+function fmtUsd(value: number | null | undefined): string {
+ if (value === null || value === undefined) return '—';
+ // Sub-cent precision for BYOK / per-call values, but cap at $0.01 floor so
+ // we don't render literal "$0.0001" all over the dashboard.
+ if (value === 0) return '$0.00';
+ if (value < 0.01) return '<$0.01';
+ if (value < 1000) return `$${value.toFixed(2)}`;
+ if (value < 1_000_000) return `$${(value / 1000).toFixed(2)}k`;
+ return `$${(value / 1_000_000).toFixed(2)}M`;
+}
+
+function fmtNumber(value: number | null | undefined): string {
+ if (value === null || value === undefined) return '—';
+ if (value < 1000) return value.toLocaleString();
+ if (value < 1_000_000) return `${(value / 1000).toFixed(1)}k`;
+ return `${(value / 1_000_000).toFixed(2)}M`;
+}
+
+function fmtMs(value: number | null | undefined): string {
+ if (value === null || value === undefined) return '—';
+ if (value < 1000) return `${Math.round(value)}ms`;
+ return `${(value / 1000).toFixed(1)}s`;
+}
+
+function fmtDate(iso: string): string {
+ try {
+ return new Date(iso).toLocaleDateString(undefined, {
+ year: 'numeric',
+ month: 'short',
+ day: 'numeric',
+ });
+ } catch {
+ return iso;
+ }
+}
+
+export function CostDashboardView() {
+ const [days, setDays] = useState<number>(30);
+
+ const { data, error, isLoading, mutate } = useSWR<CostDashboard>(
+ ['cost-dashboard', days],
+ () => costsApi.dashboard({ window_days: days }),
+ {
+ revalidateOnFocus: false,
+ shouldRetryOnError: false,
+ errorRetryCount: 0,
+ },
+ );
+
+ return (
+ <div className="space-y-6">
+ {/* Header */}
+ <div className="flex flex-col gap-3 sm:flex-row sm:items-end sm:justify-between">
+ <div>
+ <h1 className="text-2xl font-bold text-white">Cost Dashboard</h1>
+ <p className="mt-1 text-sm text-gray-400">
+ LLM spend, automation activity, and BYOK savings for the current tenant. Numbers are
+ recorded by the cost tracker — no estimation unless explicitly labelled.
+ </p>
+ </div>
+ <div className="flex flex-wrap items-center gap-2">
+ <label htmlFor="cost-window" className="sr-only">
+ Reporting window
+ </label>
+ <select
+ id="cost-window"
+ value={days}
+ onChange={(e) => setDays(Number(e.target.value))}
+ className="rounded border border-gray-600 bg-gray-800 px-3 py-1.5 text-sm text-white"
+ >
+ {WINDOW_PRESETS.map((p) => (
+ <option key={p.days} value={p.days}>
+ {p.label}
+ </option>
+ ))}
+ </select>
+ <button
+ type="button"
+ onClick={() => mutate()}
+ className="rounded border border-gray-600 bg-gray-800 px-3 py-1.5 text-sm text-gray-200 hover:bg-gray-700"
+ >
+ Refresh
+ </button>
+ </div>
+ </div>
+
+ {error && (
+ <div className="rounded-md border border-red-500/30 bg-red-500/10 px-4 py-2 text-sm text-red-200">
+ Failed to load cost dashboard: {error instanceof Error ? error.message : String(error)}
+ </div>
+ )}
+
+ {isLoading && !data && (
+ <div className="rounded-xl border border-gray-700 bg-gray-900 p-6 text-sm text-gray-400">
+ Computing cost snapshot…
+ </div>
+ )}
+
+ {data && <DashboardBody data={data} />}
+ </div>
+ );
+}
+
+function DashboardBody({ data }: { data: CostDashboard }) {
+ return (
+ <>
+ <PeriodHero data={data} />
+ <Headline data={data} />
+ <DailySpend data={data} />
+ <ModelTable data={data} />
+ <CasesAndActions data={data} />
+ <ByokPanel data={data} />
+ </>
+ );
+}
+
+function PeriodHero({ data }: { data: CostDashboard }) {
+ const { period, headline } = data;
+ // Build a short qualitative summary so operators don't have to read the
+ // KPI strip to understand the period at a glance.
+ const summary = useMemo(() => {
+ if (headline.total_calls === 0) {
+ return 'No LLM calls recorded in this window.';
+ }
+ const perRun = headline.avg_cost_per_run_usd;
+ const runsLabel = headline.total_runs === 1 ? 'investigation' : 'investigations';
+ const callsLabel = headline.total_calls === 1 ? 'call' : 'calls';
+ const cost = fmtUsd(headline.total_cost_usd);
+ const tokens = fmtNumber(headline.total_tokens);
+ if (perRun === null) {
+ return `${cost} of LLM spend across ${headline.total_calls.toLocaleString()} ${callsLabel} (${tokens} tokens). No completed investigation runs in the window.`;
+ }
+ return `${cost} of LLM spend across ${headline.total_runs.toLocaleString()} ${runsLabel}, averaging ${fmtUsd(perRun)} per run on ${tokens} tokens.`;
+ }, [headline]);
+
+ return (
+ <section className="rounded-xl border border-violet-500/30 bg-violet-950/20 p-5">
+ <p className="text-xs uppercase tracking-wide text-violet-300">Reporting period</p>
+ <p className="mt-1 text-lg font-semibold text-white">{period.label}</p>
+ <p className="mt-3 text-sm leading-relaxed text-gray-200">{summary}</p>
+ <p className="mt-2 text-xs text-gray-500">
+ {fmtDate(period.start)} → {fmtDate(period.end)} · {period.window_days}-day window
+ </p>
+ </section>
+ );
+}
+
+function Headline({ data }: { data: CostDashboard }) {
+ const { headline } = data;
+ return (
+ <section className="grid grid-cols-2 gap-4 sm:grid-cols-4" data-testid="cost-headline">
+ <KpiCard label="Total LLM spend" value={fmtUsd(headline.total_cost_usd)} sub={`${fmtNumber(headline.total_calls)} calls`} />
+ <KpiCard label="Tokens consumed" value={fmtNumber(headline.total_tokens)} sub="prompt + completion" />
+ <KpiCard label="Investigation runs" value={fmtNumber(headline.total_runs)} sub={`${data.action_counts.length} distinct actions`} />
+ <KpiCard
+ label="Avg cost / run"
+ value={fmtUsd(headline.avg_cost_per_run_usd)}
+ sub={headline.total_runs === 0 ? 'no completed runs yet' : 'rolling window mean'}
+ />
+ </section>
+ );
+}
+
+function DailySpend({ data }: { data: CostDashboard }) {
+ const { daily_costs } = data;
+ const max = useMemo(
+ () => daily_costs.reduce((acc, b) => (b.total_cost_usd > acc ? b.total_cost_usd : acc), 0),
+ [daily_costs],
+ );
+
+ return (
+ <Card title="Daily LLM spend" subtitle="One bar per UTC day in the window — bars are scaled to the peak day">
+ {daily_costs.length === 0 ? (
+ <p className="text-sm text-gray-500">No LLM activity recorded for this window.</p>
+ ) : (
+ <div data-testid="daily-spend">
+ <div className="flex h-32 items-end gap-1">
+ {daily_costs.map((bucket) => {
+ const pct = max > 0 ? (bucket.total_cost_usd / max) * 100 : 0;
+ return (
+ <div
+ key={bucket.day}
+ className="group relative flex h-full flex-1 flex-col justify-end"
+ title={`${fmtDate(bucket.day)}: ${fmtUsd(bucket.total_cost_usd)} · ${fmtNumber(bucket.call_count)} calls · ${fmtNumber(bucket.total_tokens)} tokens`}
+ >
+ <div
+ className="rounded-t bg-violet-500/70 transition-colors group-hover:bg-violet-400"
+ style={{ height: `${Math.max(pct, bucket.total_cost_usd > 0 ? 2 : 0)}%` }}
+ />
+ </div>
+ );
+ })}
+ </div>
+ <div className="mt-2 flex justify-between text-xs text-gray-500">
+ <span>{fmtDate(daily_costs[0]!.day)}</span>
+ <span>peak {fmtUsd(max)}</span>
+ <span>{fmtDate(daily_costs[daily_costs.length - 1]!.day)}</span>
+ </div>
+ </div>
+ )}
+ </Card>
+ );
+}
+
+function ModelTable({ data }: { data: CostDashboard }) {
+ const { by_model } = data;
+ return (
+ <Card title="Spend by model" subtitle="Recorded vs imputed list-price cost, per model id">
+ {by_model.length === 0 ? (
+ <p className="text-sm text-gray-500">No per-model rows recorded for this window.</p>
+ ) : (
+ <div className="overflow-x-auto" data-testid="model-table">
+ <table className="w-full min-w-[720px] text-left text-sm">
+ <thead>
+ <tr className="border-b border-gray-700 text-xs uppercase tracking-wide text-gray-500">
+ <th className="py-2 pr-4 font-medium">Model</th>
+ <th className="py-2 pr-4 font-medium text-right">Calls</th>
+ <th className="py-2 pr-4 font-medium text-right">Prompt tokens</th>
+ <th className="py-2 pr-4 font-medium text-right">Completion tokens</th>
+ <th className="py-2 pr-4 font-medium text-right">Recorded</th>
+ <th className="py-2 pr-4 font-medium text-right">Imputed (list)</th>
+ <th className="py-2 font-medium text-right">Avg latency</th>
+ </tr>
+ </thead>
+ <tbody>
+ {by_model.map((m) => (
+ <tr key={m.model} className="border-b border-gray-800/80">
+ <td className="py-2.5 pr-4 font-mono text-xs text-gray-100">{m.model}</td>
+ <td className="py-2.5 pr-4 text-right text-gray-200 tabular-nums">
+ {fmtNumber(m.calls)}
+ </td>
+ <td className="py-2.5 pr-4 text-right text-gray-300 tabular-nums">
+ {fmtNumber(m.total_prompt_tokens)}
+ </td>
+ <td className="py-2.5 pr-4 text-right text-gray-300 tabular-nums">
+ {fmtNumber(m.total_completion_tokens)}
+ </td>
+ <td className="py-2.5 pr-4 text-right text-white tabular-nums">
+ {fmtUsd(m.total_cost_usd)}
+ </td>
+ <td className="py-2.5 pr-4 text-right text-gray-400 tabular-nums">
+ {fmtUsd(m.imputed_public_cost_usd)}
+ </td>
+ <td className="py-2.5 text-right text-gray-400 tabular-nums">
+ {fmtMs(m.avg_latency_ms)}
+ </td>
+ </tr>
+ ))}
+ </tbody>
+ </table>
+ </div>
+ )}
+ </Card>
+ );
+}
+
+function CasesAndActions({ data }: { data: CostDashboard }) {
+ return (
+ <section className="grid grid-cols-1 gap-4 lg:grid-cols-2">
+ <Card title="Top-cost investigations" subtitle="Cases ranked by recorded LLM spend in the window">
+ {data.top_cases.length === 0 ? (
+ <p className="text-sm text-gray-500">No case-attributed runs recorded for this window.</p>
+ ) : (
+ <ul className="divide-y divide-gray-800" data-testid="top-cases">
+ {data.top_cases.map((c) => (
+ <li key={c.case_id} className="flex items-center justify-between gap-3 py-2 text-sm">
+ <span className="truncate font-mono text-xs text-gray-200">{c.case_id}</span>
+ <span className="flex items-center gap-3">
+ <span className="text-xs text-gray-500 tabular-nums">
+ {fmtNumber(c.runs)} runs · {fmtNumber(c.total_tokens)} tokens
+ </span>
+ <span className="w-20 text-right text-white tabular-nums">{fmtUsd(c.total_cost_usd)}</span>
+ </span>
+ </li>
+ ))}
+ </ul>
+ )}
+ </Card>
+
+ <Card title="Top SOC actions" subtitle="Most-frequent audit-log actions (proxy for automation throughput)">
+ {data.action_counts.length === 0 ? (
+ <p className="text-sm text-gray-500">No audit events recorded for this window.</p>
+ ) : (
+ <ul className="divide-y divide-gray-800" data-testid="action-counts">
+ {data.action_counts.map((a) => (
+ <li key={a.action} className="flex items-center justify-between py-2 text-sm">
+ <span className="font-mono text-xs text-gray-200">{a.action}</span>
+ <span className="text-white tabular-nums">{fmtNumber(a.count)}</span>
+ </li>
+ ))}
+ </ul>
+ )}
+ </Card>
+ </section>
+ );
+}
+
+function ByokPanel({ data }: { data: CostDashboard }) {
+ const { byok_savings: b } = data;
+ const accent = b.is_byok_active
+ ? 'border-emerald-500/30 bg-emerald-950/20'
+ : 'border-gray-700 bg-gray-900';
+ const badge = b.is_byok_active
+ ? { text: 'BYOK active', cls: 'bg-emerald-500/20 text-emerald-200' }
+ : { text: 'Hosted provider', cls: 'bg-gray-700/60 text-gray-300' };
+
+ return (
+ <section
+ className={`rounded-xl border p-5 ${accent}`}
+ data-testid="byok-panel"
+ data-byok={b.is_byok_active ? 'active' : 'inactive'}
+ >
+ <div className="flex flex-wrap items-start justify-between gap-3">
+ <div>
+ <p className="text-xs uppercase tracking-wide text-gray-400">BYOK savings</p>
+ <p className="mt-1 text-lg font-semibold text-white">
+ {b.is_byok_active
+ ? `~${fmtUsd(b.savings_usd)} saved by running your own model`
+ : `Hosted via ${b.provider} — no local-model savings to attribute`}
+ </p>
+ </div>
+ <span className={`rounded-full px-3 py-1 text-xs font-medium ${badge.cls}`}>{badge.text}</span>
+ </div>
+ <dl className="mt-4 grid grid-cols-1 gap-4 text-sm sm:grid-cols-3">
+ <Stat label="Recorded cost" value={fmtUsd(b.recorded_cost_usd)} />
+ <Stat label="Imputed list-price cost" value={fmtUsd(b.imputed_public_cost_usd)} />
+ <Stat
+ label="Estimated savings"
+ value={fmtUsd(b.savings_usd)}
+ accent={b.is_byok_active ? 'text-emerald-300' : 'text-gray-300'}
+ />
+ </dl>
+ <p className="mt-4 text-xs text-gray-500">
+ Imputed cost re-prices recorded prompt + completion tokens against each model&apos;s public list
+ price. Savings approximate what an equivalent hosted call would have cost — not a billing-grade
+ figure.
+ </p>
+ </section>
+ );
+}
+
+// ── Local primitives (mirror ExecutiveDigest for visual consistency) ───────
+
+function Card({
+ title,
+ subtitle,
+ children,
+}: {
+ title: string;
+ subtitle?: string;
+ children: React.ReactNode;
+}) {
+ return (
+ <div className="rounded-xl border border-gray-700 bg-gray-900 p-5">
+ <div className="mb-4">
+ <h2 className="text-base font-semibold text-white">{title}</h2>
+ {subtitle && <p className="mt-0.5 text-xs text-gray-500">{subtitle}</p>}
+ </div>
+ {children}
+ </div>
+ );
+}
+
+function KpiCard({
+ label,
+ value,
+ sub,
+}: {
+ label: string;
+ value: number | string;
+ sub?: string;
+}) {
+ return (
+ <div className="rounded-lg border border-gray-700 bg-gray-800 p-4">
+ <p className="text-xs text-gray-400">{label}</p>
+ <p className="mt-1 text-2xl font-semibold text-white tabular-nums">{value}</p>
+ {sub && <p className="mt-1 text-xs text-gray-500">{sub}</p>}
+ </div>
+ );
+}
+
+function Stat({
+ label,
+ value,
+ accent,
+}: {
+ label: string;
+ value: number | string;
+ accent?: string;
+}) {
+ return (
+ <div>
+ <dt className="text-xs text-gray-500">{label}</dt>
+ <dd className={`mt-1 text-xl font-semibold tabular-nums ${accent ?? 'text-white'}`}>{value}</dd>
+ </div>
+ );
+}
diff --git a/apps/web/src/components/layout/Sidebar.tsx b/apps/web/src/components/layout/Sidebar.tsx
index 604bf6764..6a28cbe6b 100644
--- a/apps/web/src/components/layout/Sidebar.tsx
+++ b/apps/web/src/components/layout/Sidebar.tsx
@@ -122,6 +122,12 @@ const DocumentReportIcon = () => (
</svg>
);
+const CurrencyIcon = () => (
+ <svg className="w-5 h-5" fill="none" viewBox="0 0 24 24" stroke="currentColor">
+ <path strokeLinecap="round" strokeLinejoin="round" strokeWidth={1.5} d="M12 6v12m-3-2.818l.879.659c1.171.879 3.07.879 4.242 0 1.172-.879 1.172-2.303 0-3.182C13.536 12.219 12.768 12 12 12c-.725 0-1.45-.22-2.003-.659-1.106-.879-1.106-2.303 0-3.182s2.9-.879 4.006 0l.415.33M21 12a9 9 0 11-18 0 9 9 0 0118 0z" />
+ </svg>
+);
+
const navSections: NavSection[] = [
{
items: [
@@ -282,6 +288,11 @@ const navSections: NavSection[] = [
href: '/reports/digest',
icon: <DocumentReportIcon />,
},
+ {
+ label: 'Cost Dashboard',
+ href: '/costs',
+ icon: <CurrencyIcon />,
+ },
{
label: 'Audit Log',
href: '/audit',
diff --git a/apps/web/src/lib/api.ts b/apps/web/src/lib/api.ts
index 276c6f95d..23f366806 100644
--- a/apps/web/src/lib/api.ts
+++ b/apps/web/src/lib/api.ts
@@ -3424,6 +3424,120 @@ export const reportsApi = {
},
};
+// ─── Cost dashboard (WS-H1) ─────────────────────────────────────────────────
+
+export interface DashboardPeriod {
+ /** ISO timestamp marking the start of the rolling window (inclusive). */
+ start: string;
+ /** ISO timestamp marking the end of the window (exclusive, i.e. now()). */
+ end: string;
+ /** Width of the window in days, derived from start/end. */
+ window_days: number;
+ /** Human-readable label, e.g. "Apr 9 – May 9, 2026". */
+ label: string;
+}
+
+export interface CostHeadline {
+ /** Sum of recorded LLM cost in USD over the window. */
+ total_cost_usd: number;
+ /** Sum of prompt + completion tokens. */
+ total_tokens: number;
+ /** Total LLM API call count (one row in aisoc_run_costs ≈ one call). */
+ total_calls: number;
+ /** Distinct investigation_runs that produced cost in the window. */
+ total_runs: number;
+ /** Mean cost per run; null when no runs landed in the window. */
+ avg_cost_per_run_usd: number | null;
+}
+
+export interface CostBucket {
+ /** Calendar day in UTC, ISO ``YYYY-MM-DD``. */
+ day: string;
+ total_cost_usd: number;
+ total_tokens: number;
+ call_count: number;
+}
+
+export interface ModelBreakdown {
+ /** Lowercased model id, e.g. ``gpt-4o-mini``. */
+ model: string;
+ runs: number;
+ calls: number;
+ total_prompt_tokens: number;
+ total_completion_tokens: number;
+ total_cost_usd: number;
+ /** What this volume would have cost on the public list price. */
+ imputed_public_cost_usd: number;
+ avg_latency_ms: number | null;
+}
+
+export interface TopCostCase {
+ case_id: string;
+ runs: number;
+ total_cost_usd: number;
+ total_tokens: number;
+}
+
+export interface ActionCount {
+ /** ``cases:read``, ``alerts:write``, etc. — straight from audit_log.action. */
+ action: string;
+ count: number;
+}
+
+export interface ByokSavings {
+ /** True iff the current LLM provider is loopback / private (BYOK active). */
+ is_byok_active: boolean;
+ /** Provider id from /llm/status (e.g. ``openai``, ``local-ollama``). */
+ provider: string;
+ /** Recorded cost — what the cost tracker actually booked. */
+ recorded_cost_usd: number;
+ /** Re-priced cost using public list pricing (BYOK-neutral baseline). */
+ imputed_public_cost_usd: number;
+ /**
+ * Estimated savings vs hosted: equals imputed_public_cost on BYOK,
+ * ``max(imputed - recorded, 0)`` otherwise.
+ */
+ savings_usd: number;
+}
+
+export interface CostDashboard {
+ tenant_id: string;
+ period: DashboardPeriod;
+ headline: CostHeadline;
+ daily_costs: CostBucket[];
+ by_model: ModelBreakdown[];
+ top_cases: TopCostCase[];
+ action_counts: ActionCount[];
+ byok_savings: ByokSavings;
+}
+
+/**
+ * Query parameters for the cost-dashboard endpoint. Declared as a `type`
+ * (not interface) so it satisfies the request helper's
+ * `Record<string, string | number | boolean | undefined>` constraint.
+ */
+export type CostDashboardParams = {
+ /**
+ * Rolling window in days. The API clamps to ``[1, 365]`` and defaults
+ * to 30 — leaving this unset is the right call for the default view.
+ */
+ window_days?: number;
+};
+
+export const costsApi = {
+ /**
+ * WS-H1 — fetch the cost dashboard snapshot for the current tenant.
+ *
+ * Backs the admin cost dashboard at ``apps/web/src/app/(admin)/costs``.
+ * Requires the ``reports:read`` permission server-side (granted to
+ * tenant_admin / soc_lead / soc_analyst / threat_hunter / viewer), so
+ * the page is gated by the same role bar that protects the executive
+ * digest.
+ */
+ dashboard: (params: CostDashboardParams = {}) =>
+ request<CostDashboard>('/api/v1/costs/dashboard', { params }),
+};
+
// ─── Audit log / compliance bundle helpers ──────────────────────────────────
/**
@@ -3597,4 +3711,5 @@ export default {
feedback: feedbackApi,
deployment: deploymentApi,
reports: reportsApi,
+ costs: costsApi,
};
diff --git a/services/api/app/api/v1/endpoints/costs.py b/services/api/app/api/v1/endpoints/costs.py
new file mode 100644
index 000000000..fb6200dae
--- /dev/null
+++ b/services/api/app/api/v1/endpoints/costs.py
@@ -0,0 +1,116 @@
+"""Cost dashboard API endpoints.
+
+WS-H1 — buyer-value plan
+========================
+
+Backs the admin cost dashboard at ``apps/web/src/app/(admin)/costs/`` with a
+single consolidated read endpoint. The actual aggregation lives in
+``app.services.cost_dashboard`` so the SQL surface stays there and the
+endpoint is just a thin tenant-scoping + permission layer.
+
+Why a new router instead of extending ``investigations.py``?
+------------------------------------------------------------
+
+``GET /api/v1/investigations/costs/aggregate`` is a per-run breakdown for an
+analyst drilling into a single investigation. The dashboard answers a
+fundamentally different question — "where is *all* my LLM money going across
+my whole tenant, day by day?" — and pulls in audit_log + LLM provider
+context that ``investigations.py`` has no business knowing about. Keeping
+the surfaces separate keeps each endpoint cohesive.
+
+Permissions
+-----------
+
+The dashboard is a financial-oversight surface, so we gate it behind
+``reports:read``. ``platform_admin`` and ``tenant_admin`` always see it via
+the static role table; ``soc_lead`` and analysts inherit it because they
+already get ``reports:read``. Viewers also get it (read-only).
+"""
+
+from __future__ import annotations
+
+from typing import Annotated
+
+from fastapi import APIRouter, Depends, HTTPException, Query, status
+
+from app.api.v1.deps import AuthUser, require_permission
+from app.api.v1.endpoints.llm_status import llm_status
+from app.db.rls import TenantDBSession
+from app.services.cost_dashboard import CostDashboard, build_cost_dashboard
+
+router = APIRouter(prefix="/costs", tags=["costs"])
+
+# Bound the dashboard window so a malformed query parameter cannot trigger an
+# unbounded aggregate scan. 365 days covers every realistic operator question
+# ("annual review") without letting a typo turn the dashboard into a DoS.
+_MIN_WINDOW_DAYS = 1
+_MAX_WINDOW_DAYS = 365
+_DEFAULT_WINDOW_DAYS = 30
+
+
+ "/dashboard",
+ response_model=CostDashboard,
+ summary="LLM spend, action counts, top-cost cases, and BYOK savings for the tenant",
+)
+async def get_cost_dashboard(
+ current_user: Annotated[AuthUser, Depends(require_permission("reports:read"))],
+ db: TenantDBSession,
+ window_days: int = Query(
+ default=_DEFAULT_WINDOW_DAYS,
+ ge=_MIN_WINDOW_DAYS,
+ le=_MAX_WINDOW_DAYS,
+ description=(
+ "Rolling window in days. Counts back from now() (UTC). "
+ "Defaults to the last 30 days; capped at 365."
+ ),
+ ),
+) -> CostDashboard:
+ """Return a deterministic snapshot of cost, activity, and BYOK savings.
+
+ The response covers the rolling ``window_days``-long window ending at
+ ``now()`` (UTC) and includes:
+
+ * **headline** — total spend / tokens / calls / runs and average
+ cost-per-run across the window.
+ * **daily_costs** — per-day buckets so the UI can plot a trend line.
+ * **by_model** — spend, tokens, runs, and average latency per model
+ with the imputed public-list cost for context.
+ * **top_cases** — the most expensive ``case_id`` values, the closest
+ proxy AiSOC has for "top-cost playbook runs" since each playbook
+ run lives under a case (no separate ``playbook_runs`` table).
+ * **action_counts** — ``audit_log`` action distribution so operators
+ can see how much SOC activity their LLM spend is buying.
+ * **byok_savings** — imputed delta between recorded cost and public
+ list pricing. ``is_byok_active`` reflects whether the live LLM
+ provider is loopback / private (per ``/llm/status``).
+
+ Tenant scoping is enforced by ``TenantDBSession`` (Postgres RLS sets
+ ``app.current_tenant_id``) plus an explicit ``tenant_id`` predicate in
+ the underlying query, so the same payload is safe to render for any
+ role with ``reports:read``.
+ """
+ if window_days < _MIN_WINDOW_DAYS or window_days > _MAX_WINDOW_DAYS:
+ # FastAPI's ge/le already short-circuits this for the typical
+ # request, but defence-in-depth: a tampered router or programmatic
+ # caller cannot bypass the clamp.
+ raise HTTPException(
+ status_code=status.HTTP_400_BAD_REQUEST,
+ detail=(
+ f"window_days must be between {_MIN_WINDOW_DAYS} and "
+ f"{_MAX_WINDOW_DAYS}"
+ ),
+ )
+
+ # Pull the live LLM provider snapshot from the same code path the
+ # /llm/status endpoint uses, so the BYOK panel cannot drift from the
+ # provider indicator the operator sees in Settings.
+ llm = llm_status()
+
+ return await build_cost_dashboard(
+ db,
+ current_user.tenant_id,
+ window_days=window_days,
+ llm_provider=str(llm.get("provider") or "unknown"),
+ is_local=bool(llm.get("is_local")),
+ )
diff --git a/services/api/app/api/v1/router.py b/services/api/app/api/v1/router.py
index e4af8ddf6..c2bbf03d8 100644
--- a/services/api/app/api/v1/router.py
+++ b/services/api/app/api/v1/router.py
@@ -16,6 +16,7 @@ from app.api.v1.endpoints import (
community,
compliance,
connectors,
+ costs,
deployment,
detection_compat,
detection_loop,
@@ -90,6 +91,12 @@ api_router.include_router(metrics.router)
api_router.include_router(sla.router)
api_router.include_router(investigations.router)
+# Cost dashboard — WS-H1 (buyer-value plan).
+# Aggregates LLM spend / token volume from aisoc_run_costs joined with
+# investigation_runs, plus action counts from audit_log and BYOK savings
+# imputed from public list pricing. Backs apps/web/src/app/(admin)/costs.
+api_router.include_router(costs.router)
+
# Mobile responder PWA (Phase 4B)
api_router.include_router(push.router)
api_router.include_router(oncall.router)
diff --git a/services/api/app/services/cost_dashboard.py b/services/api/app/services/cost_dashboard.py
new file mode 100644
index 000000000..46cd9698e
--- /dev/null
+++ b/services/api/app/services/cost_dashboard.py
@@ -0,0 +1,582 @@
+"""Cost dashboard builder.
+
+WS-H1 — buyer-value plan
+========================
+Produces a deterministic snapshot of LLM spend, automation activity and
+BYOK savings for a tenant over a fixed window (default: last 30 days).
+
+The output backs the admin cost dashboard at
+``apps/web/src/app/(admin)/costs/`` and answers:
+
+ * Where is my LLM money going? (daily time-series + per-model breakdown)
+ * Which investigations are the most expensive? (top-cost cases)
+ * How much SOC activity am I getting for that money? (action counts)
+ * Am I saving money by running my own model? (BYOK imputed savings)
+
+Following the WS-G2 pattern, the module splits into:
+
+ 1. ``build_dashboard_from_rows`` — a *pure* function that consumes
+ pre-fetched rows and emits a ``CostDashboard``. Fully deterministic
+ and tested without a database.
+
+ 2. ``build_cost_dashboard`` — a thin async orchestrator that runs the
+ SQL queries and forwards rows into the pure builder.
+
+BYOK savings are *imputed*: we re-price every recorded prompt+completion
+token pair against the public list price for the model that handled it
+(``cost_telemetry._PRICING``). When the runtime LLM is local
+(``llm_status().is_local``), the difference between imputed cost and
+recorded cost approximates what the operator would have paid a hosted
+provider had they not brought their own key. We never claim this is a
+billing-grade number — the response carries an ``is_byok_active`` flag so
+the UI can label the panel accordingly.
+"""
+
+from __future__ import annotations
+
+import uuid
+from collections import Counter, defaultdict
+from dataclasses import dataclass, field
+from datetime import UTC, date, datetime, timedelta
+from typing import Any
+
+from pydantic import BaseModel, Field
+from sqlalchemy import text
+from sqlalchemy.ext.asyncio import AsyncSession
+
+
+# ---------------------------------------------------------------------------
+# Public list pricing for BYOK imputation.
+#
+# Mirrors ``services/agents/app/core/cost_telemetry._PRICING`` but lives
+# here too so the API service doesn't need to import from the agents
+# package (different deploy unit, no cross-import in production).
+# Prices are USD per 1k tokens, (input, output).
+# ---------------------------------------------------------------------------
+
+_PUBLIC_PRICING: dict[str, tuple[float, float]] = {
+ "gpt-4o": (0.005, 0.015),
+ "gpt-4o-mini": (0.00015, 0.0006),
+ "gpt-4-turbo": (0.01, 0.03),
+ "gpt-4": (0.03, 0.06),
+ "gpt-3.5-turbo": (0.0005, 0.0015),
+ "claude-3-5-sonnet-20241022": (0.003, 0.015),
+ "claude-3-opus-20240229": (0.015, 0.075),
+ "claude-3-haiku-20240307": (0.00025, 0.00125),
+ "gemini-1.5-pro": (0.00125, 0.005),
+ "gemini-1.5-flash": (0.000075, 0.0003),
+}
+
+# Conservative default for unknown models so we don't claim massive
+# savings on a bespoke local model that has no public list price.
+_DEFAULT_PUBLIC_PRICING: tuple[float, float] = (0.001, 0.002)
+
+
+def _impute_public_cost(
+ model: str,
+ prompt_tokens: int,
+ completion_tokens: int,
+) -> float:
+ """Return what ``model`` would cost on its public list price."""
+ in_price, out_price = _PUBLIC_PRICING.get(
+ (model or "").lower(),
+ _DEFAULT_PUBLIC_PRICING,
+ )
+ return round(
+ (max(prompt_tokens, 0) / 1000) * in_price
+ + (max(completion_tokens, 0) / 1000) * out_price,
+ 6,
+ )
+
+
+# ---------------------------------------------------------------------------
+# Output schemas (Pydantic) — what the endpoint returns.
+# ---------------------------------------------------------------------------
+
+
+class DashboardPeriod(BaseModel):
+ start: datetime
+ end: datetime
+ window_days: int
+ label: str
+
+
+class CostBucket(BaseModel):
+ """LLM spend bucketed by day."""
+
+ day: date
+ total_cost_usd: float
+ total_tokens: int
+ call_count: int
+
+
+class ModelBreakdown(BaseModel):
+ """Spend / volume rolled up per model over the window."""
+
+ model: str
+ runs: int
+ calls: int
+ total_prompt_tokens: int
+ total_completion_tokens: int
+ total_cost_usd: float
+ imputed_public_cost_usd: float
+ avg_latency_ms: float | None
+
+
+class TopCostCase(BaseModel):
+ """The most expensive cases over the window.
+
+ Top-cost playbooks ≈ top-cost cases in the AiSOC data model: a
+ case is the unit of work an analyst (or playbook) drives, and
+ ``investigation_runs.case_id`` is the only stable join we can make
+ between LLM cost and "what was this money spent on?".
+ """
+
+ case_id: str
+ runs: int
+ total_cost_usd: float
+ total_tokens: int
+
+
+class ActionCount(BaseModel):
+ """How many of each kind of action SOC operators took."""
+
+ action: str
+ count: int
+
+
+class ByokSavings(BaseModel):
+ """Imputed savings vs hosted pricing.
+
+ ``is_byok_active`` is True when the live LLM provider (per
+ ``/llm/status``) is loopback or private — i.e. the operator is
+ actually running their own model. When False, the savings are still
+ computed (so the UI can show "if you switched to BYOK, you'd save
+ ~X") but should be labelled "potential savings" in the UI.
+ """
+
+ is_byok_active: bool
+ provider: str
+ recorded_cost_usd: float
+ imputed_public_cost_usd: float
+ savings_usd: float
+
+
+class CostHeadline(BaseModel):
+ total_cost_usd: float
+ total_tokens: int
+ total_calls: int
+ total_runs: int
+ avg_cost_per_run_usd: float | None
+
+
+class CostDashboard(BaseModel):
+ """Top-level deterministic snapshot."""
+
+ tenant_id: uuid.UUID
+ period: DashboardPeriod
+ headline: CostHeadline
+ daily_costs: list[CostBucket] = Field(default_factory=list)
+ by_model: list[ModelBreakdown] = Field(default_factory=list)
+ top_cases: list[TopCostCase] = Field(default_factory=list)
+ action_counts: list[ActionCount] = Field(default_factory=list)
+ byok_savings: ByokSavings
+
+
+# ---------------------------------------------------------------------------
+# Pure-data input rows.
+# ---------------------------------------------------------------------------
+
+
+@dataclass(frozen=True)
+class CostRow:
+ """One ``aisoc_run_costs`` row joined with its investigation_run."""
+
+ run_id: str
+ case_id: str
+ model: str
+ prompt_tokens: int
+ completion_tokens: int
+ cost_usd: float
+ latency_ms: float
+ call_count: int
+ started_at: datetime
+
+
+@dataclass(frozen=True)
+class AuditRow:
+ """One ``audit_log`` row reduced to its action."""
+
+ action: str
+
+
+@dataclass(frozen=True)
+class LlmContext:
+ """Live LLM provider snapshot (subset of ``llm_status()``)."""
+
+ provider: str
+ is_local: bool
+
+
+@dataclass
+class DashboardInputs:
+ """Bundle of pre-fetched rows for a tenant + period."""
+
+ tenant_id: uuid.UUID
+ period_start: datetime
+ period_end: datetime
+ cost_rows: list[CostRow] = field(default_factory=list)
+ audit_rows: list[AuditRow] = field(default_factory=list)
+ llm: LlmContext = field(
+ default_factory=lambda: LlmContext(provider="none", is_local=False)
+ )
+
+
+# ---------------------------------------------------------------------------
+# Pure helpers (independently unit-tested).
+# ---------------------------------------------------------------------------
+
+
+def _format_period_label(start: datetime, end: datetime) -> str:
+ """Render a human-friendly span like "Apr 9 – May 9, 2026"."""
+ same_year = start.year == end.year
+ same_month = same_year and start.month == end.month
+ if same_month:
+ return f"{start.strftime('%b %-d')} – {end.strftime('%-d, %Y')}"
+ if same_year:
+ return f"{start.strftime('%b %-d')} – {end.strftime('%b %-d, %Y')}"
+ return f"{start.strftime('%b %-d, %Y')} – {end.strftime('%b %-d, %Y')}"
+
+
+def _bucket_by_day(rows: list[CostRow]) -> list[CostBucket]:
+ """Group cost rows by UTC calendar date, ascending."""
+ buckets: dict[date, dict[str, float]] = defaultdict(
+ lambda: {"cost": 0.0, "tokens": 0, "calls": 0}
+ )
+ for r in rows:
+ d = r.started_at.astimezone(UTC).date()
+ b = buckets[d]
+ b["cost"] += r.cost_usd
+ b["tokens"] += r.prompt_tokens + r.completion_tokens
+ b["calls"] += r.call_count
+ return [
+ CostBucket(
+ day=d,
+ total_cost_usd=round(buckets[d]["cost"], 4),
+ total_tokens=int(buckets[d]["tokens"]),
+ call_count=int(buckets[d]["calls"]),
+ )
+ for d in sorted(buckets)
+ ]
+
+
+def _model_breakdown(rows: list[CostRow]) -> list[ModelBreakdown]:
+ """Aggregate rows per model, sorted by spend descending."""
+ by_model: dict[str, dict[str, Any]] = defaultdict(
+ lambda: {
+ "runs": set(),
+ "calls": 0,
+ "prompt": 0,
+ "completion": 0,
+ "cost": 0.0,
+ "imputed": 0.0,
+ "latency_ms": 0.0,
+ }
+ )
+ for r in rows:
+ m = (r.model or "unknown").lower()
+ agg = by_model[m]
+ agg["runs"].add(r.run_id)
+ agg["calls"] += r.call_count
+ agg["prompt"] += r.prompt_tokens
+ agg["completion"] += r.completion_tokens
+ agg["cost"] += r.cost_usd
+ agg["imputed"] += _impute_public_cost(
+ m, r.prompt_tokens, r.completion_tokens
+ )
+ agg["latency_ms"] += r.latency_ms
+
+ breakdowns = [
+ ModelBreakdown(
+ model=m,
+ runs=len(agg["runs"]),
+ calls=int(agg["calls"]),
+ total_prompt_tokens=int(agg["prompt"]),
+ total_completion_tokens=int(agg["completion"]),
+ total_cost_usd=round(agg["cost"], 4),
+ imputed_public_cost_usd=round(agg["imputed"], 4),
+ avg_latency_ms=(
+ round(agg["latency_ms"] / agg["calls"], 2)
+ if agg["calls"]
+ else None
+ ),
+ )
+ for m, agg in by_model.items()
+ ]
+ breakdowns.sort(key=lambda b: (-b.total_cost_usd, b.model))
+ return breakdowns
+
+
+def _top_cases(rows: list[CostRow], *, limit: int = 10) -> list[TopCostCase]:
+ """The most expensive cases in the window."""
+ by_case: dict[str, dict[str, Any]] = defaultdict(
+ lambda: {"runs": set(), "cost": 0.0, "tokens": 0}
+ )
+ for r in rows:
+ if not r.case_id:
+ continue
+ agg = by_case[r.case_id]
+ agg["runs"].add(r.run_id)
+ agg["cost"] += r.cost_usd
+ agg["tokens"] += r.prompt_tokens + r.completion_tokens
+
+ items = [
+ TopCostCase(
+ case_id=case_id,
+ runs=len(agg["runs"]),
+ total_cost_usd=round(agg["cost"], 4),
+ total_tokens=int(agg["tokens"]),
+ )
+ for case_id, agg in by_case.items()
+ ]
+ items.sort(key=lambda c: (-c.total_cost_usd, c.case_id))
+ return items[:limit]
+
+
+def _action_counts(rows: list[AuditRow], *, limit: int = 20) -> list[ActionCount]:
+ """How many of each action were recorded over the window."""
+ counter: Counter[str] = Counter(r.action for r in rows if r.action)
+ return [
+ ActionCount(action=a, count=c)
+ for a, c in counter.most_common(limit)
+ ]
+
+
+def _byok_savings(rows: list[CostRow], llm: LlmContext) -> ByokSavings:
+ """Imputed savings vs hosted public pricing.
+
+ The ``recorded_cost_usd`` reflects what the cost tracker actually
+ booked: on a hosted provider this is the public price, on a local
+ BYOK provider this is the *imputed* price (the agents service uses
+ the same pricing table when no upstream billing exists, so on
+ BYOK the recorded cost typically already matches imputed and the
+ delta is small or zero).
+
+ Therefore on BYOK we report ``savings = imputed_public`` (i.e. the
+ operator avoided paying the hosted provider entirely). On a hosted
+ provider we report ``savings = max(imputed - recorded, 0)`` so the
+ UI can still surface a "you'd save X if you self-hosted" hint.
+ """
+ recorded = sum(r.cost_usd for r in rows)
+ imputed = sum(
+ _impute_public_cost(r.model, r.prompt_tokens, r.completion_tokens)
+ for r in rows
+ )
+ if llm.is_local:
+ savings = imputed
+ else:
+ savings = max(imputed - recorded, 0.0)
+ return ByokSavings(
+ is_byok_active=bool(llm.is_local),
+ provider=llm.provider or "unknown",
+ recorded_cost_usd=round(recorded, 4),
+ imputed_public_cost_usd=round(imputed, 4),
+ savings_usd=round(savings, 4),
+ )
+
+
+def _headline(rows: list[CostRow]) -> CostHeadline:
+ total_cost = sum(r.cost_usd for r in rows)
+ total_tokens = sum(r.prompt_tokens + r.completion_tokens for r in rows)
+ total_calls = sum(r.call_count for r in rows)
+ total_runs = len({r.run_id for r in rows if r.run_id})
+ return CostHeadline(
+ total_cost_usd=round(total_cost, 4),
+ total_tokens=int(total_tokens),
+ total_calls=int(total_calls),
+ total_runs=total_runs,
+ avg_cost_per_run_usd=(
+ round(total_cost / total_runs, 4) if total_runs else None
+ ),
+ )
+
+
+# ---------------------------------------------------------------------------
+# Pure top-level builder.
+# ---------------------------------------------------------------------------
+
+
+def build_dashboard_from_rows(inputs: DashboardInputs) -> CostDashboard:
+ """Pure function: rows in → CostDashboard out. Deterministic."""
+ window_days = max(
+ int(round((inputs.period_end - inputs.period_start).total_seconds() / 86400)),
+ 1,
+ )
+ period = DashboardPeriod(
+ start=inputs.period_start,
+ end=inputs.period_end,
+ window_days=window_days,
+ label=_format_period_label(inputs.period_start, inputs.period_end),
+ )
+ return CostDashboard(
+ tenant_id=inputs.tenant_id,
+ period=period,
+ headline=_headline(inputs.cost_rows),
+ daily_costs=_bucket_by_day(inputs.cost_rows),
+ by_model=_model_breakdown(inputs.cost_rows),
+ top_cases=_top_cases(inputs.cost_rows),
+ action_counts=_action_counts(inputs.audit_rows),
+ byok_savings=_byok_savings(inputs.cost_rows, inputs.llm),
+ )
+
+
+# ---------------------------------------------------------------------------
+# DB orchestrator — the only place SQL lives.
+# ---------------------------------------------------------------------------
+
+
+_COST_QUERY = text(
+ """
+ SELECT c.run_id,
+ r.case_id,
+ c.model,
+ c.total_prompt_tokens AS prompt_tokens,
+ c.total_completion_tokens AS completion_tokens,
+ c.total_cost_usd AS cost_usd,
+ c.total_latency_ms AS latency_ms,
+ c.call_count AS call_count,
+ r.started_at AS started_at
+ FROM aisoc_run_costs c
+ JOIN investigation_runs r ON r.id::text = c.run_id
+ WHERE r.tenant_id = :tenant_id
+ AND r.started_at >= :start_at
+ AND r.started_at < :end_at
+ """
+)
+
+
+_AUDIT_QUERY = text(
+ """
+ SELECT action
+ FROM audit_log
+ WHERE tenant_id = :tenant_id
+ AND created_at >= :start_at
+ AND created_at < :end_at
+ """
+)
+
+
+async def _fetch_cost_rows(
+ db: AsyncSession,
+ tenant_id: uuid.UUID,
+ start: datetime,
+ end: datetime,
+) -> list[CostRow]:
+ result = await db.execute(
+ _COST_QUERY,
+ {"tenant_id": str(tenant_id), "start_at": start, "end_at": end},
+ )
+ rows: list[CostRow] = []
+ for r in result.mappings():
+ started_at = r["started_at"]
+ if started_at is not None and started_at.tzinfo is None:
+ started_at = started_at.replace(tzinfo=UTC)
+ rows.append(
+ CostRow(
+ run_id=str(r["run_id"]),
+ case_id=str(r["case_id"] or ""),
+ model=str(r["model"] or "unknown"),
+ prompt_tokens=int(r["prompt_tokens"] or 0),
+ completion_tokens=int(r["completion_tokens"] or 0),
+ cost_usd=float(r["cost_usd"] or 0.0),
+ latency_ms=float(r["latency_ms"] or 0.0),
+ call_count=int(r["call_count"] or 0),
+ started_at=started_at or end,
+ )
+ )
+ return rows
+
+
+async def _fetch_audit_rows(
+ db: AsyncSession,
+ tenant_id: uuid.UUID,
+ start: datetime,
+ end: datetime,
+) -> list[AuditRow]:
+ result = await db.execute(
+ _AUDIT_QUERY,
+ {"tenant_id": str(tenant_id), "start_at": start, "end_at": end},
+ )
+ return [AuditRow(action=str(r["action"] or "")) for r in result.mappings()]
+
+
+async def build_cost_dashboard(
+ db: AsyncSession,
+ tenant_id: uuid.UUID,
+ *,
+ window_days: int = 30,
+ period_end: datetime | None = None,
+ llm_provider: str | None = None,
+ is_local: bool | None = None,
+) -> CostDashboard:
+ """Async orchestrator: query the tenant DB and build a ``CostDashboard``.
+
+ ``window_days`` is clamped to ``[1, 365]`` so a malformed query
+ parameter cannot cause an unbounded scan. ``llm_provider`` /
+ ``is_local`` come from ``llm_status()`` and are threaded through so
+ the BYOK panel reports against the real runtime config.
+ """
+ if window_days < 1:
+ window_days = 1
+ if window_days > 365:
+ window_days = 365
+
+ end = period_end or datetime.now(UTC)
+ start = end - timedelta(days=window_days)
+
+ cost_rows = await _fetch_cost_rows(db, tenant_id, start, end)
+ audit_rows = await _fetch_audit_rows(db, tenant_id, start, end)
+
+ inputs = DashboardInputs(
+ tenant_id=tenant_id,
+ period_start=start,
+ period_end=end,
+ cost_rows=cost_rows,
+ audit_rows=audit_rows,
+ llm=LlmContext(
+ provider=llm_provider or "unknown",
+ is_local=bool(is_local),
+ ),
+ )
+ return build_dashboard_from_rows(inputs)
+
+
+__all__ = [
+ "ActionCount",
+ "AuditRow",
+ "ByokSavings",
+ "CostBucket",
+ "CostDashboard",
+ "CostHeadline",
+ "CostRow",
+ "DashboardInputs",
+ "DashboardPeriod",
+ "LlmContext",
+ "ModelBreakdown",
+ "TopCostCase",
+ "build_cost_dashboard",
+ "build_dashboard_from_rows",
+]
+
+
+# Internal helpers exported for tests.
+_internal_helpers: dict[str, Any] = {
+ "_format_period_label": _format_period_label,
+ "_bucket_by_day": _bucket_by_day,
+ "_model_breakdown": _model_breakdown,
+ "_top_cases": _top_cases,
+ "_action_counts": _action_counts,
+ "_byok_savings": _byok_savings,
+ "_headline": _headline,
+ "_impute_public_cost": _impute_public_cost,
+}
diff --git a/services/api/tests/test_cost_dashboard.py b/services/api/tests/test_cost_dashboard.py
new file mode 100644
index 000000000..4f1c6c952
--- /dev/null
+++ b/services/api/tests/test_cost_dashboard.py
@@ -0,0 +1,444 @@
+"""Tests for WS-H1 — cost dashboard builder.
+
+The cost dashboard splits into a pure ``build_dashboard_from_rows`` and a
+thin async DB orchestrator. We exercise the pure builder against
+deterministic input rows so the regression surface is the actual aggregation
+logic and not Postgres / SQLAlchemy plumbing.
+
+The tests deliberately cover:
+
+* daily bucketing across UTC midnight (timezone correctness)
+* per-model aggregation, including unknown models that fall back to the
+ default public-list price
+* top-cost case ranking with ties broken deterministically by ``case_id``
+* action-count ordering (most-common first) and the limit clamp
+* BYOK savings semantics:
+ - hosted provider with no recorded cost → zero or modest delta
+ - local provider → full imputed cost reported as savings
+* headline averages on empty input (no division by zero)
+* window clamping inside the orchestrator boundary helper
+"""
+
+from __future__ import annotations
+
+import uuid
+from datetime import UTC, datetime, timedelta
+
+import pytest
+
+from app.services.cost_dashboard import (
+ AuditRow,
+ CostRow,
+ DashboardInputs,
+ LlmContext,
+ _impute_public_cost,
+ _internal_helpers,
+ build_dashboard_from_rows,
+)
+
+PERIOD_START = datetime(2026, 5, 2, 0, 0, tzinfo=UTC)
+PERIOD_END = datetime(2026, 5, 9, 0, 0, tzinfo=UTC)
+TENANT_ID = uuid.uuid4()
+
+
+def _cost(
+ *,
+ run_id: str | None = None,
+ case_id: str = "CASE-1",
+ model: str = "gpt-4o-mini",
+ prompt_tokens: int = 1000,
+ completion_tokens: int = 500,
+ cost_usd: float | None = None,
+ latency_ms: float = 250.0,
+ call_count: int = 1,
+ started_at: datetime | None = None,
+) -> CostRow:
+ """Builder that fills sensible defaults for a CostRow.
+
+ When ``cost_usd`` is omitted we fall back to the imputed public cost so a
+ test that wants "what a hosted call would have charged" can drop into
+ the constructor without recomputing pricing by hand.
+ """
+ if cost_usd is None:
+ cost_usd = _impute_public_cost(model, prompt_tokens, completion_tokens)
+ return CostRow(
+ run_id=run_id or str(uuid.uuid4()),
+ case_id=case_id,
+ model=model,
+ prompt_tokens=prompt_tokens,
+ completion_tokens=completion_tokens,
+ cost_usd=cost_usd,
+ latency_ms=latency_ms,
+ call_count=call_count,
+ started_at=started_at or PERIOD_START + timedelta(hours=1),
+ )
+
+
+# ---------------------------------------------------------------------------
+# Pricing / imputation
+# ---------------------------------------------------------------------------
+
+
+def test_impute_public_cost_known_model() -> None:
+ # gpt-4o-mini: $0.00015 / 1k input, $0.0006 / 1k output
+ cost = _impute_public_cost("gpt-4o-mini", 1000, 500)
+ assert cost == pytest.approx(0.00015 + 0.0003, rel=1e-9)
+
+
+def test_impute_public_cost_unknown_model_uses_default() -> None:
+ # Unknown model falls back to the conservative default, not zero, so we
+ # never silently report 100% savings on a bespoke local model.
+ cost = _impute_public_cost("super-secret-llm", 1000, 1000)
+ assert cost > 0
+
+
+def test_impute_public_cost_negative_token_counts_clamped() -> None:
+ # Defensive: a malformed row with negative tokens shouldn't produce a
+ # negative cost (which would fold the totals).
+ assert _impute_public_cost("gpt-4o-mini", -5, -10) == 0.0
+
+
+def test_impute_public_cost_case_insensitive() -> None:
+ a = _impute_public_cost("GPT-4o", 1000, 500)
+ b = _impute_public_cost("gpt-4o", 1000, 500)
+ assert a == b
+
+
+# ---------------------------------------------------------------------------
+# Pure helpers
+# ---------------------------------------------------------------------------
+
+
+def test_format_period_label_same_month() -> None:
+ fmt = _internal_helpers["_format_period_label"]
+ label = fmt(PERIOD_START, PERIOD_END)
+ assert "May" in label
+ assert "2026" in label
+
+
+def test_format_period_label_cross_year() -> None:
+ fmt = _internal_helpers["_format_period_label"]
+ label = fmt(
+ datetime(2025, 12, 28, tzinfo=UTC),
+ datetime(2026, 1, 4, tzinfo=UTC),
+ )
+ assert "2025" in label
+ assert "2026" in label
+
+
+def test_bucket_by_day_groups_across_utc_midnight() -> None:
+ bucket = _internal_helpers["_bucket_by_day"]
+ rows = [
+ _cost(started_at=datetime(2026, 5, 2, 23, 0, tzinfo=UTC), cost_usd=1.0),
+ _cost(started_at=datetime(2026, 5, 2, 23, 30, tzinfo=UTC), cost_usd=2.0),
+ # 30 min later → next UTC day → separate bucket
+ _cost(started_at=datetime(2026, 5, 3, 0, 30, tzinfo=UTC), cost_usd=4.0),
+ ]
+ buckets = bucket(rows)
+ assert len(buckets) == 2
+ assert buckets[0].day.isoformat() == "2026-05-02"
+ assert buckets[0].total_cost_usd == pytest.approx(3.0)
+ assert buckets[1].day.isoformat() == "2026-05-03"
+ assert buckets[1].total_cost_usd == pytest.approx(4.0)
+
+
+def test_bucket_by_day_empty() -> None:
+ assert _internal_helpers["_bucket_by_day"]([]) == []
+
+
+def test_model_breakdown_sorts_by_spend_descending() -> None:
+ breakdown = _internal_helpers["_model_breakdown"]
+ rows = [
+ _cost(model="gpt-4o-mini", cost_usd=0.5, run_id="r1"),
+ _cost(model="gpt-4o", cost_usd=10.0, run_id="r2"),
+ _cost(model="gpt-3.5-turbo", cost_usd=2.0, run_id="r3"),
+ ]
+ out = breakdown(rows)
+ assert [b.model for b in out] == ["gpt-4o", "gpt-3.5-turbo", "gpt-4o-mini"]
+ assert out[0].total_cost_usd == 10.0
+
+
+def test_model_breakdown_aggregates_runs_and_calls() -> None:
+ breakdown = _internal_helpers["_model_breakdown"]
+ rows = [
+ _cost(model="gpt-4o", run_id="r1", call_count=3, cost_usd=1.0),
+ _cost(model="gpt-4o", run_id="r1", call_count=2, cost_usd=2.0),
+ _cost(model="gpt-4o", run_id="r2", call_count=1, cost_usd=0.5),
+ ]
+ out = breakdown(rows)
+ assert len(out) == 1
+ assert out[0].runs == 2 # r1, r2 — distinct
+ assert out[0].calls == 6 # 3 + 2 + 1
+ assert out[0].total_cost_usd == pytest.approx(3.5)
+
+
+def test_model_breakdown_avg_latency() -> None:
+ breakdown = _internal_helpers["_model_breakdown"]
+ rows = [
+ _cost(model="gpt-4o", run_id="r1", call_count=2, latency_ms=200.0),
+ _cost(model="gpt-4o", run_id="r1", call_count=2, latency_ms=400.0),
+ ]
+ out = breakdown(rows)
+ # (200 + 400) / (2 + 2) = 150 ms per call
+ assert out[0].avg_latency_ms == pytest.approx(150.0)
+
+
+def test_top_cases_ranks_by_cost_desc_then_case_id() -> None:
+ top = _internal_helpers["_top_cases"]
+ rows = [
+ _cost(case_id="C-2", cost_usd=5.0, run_id="r1"),
+ _cost(case_id="C-1", cost_usd=5.0, run_id="r2"), # tie with C-2
+ _cost(case_id="C-3", cost_usd=10.0, run_id="r3"),
+ ]
+ out = top(rows)
+ # Most expensive first, ties broken by case_id ascending.
+ assert [c.case_id for c in out] == ["C-3", "C-1", "C-2"]
+
+
+def test_top_cases_skips_blank_case_id() -> None:
+ top = _internal_helpers["_top_cases"]
+ rows = [
+ _cost(case_id="", cost_usd=99.0),
+ _cost(case_id="C-1", cost_usd=1.0),
+ ]
+ out = top(rows)
+ assert [c.case_id for c in out] == ["C-1"]
+
+
+def test_top_cases_respects_limit() -> None:
+ top = _internal_helpers["_top_cases"]
+ rows = [_cost(case_id=f"C-{i:02d}", cost_usd=float(i)) for i in range(15)]
+ out = top(rows, limit=5)
+ assert len(out) == 5
+ assert out[0].case_id == "C-14"
+
+
+def test_action_counts_orders_by_frequency() -> None:
+ counts = _internal_helpers["_action_counts"]
+ rows = [
+ AuditRow(action="cases:read"),
+ AuditRow(action="cases:read"),
+ AuditRow(action="cases:write"),
+ AuditRow(action="alerts:read"),
+ AuditRow(action="alerts:read"),
+ AuditRow(action="alerts:read"),
+ ]
+ out = counts(rows)
+ assert [a.action for a in out] == ["alerts:read", "cases:read", "cases:write"]
+ assert out[0].count == 3
+
+
+def test_action_counts_drops_blanks() -> None:
+ counts = _internal_helpers["_action_counts"]
+ rows = [AuditRow(action=""), AuditRow(action="cases:read")]
+ out = counts(rows)
+ assert len(out) == 1
+ assert out[0].action == "cases:read"
+
+
+def test_action_counts_respects_limit() -> None:
+ counts = _internal_helpers["_action_counts"]
+ rows = [AuditRow(action=f"action-{i}") for i in range(50)]
+ out = counts(rows, limit=10)
+ assert len(out) == 10
+
+
+# ---------------------------------------------------------------------------
+# BYOK savings
+# ---------------------------------------------------------------------------
+
+
+def test_byok_savings_local_reports_full_imputed_cost() -> None:
+ savings_fn = _internal_helpers["_byok_savings"]
+ rows = [
+ _cost(model="gpt-4o-mini", prompt_tokens=10_000, completion_tokens=5_000),
+ ]
+ # On BYOK the recorded cost typically already matches imputed (the agent
+ # uses the same pricing table) so savings should ≈ imputed.
+ result = savings_fn(rows, LlmContext(provider="local-ollama", is_local=True))
+ assert result.is_byok_active is True
+ assert result.savings_usd > 0
+ assert result.savings_usd == pytest.approx(result.imputed_public_cost_usd)
+
+
+def test_byok_savings_hosted_reports_max_zero() -> None:
+ savings_fn = _internal_helpers["_byok_savings"]
+ # Hosted provider where the recorded cost matches imputed → zero savings.
+ rows = [
+ _cost(model="gpt-4o", prompt_tokens=1000, completion_tokens=500, cost_usd=0.0125),
+ ]
+ result = savings_fn(rows, LlmContext(provider="openai", is_local=False))
+ assert result.is_byok_active is False
+ assert result.savings_usd == 0.0
+
+
+def test_byok_savings_hosted_with_discount_reports_positive() -> None:
+ savings_fn = _internal_helpers["_byok_savings"]
+ # Operator paid less than list price (negotiated rate) → positive
+ # potential additional savings if they switched to BYOK.
+ rows = [_cost(model="gpt-4o", cost_usd=0.001)] # imputed ≈ $0.0125
+ result = savings_fn(rows, LlmContext(provider="openai", is_local=False))
+ assert result.is_byok_active is False
+ assert result.savings_usd > 0
+ assert result.savings_usd < result.imputed_public_cost_usd
+
+
+def test_byok_savings_empty_rows() -> None:
+ savings_fn = _internal_helpers["_byok_savings"]
+ result = savings_fn([], LlmContext(provider="none", is_local=False))
+ assert result.recorded_cost_usd == 0.0
+ assert result.imputed_public_cost_usd == 0.0
+ assert result.savings_usd == 0.0
+
+
+# ---------------------------------------------------------------------------
+# Headline
+# ---------------------------------------------------------------------------
+
+
+def test_headline_zero_runs_avoids_div_by_zero() -> None:
+ headline = _internal_helpers["_headline"]
+ out = headline([])
+ assert out.total_runs == 0
+ assert out.avg_cost_per_run_usd is None
+
+
+def test_headline_aggregates_distinct_runs() -> None:
+ headline = _internal_helpers["_headline"]
+ rows = [
+ _cost(run_id="r1", cost_usd=1.0),
+ _cost(run_id="r1", cost_usd=2.0), # same run, different model call
+ _cost(run_id="r2", cost_usd=3.0),
+ ]
+ out = headline(rows)
+ assert out.total_runs == 2
+ assert out.total_cost_usd == pytest.approx(6.0)
+ assert out.avg_cost_per_run_usd == pytest.approx(3.0)
+
+
+# ---------------------------------------------------------------------------
+# Top-level pure builder
+# ---------------------------------------------------------------------------
+
+
+def test_build_dashboard_empty_inputs_is_well_formed() -> None:
+ """Empty tenant should still return a valid CostDashboard, not raise."""
+ dashboard = build_dashboard_from_rows(
+ DashboardInputs(
+ tenant_id=TENANT_ID,
+ period_start=PERIOD_START,
+ period_end=PERIOD_END,
+ cost_rows=[],
+ audit_rows=[],
+ llm=LlmContext(provider="none", is_local=False),
+ )
+ )
+ assert dashboard.tenant_id == TENANT_ID
+ assert dashboard.period.window_days == 7
+ assert dashboard.headline.total_cost_usd == 0.0
+ assert dashboard.daily_costs == []
+ assert dashboard.by_model == []
+ assert dashboard.top_cases == []
+ assert dashboard.action_counts == []
+ # BYOK panel is always present so the UI doesn't have to special-case it.
+ assert dashboard.byok_savings.is_byok_active is False
+ assert dashboard.byok_savings.savings_usd == 0.0
+
+
+def test_build_dashboard_end_to_end() -> None:
+ """A representative tenant: 3 runs, 2 models, 2 days, mixed actions."""
+ cost_rows = [
+ _cost(
+ run_id="r1",
+ case_id="C-1",
+ model="gpt-4o-mini",
+ prompt_tokens=2000,
+ completion_tokens=1000,
+ started_at=datetime(2026, 5, 2, 10, 0, tzinfo=UTC),
+ ),
+ _cost(
+ run_id="r2",
+ case_id="C-2",
+ model="gpt-4o",
+ prompt_tokens=10_000,
+ completion_tokens=5_000,
+ cost_usd=0.125, # cheaper than imputed → operator saved
+ started_at=datetime(2026, 5, 3, 14, 0, tzinfo=UTC),
+ ),
+ _cost(
+ run_id="r3",
+ case_id="C-2", # same case, separate run → C-2 ranks #1
+ model="gpt-4o",
+ prompt_tokens=5000,
+ completion_tokens=2000,
+ cost_usd=0.05,
+ started_at=datetime(2026, 5, 3, 15, 0, tzinfo=UTC),
+ ),
+ ]
+ audit_rows = [
+ AuditRow(action="cases:read"),
+ AuditRow(action="cases:read"),
+ AuditRow(action="cases:write"),
+ AuditRow(action="alerts:read"),
+ ]
+ dashboard = build_dashboard_from_rows(
+ DashboardInputs(
+ tenant_id=TENANT_ID,
+ period_start=PERIOD_START,
+ period_end=PERIOD_END,
+ cost_rows=cost_rows,
+ audit_rows=audit_rows,
+ llm=LlmContext(provider="openai", is_local=False),
+ )
+ )
+ # Headline
+ assert dashboard.headline.total_runs == 3
+ assert dashboard.headline.total_calls == 3
+ assert dashboard.headline.total_tokens == 25_000
+
+ # Daily buckets — 2 distinct UTC days
+ assert [b.day.isoformat() for b in dashboard.daily_costs] == [
+ "2026-05-02",
+ "2026-05-03",
+ ]
+
+ # Model breakdown — gpt-4o has higher recorded cost
+ assert dashboard.by_model[0].model == "gpt-4o"
+ assert dashboard.by_model[1].model == "gpt-4o-mini"
+
+ # Top cases — C-2 has 2 runs and higher spend
+ assert dashboard.top_cases[0].case_id == "C-2"
+ assert dashboard.top_cases[0].runs == 2
+
+ # Action counts
+ assert dashboard.action_counts[0].action == "cases:read"
+ assert dashboard.action_counts[0].count == 2
+
+ # BYOK — hosted provider, recorded < imputed → positive savings
+ assert dashboard.byok_savings.is_byok_active is False
+ assert dashboard.byok_savings.savings_usd > 0
+
+
+def test_build_dashboard_byok_active_marks_local_provider() -> None:
+ cost_rows = [
+ _cost(
+ run_id="r1",
+ case_id="C-1",
+ model="gpt-4o-mini",
+ prompt_tokens=1000,
+ completion_tokens=500,
+ )
+ ]
+ dashboard = build_dashboard_from_rows(
+ DashboardInputs(
+ tenant_id=TENANT_ID,
+ period_start=PERIOD_START,
+ period_end=PERIOD_END,
+ cost_rows=cost_rows,
+ audit_rows=[],
+ llm=LlmContext(provider="local-ollama", is_local=True),
+ )
+ )
+ assert dashboard.byok_savings.is_byok_active is True
+ assert dashboard.byok_savings.provider == "local-ollama"
+ assert dashboard.byok_savings.savings_usd > 0