Luca skill endpoints: compare, leaderboard, revenue-quality, unresolved, anomalies

[danbuildss]

What this is

The 5 read-only backend endpoints Luca's skills call (spec'd in PR #214). With these merged, every Luca skill is live — he stops being prompt-only and starts reading real Zetta data.

Endpoints

Public (no auth; published data only):

Endpoint	Luca skill	What it returns
GET /api/v1/financial-intelligence/{slug}/compare?from=&to=	compare_periods	Two published snapshots + server-computed deltas (from/to/change/pct_change per metric). Luca never does his own math.
GET /api/v1/financial-intelligence/leaderboard?metric=&period_end=&limit=	get_leaderboard	Agents ranked by a published metric, with evidence_coverage + data_completeness + integrity_hash on every row. Defaults to latest published period per agent.

Internal/operator-only (behind existing internalAuth):

Endpoint	Luca skill	What it returns
GET /api/admin/financial-intelligence/revenue-quality?agent_slug=&period_start=&period_end=	get_revenue_quality	A→U evidence-grade breakdown of posted journals, verified_usd, verified_pct.
GET /api/admin/financial-intelligence/unresolved?agent_slug=&limit=	get_unresolved_items	Top unresolved/candidate economic actions — what still needs evidence. Amounts, dates, reason codes only; no private payloads.
GET /api/admin/financial-intelligence/anomalies?agent_slug=&status=	get_anomalies	Review flags by severity, with an explicit "flagged for review, not confirmed problems" framing note.

Design notes

• Read-only. No writes, no classification, no journal posting. All five are pure queries over PR Build backend financial intelligence engine #202's tables (financial_snapshots, financial_journals, financial_journal_lines, economic_actions, financial_anomalies).
• Published-only public surface. Public endpoints filter status = 'published' — preliminary snapshots never leak.
• Server-computed deltas. compare does the arithmetic so Luca's numbers are always traceable to a response.
• Fail-closed auth. Internal endpoints reuse internalAuth (ZETTA_INTERNAL_SECRET / session token); no new auth surface.
• No new dependencies. Supabase admin client + existing internal-auth only.

Depends on

• PR Build backend financial intelligence engine #202's tables (20260724000001_financial_intelligence_engine.sql) — merge/apply that first.
• Complements PR Luca analyst v1: system prompt, read-only skills, verifier, evals #214 (Luca prompt/skills/verifier/evals) — together they're the complete Luca v1.

After merge

• No new env vars (reuses SUPABASE_URL, SUPABASE_SERVICE_ROLE_KEY, ZETTA_INTERNAL_SECRET).
• Point Hermes' ZETTA_BASE_URL at production, register the 6 skills, attach the verifier hook, run luca/evals/run-evals.ts against staging.
• No DB migration needed for this PR.

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
zetta	Canceled		Jul 25, 2026 11:19pm