Compatibility Matrix
Which SDK versions are tested, which are not, and what the matrix does not claim.
0.8.0 is published (PyPI
backstop-ai, GitHub Releasev0.8.0). The SDK ranges below are the tested ranges from.github/workflows/ci.yml— not a claim of universal support, and not a claim that every combination is exercised. Wrapping an SDK outside these ranges emits a loudUserWarningnaming the tested range (PLAN 1.4.1) and proceeds unverified. Enforcement-error propagation (BudgetExceededErrorcatchable by user code, notAPIConnectionError) is verified on openai 3.14.0 + anthropic 1.5.0 (current) and openai 2.37.0 + anthropic 0.99.0 (legacy matrix) viatests/test_guardrail_visibility.py. See installation limitations.
Python
| Python | Status |
|---|---|
| 3.10 | Tested in CI |
| 3.11 | Tested in CI |
| 3.12 | Tested in CI |
Providers
| Provider | Client | Tested SDK range | Verified in CI | Status | Notes |
|---|---|---|---|---|---|
| OpenAI | openai.OpenAI |
>=2.37,<4 |
2.37.0, 3.14.0, latest¹ | Supported | Sync wrap; httpx/httpx2 family auto-detected per client |
| OpenAI | openai.AsyncOpenAI |
>=2.37,<4 |
2.37.0, 3.14.0, latest¹ | Supported | Async wrap; same family detection |
| Anthropic | anthropic.Anthropic |
>=0.98,<2 |
0.99.0, 1.6.0 | Supported | Optional dependency via backstop-ai[anthropic]; httpx2 client on >=1.0 |
| Anthropic | anthropic.AsyncAnthropic |
>=0.98,<2 |
0.99.0, 1.6.0 | Supported | Same as sync |
¹ latest is resolved in a single CI cross-check row (Python 3.12, openai
latest against anthropic 0.99.0), not across the full matrix. Anthropic
latest is not tracked by CI at all — the 1.5.0 and 1.6.0 figures in the
header note come from tests/test_guardrail_visibility.py on a developer
machine, not from the CI matrix. Treat “1.5.0 verified” as a local observation.
CI runs on ubuntu-latest only, and installs
pip install -e ".[test,metrics,anthropic]" — so the redis, otel,
fastapi and tokenizers extras get no CI execution, and neither does the
TypeScript package. See docs/sdk-matrix.md
for the full list of what the matrix does and does not cover.
Unsupported: SDKs below the floors (openai<2.37, anthropic<0.98) — their
request loop catches every transport exception, including Backstop’s
BudgetExceededError, and re-raises it as APIConnectionError, so budget
enforcement is invisible to user code. Bisected 2026-09-18: the
propagate-as-is guard first ships in openai 2.37.0 / anthropic 0.98.0
(openai 2.36.0 / anthropic 0.97.0 lack it). Older SDKs (openai<1.90,
anthropic<0.40) additionally crash against httpx>=0.28, which removed
the proxies kwarg. Also unsupported: future majors at/above the ceilings
(openai>=4, anthropic>=2 — none released as of 2026-09-18).
Backstop.wrap() warns on these but does not refuse; check with
backstop verify --live before relying on an untested version, and read
the doctor caveats before
trusting a doctor exit code.
Optional Extras
| Extra | Purpose |
|---|---|
backstop-ai[metrics] |
Prometheus metrics export |
backstop-ai[anthropic] |
Anthropic SDK support |
backstop-ai[redis] |
Shared/distributed budget across replicas |
backstop-ai[otel] |
OpenTelemetry metrics export |
backstop-ai[fastapi] |
Gateway/sidecar mode |
backstop-ai[tokenizers] |
Optional token counting support |
backstop-ai[test] |
Test dependencies |
Supported Behavior
| Capability | Local Mode |
|---|---|
| Global token budget | Supported |
| Tenant token budget | Supported in-process |
| Priority admission | Supported |
| AIMD concurrency | Supported |
| Retry handling | Supported |
| Circuit breaker | Supported (per-tenant opt-in) |
| Streaming | Supported |
| Response caching | Supported (exact + semantic) |
| Fallback chains | Supported (priority-aware) |
| Agent guardrails | Supported |
| Cloud-quota auto-tuning | Supported |
| Cost forecasting → enforcement | Supported |
| Audit log | Supported (tamper-evident) |
| Secret provider | Supported |
| Prometheus metrics | Optional |
| OpenTelemetry | Optional (otel extra) |
| Distributed budgets | Optional (redis extra) |
| Gateway / sidecar | Optional (fastapi extra) |
| Shadow / canary rollout | Supported |
| Hosted control plane | Planned |
“Supported” in this table means the feature ships and is documented. It does
not mean CI exercises it. The four rows marked Optional depend on extras
that .github/workflows/ci.yml does not install, so the distributed-budget,
OpenTelemetry, gateway and tiktoken paths have no automated coverage today.
The pyyaml wedge dependency is installed by CI.
TypeScript package
A separate backstop-ai on npm implements a subset of the above for the
OpenAI TypeScript SDK. It is not covered by anything in this page: it is a
different interception strategy (client.chat.completions.create patching, not
transport injection), has no Anthropic support, and roughly half the config
surface. It is in CI — its typecheck, build and tests run on every push, and
CI checks that its version agrees with the Python distribution’s — but the
tables here describe the Python package, not it.
Compatibility Policy
Until Backstop reaches a stable 1.0 release:
- Pin provider SDK versions in production if transport compatibility is critical.
- Run unit tests and real-provider smoke tests before provider SDK upgrades.
- Report compatibility issues with the provider issue template.