Filament Headroom Laravel Package

Product Decisions This Supports

• Build vs. buy for LLM cost/usage visibility. This is the presentation tier of a three-package family (laravel-ai-headroom does pre-flight context/limit checks, laravel-ai-headroom-ledger records entries, filament-headroom renders them). If your team has already standardised on Filament for internal admin, this replaces a bespoke dashboard or a SaaS observability subscription with in-house rendering over data you already own.
• Cost governance and showback. Spend trend vs. previous period, daily spend per model/provider, and an estimate-accuracy widget (weighted error between pre-flight estimates and reported input tokens) give you the evidence to decide on model downshifting, provider mix, or context-budget tightening. It answers "which agent/model is burning budget" without a data request to engineering.
• Metering and tenant attribution for multi-tenant products. scopeToTenant() plus tagLabel() turn the ledger into per-tenant AI cost allocation. This supports pricing decisions (who absorbs inference cost), fair-use policy, and per-tenant usage conversations — but see the caveats below before treating it as billing input.
• Context-window and reliability triage. "Context headroom" (bucketed to 100%+ / did not fit), "closest to the limit", and blocked/warned/failed widgets convert guardrail telemetry into a prioritised backlog: prompts that are too long, agents hitting limits, failover behaviour visible on the request detail page.
• Agent-run-level debugging. "Group by run" and the per-step context growth on the detail page support a concrete product question — is a multi-step agent degrading as context accumulates? — which is otherwise expensive to instrument.
• Privacy/DSAR readiness. allowForgettingTags() and the "Forget a tag value" action map a data-subject erasure request onto a context tag through the ledger's forgetTag(). This is a policy decision with a UI attached; it materially changes your compliance story and should be reviewed before enabling.
• Roadmap sequencing. Because widgets can be dropped onto your own Filament dashboards independently of the packaged /headroom pages, you can stage rollout: stats widget first for awareness, then requests/run views for the teams who need them. Adoption does not require a big-bang migration.

When to Consider This Package

Adopt when all of the following hold:

• You are on PHP 8.3+, Laravel 12 or 13, and Filament 5 — the constraint that dominates everything else. Filament 5-only means this package is unusable if your admin panel is on an earlier major, and pulling Filament in solely for this is not a reasonable trade.
• You are already writing, or are willing to write, to phoenix1331/laravel-ai-headroom-ledger ^0.1.1 — this package is a viewer, not a collector. Budget the integration work of getting entries into the ledger, which is where the real effort sits.
• You want internal visibility (engineering, platform, finance-partnered) rather than customer-facing reporting.
• You accept a pre-1.0 dependency: everything here is 0.x, the release notes carry an [Unreleased] section, and the namespace suggests a small/single-maintainer surface. Plan for pinning and for reading changelogs, not for an SLA.

Look elsewhere or build when:

• You need billable accuracy. The package is explicit that amounts are per currency, never converted, and that non-billed figures carry an "Estimate", "Includes estimates", or "Approximate" badge. That honesty is a feature, but it disqualifies the dashboard as an invoicing or revenue-recognition source. Keep your billing system of record separate, or plan a reconciliation layer.
• You need enforcement, not observation. Blocking and warning happen upstream in laravel-ai-headroom; this only reports outcomes.
• You are not on Filament. The value is the UI; without an existing panel you inherit Filament's upgrade cadence for one dashboard.
• You need enterprise support, a vendor security review, or a stable 1.x contract. Nothing here offers that yet.
• You need cross-tenant erasure or admin-of-admin actions. Note the deliberate constraint that tag forgetting is unavailable under tenant scoping because the ledger erases across all tenants — that operation must be run from a non-tenant panel, which is a real operational design decision to plan for.

Two adoption gates worth calling out to engineering: access is denied outside the local environment by default, so production rollout requires an explicit authorize() closure — good safe-by-default behaviour, but it will look like "the dashboard is broken" if not planned for. And the plugin stylesheet must be published via php artisan filament:assets, which belongs in your deploy pipeline.

How to Pitch It (Stakeholders)

To executives: We can turn on visibility into what our AI features cost and how reliably they run, inside the admin tool we already have, without buying another SaaS observability product or committing to a new vendor. It shows spend per model and provider, per agent, and — for multi-tenant products — per tenant, so we can have cost and pricing conversations backed by numbers instead of guesses. It ships with explicit labelling wherever a figure is an estimate rather than a billed amount, so nobody mistakes it for an invoice, and it includes a supported path for honouring data-erasure requests against the tags we record. The trade-off is maturity: this is a first release (0.1.0) with pre-1.0 dependencies and no support contract, so we should pilot it behind an explicit access rule and treat it as internal decision-support, not a system of record.

To engineering: It is a thin Filament 5 UI over the ledger you would write anyway — no new datastore, no agent, no network calls to a third party. You get pages and widgets you can disable or subclass via pages()/widgets(), widgets you can mount on your own dashboards, RangeSelect::make() for a consistent range filter, published translations, and published assets. Authorisation runs through a single authorize() closure receiving $user, defaulting to local-only, so the production gate is one deliberate line of config rather than a scatter of policies. Costs of entry: PHP 8.3+, Laravel 12/13, Filament 5, and two sibling 0.x packages to pin and track.