Metadata-Version: 2.4
Name: mesh-cost-firewall
Version: 0.1.0
Summary: Real-time AI agent cost gating system with budget enforcement and graceful degradation
Project-URL: Homepage, https://github.com/yourusername/mesh-cost-firewall
Project-URL: Documentation, https://github.com/yourusername/mesh-cost-firewall#readme
Project-URL: Repository, https://github.com/yourusername/mesh-cost-firewall
Author-email: Zach <builder@zachos.dev>
License: MIT
Keywords: agents,ai,budget,cost-control,llm,rate-limiting
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Requires-Python: >=3.11
Requires-Dist: fastapi>=0.115.0
Requires-Dist: httpx>=0.27.0
Requires-Dist: pydantic-settings>=2.5.0
Requires-Dist: pydantic>=2.9.0
Requires-Dist: python-dotenv>=1.0.0
Requires-Dist: redis>=5.0.0
Requires-Dist: stripe>=10.0.0
Requires-Dist: tiktoken>=0.7.0
Requires-Dist: uvicorn[standard]>=0.30.0
Provides-Extra: dev
Requires-Dist: black>=24.0.0; extra == 'dev'
Requires-Dist: mypy>=1.11.0; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.24.0; extra == 'dev'
Requires-Dist: pytest-cov>=5.0.0; extra == 'dev'
Requires-Dist: pytest>=8.3.0; extra == 'dev'
Requires-Dist: ruff>=0.6.0; extra == 'dev'
Description-Content-Type: text/markdown

# mesh-cost-firewall

Real-time AI agent cost gating system that prevents budget overruns before they happen.

## What is this?

mesh-cost-firewall is a cost control middleware that sits between your agent mesh and LLM APIs, automatically rejecting or rate-limiting requests that would breach per-agent, per-user, or global budget limits. Instead of discovering runaway costs in your billing dashboard, agents hit configurable spending ceilings and fail gracefully. Built for autonomous multi-agent systems where financial guardrails are essential.

## Features

- **Multi-level budget enforcement** — Global, per-user, and per-agent cost caps
- **Real-time cost estimation** — Pre-request cost prediction before API calls
- **Graceful rate limiting** — Circuit breaker pattern for budget exhaustion
- **LLM model awareness** — Built-in pricing for GPT-4, Claude, and other major models
- **Request interception** — Transparent proxy layer between agents and APIs
- **Configuration as code** — YAML/env-based budget definitions
- **Docker-native** — Ships with Dockerfile and docker-compose for instant deployment
- **Production-ready** — Handles concurrent requests, persistent state, and monitoring hooks

## Quick Start

### Installation

```bash
# Clone and install
git clone <repo>
cd mesh-cost-firewall
pip install -e .

# Or with Docker
docker-compose up -d
```

### Configuration

Create a `.env` file (see `.env.example`):

```env
GLOBAL_BUDGET_CENTS=100000
DEFAULT_USER_BUDGET_CENTS=10000
DEFAULT_AGENT_BUDGET_CENTS=1000

OPENAI_API_KEY=sk-...
ANTHROPIC_API_KEY=sk-ant-...
```

### Basic Usage

```python
from mesh_cost_firewall import CostFirewall

firewall = CostFirewall(config_path="config.yaml")

# Wrap your LLM call
result = firewall.request(
    agent_id="researcher_1",
    user_id="user_42",
    model="gpt-4",
    tokens=2000,
    endpoint="https://api.openai.com/v1/chat/completions"
)

if result.allowed:
    # Safe to proceed
    response = call_llm_api(...)
else:
    # Budget exhausted
    logger.warning(f"Request rejected: {result.reason}")
```

Or use as an HTTP proxy:

```bash
export FIREWALL_PORT=8000
python -m mesh_cost_firewall.main
curl -X POST http://localhost:8000/v1/chat/completions \
  -H "X-Agent-Id: researcher_1" \
  -H "X-User-Id: user_42" \
  -d '{"model": "gpt-4", ...}'
```

## Tech Stack

- **Python 3.9+** — Core runtime
- **FastAPI** — HTTP proxy and API
- **Pydantic** — Configuration validation
- **APScheduler** — Budget reset scheduling
- **Docker** — Containerization
- **SQLite** — Persistent state (upgradeable to Postgres)

## License

MIT