Laravel Ai Headroom Laravel Package

Product Decisions This Supports

• Hard spend and context guardrails before the call, not after. EnsureHeadroom sits in the agent middleware stack and evaluates every generation step — including streams — against maxPercentOfContext, maxCost and the context window. This is the difference between "we noticed the bill at month end" and "the request never left the building." It directly de-risks shipping agentic features with loops and tool calls, where a single bad prompt can fan out into dozens of paid steps.
• Budget tiers as a product feature, not an ops chore. ->report() turns a hard block into a soft warning (HeadroomLow + pass-through), so you can ship a "you're approaching your limit" UX instead of a 500. Per-tenant ceilings become a plan-tier differentiator (free / pro / enterprise token allowances) rather than an ad-hoc rate limiter.
• Cost attribution and chargeback. Headroom::resolveContextUsing() tags requests with scalars like tenant_id, and events (TokensCounted, TokensUsed, RequestFailed) are linked by ULID requestId plus laravel/ai's invocation ID. That is enough to build per-tenant, per-agent, per-model cost reporting without Headroom becoming a data store — a meaningful build-vs-buy win, since the alternative is instrumenting every call site yourself.
• Model selection and roadmap pricing. php artisan headroom:models surfaces context windows, max output, prices, cache prices and long-prompt tiers, flags overrides/additions, and warns when shipped prices are >60 days stale. This is the artifact you bring to a "should we move this agent from Claude to Gemini" conversation — and the staleness warning is an honest signal that pricing is a maintained dependency, not a one-time config.
• Pre-flight gating in CI. headroom:inspect --json exits non-zero when a request doesn't fit, so prompt/tool/schema changes that blow the context window get caught in the pipeline instead of in production. Same for regression-testing prompt bloat as a reviewable diff.
• Test-time determinism. Headroom::fake() with assertCounted(), assertCountedTimes(), assertNothingCounted() and matching by agent class, model or * means feature tests can assert "this request would have been blocked" without spending a cent or hitting a provider. Unmatched requests estimate locally. This lowers the cost of writing tests around AI features enough that teams will actually do it.
• Privacy-safe observability. Events never carry prompt, response or error text, and the native-count cache stores only a SHA-256 fingerprint and the count. That's a deliberate product decision that makes the package viable in regulated or data-sensitive contexts where "log everything" is a non-starter.
• Accuracy vs latency as a tunable, not a fork. auto counting estimates first and only escalates to a native provider count when within escalation_band of a limit; self-calibration learns a per-model correction from real usage and reports CountMethod::Calibrated with measured error as confidence. This lets you default to cheap/fast and tighten only where limits are close.
• Multi-currency pricing for non-US go-to-market. USD/GBP via currency + exchange_rates. Small, but it removes a "why is our dashboard in dollars" objection for UK/EU-facing products.

When to Consider This Package

Adopt when most of these hold:

• You are on Laravel and building agents with laravel/ai (the middleware, counters and Headroom::for() are written against its agent API — this is the load-bearing dependency).
• You have metered or unbounded AI cost exposure: multi-tenant SaaS, per-customer allowances, agent loops, tool-calling chains, or user-supplied prompts where a single request can be expensive.
• You need pre-call enforcement, not post-hoc dashboards. If your requirement is "block/flag before spending," this is the shape you want.
• You want cost data without operating a pipeline — events-as-public-API plus resolveContextUsing() gives you attribution while your existing logging/metrics stack does the storing.
• You need CI enforcement of context-window fit for prompts, tools and attachments.

Look elsewhere or wait when:

• You are not on Laravel/laravel/ai. Nothing here is portable; the value proposition collapses.
• You need billing-grade accuracy. Counting is Native / Estimated / Calibrated, with a safety margin that shrinks toward safety_margin_floor as calibration improves. It is a guardrail, not an invoice. If money changes hands on the number, meter provider-side.
• You need a governed spend control plane. This is a library: no budgets workflow, no approval chains, no alerting/on-call integration, no historical dashboards. Pair it with your observability stack, or buy a gateway if that's the actual requirement.
• v0.1.0 maturity is a blocker. Pre-1.0 with a very large first surface area (value objects, enums, config keys, events, exceptions all shipped at once). Expect churn; pin versions and treat TokenCount, Cost, config keys and event payloads as provisional until 1.0.
• Multi-node deployments without a shared cache. Self-calibration and the optional native-count cache live in the cache store (HEADROOM_CALIBRATION_STORE, HEADROOM_CACHE_STORE). On ephemeral or per-node caches, calibration will diverge or reset; verify your cache backend before promising accuracy.
• Latency-critical, high-QPS paths with strict p99. auto avoids most native calls, but escalation and any native configuration add a provider round-trip to the critical path.
• Non-USD/GBP or exotic providers/models. Currency support is two-way; unknown models fall back to fallback_model with estimate_ratios, so accuracy degrades quietly. Check headroom:models covers your real model list first.
• You need attachment token accounting to be exact. Images/documents/audio/video use fixed attachment_tokens — fine for guardrails, wrong for precise cost.

Rollout note: start in report() mode with a generous maxPercentOfContext, watch HeadroomLow and TokensCounted for a week to establish real distributions, then tighten limits and flip to blocking. Verify headroom:calibration reaches "active" per model (needs min_samples) before relying on calibrated confidence.

How to Pitch It (Stakeholders)

For executives (one paragraph): This package puts a hard ceiling on what any single AI request can spend or consume before the request is sent, and gives us per-customer cost attribution without storing prompt or response content. It converts AI cost from an unpredictable monthly surprise into a configured limit we can price into plans, and it lets us enforce those limits in CI so prompt changes can't silently blow up spend. It's a small, self-contained Laravel package rather than a platform commitment — the main caveat is that it's a v0.1.0 guardrail, not a billing system, so we should pilot it in report-only mode before enforcing.

For engineering (the honest version): It's a middleware plus a counting layer for laravel/ai. auto counting estimates locally with OpenAI's tokeniser and only calls the provider's native counter when the estimate is within escalation_band of a limit, so you don't pay latency on clear passes or clear fails. Native counters exist for Anthropic, OpenAI and Gemini, pluggable via the counters map. Streaming is covered. Events are the integration point — they carry a ULID requestId, agent, model, counts and cost, and never prompt or response text, so wire them into existing logging/metrics and don't expect this thing to be your datastore. Headroom::fake() makes AI features testable without provider calls or spend. Things to scrutinise in review: pre-1.0 API surface (pin it), the cache store dependency for calibration in multi-node setups, price-registry staleness (there's a 60-day warning — honour it), and the fact that attachment and non-OpenAI estimates carry safety margins rather than precision. Ship it behind ->report() first, measure, then enforce.