Laravel Ai Headroom Ledger Laravel Package

Product Decisions This Supports

• Customer-facing usage dashboards and billing surfaces. paginate() plus orderBy(EntrySort::Cost|PercentUsed|CountedAt...) makes it practical to ship a "usage & spend" screen without hand-rolling query logic — sort by cost, tokens, or when a limit was hit, with stable tie-breaking (request ID) so pages don't jitter.
• Multi-tenant SaaS architecture. The new scoped LedgerQuery::find($requestId) / run($invocationId) returning null unless every filter matches is the single most product-relevant item here: it turns "don't leak another tenant's data" from a documented caveat into an enforced default. This should be treated as a prerequisite for any per-customer analytics or support-console feature.
• Roadmap: provider/model cost optimisation and routing. forCountMethod() and GroupedQuery::accuracy() let you answer "how accurate were our token estimates vs. actuals, by model/provider/agent/run" — the evidence base for negotiating pricing, switching models, or justifying a routing/reasoning-effort roadmap item.
• Support and forensics workflows. Filtered lookup by request or invocation ID means support staff can pull a single customer's request history without exposing the tenant boundary — a build-vs-buy argument against writing bespoke audit queries.
• Estimate-accuracy as a trust metric. AccuracyStats (Arrayable, so directly serialisable to API responses) supports an internal or customer-facing "we estimate within X% of actuals" commitment — useful for pricing predictability and for deciding whether estimates can be shown pre-flight.
• Build vs buy: ordering, pagination, rollup-aware filtering, and scoped lookups are exactly the plumbing teams rebuild badly in-house. Each release of this kind steadily shrinks the custom-query layer a team would otherwise own.

When to Consider This Package

Adopt when:

• You already record LLM/AI usage in Laravel and need per-tenant, per-model, per-agent reporting on cost, tokens, and limit usage.
• You need pagination and deterministic ordering on ledger entries for a real UI — including sorting by estimated-vs-actual figures, with consistent null handling and defined tie-breaks.
• You run multi-tenant and want filter-enforced lookups by request/run ID rather than calling unscoped accessors and remembering to scope by hand.
• You want estimate-accuracy reporting broken down by model, provider, agent, tag, or run, including sparse days with zero samples (useful for time-series charts that must not have gaps).
• You rely on daily rollups for performance and want your filters and sorts to be answered from them rather than forcing raw scans.

Look elsewhere or wait when:

• You need multi-currency aggregation with conversion — this release explicitly sorts by stored value without conversion, so cross-currency totals are your problem, not the package's.
• Your reporting needs join-heavy ad-hoc analytics across arbitrary dimensions beyond those exposed (grouping is constrained to model, provider, agent, tag, run, day).
• You're not on a database/version covered by the "requests without the figure sort last on every database" guarantee and need exotic sort semantics.
• You still call the unscoped Ledger::find() / Ledger::run() in a tenant-facing path — behaviour is unchanged, so existing code carries the risk until migrated.
• You need sub-day (hourly/minutely) accuracy granularity; rollups are daily.

How to Pitch It (Stakeholders)

To executives: This release converts raw AI-usage logging into shippable product surface — sortable, paginated usage and cost reporting, plus accuracy metrics that tell us how far our estimates diverge from real spend by model and provider. It also closes a data-isolation gap: per-tenant lookups by request ID cannot return another customer's data. That's a security and compliance win, not just a feature.

To engineering: Low-risk, additive release — new methods and an enum, no breaking changes. Ledger::find()/run() are unchanged but now documented as unscoped, with filtered LedgerQuery equivalents recommended; we should migrate tenant-facing call sites. Rollup-backed filters and sorts mean these queries stay cheap at scale. AccuracyStats is Arrayable, so it drops straight into our API resources.

To product/design: New capabilities are sorting by cost/tokens/percent-used/recency, paged entry lists with correct totals on out-of-range pages, filtering by how a limit was counted, and an accuracy breakdown for either a time series or a per-model/provider/agent/tag/run comparison. Sparse days appear as empty rather than missing, so charts stay honest.

Caveats to state up front: amounts in different currencies are sorted by stored value with no conversion — we must not present mixed-currency totals as meaningful; and estimate-accuracy is only as good as the rollups, which are daily-grained.

Recommendation: Adopt. Prioritise (1) migrating tenant-facing ID lookups to the scoped query methods, (2) a cost-sorted, paginated usage page, (3) an estimate-accuracy view by model/provider as input to pricing and model-routing decisions.