# Backstop

> In-process token budget enforcement, circuit breaking, and concurrency control for OpenAI and Anthropic SDK clients. Wraps the SDK's internal httpx transport — no proxy, no call-site changes.

- Documentation: /README.md
- Quick start: /docs/quickstart.md
- Install guide: /docs/install.md
- SDK compatibility matrix: /docs/sdk-matrix.md
- Compatibility details: /docs/compatibility.md
- Architecture: /docs/architecture.md
- Benchmarks: /docs/benchmarks.md
- Examples: /examples/

## Install (0.6.0 unreleased)

The distribution is `backstop-ai`; the import is `backstop`. PyPI publication is pending.
Until then, install from source:

```bash
git clone https://github.com/RavaniRoshan/backstop.git
cd backstop && pip install -e ".[anthropic]"
```

After publication:
- `pip install backstop-ai` — OpenAI + base
- `pip install "backstop-ai[anthropic]"` — OpenAI + Anthropic
- `pip install "backstop-ai[redis]"` — shared/distributed budget
- `pip install "backstop-ai[otel]"` — OpenTelemetry metrics export
- `pip install "backstop-ai[fastapi]"` — per-tenant FastAPI example

## Quick start

```python
from openai import OpenAI
from backstop import Backstop
from backstop.exceptions import BudgetExceededError

client = Backstop.wrap(OpenAI(), budget=50_000)
try:
    response = client.chat.completions.create(
        model="gpt-4o-mini",
        messages=[{"role": "user", "content": "Hello."}],
    )
except BudgetExceededError:
    print("Budget exhausted")
```

## Keyless proof (no API key needed)

```bash
backstop verify   # 8/8 PASS in ~2s, purely offline
backstop demo     # side-by-side runaway loop comparison
```

## SDK compatibility

- OpenAI: `>=2.37,<4` on Python 3.10–3.12 ✅
- Anthropic: `>=0.98,<2` on Python 3.10–3.12 ✅

Run `backstop doctor` to check your installed versions.

## CLIs

- `backstop verify` — proves enforcement offline in ~2s with 8 checks
- `backstop demo` — side-by-side runaway loop (unprotected vs wrapped)
- `backstop doctor` — checks SDK versions and wrap path
- `backstop benchmark` — reproducible overhead measurement
- `backstop metrics` — Prometheus endpoint
- `backstop real-openai` / `real-anthropic` — live smoke tests (require API key)

## Agentic-installer quickstart

If you are an agent installing Backstop into a codebase:

1. Check SDK compatibility: OpenAI `>=2.37,<4`, Anthropic `>=0.98,<2`.
2. Until PyPI publication, install from source.
3. Integration: `client = Backstop.wrap(client, budget=50_000)` — one line.
4. Verify: `backstop verify` proves enforcement without any API key.
5. Catch `backstop.exceptions.BudgetExceededError` to handle budget exhaustion.
