README

Metrics for AI agent runs in Laravel. Its first metric is a polymorphic, cost-aware LLM token-usage ledger: attribute every model call to any owner (user, workspace, organization) and, optionally, to the thing that produced it (a chat message, a report, an enriched record), derive cost from configurable per-model pricing, and query usage and spend per owner. It is built to grow into other agent-run measurements (latency, tool calls, outcomes) over time.

Built to be reused across projects: the ledger is provider-neutral and stores plain provider/model strings, so it works with any LLM stack (Prism, a raw SDK, anything) that can hand you prompt and completion token counts.

Install

composer require whilesmart/eloquent-agent-metrics
php artisan vendor:publish --tag=token-usage-config
php artisan vendor:publish --tag=token-usage-migrations
php artisan migrate

Record usage

TokenMeter is the single write path. Give it the owner, the provider and model that ran, and the raw usage counts; it derives the total and the cost and writes one immutable row.

use Whilesmart\AgentMetrics\Facades\TokenMeter;

TokenMeter::record(
    owner: $workspace,
    provider: 'gemini',
    model: 'gemini-2.0-flash',
    usage: ['prompt_tokens' => 1200, 'completion_tokens' => 300],
    operation: 'report.narrative',
    subject: $report,            // optional: what produced the usage
    metadata: ['harness' => 'report-writer'],
);

The usage array matches the shape most engines already return (prompt_tokens, completion_tokens, and an optional total_tokens).

Query an owner

Add the trait to any owner model:

use Whilesmart\AgentMetrics\Traits\HasTokenUsage;

class Workspace extends Model
{
    use HasTokenUsage;
}

$workspace->tokensUsed(now()->startOfMonth());   // tokens this month
$workspace->tokenCost(now()->startOfMonth());    // cost in currency micro-units

Pricing

config/token-usage.php holds a per-model pricing map. Each rate is the price in currency micro-units (1e-6 of one unit) per 1,000,000 tokens. A model with no entry records a null cost while still counting tokens.

API

Read endpoints, scoped to the owners the authenticated user may access (via whilesmart/eloquent-owner-access):

• GET /api/token-usage paginated ledger, filterable by owner_type/owner_id, operation, provider, model, since, until.
• GET /api/token-usage/{id} a single row.
• GET /api/token-usage/summary aggregated totals plus breakdowns by operation and model.

Set TOKEN_USAGE_REGISTER_ROUTES=false to register your own routes instead.

Customization

Three seams let a host adapt the package without forking it.

Response formatter. Point response_formatter at your own class implementing Whilesmart\AgentMetrics\Interfaces\ResponseFormatterInterface to change the API envelope:

// config/token-usage.php
'response_formatter' => \App\Http\AgentMetrics\MyFormatter::class,

Middleware hooks. Register classes implementing Whilesmart\AgentMetrics\Interfaces\MiddlewareHookInterface; each runs before (may return a replacement Request) and after (returns the JsonResponse) around every read action, keyed by a HookAction (index, show, summary):

// config/token-usage.php
'middleware_hooks' => [
    \App\Http\AgentMetrics\UsageHook::class,
],

Events. Whilesmart\AgentMetrics\Events\TokenUsageRecorded fires after every recorded row, so you can enforce quotas or fan out to your own analytics from a listener.