Files · Mistral AI Spend Governance for Stripe SMB Subscription Billing
76 (1 binary, 703.0 kB total)attempt 1
README.md·8803 B·markdown
markdown
# Mistral AI Spend Governance for Stripe SMB Subscription Billing
> Enforce per-customer LLM spend caps for Stripe billing workflows, automatically downgrading models when budgets are exceeded.
A tutorialized reference solution from [reaatech.com](https://reaatech.com), demonstrating how to build production-grade AI spend governance using the `@reaatech/*` package family.
## What this does
This recipe gives SMB SaaS operators real-time control over Mistral AI LLM costs at the customer (tenant) level. Each Stripe subscription is linked to a daily budget — when a tenant approaches their soft cap the router auto-downgrades to a cheaper Mistral model; when they hit the hard cap all LLM calls are blocked until the billing cycle resets.
The system consists of an Express API server that wires together five REAA packages (BudgetController, SpendStore, PricingEngine, LLMRouter, and cost telemetry), a cron job that resets budgets on Stripe billing boundaries, and a Next.js dashboard for live monitoring and policy configuration.
## Architecture
```
┌─────────────────────────────────────────────────────────┐
│ Next.js Dashboard │
│ app/page.tsx app/budgets/... app/spend/ │
│ (overview stats) (budget CRUD UI) (spend view) │
└──────────────────────────┬──────────────────────────────┘
│ fetch() to localhost:3001
▼
┌─────────────────── Express API Server (port 3001) ──────┐
│ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌────────┐ │
│ │ Budget │ │ Spend │ │ Webhooks │ │ Health │ │
│ │ Admin │ │ Tracker │ │ Router │ │ Router │ │
│ │ Router │ │ Router │ │ │ │ │ │
│ └────┬─────┘ └────┬─────┘ └────┬─────┘ └───┬────┘ │
│ │ │ │ │ │
│ ▼ ▼ ▼ ▼ │
│ ┌──────────────────────────────────────────────────┐ │
│ │ Services Layer │ │
│ │ budget-service.ts router-service.ts │ │
│ │ cost-pipeline.ts stripe-client.ts │ │
│ │ stripe-webhook.ts mistral-client.ts │ │
│ └──────────────────────────────────────────────────┘ │
│ │ │ │ │
│ ▼ ▼ ▼ │
│ ┌──────────────────────────────────────────────────┐ │
│ │ @reaatech/* Packages │ │
│ │ ┌──────────────┐ ┌───────────────┐ │ │
│ │ │BudgetController│ │ SpendStore │ │ │
│ │ │(agent-budget- │ │(agent-budget-│ │ │
│ │ │ engine) │ │ spend-tracker)│ │ │
│ │ └──────────────┘ └───────────────┘ │ │
│ │ ┌──────────────┐ ┌───────────────┐ │ │
│ │ │PricingEngine │ │ LLMRouter │ │ │
│ │ │(agent-budget-│ │(llm-router- │ │ │
│ │ │ pricing) │ │ engine) │ │ │
│ │ └──────────────┘ └───────────────┘ │ │
│ │ ┌────────────────────────────────────┐ │ │
│ │ │ llm-cost-telemetry │ │ │
│ │ │ (CostSpan, generateId, loadConfig) │ │ │
│ │ └────────────────────────────────────┘ │ │
│ └──────────────────────────────────────────────────┘ │
│ │
│ ┌──────────────────────────────────────────────────┐ │
│ │ Cron: budget-reset.ts (daily / on billing cycle) │ │
│ └──────────────────────────────────────────────────┘ │
└──────────────────────────────────────────────────────────┘
│ │
▼ ▼
┌──────────┐ ┌──────────────┐
│ Mistral │ │ Stripe │
│ AI API │ │ API │
└──────────┘ └──────────────┘
```
The cost pipeline flows: Mistral API call → `wrapWithCostTracking()` extracts token usage → `PricingEngine.computeCost()` calculates cost → `BudgetController.record()` updates state → state change fires threshold events → `LLMRouter` auto-downgrades on next request.
## Prerequisites
- **Node.js** >= 22
- **pnpm** (install via `corepack enable && corepack prepare pnpm@latest --activate`)
- **Mistral AI API key** — get one from [console.mistral.ai](https://console.mistral.ai)
- **Stripe account** — with a subscription product and usage-based billing configured
## Quick Start
```bash
# 1. Install dependencies
pnpm install
# 2. Configure environment
cp .env.example .env
# Edit .env with your Mistral AI API key and Stripe credentials
# 3. Start the Next.js dev server (port 3000)
pnpm dev
# 4. In another terminal, start the Express API server (port 3001)
cd src && npx tsx app.ts
```
Open [http://localhost:3000](http://localhost:3000) to view the dashboard.
## API Reference
| Method | Endpoint | Description |
|--------|----------|-------------|
| `GET` | `/api/health` | Health check — pings Mistral, Stripe, and budget services |
| `GET` | `/api/budgets` | List all budget policies |
| `GET` | `/api/budgets/:scopeType/:scopeKey` | Get budget detail and current state |
| `POST` | `/api/budgets` | Create or update a budget policy |
| `DELETE` | `/api/budgets/:scopeType/:scopeKey` | Remove a budget policy |
| `POST` | `/api/budgets/:scopeType/:scopeKey/reset` | Reset spend counters for a budget |
| `GET` | `/api/spend/:scopeType/:scopeKey` | Get current spend total and rate |
| `GET` | `/api/spend/:scopeType/:scopeKey/spikes` | Get anomaly spike detections |
| `GET` | `/api/spend/:scopeType/:scopeKey/history` | Get spend history entries |
| `POST` | `/api/webhooks/stripe` | Stripe webhook receiver |
## Environment Variables
| Variable | Description | Default |
|----------|-------------|---------|
| `NODE_ENV` | Runtime environment | `development` |
| `MISTRAL_API_KEY` | Mistral AI API key | — |
| `STRIPE_SECRET_KEY` | Stripe secret key | — |
| `STRIPE_WEBHOOK_SECRET` | Stripe webhook signing secret | — |
| `OTEL_SERVICE_NAME` | OpenTelemetry service name | `mistral-spend-governance` |
| `DEFAULT_DAILY_BUDGET` | Default daily LLM spend budget per tenant | `10.0` |
| `NEXT_PUBLIC_APP_URL` | Public dashboard URL | `http://localhost:3000` |
## Testing
```bash
pnpm test
```
Runs vitest with coverage reporting. Test files live in `tests/` and mirror the `src/` structure. The Express API and all REAA package integrations are tested with MSW-mocked HTTP handlers.
## License
MIT — see [LICENSE](./LICENSE).