Budget Intelligence: Forecaster, Agent Budgets, and Alerts

2026-03-11

budget-forecasteragent-budget-managerbudget-alerts

What We Built

Wired the existing BudgetForecaster and AgentBudgetManager classes into live API routes. The /v1/budget/forecast endpoint now returns trend analysis, projected depletion dates, anomaly detection, and confidence scoring — powered by 30-day historical spend data from Redis instead of the previous inline arithmetic.

Added per-agent budget management endpoints (/v1/budget/agents) allowing operators to set conversation, hourly, and daily spend limits per agent with configurable exhaustion actions (downgrade model or stop). Added budget alert configuration and history endpoints for threshold-based webhook notifications.

Why It Matters

Budget intelligence was built but unwired — the forecaster existed as a standalone class but the API returned simple spend/limit math. Now operators get proactive warnings: "at current rate you'll hit your limit in 12 days" with anomaly detection flagging unexpected spend spikes. Per-agent budgets prevent any single agent from consuming disproportionate resources. Alert webhooks enable integration with PagerDuty, Slack, or custom monitoring.

How It Works

Forecaster wiring: GET /v1/budget/forecast initializes a per-tenant BudgetForecaster, seeds it with 30 days of daily spend from Redis counters, then calls forecast() and detectAnomalies(). Response includes avgDailySpendUsd, depletionDate, daysRemaining, trend (increasing/decreasing/stable), projectedPeriodSpendUsd, confidence, and anomaly array with Z-score severity.
Agent budgets: AgentBudgetManager persisted to ConfigStore under agent-budget:{agentId} keys. Supports perConversationUsd, perHourUsd, perDayUsd limits with downgrade or stop exhaustion actions. Includes leaderboard ranking agents by total spend.
Alerts: ConfigStore-backed alert configuration with customizable thresholds (default 80/90/95%), webhook URL, and enable/disable toggle. History endpoint with NaN-safe pagination.
Dashboard: Budget Gauge section with radial SVG gauges (green/amber/red based on threshold proximity, CSS pulse animation at warning levels), depletion countdown, forecast stats in glassStatCard, anomaly cards, and agent budget leaderboard table.

The Numbers

5 new API endpoints (+ 6 JWT-authenticated dashboard bridges including write endpoints)
7 new SDK methods across TypeScript and Python (sync + async)
14 route-level tests (up from 6)
30-day rolling forecast window with confidence scoring
Per-agent budget granularity: conversation, hourly, daily

Competitive Edge

No AI gateway competitor offers integrated budget intelligence with anomaly detection. Portkey and OpenRouter provide spend tracking but not forecasting — they tell you what you spent, not what you're about to spend. BrainstormRouter's BudgetForecaster with linear regression trend analysis and Z-score anomaly detection turns budget management from reactive monitoring into proactive cost control.

Lockstep Checklist

[x] API Routes: src/api/routes/budget.ts rewritten, src/api/routes/auth.ts updated with 4 new bridges.
[x] TS SDK: packages/sdk-ts/src/resources/budget.ts updated with 6 new methods and types.
[x] Python SDK: packages/sdk-py/src/brainstormrouter/resources/budget.py updated with sync + async methods.
[x] MCP Schemas: br_get_budget_forecast description updated in tool-manifest.ts and agents.json.
[x] Dashboard: site/dashboard/src/pages/insights.ts — Budget Gauge, forecast panel, agent budgets, anomaly cards.
[x] Tests: src/api/routes/budget.test.ts — 14 tests covering forecast shape, agent CRUD, alert config, pagination.