Filament Headroom Laravel Package

Technical Evaluation

This is a first-release Filament plugin that adds a read-only AI usage and cost dashboard on top of phoenix1331/laravel-ai-headroom and phoenix1331/laravel-ai-headroom-ledger. It is best evaluated as an internal observability and governance UI, not as an AI runtime control plane.

• Architecture fit: Strong fit for Laravel applications already using Filament 5 and the Headroom ledger packages. It adds pages, widgets, filters, tenant scoping, and cost/usage visualisations without changing the host application’s main dashboard unless explicitly placed there.
• Integration feasibility: Straightforward for teams on the required stack: PHP 8.3+, Laravel 12/13, Filament 5, and the two Headroom packages. Configuration is plugin-based and covers authorization, navigation, default ranges, tag labels, tenant scoping, and optional tag forgetting.
• Technical risk: High stack-tightness. The plugin requires very recent Laravel/Filament versions and pre-1.0 Headroom dependencies (^0.1, ^0.1.1), so API or schema changes are plausible. Default access is local-only, which is safe but requires deliberate production authorization configuration.
• TPM leverage: Useful for AI spend visibility, model/provider comparison, context-window pressure monitoring, blocked/warned request analysis, tenant-level reporting, and data-subject requests through ledger tag forgetting. It is not positioned as a customer-facing analytics product.
• Key questions: Is the ledger populated consistently enough to make estimates and reported usage trustworthy? Who owns production authorization? Are tenant tags standardised? Is the team prepared to track pre-1.0 dependency changes? What does “estimated” vs billed cost mean for finance reporting? Are tag values potentially sensitive, and is the forget-tag workflow approved for DSR use?

Integration Approach

• Stack fit: Only compatible with modern Laravel/Filament applications. Teams on PHP 8.2 or below, Laravel 10/11, or Filament 3/4 cannot adopt without an upgrade. The plugin assumes the Headroom ledger is already installed and populated.
• Migration path: No migration from a prior plugin version exists because this is v0.1.0. Initial adoption should be a greenfield installation: require the plugin and Headroom dependencies, publish Filament assets and translations, then configure HeadroomPlugin::authorize(), navigation options, defaultRange(), tagLabel(), and optional tenant scoping.
• Compatibility: Tight coupling to Filament 5 and Laravel 12/13 is the primary compatibility constraint. The Headroom dependency versions are early and should be pinned deliberately. Widgets can be used on existing Filament dashboards or kept on the dedicated /headroom pages.
• Sequencing: Start in local with representative ledger data. Configure authorization before any non-local exposure. Validate cost labels, estimate accuracy, tenant scoping, and filter behaviour. Then enable the plugin on an internal admin panel. Add scopeToTenant() before tenant-facing use. Enable allowForgettingTags() only after legal/privacy approval and audit procedures are in place.

Operational Impact

• Maintenance: Expect active maintenance during the pre-1.0 phase. The plugin depends on two early-stage Headroom packages and a recent Filament major version, so upgrade testing should be planned alongside Laravel/Filament upgrades.
• Support: No support model or SLA is indicated in the release notes. Treat this as open-source/internal tooling unless a commercial support arrangement exists. Teams need an internal owner for authorization, tenant mapping, cost interpretation, and ledger data quality.
• Scaling: Dashboard performance will depend on ledger size, indexing, retention, and query patterns. Range filters, per-model/provider spend, run grouping, and “closest to limit” queries can become expensive at high request volume. Validate with production-like data and set retention/archiving expectations.
• Failure modes: Missing or partial ledger usage can understate spend and tokens. Estimated costs may be mistaken for billed costs despite labelling. Misconfigured authorization could expose AI usage data. Incorrect tenant tag mapping could leak or hide data. The tag-forgetting action is irreversible and explicitly cross-tenant, so it must be tightly controlled. Widgets may show gaps where usage was never reported.
• Ramp-up: Low for teams already fluent in Filament and Laravel. Moderate for finance, platform, and privacy stakeholders who need to understand estimate semantics, calibration status, tenant tags, and DSR implications. Publish translations and document the meaning of cost badges before broad internal rollout.