- How do I install laravel-ai-headroom in a Laravel app?
- Install it with Composer using composer require phoenix1331/laravel-ai-headroom, then publish the config file so config/ai-headroom.php is available to your application. The service provider, Headroom facade, and agent middleware are registered automatically following standard Laravel package conventions. Configuration is driven by environment overrides such as HEADROOM_CURRENCY, HEADROOM_CACHE, and HEADROOM_CALIBRATION_STORE. After publishing, run the Artisan commands to inspect your context and token budgets.
- Which Laravel and PHP versions does laravel-ai-headroom support?
- The package ships as a conventional Laravel package with a service provider, publishable config, facade, middleware, and Artisan commands, so it follows normal Laravel package conventions. However, the release notes do not state an explicit PHP, Laravel, or laravel/ai version constraint, so you should check the composer.json requirements before adopting it. Because the package is pre-1.0 and couples to laravel/ai internals such as driver names and withMessages and withTools semantics, pin both packages to tested versions. Verify compatibility in a staging branch before rolling out to production.
- How do I enforce token and context limits on an AI agent step?
- Enforcement is opt-in per agent by attaching the EnsureHeadroom agent middleware, so you choose exactly which agent steps are governed. The package explicitly supports a non-blocking report mode, which lets you observe counts and would-be blocks before you turn on hard enforcement. A staged rollout therefore looks like: attach the middleware in report mode, watch the emitted events, then switch to blocking once margins look sane. This sits at the seam where a step is about to be sent to a provider, so it adds counting, limiting, and cost estimation without persisting prompts or responses.
- Does laravel-ai-headroom send my prompt content to the AI provider when counting tokens?
- Yes, when native counting is used the prompt content is transmitted to the provider counting endpoints such as count_tokens, input_tokens, or countTokens. That is a data-egress path you need to account for if you have prompt-confidentiality or data-residency requirements, and it also adds latency and rate-limit surface in auto escalation bands. The package provides estimate-based counting that avoids provider round-trips for clear passes and clear fails, but the documentation should be reviewed to confirm whether estimation can be forced globally. Treat native counting as a deliberate configuration decision rather than a default you ignore.
- How accurate is token counting for non-OpenAI providers like Anthropic or Gemini?
- For non-OpenAI providers the package relies on per-provider estimate_ratios plus a safety margin until calibration matures. Calibration learns correction factors over time and stores them in HEADROOM_CALIBRATION_STORE, which is cache-backed. That is acceptable when running in report mode, but weaker as a hard gate until the factors stabilise. Be aware that a cache flush or eviction silently resets models to still learning, which widens safety margins and can change block behaviour.
- How do I test token limits in my test suite with Headroom::fake()?
- The package ships Headroom::fake() with assertion helpers so you can exercise token limits and blocking behaviour without hitting a provider. You can assert that counting happened, that a step was blocked, or that a limit was reported inside ordinary Laravel feature tests. Combined with the event API, this makes prompt and context regressions testable in CI rather than only in manual runs. Use the fake in unit and feature tests and keep a small number of integration tests against real providers for calibration sanity.
- What Artisan commands does laravel-ai-headroom provide?
- The package registers five Artisan commands covering inspection, calibration, and registry workflows. The most immediately useful is headroom:inspect, which exits non-zero when a prompt or context exceeds its headroom, giving you a CI gate for prompt and context regressions from day one. The remaining commands support calibration and registry maintenance tasks. Run them in CI and in your deployment pipeline rather than ad hoc on developer machines.
- How do I monitor token usage and blocked requests in production?
- The package emits events including TokensCounted, TokensUsed, HeadroomLow, RequestBlocked, and RequestFailed. These are the intended integration point for observability, and you do not have to adopt the package's own storage to use them. Wire listeners to your existing logging, metrics, or alerting stack so that HeadroomLow and RequestBlocked surface before users notice degraded behaviour. This also gives you the data needed to tune limits and safety margins over time.
- How do I keep the model registry of prices and context windows up to date?
- The package ships a dated model registry and warns when it is older than 60 days. Registry staleness is a correctness risk, not a cosmetic one: stale prices mean cost limits enforce against wrong numbers, and stale context windows can produce false passes or false blocks. Any enforcement deployment needs a named owner responsible for refreshing the registry and re-running your calibration and inspection jobs afterwards. Treat registry updates like dependency updates in your release process.
- Is laravel-ai-headroom safe to use with concurrent queue workers and in production generally?
- The package is functional but pre-1.0, so assume breaking changes across minor versions until a 1.0 release and pin versions accordingly. Calibration state is cache-backed, so use a shared cache store such as Redis rather than an array or file store, otherwise each worker learns independently. The cache-write contention behaviour of concurrent writers to the same calibration key is not stated in the documentation, so exercise it under load before relying on hard blocks. Starting in report mode with events wired into your observability stack is the low-risk path to production.