Files · Agnostic AI Budget Control for SMB Agent Workflows

# Agnostic AI Budget Control for SMB Agent Workflows
 
> Real-time spend enforcement and cost-aware routing across any LLM provider for small business AI agents.
 
Multi-provider budget enforcement, cost-aware routing, and real-time dashboards via Langfuse. This solution layers `@reaatech/agent-budget-engine` and `@reaatech/llm-router-core` to cap per-session and monthly spend while routing requests to the cheapest capable model. `@reaatech/agent-budget-middleware` intercepts every LLM call pre-flight to enforce limits, while `@reaatech/llm-router-engine` dynamically selects from multiple providers based on real-time cost and latency. Telemetry flows into Langfuse for dashboards, ensuring SMB owners see exactly where their AI budget goes without vendor lock-in.
 
## Prerequisites
 
- **Node.js** >= 22
- **pnpm** 10.x
- **Redis** instance (local or remote)
- **Langfuse** account (for telemetry dashboards)
 
## Setup
 
```bash
cp .env.example .env
# Fill in required API keys and configuration in .env
pnpm install
pnpm dev
```
 
## Architecture
 
```
┌─ Budget Guard ─────────────────────────────────────┐
│  BudgetInterceptor → BudgetController → RedisSpendStore │
│                      → DefaultPricingProvider          │
└────────────────────────────────────────────────────┘
                       │
┌─ LLM Router ───────────────────────────────────────┐
│  LLMRouter → ModelRegistry → executeModel callback  │
│              → BudgetConfig / fallback chains        │
└────────────────────────────────────────────────────┘
                       │
┌─ Telemetry Pipeline ───────────────────────────────┐
│  CostCollector → CostAggregator → BudgetManager     │
│       ↓                                             │
│  Langfuse (traces + dashboards)                     │
└────────────────────────────────────────────────────┘
```
 
### Component layout
 
- **budget-guard** → **budget-controller** → **Redis spend store**: per-scope budget enforcement with soft/hard caps, auto-downgrade, and tool filtering
- **router** → **model registry** → **executeModel**: provider-agnostic model routing with cost-optimized strategy and fallback chains
- **telemetry pipeline** → **cost collector** → **aggregator** → **budget manager** → **langfuse**: real-time cost tracking, multi-dimensional aggregation, per-tenant budget enforcement, and observability dashboards
 
## API Endpoints
 
| Method | Path | Description |
|--------|------|-------------|
| `POST` | `/api/webhooks/usage` | Ingest a cost telemetry span (validated via `CostSpanSchema`) |
| `GET` | `/api/webhooks/usage?tenant=&period=` | Retrieve aggregated telemetry summary |
| `POST` | `/api/budget/check` | Pre-flight budget check before an LLM call |
| `POST` | `/api/budget/record` | Record actual spend after an LLM call completes |
| `POST` | `/api/router` | Route an LLM request through the cost-optimized router |
| `GET` | `/api/router` | List registered models for introspection |
 
## Environment Variables
 
| Variable | Required | Default | Description |
|----------|----------|---------|-------------|
| `REDIS_URL` | Yes | `redis://localhost:6379` | Redis connection string |
| `REDIS_PASSWORD` | No | — | Optional Redis password |
| `LANGFUSE_PUBLIC_KEY` | Yes | — | Langfuse project public key |
| `LANGFUSE_SECRET_KEY` | Yes | — | Langfuse project secret key |
| `LANGFUSE_BASE_URL` | No | `https://cloud.langfuse.com` | Langfuse API base URL |
| `DEFAULT_DAILY_BUDGET` | No | `100` | Default daily budget in USD |
| `DEFAULT_MONTHLY_BUDGET` | No | `2000` | Default monthly budget in USD |
| `ROUTER_CONFIG_MODELS` | Yes | — | JSON array of model definitions |
| `OPENAI_API_KEY` | Yes* | — | API key for OpenAI provider |
| `ANTHROPIC_API_KEY` | Yes* | — | API key for Anthropic provider |
| `DEEPSEEK_API_KEY` | Yes* | — | API key for DeepSeek provider |
| `GROQ_API_KEY` | Yes* | — | API key for Groq provider |
| `DEFAULT_INPUT_COST_PER_MILLION` | No | `10` | Fallback input cost per 1M tokens |
| `DEFAULT_OUTPUT_COST_PER_MILLION` | No | `30` | Fallback output cost per 1M tokens |
| `TENANT_BUDGETS` | No | `{}` | JSON mapping tenant IDs to daily/monthly budgets |
 
*Provider API keys are required only for the providers you configure in `ROUTER_CONFIG_MODELS`.
 
## License
 
MIT — see [LICENSE](./LICENSE).