llm-budget-guard

TypeScript library for LLM cost tracking, budget enforcement, rate limits, pricing, and audit trails. A CostTracker orchestrates recording, optional budgets and rate limiters, YAML-backed pricing, and pluggable storage backends.

Install

npm install llm-budget-guard

Requires Node.js 18+.

Quick start

import { CostTracker, createBudget } from 'llm-budget-guard';

const tracker = new CostTracker({
  budgets: [
    createBudget({ name: 'daily', limit: 25.0, period: 'day' }),
  ],
});

await tracker.record({
  model: 'gpt-4o',
  inputTokens: 1200,
  outputTokens: 400,
});

const report = await tracker.getCosts();
console.log(report.totalCost, report.totalCalls);

Wrap client calls with track() to extract usage from provider-shaped responses (OpenAI, Anthropic, Bedrock, Vertex).

Main modules

| Area | Exports | Role | |------|---------|------| | Core | CostTracker, createCostRecord, createCostReport, createUsageData | Record spend, query reports, model helpers | | Budget | createBudget, BudgetTracker, BudgetAction | Period budgets, tags, warnings, reserve/finalize | | Limits | RateLimiter, SlidingWindowCounter | Sliding-window limits (global, model, provider, tag) | | Spans | Span, runInSpan, getCurrentSpan | Async-local attribution of cost to operations | | Pricing | PricingLoader, getPricing | Load src/pricing/data/*.yaml, overrides, prefix match | | Providers | detectProvider, OpenAIProvider, … | Model routing and usage extraction | | Backends | MemoryBackend, … | Persistence (memory default in CostTracker) | | Audit | AuditLogger, LoggingAuditBackend, … | Structured audit events and queries | | Resilience | CircuitBreaker, retryWithBackoff, ResilientOperation | Breakers and backoff around flaky dependencies | | Security | FernetEncryption, FieldEncryption, secrets providers | Optional encryption and secret loading |

Configuration highlights

• CostTracker: budgets, rateLimits, backend, pricingOverrides, onTrackingFailure (block | allow | fallback), auditEnabled, autoDetectProvider.
• Budgets: period (day, hour, week, …), warningThreshold (default 0.8), optional tags for scoped budgets.
• Rate limits: scope of global, model, provider, or tag:<key>.

Development

npm install
npm run build
npm run typecheck
npm test              # vitest watch
npx vitest run        # CI-style single run
npm run test:coverage

Tests live under tests/ and target the implementation in src/ (models, budgets, rate limits, pricing loader, providers, memory backend, tracker, resilience, spans, audit).

License

MIT