Introduction

Laravel Spectra is a comprehensive observability package for AI and LLM operations in Laravel applications. It intercepts outgoing requests to AI providers, extracts usage metrics such as token counts and media quantities, calculates costs from a database-driven pricing catalog, and persists analytics-ready records that power a built-in real-time dashboard.

Modern applications increasingly rely on AI APIs for text generation, image synthesis, embeddings, speech processing, and more. As usage grows, so does the need to answer critical operational questions: which models are consuming the most tokens, how much each feature costs, which users are driving the highest spend, and where latency and failure patterns emerge. Spectra provides a single, unified observability layer that answers all of these questions without requiring you to instrument each call manually.

How It Works

When your application sends a request to a supported AI provider, Spectra intercepts it through one of several tracking mechanisms — automatic watchers, provider macros, Guzzle middleware, or explicit manual tracking. The intercepted request flows through a processing pipeline that identifies the provider, resolves the appropriate handler, extracts usage metrics into typed data transfer objects, calculates the cost from the pricing catalog, and persists the complete record to the database. Daily statistics are aggregated in real time, and traces can optionally be exported to OpenTelemetry-compatible backends.

The entire process is transparent to your application code. In most cases, you install the package, run the installer, and tracking begins automatically with no code changes required.

Supported Providers

Provider	Model Types
OpenAI	Text, Embedding, Image, Video, TTS, STT
Anthropic	Text
Google AI	Text, Embedding, Image, TTS
Groq	Text
xAI (Grok)	Text, Image, Video
OpenRouter	Text, Image
Ollama	Text
Replicate	Text, Image, Video
ElevenLabs	TTS
Cohere	Text
Azure OpenAI	Text, Embedding, Image, Video, TTS, STT

You can also add support for additional providers by creating a custom provider class. See Custom Providers for details.

Key Features

• Automatic tracking — Watchers intercept Laravel HTTP client and OpenAI PHP SDK requests with zero code changes. Provider macros and Guzzle middleware provide additional integration points.
• Multimodal support — Track text completions, embeddings, image generation, video generation, text-to-speech, and speech-to-text across all major providers.
• Cost calculation — A database-driven pricing catalog with support for token-based, per-image, per-video, per-minute, per-second, and per-character pricing. Multiple pricing tiers (standard, batch, flex, priority) are supported per model.
• Budget enforcement — Define cost, token, and request-count limits per user, team, or any Eloquent model. Enforce budgets via middleware with hard blocks or soft warning events.
• Real-time dashboard — A built-in SPA with request exploration, cost analysis, cost comparison, pricing management, and per-user analytics.
• Streaming support — Track SSE streaming responses with time-to-first-token metrics and full token accounting, including streamed image generation via OpenAI's Responses API.
• Media persistence — Automatically download and store generated images and videos to any Laravel filesystem disk before provider URLs expire.
• Tags and metadata — Attach custom key-value context to any request for filtering and grouping in the dashboard.
• User attribution — Automatically associate requests with the authenticated user or manually assign them to any Eloquent model.
• Flexible persistence — Persist records synchronously, after the HTTP response, or via a queue job depending on your latency requirements.
• OpenTelemetry integration — Export AI request traces to any OTLP-compatible backend for correlation with your existing observability infrastructure.
• Extensible — Add custom provider support by implementing a handler class and registering it in the configuration.