PHPackages                             padosoft/laravel-ai-finops - 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. padosoft/laravel-ai-finops

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

padosoft/laravel-ai-finops
==========================

Enterprise AI spend-governance for Laravel: cross-provider metering, budgets, policy enforcement, chargeback, forecasting, cost-aware routing and FinOps — the governance brick for AI agents. Hooks the official laravel/ai SDK at a single point.

v1.2.1(1w ago)186↓65.1%1Apache-2.0PHPPHP ^8.3CI passing

Since May 27Pushed 1w agoCompare

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

READMEChangelog (4)Dependencies (11)Versions (8)Used By (1)

Laravel AI FinOps
=================

[](#laravel-ai-finops)

> **Govern every euro your AI spends.** Cross-provider metering, budgets, policy enforcement, chargeback, forecasting and cost‑aware routing for Laravel — the FinOps/governance brick for AI agents.

 [![CI](https://github.com/padosoft/laravel-ai-finops/actions/workflows/ci.yml/badge.svg)](https://github.com/padosoft/laravel-ai-finops/actions/workflows/ci.yml) [![PHP](https://camo.githubusercontent.com/0834b91e089583ebf71bdce122d3ea5f97bfc28fd9f743e349ce9520958d3bfa/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f5048502d382e33253230253743253230382e34253230253743253230382e352d373737424234)](https://camo.githubusercontent.com/0834b91e089583ebf71bdce122d3ea5f97bfc28fd9f743e349ce9520958d3bfa/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f5048502d382e33253230253743253230382e34253230253743253230382e352d373737424234) [![Laravel](https://camo.githubusercontent.com/9968736f39e4b95ff4a6c6a2e49141a56ffd5919aea3b65a9879d0175ac2dc93/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f4c61726176656c2d313225323025374325323031332d464632443230)](https://camo.githubusercontent.com/9968736f39e4b95ff4a6c6a2e49141a56ffd5919aea3b65a9879d0175ac2dc93/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f4c61726176656c2d313225323025374325323031332d464632443230) [![laravel/ai](https://camo.githubusercontent.com/880058c6e9a00cb25a95cda4928f3a2b8b7c1a63807e888ff80a723bee60d437/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f6c61726176656c25324661692d302e36253230253743253230302e372d363336364631)](https://camo.githubusercontent.com/880058c6e9a00cb25a95cda4928f3a2b8b7c1a63807e888ff80a723bee60d437/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f6c61726176656c25324661692d302e36253230253743253230302e372d363336364631) [![License](https://camo.githubusercontent.com/35b94db23d3ed026343335f74d52ce31e74b77ad7dab4e4b89f49f2026e0937f/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f6c6963656e73652d4170616368652d2d322e302d626c7565)](https://camo.githubusercontent.com/35b94db23d3ed026343335f74d52ce31e74b77ad7dab4e4b89f49f2026e0937f/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f6c6963656e73652d4170616368652d2d322e302d626c7565)

[![Laravel AI FinOps](resources/laravel-ai-finops-banner.png)](resources/laravel-ai-finops-banner.png)

`laravel-ai-finops` plugs into the official [`laravel/ai`](https://github.com/laravel/ai) SDK at a **single point** and meters **every** AI call — any provider, any model — then lets you set budgets, enforce policies, attribute spend, forecast overruns and route by quality‑per‑dollar. It is **zero‑hard‑dependency** on the rest of your stack: every sibling integration is an opt‑in seam.

---

Table of Contents
-----------------

[](#table-of-contents)

- [Why it's different](#why-its-different)
- [Quick start](#quick-start)
- [How it works](#how-it-works)
- [Features](#features)
- [Web Admin Panel](#web-admin-panel)
- [API overview](#api-overview)
- [Artisan commands](#artisan-commands)
- [Integrations (opt‑in seams)](#integrations-optin-seams)
- [Configuration](#configuration)
- [Testing](#testing)
- [License](#license)

---

Why it's different
------------------

[](#why-its-different)

Most tools either **track** cost or **block** it. This package does both, and goes further:

- 🎯 **One hook, every provider.** A single listener on the `laravel/ai` lifecycle meters OpenAI, Anthropic, Gemini, Mistral, DeepSeek, xAI, Bedrock, Azure, **and `padosoft/laravel-ai-regolo`** — no per‑provider wiring.
- 💸 **Always‑fresh, multi‑source pricing.** LiteLLM's 2,600+ model price DB **⊕ OpenRouter's live models API ⊕ your local manual prices** (for feed‑less providers like **regolo.ai** — EUR / per‑1M entry). A per‑provider authority map picks *who actually bills you*; unmapped providers fall back to the **freshest‑synced** feed (env‑configurable tie‑break). Manual overrides always win. Never ship stale hard‑coded prices again.
- 🧾 **Flat‑rate subscription coverage.** Pay a monthly plan (Claude Max, OpenAI Pro…)? Define a `[from, to]` window per provider and calls are metered at **€0** while covered (tokens still tracked); routing prefers covered providers to "stay within the plan", and you shorten the window the moment the provider says the quota is spent. Plus an optional per‑provider overhead % (e.g. OpenRouter's ~5.5% credit fee) folded into estimates — the raw ledger stays pass‑through.
- 🎯 **Truest‑cost cascade + we recover what `laravel/ai` throws away.** The official SDK normalizes every response to **tokens only** and **drops the provider's real billed cost** (and raw payload). We get it back: a global HTTP capture reads e.g. OpenRouter's `usage.cost` before it's discarded, so each call is priced by the truest number available — **(a) actual billed cost → (b) actual tokens × your tariff → (c) estimated tokens × tariff** — and every ledger row records **which method** and **whether tokens were estimated**. Token estimation is built‑in (heuristic), with **exact counts via the optional [`yethee/tiktoken`](https://github.com/yethee/tiktoken-php)**. Media providers (fal.ai) are priced per second/image/megapixel.
- 🧱 **N‑scope budgets** (global → tenant → user → cost‑center → provider → model → agent → purpose) × periods (daily…yearly + rolling), with soft/hard limits. A hard budget blocks further calls with HTTP **402**; pass a pre‑flight cost estimate (or use `diagnostics/estimate`) to also block the single call that *would* exceed.
- 🛡️ **Policy DSL + approvals** — declarative `block / require_approval / downgrade / throttle / queue`with a human approval workflow; scoped **kill switches**; HTTP **402** enforcement.
- 🧠 **Cost‑aware routing** — pick the cheapest model that clears a quality bar (quality from `eval-harness`).
- 🔮 **Forecasting & anomalies**, 🧪 **what‑if simulator** (replay traffic re‑priced on another model), 📡 **live streaming meter with mid‑stream cutoff**, 🌱 **CO₂/ESG footprint**, 💳 **prepaid credit pools**, 📈 **provider price‑change watcher**, 🗣️ **NL FinOps copilot**.
- 🧾 **Chargeback/showback**, immutable **audit trail**, multi‑currency, multi‑tenant, GDPR‑friendly.
- 🔗 **Agentic glue** — a `trace‑id` + per‑step attribution stamps every call in an agent run, so a `laravel-flow` run's cost is broken down step‑by‑step under one trace.

Everything is **config‑toggleable** and **EU‑compliant by default**.

---

Quick start
-----------

[](#quick-start)

```
composer require padosoft/laravel-ai-finops
php artisan vendor:publish --tag=ai-finops-config
php artisan vendor:publish --tag=ai-finops-migrations
php artisan migrate
```

That's it — if you're already using `laravel/ai`, **metering starts automatically**. Every agent prompt, embedding and stream is priced and written to the usage ledger.

Add a budget and watch enforcement kick in:

```
use Padosoft\LaravelAiFinOps\Models\Budget;

Budget::create([
    'name' => 'Monthly cap', 'scope_type' => 'global',
    // Budgets compare against spend in the base currency (default USD). Set
    // ai-finops.currency.base (and an FX provider) to budget in another currency.
    'limit_amount' => 500, 'currency' => 'USD', 'period' => 'monthly',
    'soft_limit_pct' => 80, 'hard' => true,
]);
// Once the hard limit is reached, further AI calls abort with HTTP 402.
// Pass a pre-flight estimate to also block the single call that would exceed.
```

Attribute an agent run's cost per step:

```
app(\Padosoft\LaravelAiFinOps\Support\TraceContext::class)->within(
    ['trace_id' => $runId, 'agent_step' => 'summarize', 'tenant_id' => $tenantId],
    fn () => $agent->respond($prompt), // every laravel/ai call here is metered under this trace+step
);
```

---

How it works
------------

[](#how-it-works)

Each call becomes an **`AiCallEnvelope`** — a provider‑agnostic record (provider, model, tokens, cost, currency, tenant, cost‑center, agent step, purpose, `trace‑id`). It flows through the hook:

1. **Pre‑flight** — estimate + `PolicyEngine` → `allow | block | throttle | downgrade | queue | require‑approval` (kill switches, guardrails, hard budgets, declarative policies).
2. **Post‑flight** — the **cost cascade** picks the truest number — provider's actual billed cost → actual tokens × tariff → estimated tokens × tariff (multi‑source pricing ⊕ overrides ⊕ subscription coverage) → append‑only **ledger**, recording `cost_method` (actual/computed/estimated/covered), `tokens_estimated`, `billed_cost`, and frozen price provenance (source, exact rates, upstream provider) → budgets, forecasts and alerts update.

The envelope is also the **cross‑package contract**: any Padosoft package can populate its context tags so FinOps attributes and governs spend consistently.

---

Features
--------

[](#features)

AreaWhat you getMeteringSingle `laravel/ai` hook; immutable usage ledger; multimodal token trackingPricingMulti‑source: LiteLLM ⊕ OpenRouter (live) ⊕ manual (regolo, EUR/per‑1M); per‑provider authority map → freshest‑sync → env tie‑break; overrides win; cache/discount awareSubscriptionsFlat‑rate coverage windows → covered calls cost €0 (tokens tracked); per‑provider overhead % for estimatesCost accuracyCascade: **actual billed cost** (recovered from the provider response that laravel/ai drops) → **actual tokens × tariff** → **estimated tokens × tariff**; per‑call `cost_method` + `tokens_estimated` + `billed_cost`. Token estimator (heuristic; exact via optional `yethee/tiktoken`). fal.ai priced per second/image/megapixelBudgetsN‑scope hierarchy × periods; soft/hard; burndown; in‑flight enforcementPoliciesDSL (scope + min‑cost + model) → block/approval/downgrade/throttle/queue; simulateApprovalsPending → approve/reject workflowKill switchGlobal + per provider/tenant; config or storedChargebackCost centers + allocation report (showback/chargeback)ForecastRun‑rate projection + will‑exceed/exceed‑on; spike anomaly detection + ackRoutingQuality‑per‑dollar model selection (eval‑harness seam)What‑ifReplay historical traffic re‑priced on a target model → savingsStreamingLive cost meter + mid‑stream cutoff helperCreditsPrepaid pools + top‑up + ledgerAlertsMulti‑channel rules (mail/Slack/Teams/webhook/SMS) at % thresholdsFootprintEnergy (kWh) + CO₂e estimateAuditImmutable log of every governance mutationCopilotNatural‑language questions over your spend (ai‑chat/AskMyDocs seam)Price watchDetect provider list‑price changes for watched models---

Web Admin Panel
---------------

[](#web-admin-panel)

A **WOW, production-grade web admin panel** ships separately as [`padosoft/laravel-ai-finops-admin`](https://github.com/padosoft/laravel-ai-finops-admin) — a React + Vite + Tailwind console that drives every endpoint below: live cost dashboards, budgets & burndown, policies & approvals, cost-aware routing, forecasting & anomalies, what-if, chargeback, alerts, credit pools, CO₂/ESG and a natural-language FinOps copilot.

[![AI FinOps admin dashboard](resources/screenshoots/Ai-Finops-Web-Panel-Dashboard-Dark.png)](resources/screenshoots/Ai-Finops-Web-Panel-Dashboard-Dark.png)

```
composer require padosoft/laravel-ai-finops-admin
```

Then open `/admin/ai-finops`. The panel consumes this package's API (session + CSRF) — no mocks.

---

API overview
------------

[](#api-overview)

All endpoints are mounted under `config('ai-finops.routes.prefix')` (default `api/ai-finops`, i.e. URL path `/api/ai-finops`). The public `health` probe is open; every other endpoint is wrapped with `auth_middleware`.

`usage` (rows carry `cost_method` · `tokens_estimated` · `billed_cost`) · `usage/{id}` · `usage/{traceId}/trace` · `diagnostics/estimate` (token counts **or** a `prompt`/`messages` to estimate) · `pricing/models` (`?source=`) · `pricing/sync` · `pricing/sync/status` (per‑source + `has_openrouter_key`) · `pricing/overrides` · `pricing/subscription-windows` (flat‑rate €0 canoni) · `budgets/*` · `policies/*` · `approvals/*` · `cost-centers` · `chargeback/report` · `routing/*` · `forecast` · `anomalies` · `whatif/*` · `footprint/*` · `credits/pools/*` · `alerts/*` · `price-watch/*` · `copilot/*` · `audit` · `settings` · `settings/kill-switch` · `dashboard/*`

> The companion **`laravel-ai-finops-admin`** (React + Vite + Tailwind) consumes this surface.

---

Artisan commands
----------------

[](#artisan-commands)

```
php artisan ai-finops:report --days=30     # spend summary
php artisan ai-finops:prune --days=730     # ledger retention
php artisan ai-finops:check-alerts         # evaluate alert thresholds (schedule it)
php artisan ai-finops:capture-prices       # snapshot watched model prices
```

---

Integrations (opt‑in seams)
---------------------------

[](#integrations-optin-seams)

No hard dependency on sibling packages — bind an adapter to enable each:

ContractEnablesBacked by`QualityScoreProvider`cost‑aware routing`padosoft/eval-harness``GuardrailProvider`guardrail‑linked spend`laravel-pii-redactor` / `laravel-ai-act-compliance``CopilotProvider`NL FinOps copilot`laravel-ai-chat` / `AskMyDocs````
$this->app->singleton(\Padosoft\LaravelAiFinOps\Contracts\QualityScoreProvider::class, MyEvalHarnessScores::class);
```

Then flip the matching toggle under `config('ai-finops.integrations.*')` / `features.*`.

---

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

[](#configuration)

`config/ai-finops.php` toggles everything: master `enabled` / `metering` / `enforcement`, scoped `kill_switch`, multi‑tenancy resolver, currency + FX, **multi‑source pricing**, per‑feature flags, alert channels, footprint factors, retention. Sensible, EU‑friendly defaults out of the box.

**Multi‑source pricing** is config‑driven — enable feeds, pick who's authoritative per provider, and break ties by freshness:

```
'pricing' => [
    'overrides_win'  => true,                                   // manual prices always win
    'sources'        => ['manual', 'litellm', 'openrouter'],    // enabled, in precedence order
    'default_winner' => ['manual', 'litellm', 'openrouter'],    // tie / unknown-freshness order

    'openrouter' => [
        'enabled'       => env('AI_FINOPS_PRICING_OPENROUTER', false),
        'key'           => env('AI_FINOPS_PRICING_OPENROUTER_KEY'), // optional; exposed only as has_*
        'allow_keyless' => true,                                    // public list works without a key
    ],

    // "Who actually bills you": route a provider's price to a specific feed.
    'provider_source_map' => ['openrouter' => 'openrouter', 'regolo' => 'manual'],

    // Account-level overhead for ESTIMATES only (e.g. OpenRouter ~5.5% credit fee). Never the ledger.
    'fees' => ['openrouter' => ['markup_pct' => 5.5]],
],
```

Resolution order: **manual override → `provider_source_map` → freshest `synced_at` → `default_winner`**. Feed‑less providers (e.g. **regolo.ai**, EUR / per‑1M) are entered by hand via `pricing/overrides`. **Flat‑rate subscription windows** (`pricing/subscription-windows`) meter covered calls at **€0** while active — the raw ledger stays pass‑through truth.

**Cost cascade & actual‑cost recovery.** Opt in to recover the provider's real billed cost that `laravel/ai` discards (it keeps tokens only); a global HTTP middleware captures `usage.cost` for the listed hosts (never message content). Token estimation (cascade case c) is built‑in; install the optional **`yethee/tiktoken`** for exact OpenAI/compatible counts (the heuristic is used otherwise):

```
'pricing' => [
    // …sources / provider_source_map / fees as above…

    'actual_cost' => [
        'enabled'   => env('AI_FINOPS_ACTUAL_COST', false), // capture provider usage.cost (e.g. OpenRouter)
        'hosts'     => ['openrouter.ai'],
        'openrouter' => ['generation_lookup' => false, 'credit_to_currency' => 1.0],
    ],
    'token_estimation' => ['enabled' => true, 'expected_output_ratio' => 1.0],
],
```

Each ledger row records `cost_method` (`actual` | `computed` | `estimated` | `covered`), `tokens_estimated`, and `billed_cost` — so you can tell invoiced truth from a tariff estimate. (For `actual` rows, `cost_total` is the provider's billed amount; the `cost_input`/`cost_output` split is tariff‑derived for analytics and may not sum exactly to `cost_total`.) Media providers (**fal.ai**) are priced per second/image/megapixel via a manual `unit` + `unit_rate`.

---

Testing
-------

[](#testing)

```
composer install
vendor/bin/phpunit          # Unit + Feature + E2E
vendor/bin/pint --test      # code style
```

The suite is hermetic (no network) and runs on PHP 8.3 / 8.4 / 8.5 in CI.

---

License
-------

[](#license)

Apache‑2.0 © [Padosoft](https://github.com/padosoft)

###  Health Score

46

—

FairBetter than 92% of packages

Maintenance98

Actively maintained with recent releases

Popularity15

Limited adoption so far

Community10

Small or concentrated contributor base

Maturity53

Maturing project, gaining track record

 Bus Factor1

Top contributor holds 95.5% of commits — single point of failure

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 ~1 days

Total

4

Last Release

8d ago

### Community

Maintainers

![](https://avatars.githubusercontent.com/u/10467699?v=4)[Lorenzo](/maintainers/lopadova)[@lopadova](https://github.com/lopadova)

---

Top Contributors

[![lopadova](https://avatars.githubusercontent.com/u/10467699?v=4)](https://github.com/lopadova "lopadova (21 commits)")[![imgbot[bot]](https://avatars.githubusercontent.com/in/4706?v=4)](https://github.com/imgbot[bot] "imgbot[bot] (1 commits)")

---

Tags

ai-budgetai-financeai-finance-toolai-financialai-financial-advisorai-finopsai-goveranceai-spendai-spend-trackerlaraveltokensaiagentsllmcostlaravel-aichargebackpricingbudgetfinopsgovernancespend

###  Code Quality

TestsPHPUnit

Code StyleLaravel Pint

### Embed Badge

![Health badge](/badges/padosoft-laravel-ai-finops/health.svg)

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

###  Alternatives

[psalm/plugin-laravel

Psalm plugin for Laravel

3325.1M337](/packages/psalm-plugin-laravel)[larastan/larastan

Larastan - Discover bugs in your code without running it. A phpstan/phpstan extension for Laravel

6.4k51.0M7.4k](/packages/larastan-larastan)[laravel/ai

The official AI SDK for Laravel.

9782.1M153](/packages/laravel-ai)[laravel/pulse

Laravel Pulse is a real-time application performance monitoring tool and dashboard for your Laravel application.

1.7k14.1M120](/packages/laravel-pulse)[calebdw/larastan

Larastan - Discover bugs in your code without running it. A phpstan/phpstan extension for Laravel

15104.9k4](/packages/calebdw-larastan)

PHPackages © 2026

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