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.
Python agentic-aiai-securityalert-triageblue-teamcybersecuritydetection-engineeringincident-responselanggraphllm-agentsmcpmitre-attackmodel-context-protocolpurple-teamsecurity-operationsself-hostedsiemsoarsocthreat-detectionthreat-intelligence
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.tsxnew file mode 100644index 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.tsxnew file mode 100644index 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.tsxnew file mode 100644index 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.tsxnew file mode 100644index 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'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.tsxindex 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.tsindex 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.pynew file mode 100644index 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.pyindex 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.pynew file mode 100644index 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.pynew file mode 100644index 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