Metadata-Version: 2.4
Name: ai-agent-spend-guardian
Version: 0.1.0
Summary: Real-time cost monitoring for AI agent deployments across LLM providers
Author: AI Agent Spend Guardian Team
License: MIT
License-File: LICENSE
Requires-Python: >=3.10
Requires-Dist: aiosqlite>=0.19.0
Requires-Dist: alembic>=1.13.1
Requires-Dist: fastapi>=0.109.0
Requires-Dist: httpx>=0.26.0
Requires-Dist: passlib[bcrypt]>=1.7.4
Requires-Dist: psycopg2-binary>=2.9.9
Requires-Dist: pydantic-settings>=2.1.0
Requires-Dist: pydantic>=2.5.3
Requires-Dist: python-dotenv>=1.0.0
Requires-Dist: python-jose[cryptography]>=3.3.0
Requires-Dist: python-multipart>=0.0.6
Requires-Dist: sqlalchemy>=2.0.25
Requires-Dist: stripe>=8.0.0
Requires-Dist: uvicorn[standard]>=0.27.0
Provides-Extra: dev
Requires-Dist: black>=23.12.1; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.23.3; extra == 'dev'
Requires-Dist: pytest>=7.4.4; extra == 'dev'
Requires-Dist: ruff>=0.1.11; extra == 'dev'
Description-Content-Type: text/markdown

# AI Agent Spend Guardian

Real-time cost monitoring and budget controls for autonomous AI agent deployments.

## What is this?

AI Agent Spend Guardian is a cost tracking and monitoring dashboard built for teams running AI agents across platforms like n8n, Composio, LangChain, and AutoGPT. It aggregates LLM API expenses across OpenAI, Anthropic, and local model providers in one unified interface, solving the critical blind spot where teams deploy autonomous agents with zero cost visibility and no budget safeguards.

## Features

- **Multi-provider cost tracking** — Monitor spending across OpenAI, Anthropic, Ollama, Groq, Together AI, and other LLM providers
- **Real-time dashboards** — Web UI and CLI tools for instant cost visibility
- **Budget controls** — Set spending limits per agent, workflow, or team with automated alerts
- **Agent-aware insights** — Track costs by individual agent, workflow execution, or time period
- **Alerting** — Slack and Discord webhooks for budget breach notifications
- **Export & reporting** — CSV exports for finance teams and compliance audits
- **Provider-agnostic** — Works with any LLM API, including self-hosted and local models
- **Offline support** — CLI tool parses local API logs and env files without external connectivity

## Quick Start

### Installation

```bash
pip install -r requirements.txt
```

### Configuration

Copy `.env.example` to `.env` and add your API credentials:

```bash
cp .env.example .env
```

Edit `.env` with your provider keys:

```
OPENAI_API_KEY=sk-...
ANTHROPIC_API_KEY=sk-ant-...
DATABASE_URL=postgresql://user:password@localhost/agent_spend_guardian
```

### Run the Application

Start the FastAPI server:

```bash
python -m agent_spend_guardian.main
```

The dashboard will be available at `http://localhost:8000`.

### CLI Usage

Generate a cost report from local logs:

```bash
python -m agent_spend_guardian.cli report --days 7 --format csv
```

Set a budget alert:

```bash
python -m agent_spend_guardian.cli budget set --agent my-agent --limit 100.00
```

## Usage Examples

### Web Dashboard

Access the dashboard to:
- View real-time spending across all agents
- Set budget limits and thresholds
- Inspect cost breakdowns by provider, model, and agent
- Export reports for finance review

### API Integration

```python
from agent_spend_guardian.tracker import SpendTracker

tracker = SpendTracker()

# Log an API call
tracker.log_call(
    agent_id="my-agent",
    provider="openai",
    model="gpt-4",
    tokens_used=1500,
    cost=0.045
)

# Retrieve costs
costs = tracker.get_agent_costs("my-agent", days=7)
print(f"7-day spend: ${costs['total']}")
```

### Budget Alerts

Configure Slack notifications:

```bash
python -m agent_spend_guardian.cli alert configure \
  --channel #costs \
  --webhook https://hooks.slack.com/services/YOUR/WEBHOOK
```

## Tech Stack

- **Backend**: Python 3.10+, FastAPI
- **Database**: PostgreSQL (production), SQLite (local CLI)
- **ORM**: SQLAlchemy with Alembic migrations
- **Frontend**: React (dashboard)
- **Authentication**: JWT-based auth
- **Deployment**: Docker-ready

## Development

### Database Migrations

```bash
alembic upgrade head
```

### Contributing

See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines on submitting issues and pull requests.

### Monetization

Freemium SaaS model with free tier, Pro ($39/mo), and Enterprise ($299/mo) plans. See [MONETIZATION.md](MONETIZATION.md) for details.

## License

MIT License — see [LICENSE](LICENSE) for details.