USAIGE: Track Token Usage and Costs for Laravel AI SDK Requests

USAIGE is a Laravel package that attaches observability to the Laravel AI SDK. It records every AI request as a run with token counts, costs, provider and model details, timing, and error status — then surfaces all of it through a built-in web dashboard.

#Two Helpers, Three Lines

The integration is built around two global helpers. ai_run() opens a tracking context tied to a feature identifier, and ai_usage() records what the SDK response consumed:

$run = ai_run('summarize-document');
$response = Ai::text('Summarize: ' . $document->content);
$usage = ai_usage($run, $response);

The package detects the response shape automatically. It handles responses from the Laravel AI SDK, the OpenAI PHP SDK, and plain arrays, pulling token counts without any extra configuration. When none of those shapes match, you can pass the counts directly:

$usage = ai_usage($run, promptTokens: 200, completionTokens: 80);

#Provider, Model, and Cost Resolution

USAIGE reads config/ai.php to fill in the provider and model on each run. Both can be overridden per call or by passing a Lab enum directly:

$run = ai_run('classify-ticket', model: 'gpt-4o-mini', provider: 'openai');

Costs are stored with sub-cent precision. The ai_usages table keeps both prompt and completion token counts alongside the USD total per run, so you can query spend by feature, user, model, or date range using the AiRun model.

#User Tracking and Metadata

By default, the run is associated with auth()->id(). You can override this globally when the default resolver does not fit:

use Laraveljutsu\Usaige\Facades\Usaige;
 
Usaige::resolveUsersUsing(fn () => auth()->user()?->team_id);

Or pass a user ID per call. Runs also accept arbitrary JSON metadata for attaching context like ticket IDs or tenant identifiers:

$run = ai_run('generate-report', metadata: [
    'tenant_id' => $tenant->id,
    'ticket'    => 'PROJ-1042',
]);

When an AI call fails before ai_usage() runs, you can record the failure explicitly:

$run->fail('Rate limit exceeded');

#Dashboard

The package registers a dashboard at /usaige that lists all runs with their status, provider, model, token counts, costs, and duration. Access is controlled through middleware configuration in config/usaige.php, or with a callback:

Usaige::auth(fn ($request) => $request->user()?->isAdmin());

The dashboard path, middleware, and database table names are all configurable through the published config file.

#Installation

The package requires PHP 8.5+, Laravel 11+, and laravel/ai ^0.8.1:

composer require laraveljutsu/usaige
php artisan migrate

You can find the source and full documentation on GitHub.