Metadata-Version: 2.4
Name: agent-cost-attribution-layer
Version: 0.1.0
Summary: Middleware proxy for AI agent request attribution and compliance audit trails
Author: Agent Cost Attribution Team
License: MIT
Requires-Python: >=3.10
Requires-Dist: aiosqlite>=0.19.0
Requires-Dist: alembic>=1.13.1
Requires-Dist: click>=8.1.7
Requires-Dist: fastapi>=0.109.0
Requires-Dist: httpx>=0.26.0
Requires-Dist: passlib[bcrypt]>=1.7.4
Requires-Dist: pydantic-settings>=2.1.0
Requires-Dist: pydantic>=2.5.3
Requires-Dist: python-jose[cryptography]>=3.3.0
Requires-Dist: python-multipart>=0.0.6
Requires-Dist: rich>=13.7.0
Requires-Dist: sqlalchemy>=2.0.25
Requires-Dist: stripe>=7.11.0
Requires-Dist: uvicorn[standard]>=0.27.0
Provides-Extra: dev
Requires-Dist: httpx>=0.26.0; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.23.3; extra == 'dev'
Requires-Dist: pytest-cov>=4.1.0; extra == 'dev'
Requires-Dist: pytest>=7.4.4; extra == 'dev'
Description-Content-Type: text/markdown

# agent-cost-attribution-layer

A FastAPI-based middleware proxy that automatically attributes every AI request to agents, users, and tasks—generating compliance-ready audit trails for multi-agent deployments.

## What is this?

This is a transparent proxy layer that sits between your AI agents and LLM APIs (OpenAI, Anthropic, local models, etc.). It automatically tags every request with agent identity, user attribution, task context, and cost, then logs everything to a queryable audit database. It solves the core problem revealed by the VS Code Copilot attribution drama: **"Who authorized this AI action and what data did it use?"** Unlike cost-monitoring tools, this focuses on consent tracking, regulatory compliance, and multi-agent accountability.

## Features

- **Transparent proxy** — Drop-in replacement for OpenAI/Anthropic client calls; no agent code changes required
- **Automatic attribution** — Tags every request with agent ID, user ID, task context, and timestamp
- **Audit trails** — SQLite-backed compliance log with prompt hashes, token usage, and costs
- **REST API** — Query attribution history: "Show all AI actions by user X in the last 30 days"
- **Export compliance** — CSV (legal), JSON (monitoring), and GDPR-compliant deletion endpoints
- **CLI tooling** — `agent-attr proxy start --port 8080 --log-db audit.db`
- **Rate limiting** — Per-user, per-agent quotas with configurable tiers
- **Multi-tier pricing** — Freemium (local), Pro (cloud-hosted), Enterprise (SOC2 audit trails)

## Quick Start

### Installation

```bash
# Clone and install
git clone https://github.com/yourusername/agent-cost-attribution-layer.git
cd agent-cost-attribution-layer
pip install -e .
```

### Basic Setup

```bash
# Copy environment template
cp .env.example .env

# Start the proxy server
agent-attr proxy start --port 8080 --log-db ./audit.db
```

### Docker Deployment

```bash
docker-compose up -d
```

The proxy is now listening on `http://localhost:8080`.

## Usage

### Redirect agent requests through the proxy

Before:
```python
from openai import OpenAI
client = OpenAI(api_key="sk-...")
response = client.chat.completions.create(model="gpt-4", messages=[...])
```

After (one-line change):
```python
from openai import OpenAI
client = OpenAI(api_key="sk-...", base_url="http://localhost:8080/v1")
# Add attribution headers
client.default_headers = {
    "X-Agent-ID": "code-review-bot",
    "X-User-ID": "user-123",
    "X-Task-Context": "PR review #456"
}
response = client.chat.completions.create(model="gpt-4", messages=[...])
```

### Query audit logs via REST API

```bash
# Get all actions by a user in the last 30 days
curl http://localhost:8080/audit/user/user-123?days=30

# Get all actions by an agent
curl http://localhost:8080/audit/agent/code-review-bot

# Export as CSV (for compliance)
curl http://localhost:8080/audit/export/csv?start_date=2026-05-01&end_date=2026-05-31 > audit.csv
```

### CLI commands

```bash
# Start proxy
agent-attr proxy start --port 8080 --log-db audit.db

# Query logs
agent-attr audit query --agent code-review-bot --days 7

# Export for compliance
agent-attr audit export --format csv --output audit.csv

# GDPR deletion
agent-attr audit delete --user user-123
```

## Tech Stack

- **FastAPI** — High-performance async proxy server
- **SQLite** — Local-first audit log (no external DB required)
- **Pydantic** — Request/response validation
- **pytest** — Test suite
- **Docker** — Container deployment
- **Python 3.10+**

## License

MIT