PHPackages                             oi-lab/oi-laravel-ai - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [Utility & Helpers](/categories/utility)
4. /
5. oi-lab/oi-laravel-ai

ActiveLibrary[Utility & Helpers](/categories/utility)

oi-lab/oi-laravel-ai
====================

AI backend for Laravel: provider/model catalog with pricing, request usage tracking and cost reporting, agent system-prompt registry and a self-updating tariff registry.

v1.2.0(3w ago)086↑450%1MITPHP ^8.3

Since Jun 30Compare

[ Source](https://github.com/oi-lab/oi-laravel-ai)[ Packagist](https://packagist.org/packages/oi-lab/oi-laravel-ai)[ RSS](/packages/oi-lab-oi-laravel-ai/feed)WikiDiscussions Synced 1w ago

READMEChangelogDependencies (24)Versions (6)Used By (1)

[![OI Laravel AI](./assets/github-preview.png)](./assets/github-preview.png)

OI Laravel AI Add-on
====================

[](#oi-laravel-ai-add-on)

[![Latest Version on Packagist](https://camo.githubusercontent.com/646050670b23cd7271d6bd67ef44894b3fa417ef9ff816fcad7203146c25105c/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f762f6f692d6c61622f6f692d6c61726176656c2d61692e737667)](https://packagist.org/packages/oi-lab/oi-laravel-ai)[![Total Downloads](https://camo.githubusercontent.com/93f5e9c3c38626bc46c1bd1334f0f0d221bd3dbdbf15209b232725f38237a637/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f64742f6f692d6c61622f6f692d6c61726176656c2d61692e737667)](https://packagist.org/packages/oi-lab/oi-laravel-ai)[![Tests](https://camo.githubusercontent.com/25b422e03aa81539b07a9df941675f786e3382ea3c7fb5453a2cc2b134f8015d/68747470733a2f2f696d672e736869656c64732e696f2f6769746875622f616374696f6e732f776f726b666c6f772f7374617475732f6f692d6c61622f6f692d6c61726176656c2d61692f74657374732e796d6c3f6c6162656c3d7465737473)](https://github.com/oi-lab/oi-laravel-ai/actions)[![License](https://camo.githubusercontent.com/9322d6b289f5c9c549a7f6af5431e0578646c58261a60510fc27bd039b788a05/68747470733a2f2f696d672e736869656c64732e696f2f6769746875622f6c6963656e73652f6f692d6c61622f6f692d6c61726176656c2d6169)](LICENSE)

The AI backend for your Laravel application. It maintains a provider/model catalog with pricing, records the token usage of every agent call, reports cost per project / agent / model, and centralizes your agents' system prompts.

Features
--------

[](#features)

- **Provider & model catalog** — `AiProvider` / `AiModel` tables with per-1M-token input/output pricing, seeded from a JSON registry shipped with the package.
- **Automatic usage tracking** — a listener records every `Laravel\Ai\Events\AgentPrompted` event into `ai_requests` (tokens, model, provider, project), with zero host code.
- **Cost reporting** — `AiUsageReporter` aggregates usage into per-project, per-agent, and per-model cost summaries over any period.
- **Prompt registry** — `AiPromptVariableRegistry` is the single source of truth for agent system prompts, with `:variable` placeholder compilation (mirrors mail templating).
- **Self-updating tariffs** — `php artisan ai:update-registry` fetches a fresh catalog and pricing from a remote URL and persists it locally.
- **Host-agnostic** — resolves the host's `Project` / `AgentRun` models through config and persists settings through a `SettingStore` contract.

Requirements
------------

[](#requirements)

- PHP 8.2+
- Laravel 12 or 13
- [`laravel/ai`](https://github.com/laravel/ai) 0.7+

Installation
------------

[](#installation)

```
composer require oi-lab/oi-laravel-ai
```

The package auto-discovers and registers itself via Laravel's service provider mechanism.

### Assisted installation (recommended)

[](#assisted-installation-recommended)

Run the interactive installer and answer the prompts — it publishes the config, captures the host models / setting store / registry into your `.env`, runs the migrations, and seeds the catalog. Every step is confirmed, so it is safe to re-run:

```
php artisan ai:install
```

### Manual installation

[](#manual-installation)

```
php artisan vendor:publish --tag=oi-laravel-ai-config
php artisan vendor:publish --tag=oi-laravel-ai-migrations
php artisan migrate
```

> The `ai_requests` table has nullable foreign keys to your `projects` and `agent_runs` tables (UUID keys). Make sure those tables exist before migrating, or adjust the published migration to match your schema.

Configuration
-------------

[](#configuration)

`config/oi-laravel-ai.php`:

KeyDescription`models.project`Host `Project` model the `AiRequest.project_id` FK resolves to.`models.agent_run`Host `AgentRun` model the `AiRequest.agent_run_id` FK resolves to.`setting_store`Class implementing `SettingStore`, used to persist default models and prompt overrides. Leave `null` to auto-detect: the `oi-lab/oi-laravel-settings` adapter is wired automatically when that package is installed.`context_binding`Container binding resolving the "current team" used to scope settings.`registry.path`Writable, host-owned registry copy used by the seeder and `ai:update-registry`. Falls back to the bundled `assets/registry.json` when null.`registry.url`Canonical raw URL `ai:update-registry` fetches a fresh registry from.All keys read from environment variables (`OI_AI_PROJECT_MODEL`, `OI_AI_SETTING_STORE`, `OI_AI_REGISTRY_PATH`, `OI_AI_REGISTRY_URL`, …).

Usage
-----

[](#usage)

### Catalog

[](#catalog)

```
use OiLab\OiLaravelAi\Support\AiCatalog;

$registry = AiCatalog::read();   // bundled asset or host-configured path
$counts = AiCatalog::sync($registry); // upserts providers + models
// ['providers' => 5, 'models' => 15]
```

Seed the catalog (and, when a `SettingStore` is bound, the default models + prompts) from your `DatabaseSeeder`:

```
$this->call(\OiLab\OiLaravelAi\Database\Seeders\AiCatalogSeeder::class);
```

### Usage tracking

[](#usage-tracking)

Tracking is automatic. Once the package is installed, every agent prompt dispatched through `laravel/ai` is recorded:

```
use OiLab\OiLaravelAi\Models\AiRequest;

AiRequest::query()->where('prompt_type', 'DocWriterAgent')->count();
```

### Cost reporting

[](#cost-reporting)

```
use OiLab\OiLaravelAi\Services\AiUsageReporter;

$summary = app(AiUsageReporter::class)->summaryForProjects(
    projectIds: [$project->id],
    start: now()->startOfMonth(),
    end: now()->endOfMonth(),
);

$summary->estimated_cost_usd; // float, rounded to 4 decimals
$summary->by_agent_type;      // [['prompt_type' => ..., 'count' => ..., ...], ...]
$summary->by_model;           // [['model_name' => ..., 'count' => ..., ...], ...]
```

### Prompt registry

[](#prompt-registry)

```
use OiLab\OiLaravelAi\Support\AiPromptVariableRegistry;

$prompt = AiPromptVariableRegistry::compile(
    AiPromptVariableRegistry::defaultPrompt(AiPromptVariableRegistry::DOC_WRITER),
    ['project_name' => 'Acme', 'language' => 'français'],
);
```

The `app_name` global is injected automatically. Use `AiPromptVariableRegistry::keys()`, `label()`, and `variablesFor()` to build a settings UI.

Commands
--------

[](#commands)

```
# Assisted, interactive installation (publish, configure, migrate, seed).
php artisan ai:install [--force]

# Refresh the catalog + pricing from the configured remote registry URL.
php artisan ai:update-registry [--url=https://…] [--no-write]
```

Customizing host models
-----------------------

[](#customizing-host-models)

The package never hardcodes your domain models. Override the bindings in config so `AiRequest` belongs to your own `Project` / `AgentRun`:

```
'models' => [
    'project' => \App\Models\Project::class,
    'agent_run' => \App\Models\AgentRun::class,
],
```

Settings (default models, prompt overrides) are persisted through the `SettingStore` contract. Install the recommended `oi-lab/oi-laravel-settings` (listed under `suggest`) and its adapter is wired automatically. To use your own storage, implement `OiLab\OiLaravelAi\Contracts\SettingStore` and point `setting_store` at it.

Testing
-------

[](#testing)

```
composer test
```

AI Assistant Skills
-------------------

[](#ai-assistant-skills)

This package ships a skill that teaches AI coding assistants (Claude Code, JetBrains AI) how to use it. The recommended way to install it is the unified `oi:skills` command from `oi-lab/oi-laravel-development`:

```
php artisan oi:skills oilab-laravel-ai --project
```

A deprecated package-local fallback is available for projects that don't use `oi-lab/oi-laravel-development`:

```
php artisan oi-ai:install-ai-skill
```

See [docs/advanced/skills.md](docs/advanced/skills.md) for details.

Documentation
-------------

[](#documentation)

The `docs/` folder is importable into any app using [`oi-lab/oi-laravel-documentation`](https://packagist.org/packages/oi-lab/oi-laravel-documentation):

```
php artisan doc:import
```

License
-------

[](#license)

The MIT License (MIT). See [LICENSE](LICENSE).

Credits
-------

[](#credits)

**[Olivier Lacombe](https://www.olacombe.com)** - Creator and maintainer

Olivier is a Product & Technology Director based in Montpellier, France, with over 20 years of experience innovating in UX/UI and emerging technologies. He specializes in guiding enterprises toward cutting-edge digital solutions, combining user-centered design with continuous optimization and artificial intelligence integration.

**Projects & Resources:**

- [OI Dev Docs](https://dev.olacombe.com) - Documentation for all Open Source OI Lab packages
- [OnAI](https://onai.olacombe.com) - Training courses and masterclasses on generative AI for businesses
- [Promptr](https://promptr.olacombe.com) - Prompt engineering Management Platform

Support
-------

[](#support)

For support, please open an issue on the [GitHub repository](https://github.com/oi-lab/oi-laravel-ai/issues).

###  Health Score

44

—

FairBetter than 90% of packages

Maintenance95

Actively maintained with recent releases

Popularity12

Limited adoption so far

Community6

Small or concentrated contributor base

Maturity52

Maturing project, gaining track record

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Every ~7 days

Total

5

Last Release

23d ago

PHP version history (2 changes)v1.0.0PHP ^8.2

v1.2.0PHP ^8.3

### Community

Maintainers

![](https://avatars.githubusercontent.com/u/369876?v=4)[Olivier Lacombe](/maintainers/olacombe)[@olacombe](https://github.com/olacombe)

---

Tags

laravelaiusagellmpricingprompts

###  Code Quality

TestsPest

Code StyleLaravel Pint

### Embed Badge

![Health badge](/badges/oi-lab-oi-laravel-ai/health.svg)

```
[![Health](https://phpackages.com/badges/oi-lab-oi-laravel-ai/health.svg)](https://phpackages.com/packages/oi-lab-oi-laravel-ai)
```

###  Alternatives

[laravel/ai

The official AI SDK for Laravel.

1.1k4.6M333](/packages/laravel-ai)[psalm/plugin-laravel

Psalm plugin for Laravel

3345.4M354](/packages/psalm-plugin-laravel)[laravel/cashier

Laravel Cashier provides an expressive, fluent interface to Stripe's subscription billing services.

2.6k31.8M163](/packages/laravel-cashier)[laravel/mcp

Rapidly build MCP servers for your Laravel applications.

79227.1M246](/packages/laravel-mcp)[aedart/athenaeum

Athenaeum is a mono repository; a collection of various PHP packages

265.2k](/packages/aedart-athenaeum)[api-platform/laravel

API Platform support for Laravel

58190.1k21](/packages/api-platform-laravel)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)