agent-budget-controller · packages

Manages agent spending limits and budget configurations via a command-line interface. It provides commands to define budget caps, generate spend reports, and perform pre-flight checks for specific scopes.

Enforces LLM spending limits by providing a `BudgetController` class that manages state, performs pre-flight cost checks, and dynamically filters tools or downgrades models. It requires a `PricingProvider` implementation to calculate request costs and a `SpendStore` to persist usage data.

Filters LLM model candidates by remaining budget and blocks requests when limits are exceeded. It provides a `BudgetAwareStrategy` class that integrates with the LLM Router pattern and requires a `BudgetController` instance to track spending.

Enforces LLM spending limits by providing Express/Fastify middleware and a `BudgetInterceptor` class that dynamically filters tools, downgrades models, and records token usage. It requires a `BudgetController` instance from the `@reaatech/agent-budget-engine` package to manage budget state and policy logic.

Extracts GenAI usage metrics from OpenTelemetry span attributes to automatically record spend entries against budget scopes. It provides a `SpanListener` class that integrates with a `BudgetController` to process span data as they complete.

Calculates LLM token costs and estimates budgets using a `PricingEngine` class that supports built-in pricing tables for major providers, model name normalization, and LRU-cached lookups. It allows for custom pricing overrides and provides utility methods to compute exact costs based on input and output token counts.

Tracks and analyzes real-time spend data using an in-memory circular buffer for O(1) lookups and sliding-window aggregations. It provides a `SpendStore` class that enables cost projection, spike detection, and multi-index querying without external database dependencies.

Provides TypeScript interfaces, Zod schemas, and error classes for defining and validating agent budget policies, enforcement actions, and spend tracking. It serves as the shared type definition library for the `@reaatech/agent-budget-*` ecosystem.