Metadata-Version: 2.4
Name: costfuse
Version: 0.2.0
Summary: A fuse box for your AI bill. Drop-in budget guardrails and runaway-loop kill switch for Claude and OpenAI agents.
Author: costfuse
License: Apache-2.0
Project-URL: Homepage, https://github.com/costfuse/costfuse
Project-URL: Repository, https://github.com/costfuse/costfuse
Project-URL: Issues, https://github.com/costfuse/costfuse/issues
Keywords: ai,anthropic,claude,openai,guardrails,kill-switch,budget,tokens,agent,eu-ai-act,compliance
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Libraries
Requires-Python: >=3.9
Description-Content-Type: text/markdown
Provides-Extra: dev
Requires-Dist: anthropic>=0.30.0; extra == "dev"
Requires-Dist: openai>=1.0.0; extra == "dev"
Requires-Dist: pytest>=7.0; extra == "dev"
Provides-Extra: anthropic
Requires-Dist: anthropic>=0.30.0; extra == "anthropic"
Provides-Extra: openai
Requires-Dist: openai>=1.0.0; extra == "openai"

# costfuse (Python)

**A fuse box for your AI bill.**

Drop-in budget guardrails and runaway-loop kill switch for AI agents. Wrap your Anthropic or OpenAI client; costfuse kills requests before they spend money you didn't plan for, and writes an audit log you can hand to a regulator.

The Python version of [costfuse](https://github.com/costfuse/costfuse) — feature parity with the Node SDK.

## Install

```bash
pip install costfuse
```

## Use it

```python
from anthropic import Anthropic
from costfuse import wrap, CostfuseConfig

claude = wrap(Anthropic(), CostfuseConfig(
    max_spend_per_hour=5.00,
    max_same_prompt_in_window={"count": 5, "window_ms": 60_000},
    max_calls_per_minute=60,
    audit_log_path="./costfuse-audit.jsonl",
))

# Use it exactly like the original client:
claude.messages.create(
    model="claude-haiku-4-5",
    max_tokens=200,
    messages=[{"role": "user", "content": "Hello."}],
)
```

If a rule trips, the call raises `CostfuseBlocked` before any tokens are spent.

## Rules

| Rule | What it blocks |
| --- | --- |
| `max_spend_per_hour` | Hard USD cap in the last 60 minutes |
| `max_spend_per_day` | Hard USD cap in the last 24 hours |
| `max_calls_per_minute` | Rate limit |
| `max_same_prompt_in_window` | Same prompt fingerprint repeating — runaway-loop detection |
| `max_recursion_depth` | Agent calling itself too deeply |

## OpenAI also supported

```python
from openai import OpenAI
from costfuse import wrap, CostfuseConfig

oai = wrap(OpenAI(), CostfuseConfig(max_spend_per_hour=5.00))
oai.chat.completions.create(model="gpt-4o-mini", messages=[...])
```

## Recommended onboarding: log-only first, enforce later

For your first week, run with `kill_on_breach=False`. Costfuse will observe and write the audit log without blocking anything.

```python
claude = wrap(Anthropic(), CostfuseConfig(
    max_spend_per_hour=10,
    kill_on_breach=False,           # observe-only
    audit_log_path="./costfuse-audit.jsonl",
))
```

## Local testing

Three test scripts ship with the repo:

```bash
cd python
pip install -e ".[dev]"
python examples/mock_test.py          # zero spend, all rules
python examples/loop_test.py          # simulated runaway, zero spend
ANTHROPIC_API_KEY=sk-... python examples/claude_test.py   # real calls, < $0.01 spend
```

## License

Apache-2.0
