Laravel Spectra Laravel Package

Product Decisions This Supports

Spectra 2.0 turns AI spend from an estimate into a defensible, per-request ledger, which unlocks a specific class of product decisions rather than generic "observability."

• Pricing and packaging decisions. With 12 catalogs refreshed to October 2026 models (Claude 5.x, GPT-6/GPT-5.6, Gemini 3.8/4, Grok 4.5–4.7) and per-catalog currency plus exchange rates, PMs can answer "what does a typical session cost us in EUR?" without a spreadsheet reconciliation. That is the input to seat pricing, credit packs, and whether a free tier is affordable per cohort rather than on average.
• Feature-level unit economics. New pricing dimensions — cache writes, long-context aboveInputTokens thresholds, dated price changes (since), audio/image token rates, megapixel/page/request units, fast/ultrafast tiers — mean formerly invisible cost cliffs are now line items. Prompt caching, long-context surcharges, and reasoning tokens are exactly the levers that decide whether a feature is viable; the 2.0 fixes (Anthropic cache reads/writes, Gemini thinking and tool-use tokens, xAI reasoning) mean earlier cost baselines were systematically understated and should be re-derived before any pricing decision is finalized.
• Roadmap sequencing for agentic and streaming features. Streaming is now tracked as the app consumes it (SSE, NDJSON, streamed JSON arrays, early-aborted streams, in-stream error events) across the HTTP client, Prism, the Laravel AI SDK, openai-php and Guzzle. Previously a streamed response stored a zero-token row and left the app with an empty body — meaning the entire streaming roadmap was both unpriced and quietly broken at the transport level. Teams can now commit to streaming UX without a cost blind spot.
• Multi-step / agentic product bets via traces. One trace per request, with queued jobs and nested dispatches inheriting the trace id and W3C traceparent joined as the OpenTelemetry parent, plus conversation_id and conversation_turn, means a PM can price a conversation or a workflow, not just a call. That is the prerequisite for deciding whether agents are sold per-seat, per-run, or per-outcome.
• Margin guardrails and budget-driven scope cuts. Budgets now work with morph maps (the 1.x class-name vs morph-alias bug meant per-user and budget lookups silently found nothing in any app using a morph map — a correctness failure, not a cosmetic one), multipart audio uploads price correctly when the file precedes the model, and alerts fire once per period instead of on every FPM request. Reliable per-tenant budgets turn "we should cap usage" from an aspiration into a shippable feature.
• Build vs. buy. The 2.0 surface — 12 maintained catalogs, provider-reported costs, regional surcharges, retired-model history, alias/snapshot/routing-suffix resolution, OpenTelemetry GenAI semantic conventions, media-aware pruning, and a redesigned dashboard with token breakdowns and a trace timeline — is a standing maintenance obligation, not a one-time build. That argues for buy unless AI cost is itself a differentiating product surface.
• Incident and support triage. error_type/error_message stored from the provider, connection failures recorded and still thrown, request_source, laravel_request_id, ip_address, user_agent, and provider-reported latency replacing client-side timing give support a defensible answer to "why did this user's request fail and what did we still pay for?"
• Retention and privacy decisions. Prompt storage off now genuinely stops the raw body being saved (it didn't in 1.x), and spectra:prune --stats-days with chunked deletion plus media cleanup lets a PM set a retention policy that survives a legal review.
• Where the roadmap is heading. The dashboard's trace timeline, conversation columns, and OpenTelemetry semantic-convention spans signal that the next competitive axis is conversation- and workflow-level accounting. Teams that adopt now are positioned for it; teams that build bespoke token logging will be re-platforming into it later.

When to Consider This Package

Strong fit when:

• You ship LLM features on Laravel 12 or 13 with more than one provider, or one provider plus caching, streaming, or reasoning models. The catalog breadth and alias/snapshot resolution are the point.
• AI inference is a material COGS line, or is about to be one. Per-user, per-tenant, or per-feature attribution is a real question someone in finance is asking.
• You are introducing budgets, quotas, or metered billing and need enforcement that survives queue workers and Octane rather than firing per FPM request.
• You run agentic or multi-step flows where the unit of cost is a conversation or a job chain, not a single call. The trace model with traceparent interop is the differentiator here.
• You already use OpenTelemetry or expect to. GenAI semantic-convention spans mean you don't have to choose between a vendor dashboard and your existing observability stack.
• Prompt payloads, user identifiers, and IPs are involved and someone will ask about retention. The storage-off fix and pruning options matter.

Look elsewhere or wait when:

• You are on Laravel 11. Support is dropped, and the justification given — that Laravel 11 no longer receives security fixes — is legitimate rather than arbitrary. Treat this as an upgrade gate: the framework upgrade is the real project, and Spectra 2.0 is a passenger.
• You run a non-Laravel PHP stack or a polyglot service fleet. The tracking layer is framework-shaped. The OpenTelemetry output partially mitigates this, but you would be paying for a dashboard you can only half-feed.
• You need vendor-side billing reconciliation for invoicing. Provider-reported costs and currency conversion are useful, but this is an internal cost-intelligence tool, not a billing system of record. Don't let it become one without a reconciliation step.
• You need sub-request latency profiling. This prices and attributes AI calls; it is not an APM replacement. Pair it with one.
• Your spend is trivial and single-provider. Below a meaningful threshold, the migration cost — new columns, migrations, a scoped-service change, and an audit of any code touching global tags, trackables, or tier settings — exceeds the value. Note that the leak fixes are behavioural corrections; code that accidentally relied on the leaky behaviour will now behave differently.

Two adoption risks to raise explicitly:

1. Re-baseline before you decide. The 1.x numbers were wrong in known directions: Anthropic cache reads subtracted from an already-exclusive input_tokens and cache writes never billed at all; Gemini thinking/tool-use tokens and xAI reasoning tokens unbilled; polled async jobs counted once per poll, inflating daily stats and budgets; streams stored as zero-token rows. Any pricing, packaging, or margin decision made on 1.x data should be treated as provisional until re-measured. This is the single most important thing to say out loud, because the direction of error was mostly understatement for the providers people actually use.
2. The scope change is a breaking change in disguise. Spectra is now a scoped service to stop global tags, trackables, tiers and metadata leaking between queued jobs and Octane requests. That is correct, but any code setting global state and expecting it to persist across a job boundary will now find it absent. Budget the migration as an engineering task with a test pass, not a composer bump.

How to Pitch It (Stakeholders)

For executives — one paragraph: We currently cannot say what a given AI feature, customer, or conversation costs us, and what we do report is known to be wrong in the expensive direction: prompt caching, reasoning tokens, and streamed responses are all under-billed or untracked in the version we run today. Spectra 2.0 gives us a per-request, per-conversation cost ledger across every model we use, with current October 2026 pricing, currency conversion, working budgets, and a dashboard we can put in front of finance. It replaces a recurring engineering maintenance burden — twelve pricing catalogs and provider-specific billing quirks — with a dependency. The cost is a Laravel 11→12/13 upgrade we should be doing anyway on security grounds, plus a scoped migration and a re-baselining exercise. The decision it unlocks is concrete: we can price, cap, and defend AI features instead of guessing at them.

For engineering — the honest summary: This is a substantial correctness release, and much of it is bug fixes rather than features. Streaming no longer breaks the caller's response body while logging a zero-token row; Anthropic cache accounting is fixed at the root; Gemini thinking and tool-use tokens and xAI reasoning tokens are billed; async polling no longer double-counts into daily stats; morph-alias lookups for trackables now resolve; multipart uploads no longer price at $0. Saving a tracked request can no longer throw into the app — failures are reported instead — which matters for request-path safety. The architecture change to note is Spectra becoming a scoped service, which fixes real state leakage across queued jobs and Octane but will surface in any code relying on the old global behaviour. We also gain trace-per-request with queued-job propagation and W3C traceparent joining, OpenTelemetry GenAI semantic conventions, a pruning command that chunks and cleans up stored media, and a request-detail view with an input (uncached / cache-read / cache-write) and output (answer / reasoning) token breakdown. Requirements move to Laravel 12–13 and PHP 8.2–8.5. The upgrade guide is in UPGRADE.md; plan for a migration, a config review (trace_per_request, use_traceparent, exchange_rates), and a before/after cost comparison on a representative workload so we can quantify how wrong the old numbers were.

For finance and finance-adjacent stakeholders: Expect reported AI spend to increase after this upgrade without any change in usage. That is the correction landing, not a regression. Ask for the re-baselined figure before signing off on any pricing or margin model built on prior data.

What to ask for as proof in the first 30 days: a per-feature cost breakdown for one real customer cohort, one budget enforced end-to-end (including through a queued job), and one trace showing every AI call in a single user request with its total cost and token split. If those three land, the tool has earned its place in the stack.