README

An abuse firewall for AI endpoints. It stops the failure mode rate limiting does not model: a runaway agent that calls itself in a loop, or a single tenant whose spend suddenly spikes, draining the API budget before anyone notices.

This is not a rate limiter. It does two things rate limiters and cost dashboards do not:

1. Loop breaker. Detects a runaway agent within one request lifecycle: too many AI calls, or the same call repeated too many times. A self-recursing agent trips this first.
2. Spend-anomaly circuit breaker. Tracks estimated input tokens and calls per principal over a rolling window, and opens a circuit (with a cooldown) when a tenant spikes.

This is an independent open-source package. It is not affiliated with, endorsed by, or sponsored by Laravel, Laravel LLC, or any AI provider.

Requirements

• PHP 8.2+, Laravel 12 or 13

Installation

composer require laravelsecurityaudit/laravel-ai-circuit-breaker

It registers a global HTTP-client middleware, so it governs every outbound request to a known AI provider regardless of the SDK. Prism and the Http facade are covered automatically; for a client with its own Guzzle stack (openai-php), attach CircuitBreaker::stack().

Observe first, enforce when ready

By default the breaker observes: it counts, fires events, and logs, but never blocks, so it can never break a legitimate workload on a false anomaly. Turn on enforcement when you trust the thresholds:

CIRCUIT_BREAKER_ENFORCE=true

When enforcing, a tripped limit opens the circuit for that principal and throws CircuitOpenException, which fails the AI call (fail-closed). fail_open is true, so an internal error never breaks a real call.

Principals and multi-tenancy

Calls are accounted to the authenticated user, tenant-aware when your user model exposes a tenant key, falling back to the client IP. Bind your own PrincipalResolver to customise the fingerprint.

A note on spend estimates

The outbound request carries no token usage, so spend is estimated from the request body (about four characters per token). This is an anomaly brake, not billing. Exact post-hoc accounting from the response is a planned addition.

Events

LoopDetected and CircuitOpened fire in both observe and enforce mode, so you can wire SIEM, Slack, or PagerDuty with a single listener.

Configuration

php artisan vendor:publish --tag=circuit-breaker-config

CIRCUIT_BREAKER_ENABLED=true
CIRCUIT_BREAKER_ENFORCE=false
CIRCUIT_BREAKER_MAX_CALLS=25
CIRCUIT_BREAKER_MAX_REPEATS=5
CIRCUIT_BREAKER_WINDOW=60
CIRCUIT_BREAKER_MAX_TOKENS=200000
CIRCUIT_BREAKER_COOLDOWN=300

Testing

composer test
composer analyse

The Laravel Security Audit family

One detection engine, guarding every place data leaves your app.

License

The MIT License (MIT). See LICENSE.