PHPackages illuma-law/laravel-llm-router - 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. illuma-law/laravel-llm-router ActiveLibrary[Utility & Helpers](/categories/utility) illuma-law/laravel-llm-router ============================= A resilient AI routing and circuit-breaker system for LLM requests in Laravel. v0.1.4(1mo ago)062MITPHPPHP ^8.3CI passing Since Apr 20Pushed 1mo agoCompare [ Source](https://github.com/illuma-law/laravel-llm-router)[ Packagist](https://packagist.org/packages/illuma-law/laravel-llm-router)[ Docs](https://github.com/illuma-law/laravel-llm-router)[ RSS](/packages/illuma-law-laravel-llm-router/feed)WikiDiscussions main Synced 1w ago READMEChangelogDependencies (15)Versions (6)Used By (0) Laravel LLM Router ================== [](#laravel-llm-router) [![Latest Version on Packagist](https://camo.githubusercontent.com/37b0955a862865eed3df7c90b78f4025100719f37a45b9c97dfced3ba247a961/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f762f696c6c756d612d6c61772f6c61726176656c2d6c6c6d2d726f757465722e7376673f7374796c653d666c61742d737175617265)](https://packagist.org/packages/illuma-law/laravel-llm-router)[![GitHub Tests Action Status](https://camo.githubusercontent.com/e4147c37ce45c2b5fea2bbce6dd91b206cd707251a1c3923ec5bbf85b2a6bded/68747470733a2f2f696d672e736869656c64732e696f2f6769746875622f616374696f6e732f776f726b666c6f772f7374617475732f696c6c756d612d6c61772f6c61726176656c2d6c6c6d2d726f757465722f72756e2d74657374732e796d6c3f6272616e63683d6d61696e266c6162656c3d7465737473267374796c653d666c61742d737175617265)](https://github.com/illuma-law/laravel-llm-router/actions?query=workflow%3Arun-tests+branch%3Amain)[![Total Downloads](https://camo.githubusercontent.com/cf694edced5c35da87319b2153c360d88c5813ed37951a7bafe974d49564c25e/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f64742f696c6c756d612d6c61772f6c61726176656c2d6c6c6d2d726f757465722e7376673f7374796c653d666c61742d737175617265)](https://packagist.org/packages/illuma-law/laravel-llm-router) A production-grade, highly resilient LLM routing and failover system for Laravel applications. When building AI-powered features, relying on a single API provider (like OpenAI or Anthropic) introduces significant risk due to rate limits and outages. The Laravel LLM Router solves this by providing a fluent API to execute LLM requests with automatic circuit-breaking, multi-provider fallback chains, smart error classification, and tenant-aware routing. Features -------- [](#features) - **Fluent Request API**: Execute LLM calls with a clean, builder-like syntax using the `LLMRouter` facade. - **Resilient Failover**: Automatically attempt alternative providers/models when primary ones fail (e.g., fallback from OpenAI to Anthropic to Google). - **Smart Retries**: Intelligently distinguishes between transient network errors (retry the same provider) and rate limits (failover immediately to the next provider). - **Tenant Isolation**: Support for "Sovereign" tenants where requests must stay on-premise (e.g., forcing Ollama models). - **Seamless Laravel AI SDK Integration**: First-class support for `laravel/ai` agents and simple prompting. - **Extensible Configuration**: Define your own model tiers (Small, Large, etc.) via Enums, and load chains via config or database. - **Reusable Support Primitives**: Generic provider availability checks, chain row validation, and cooldown state tracking can be reused in host apps without domain coupling. Support Utilities ----------------- [](#support-utilities) The package now ships generic support classes for host applications that want to keep AI routing concerns out of domain code: - `IllumaLaw\LlmRouter\Support\ConfigProviderAvailability` - Checks provider credentials and enablement flags using configurable config paths. - `IllumaLaw\LlmRouter\Support\ChainRowValidator` - Normalizes provider/model rows, validates provider/model combinations, and removes adjacent duplicates. - `IllumaLaw\LlmRouter\Support\CooldownStore` - Tracks retryable failure counters and cooldown windows in cache. - `IllumaLaw\LlmRouter\Contracts\ProviderAvailability` - Contract for provider availability checks, bound to `ConfigProviderAvailability` by default. These are container-registered by `LLMRouterServiceProvider`, so they can be injected directly or wrapped by app-specific adapters. Installation ------------ [](#installation) Require this package with composer: ``` composer require illuma-law/laravel-llm-router ``` Publish the configuration file: ``` php artisan vendor:publish --tag="llm-router-config" ``` Configuration ------------- [](#configuration) The `config/llm-router.php` file defines your fallback tiers and retry behavior: ``` return [ 'enabled' => env('LLM_ROUTER_ENABLED', true), // Define chains of providers to try in order 'tiers' => [ 'large' => [ ['provider' => 'anthropic', 'model' => 'claude-3-5-sonnet-latest'], ['provider' => 'openai', 'model' => 'gpt-4o'], ['provider' => 'gemini', 'model' => 'gemini-1.5-pro'], ], 'small' => [ ['provider' => 'anthropic', 'model' => 'claude-3-5-haiku-latest'], ['provider' => 'openai', 'model' => 'gpt-4o-mini'], ['provider' => 'gemini', 'model' => 'gemini-1.5-flash'], ], ], // Override model for on-prem/sovereign routing 'priority_override' => [ 'provider' => 'ollama', 'model' => 'llama3.1:70b', ], // How many times to retry the same provider on a 5xx error 'max_same_provider_retries' => 1, 'retry_delay_ms' => 150, ]; ``` Usage & Integration ----------------------- [](#usage--integration) ### Seamless Laravel AI SDK Integration [](#seamless-laravel-ai-sdk-integration) The router is designed to work perfectly with the official `laravel/ai` SDK. #### Simple Prompting [](#simple-prompting) You can execute a simple prompt across a failover chain with one line. If Claude fails, it will automatically try OpenAI: ``` use IllumaLaw\LlmRouter\Facades\LLMRouter; use IllumaLaw\LlmRouter\Enums\DefaultTier; $response = LLMRouter::tier(DefaultTier::Large)->prompt('Explain quantum computing.'); echo $response->text; ``` #### Agent Integration [](#agent-integration) You can pass a `laravel/ai` agent instance directly to run its specific logic through the router's failover chain: ``` use App\Agents\LegalAnalystAgent; use IllumaLaw\LlmRouter\Facades\LLMRouter; use IllumaLaw\LlmRouter\Enums\DefaultTier; $agent = new LegalAnalystAgent(); $response = LLMRouter::forAgent($agent) ->tier(DefaultTier::Large) ->prompt('Analyze this contract...', ['context' => '...']); ``` ### Custom Execution Closure [](#custom-execution-closure) If you need full control over the execution, use the `run()` method with a closure: ``` use IllumaLaw\LlmRouter\Facades\LLMRouter; use IllumaLaw\LlmRouter\Enums\DefaultTier; use Laravel\Ai\Facades\Ai; $result = LLMRouter::tier(DefaultTier::Large) ->run(function (string $provider, string $model) use ($prompt) { // This closure is executed for each hop in the chain until success return Ai::provider($provider) ->model($model) ->prompt($prompt) ->generate(); }); ``` ### Priority & Tenant Overrides [](#priority--tenant-overrides) For enterprise applications, some customers might require their data to never leave their infrastructure. You can register a "priority resolver" in your `AppServiceProvider`: ``` use IllumaLaw\LlmRouter\Facades\LLMRouter; // AppServiceProvider.php public function boot(): void { LLMRouter::resolvePriorityUsing(function ($tenant) { // If the tenant is flagged as sovereign, trigger the priority_override (e.g. Ollama) return $tenant->is_sovereign === true; }); } ``` Then pass the tenant context to the router: ``` $result = LLMRouter::tier(DefaultTier::Large) ->forTenant($team) // Automatically switches to local models if $team is sovereign ->prompt('Summarize this document.'); ``` ### Abstracting Chain Resolution [](#abstracting-chain-resolution) If your application stores fallback chains dynamically in a database, you can implement the `ChainRepository` interface. ``` use IllumaLaw\LlmRouter\Contracts\ChainRepository; class DatabaseChainRepository implements ChainRepository { public function getChain(?string $tier = null, ?string $operation = null): ?array { return DB::table('ai_chains')->where('tier', $tier)->get()->toArray(); } public function getAgentOverride(string $agent): ?array { return null; } } ``` Register it in your Service Provider: ``` LLMRouter::useRepository(new DatabaseChainRepository()); ``` Error Handling -------------- [](#error-handling) The router automatically classifies errors: - **Transient Errors** (503, Timeouts, Network): Retries the *same* provider. - **Exhaustion Errors** (429 Rate Limits): Immediately fails over to the *next* provider in the chain. - **Terminal Errors** (401 Unauthorized, 400 Bad Request): Fails fast and propagates the exception without retrying. If the entire chain is exhausted, a `ChainExhaustedException` is thrown: ``` use IllumaLaw\LlmRouter\Exceptions\ChainExhaustedException; use IllumaLaw\LlmRouter\Facades\LLMRouter; try { $result = LLMRouter::tier('large')->prompt('...'); } catch (ChainExhaustedException $e) { // Inspect what went wrong at each step $attempts = $e->getAttempts(); Log::critical('All AI providers failed.', ['history' => $attempts]); } ``` Testing ------- [](#testing) The package includes a comprehensive test suite using Pest PHP. ``` composer test ``` License ------- [](#license) The MIT License (MIT). Please see [License File](LICENSE.md) for more information. ### Health Score 40 — FairBetter than 86% of packages Maintenance91 Actively maintained with recent releases Popularity12 Limited adoption so far Community6 Small or concentrated contributor base Maturity42 Maturing project, gaining track record Bus Factor1 Top contributor holds 100% 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 ~2 days Total 5 Last Release 43d ago ### Community Maintainers ![](https://www.gravatar.com/avatar/2affac64f2726a640084b203503518ca01f582536d60a0a299b614486ed95aaa?d=identicon)[miguelenes](/maintainers/miguelenes) --- Top Contributors [![miguelenes](https://avatars.githubusercontent.com/u/1568086?v=4)](https://github.com/miguelenes "miguelenes (10 commits)") --- Tags laravelaicircuit breakerfailoverilluma-lawllm-router ### Code Quality TestsPest Static AnalysisPHPStan Code StyleLaravel Pint ### Embed Badge ![Health badge](/badges/illuma-law-laravel-llm-router/health.svg) ``` [![Health](https://phpackages.com/badges/illuma-law-laravel-llm-router/health.svg)](https://phpackages.com/packages/illuma-law-laravel-llm-router) ``` ### Alternatives [psalm/plugin-laravel Psalm plugin for Laravel 3325.1M337](/packages/psalm-plugin-laravel)[spatie/laravel-health Monitor the health of a Laravel application 88011.3M149](/packages/spatie-laravel-health)[laravel/ai The official AI SDK for Laravel. 9782.1M153](/packages/laravel-ai)[defstudio/telegraph A laravel facade to interact with Telegram Bots 815320.5k3](/packages/defstudio-telegraph)[harris21/laravel-fuse Circuit breaker for Laravel queue jobs. Protect your workers from cascading failures. 24740.3k](/packages/harris21-laravel-fuse)[nativephp/mobile NativePHP for Mobile 97255.0k84](/packages/nativephp-mobile) PHPackages © 2026 [Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)