Download the PHP package dewaldhugo/laravel-ai-governor without Composer

Laravel AI Governor

Prompt versioning, token governance, and deployment tooling for Laravel AI applications.

Most Laravel AI packages solve the provider integration problem. AI Governor solves what comes after: how do you version prompts like schema, enforce spending limits per user, and deploy AI configuration through CI without touching production databases?

Compatible with openai-php/laravel and Anthropic. Prism PHP support coming soon.

Requirements

Compatibility

Installation

Publish the config and run migrations:

Set your provider key in .env:

Core Concepts

AI Governor is built around three independent concerns that compose into a governance layer:

Prompt Migrations — Prompt definitions live in version control as PHP files. A sync command writes them to the database deterministically, making prompt state part of your deployment pipeline.

Budget Enforcement — Any Eloquent model (User, Team, Tenant) can hold a token budget. The GovernedExecutor checks the budget before calling the provider and records usage after. Hard limits throw an exception. Soft limits log a warning.

The Adapter Contract — Provider calls are isolated behind a single interface. Swap providers by changing one config value. Your application code never changes.

Prompt Migrations

1. Generate a definition

This creates a timestamped file in app/Prompts:

2. Sync to the database

Add this to your deploy script after php artisan migrate. Prompts are scoped to the current Laravel environment automatically, so staging and production never share definitions.

Preview changes before writing:

3. Rollbacks

Revert the definition file in Git, redeploy, and run the sync command. No manual database edits required.

Executing Prompts

Resolve the prompt by name and run it through the GovernedExecutor:

PromptVersion::resolve() always returns the latest version scoped to the current environment.

Token Budgets

Add the trait to your model

Set a budget

Execute with enforcement

Pass $owner to the executor and it handles the rest:

If the user has exhausted their budget, a BudgetExceededException is thrown before the provider is called — no tokens consumed, no cost incurred.

Check usage

Route middleware

Protect entire routes without touching controller logic:

Returns a 429 JSON response when the budget is exceeded.

Note: Unauthenticated requests (where $request->user() returns null) pass through the middleware without a budget check. If your AI routes must be protected for all traffic, ensure ai.budget is applied after an authentication middleware (auth, auth:sanctum, etc.) in the stack.

Switching Providers

Change one line in config/ai-governor.php:

Set the corresponding key in .env for your chosen provider:

To build a custom adapter, implement the AiProviderAdapter contract:

Then bind it in config/ai-governor.php or register it in a Service Provider.

Testing

Use the NullAdapter to test your application logic without making real API calls.

Bind a configured instance into the container — do not use app->bind() with the class name, as that would construct the adapter with default values and ignore your configured response:

Each test that needs a different response simply re-binds a new instance. Because state lives on the instance rather than in static properties, tests running in parallel cannot interfere with each other.

Artisan Reference

CI Integration

Recommended deploy script order:

The sync command exits with code 1 if any definition fails, so a failed sync will halt your pipeline before the new release receives traffic.

Changelog

See CHANGELOG.md.

Contributing

Pull requests welcome. Please write tests for new functionality and run composer test before opening a PR.

License

MIT. See LICENSE.md.