agent-energy-budget

Agent cost control, energy budget management, and token tracking

Part of the AumOS open-source agent infrastructure portfolio.

Features

• BudgetTracker performs pre-call affordability checks and records actual spend to a per-agent JSONL log, supporting daily, weekly, and monthly limits simultaneously
• Four degradation strategies when budgets are tight: TOKEN_REDUCTION (cap output tokens to fit remaining budget), MODEL_DOWNGRADE (switch to the cheapest affordable model), CACHED_FALLBACK (signal to use cached responses), and BLOCK_WITH_ERROR (raise BudgetExceededError)
• Model pricing tables for OpenAI, Anthropic, Google, and custom models with a CostEstimator that projects spend before the call is made
• Hierarchical sub-budget allocation — a parent BudgetTracker can allocate fractional child budgets for sub-agents in a multi-agent team
• Threshold-based alert system fires warning, critical, and exhausted callbacks at configurable utilization percentages
• Middleware wrappers for LangChain, CrewAI, AutoGen, Anthropic SDK, and OpenAI SDK that intercept calls and apply budget checks transparently
• Spend reporting with per-model breakdowns, top-N cost attribution, and ASCII/matplotlib visualizations

Quick Start

Install from PyPI:

pip install agent-energy-budget

Verify the installation:

agent-energy-budget version

Basic usage:

import agent_energy_budget

# See examples/01_quickstart.py for a working example

Documentation

• Architecture
• Contributing
• Changelog
• Examples

Enterprise Upgrade

For production deployments requiring SLA-backed support and advanced integrations, contact the maintainers or see the commercial extensions documentation.

Contributing

Contributions are welcome. Please read CONTRIBUTING.md before opening a pull request.

License

Apache 2.0 — see LICENSE for full terms.

Part of AumOS — open-source agent infrastructure.