Add Enterprise Usage Analyzer (Next.js UI for CSM dashboard + grounded chat)

[Yonatan Edelstein (YoniEdelstein)]

Summary

Adds enterprise-usage-analyzer/ — a standalone Next.js 16 app that gives CSM / Sales / leadership a single screen per enterprise client with KPIs, charts, AI-generated qualitative insights, and a chat panel that can re-query BigQuery on demand.

Local-only (no deploy in this PR). Queries BigQuery via the user's own gcloud ADC and Anthropic for qualitative summaries / chat. Those are the only two destinations data leaves the machine for — no analytics, no Sentry, no third-party fonts, Next.js telemetry disabled.

What you get on screen

For a chosen client + date range (default last 30 days, max 12 months):

• KPI tiles — Registered Users, Active Users in range, Active Users that Used Tokens, Total Tokens Consumed, plus engagement-bucket breakdowns
• Time-series charts with day / week / month granularity toggle:
  • Active users over time
  • Token consumption stacked by model
  • Generation count stacked by gen_type
  • Dual-axis chart (bars = generations, line = token cost)
• Qualitative insights (LLM-generated, fused from usage + call transcripts):
  client health (Green / Yellow / Red), sentiment, feature requests, blockers, new features tried, recommended next actions, risk flags. Every claim is cited; call-backed claims include verbatim quote spans copied character-for-character from the transcripts so the CSM can validate at a glance.
• Users table — sortable, searchable, CSV-exportable
• Per-user-per-model credit consumption pivot — sortable, CSV-exportable, model column order is byte-stable across runs
• Sliding right-side chat panel — bound to the loaded client + range, with 4 BigQuery-backed tools (query_users, query_actions, query_calls, aggregate). Parallel tool execution, iteration cap = 6, threads keyed by client+range so switching clients gives a fresh thread but coming back restores history.

Architecture notes worth flagging at review

• All BigQuery queries are parameterized (@param style); the per-org CTE applies the McCann-style normalization rules in one place (src/lib/bigquery/normalize.ts) so the dashboard, insights, and chat tools all see the same roster.
• LLM output is forced through Anthropic tool-use (tool_choice set to submit_insights) and validated with Zod — no free-form JSON parsing.
• Chat history is in-memory Zustand only (no localStorage) — refreshing the browser wipes threads. That's intentional for the local-only scope but flagged as a polish item.

Repo layout

enterprise-usage-analyzer/
  src/
    app/                  Next.js App Router pages + API routes
      api/{kpis,series,users,pivot,calls,insights,chat,export/...}
    components/           Dashboard + chat UI
    lib/
      bigquery/           Parameterized BQ queries + normalize CTE
      chat/               4 tools, snapshot, prompt, tool loop
      insights/           Context builder, prompt, schema, client
  scripts/smoke-test.ts   End-to-end smoke test
  README.md               Setup + privacy boundary + acceptance test

Test plan

• cd enterprise-usage-analyzer && pnpm install
• Authenticate to BigQuery: gcloud auth application-default login
• Create .env.local from .env.example and fill in ANTHROPIC_API_KEY
• pnpm dev, open http://localhost:3000
• Pick McCann_Paris, range 2026-03-01 → 2026-05-01, click Analyze
• Verify KPI tiles, all 4 charts, both tables render and CSV exports work
• Verify the Insights section renders with verbatim quotes attached to call-backed items
• Open the chat panel, ask: "Who are the top 3 users by tokens this period?" — verify it calls query_users and answers in markdown
• Follow up: "What gen_types has the top user run?" — verify it picks up the lt_id from context and calls query_actions or aggregate

Made with Cursor