Download the PHP package jpsantosbembe/laravel-ai-budget without Composer

Laravel AI Budget

Cost-governed LLM execution for Laravel.

Most LLM packages are transport wrappers: they hand you a client and leave the bill to you. This one starts from the other end. You describe a task once as a profile — model, fallback, limits, output schema, retries and a spend ceiling — and every run through that profile is checked against the ceiling before a single token is spent, validated on the way out, and written to a usage log with its real cost.

It was extracted from a production application where it has been running since April 2026.

What it actually does

Installation

Publish the configuration when you want to own the price table or point at a live FX rate:

Getting started

Store a credential and define a profile:

Run it:

Ask what it would cost before committing to it:

Currency

Provider prices are quoted in USD; budgets are usually not. Set your currency and how to convert:

max_cost_per_run and cost_local are then expressed in that currency, and cost_usd is always kept alongside it.

Pipelines

A pipeline is an ordered list of stages. map stages fan out — one queued job per item — and single stages run once, typically to synthesise what the previous stages produced.

Progress is reported through the PipelineProgress event. It is a plain event, not a broadcast one: the durable state lives in the database and progressSnapshot() rebuilds the identical payload over HTTP, so a websocket is an optimisation rather than a requirement. Pipelines need Laravel's job_batches table (php artisan queue:batches-table).

Providers

OpenRouterTransport ships with the package. Add your own by implementing ChatTransport and registering it:

The transport is selected per credential through its provider column, so different profiles can run against different providers in the same application.

An implementation must translate provider failures into the package's exceptions — InvalidCredentialException for a rejected key, and RateLimitedException when throttled — so retries and fallback behave the same everywhere.

Schema validation

The bundled validator supports the subset of JSON Schema that structured LLM output actually uses: type, required, properties, items and enum, recursively. That keeps the package dependency-free. If you need the full spec, implement SchemaValidator around a real validator and point ai-budget.schema_validator at it.

Behaviour worth knowing

A rejected API key disables the credential. A 401 means every later run would fail the same way, so the credential is switched off and the exception propagates once, instead of silently burning through your queue.

A failed re-ask is still recorded. If the output fails the schema twice, the tokens from both calls are written to the usage log before SchemaMismatchException is thrown. A run that vanished from the log would be exactly the run you most need to see: the model returning garbage while the bill climbs.

Unknown models are expensive by default. A model missing from the price table falls back to the configured generic price rather than zero, because a zero would quietly disable the ceiling for the models nobody registered.

Requirements

PHP 8.3+ and Laravel 12, on PostgreSQL, MySQL or SQLite.

Laravel 11 is deliberately not supported: as of this release every 11.x release carries an unresolved security advisory, so Composer refuses to install it under its default policy. Supporting a line you cannot install cleanly is a promise the package cannot keep.

Testing

License

MIT. See LICENSE.md.