PHPackages octopus-llm/laravel - 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. octopus-llm/laravel ActiveLibrary[Utility & Helpers](/categories/utility) octopus-llm/laravel =================== OpenAI-compatible AI gateway untuk Laravel dengan multi-key rotation, circuit breaker, dan zero-cost free tier management. v1.0.0(1mo ago)06โ†“85.7%MITPHPPHP >=8.3 Since Jun 5Pushed 1mo agoCompare [ Source](https://github.com/iskandar221201/octopus-laravel)[ Packagist](https://packagist.org/packages/octopus-llm/laravel)[ RSS](/packages/octopus-llm-laravel/feed)WikiDiscussions main Synced 1w ago READMEChangelog (1)Dependencies (7)Versions (11)Used By (0) Octopus LLM Gateway for Laravel =============================== [](#octopus-llm-gateway-for-laravel) [![Latest Stable Version](https://camo.githubusercontent.com/a48a502d57653de2d2a501e27e565462f9b67127ee4e4fa8a65047ca822c8f70/68747470733a2f2f696d672e736869656c64732e696f2f6769746875622f762f72656c656173652f69736b616e6461723232313230312f6f63746f7075732d6c61726176656c3f636f6c6f723d626c7565)](https://github.com/iskandar221201/octopus-laravel/releases)[![PHP Version](https://camo.githubusercontent.com/fb3da7b0ae981c64304f79ff1edf0eee769ca15a99f92f6aabde877f7a32d4f0/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f7068702d253345253344253230382e332d3838393262662e737667)](https://php.net)[![Laravel Version](https://camo.githubusercontent.com/e0def73bc1423c53349ca1a30374a88326600b64b133f87ff3fc6ba857f2241f/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f6c61726176656c2d25354531312e3025323025374325323025354531322e3025323025374325323025354531332e302d6666326432302e737667)](https://laravel.com)[![License](https://camo.githubusercontent.com/7013272bd27ece47364536a221edb554cd69683b68a46fc0ee96881174c4214c/68747470733a2f2f696d672e736869656c64732e696f2f62616467652f6c6963656e73652d4d49542d626c75652e737667)](LICENSE) **AI gateway with multi-key rotation, circuit breaker, and zero-cost free tier management.** Octopus LLM Gateway allows you to seamlessly integrate multiple LLM providers (like Groq, OpenRouter, Cerebras) into your Laravel application with robust fallbacks, load-balancing key rotation, circuit breaking, and automated recovery, maximizing uptime and cost efficiency. --- ๐Ÿš€ Key Features -------------- [](#-key-features) - **๐Ÿ”„ Multi-Key Rotation**: Automatically rotates API keys per provider using a Least Recently Used (LRU) algorithm to maximize rate limit usage. - **โšก Circuit Breaker**: Disables keys automatically when successive HTTP failures occur (e.g., 500, timeout) and triggers events. - **๐Ÿ›ก๏ธ Token Validation Guard**: Estimates input token counts and blocks oversized requests before hitting the remote APIs. - **๐Ÿ”„ Fallback & Retry Mechanism**: Automatically falls back to lower-priority providers if a provider's keys are completely exhausted or rate-limited. - **๐Ÿค– Automated Ping Recovery**: Background tasks test inactive keys against `/models` endpoints periodically and reactivate them upon recovery. - **๐Ÿ’ป Interactive Artisan CLI**: Commands to monitor gateway status, validate credentials, benchmark latencies, test chats, and recover keys. --- ๐Ÿ“ฆ Installation -------------- [](#-installation) Important This package requires **PHP 8.3 or higher** and **Laravel 11.0 or higher**. To install the package, run the following command in your Laravel project: ``` composer require octopus-llm/laravel ``` Publish the configuration file: ``` php artisan vendor:publish --tag=octopus-config ``` --- โš™๏ธ Configuration ---------------- [](#๏ธ-configuration) The published configuration file is located at `config/octopus.php`. Below is a breakdown of the configuration keys and their environment variables: ``` return [ /* |-------------------------------------------------------------------------- | LLM Providers |-------------------------------------------------------------------------- | Define the list of providers in order of priority. | Lowest priority number (e.g., 1) is tried first. | */ 'providers' => [ [ 'id' => 'groq', 'baseURL' => 'https://api.groq.com/openai/v1', 'model' => env('GROQ_MODEL', 'llama-3.1-8b-instant'), 'keys' => explode(',', env('GROQ_KEYS', '')), 'priority' => 1, 'cooldown' => 60, // Key cooldown time in seconds before recovery ], [ 'id' => 'openrouter', 'baseURL' => 'https://openrouter.ai/api/v1', 'model' => env('OPENROUTER_MODEL', 'mistralai/mistral-7b-instruct:free'), 'keys' => explode(',', env('OPENROUTER_KEYS', '')), 'priority' => 2, 'cooldown' => 120, 'extraHeaders' => ['HTTP-Referer' => env('APP_URL', 'http://localhost')], ], ], /* |-------------------------------------------------------------------------- | Request & Input Guards |-------------------------------------------------------------------------- */ 'guard' => [ 'temperature' => env('OCTOPUS_TEMPERATURE', 0.7), 'timeout_ms' => env('OCTOPUS_TIMEOUT_MS', 10000), 'max_input_tokens' => env('OCTOPUS_MAX_INPUT_TOKENS', 4000), 'max_retries' => env('OCTOPUS_MAX_RETRIES', 2), 'max_output_tokens' => env('OCTOPUS_MAX_OUTPUT_TOKENS', 1000), ], /* |-------------------------------------------------------------------------- | Circuit Breaker |-------------------------------------------------------------------------- */ 'circuit_breaker' => [ 'failure_threshold' => env('OCTOPUS_CB_THRESHOLD', 3), // Consecutive fails to deactivate a key ], /* |-------------------------------------------------------------------------- | State Storage |-------------------------------------------------------------------------- */ 'storage' => env('OCTOPUS_STORAGE', 'cache'), 'storage_class' => null, // Custom class implementing StorageInterface 'cache_key_prefix' => env('OCTOPUS_CACHE_PREFIX', 'octopus_llm_state'), 'cache_ttl' => env('OCTOPUS_CACHE_TTL', 86400), 'streaming' => env('OCTOPUS_STREAMING', true), ]; ``` ### ๐Ÿ“ Environment Variables (.env) [](#-environment-variables-env) Add the following environment variables to your application's `.env` file to configure the gateway: ``` # LLM Providers API Keys (comma-separated for key rotation) GROQ_KEYS=key-1,key-2 OPENROUTER_KEYS=key-or-1 CEREBRAS_KEYS=key-cerebras-1 # Optional Model Customization GROQ_MODEL=llama-3.1-8b-instant OPENROUTER_MODEL=mistralai/mistral-7b-instruct:free CEREBRAS_MODEL=llama-3.1-8b # Optional Gateway Parameter Overrides OCTOPUS_TEMPERATURE=0.7 OCTOPUS_TIMEOUT_MS=10000 OCTOPUS_MAX_INPUT_TOKENS=4000 OCTOPUS_MAX_RETRIES=2 OCTOPUS_MAX_OUTPUT_TOKENS=1000 OCTOPUS_CB_THRESHOLD=3 OCTOPUS_PING_TIMEOUT=5 OCTOPUS_STORAGE=cache OCTOPUS_CACHE_PREFIX=octopus_llm_state OCTOPUS_CACHE_TTL=86400 OCTOPUS_STREAMING=true ``` --- ๐Ÿ› ๏ธ Usage -------- [](#๏ธ-usage) ### ๐Ÿ’ฌ Sending Chat Requests [](#-sending-chat-requests) Use the `OctopusLLM` facade to send chat completion requests. ``` use OctopusLLM\Laravel\Facades\OctopusLLM; $response = OctopusLLM::chat([ ['role' => 'user', 'content' => 'What is the speed of light?'] ]); echo $response->content; // Response text echo $response->provider; // 'groq' echo $response->model; // 'llama-3.1-8b-instant' echo $response->latencyMs; // Latency in milliseconds echo $response->attempts; // Attempts taken (e.g., 1) ``` ### ๐Ÿ”€ Forcing a Specific Provider [](#-forcing-a-specific-provider) You can bypass rotation sorting and force a specific provider for a single call: ``` $response = OctopusLLM::chat( [['role' => 'user', 'content' => 'Hello']], ['forceProvider' => 'openrouter'] ); ``` ### ๐ŸŒŠ Streaming Responses [](#-streaming-responses) To stream completions token-by-token, specify the `streaming` option and pass an `onChunk` callback: ``` OctopusLLM::chat( [['role' => 'user', 'content' => 'Write a short story.']], [ 'streaming' => true, 'onChunk' => function (string $chunk) { echo $chunk; flush(); } ] ); ``` ### ๐Ÿ“Š Monitoring Status [](#-monitoring-status) To inspect the current active/inactive status of all providers and API keys: ``` $status = OctopusLLM::getStatus(); echo "Total Active Keys: " . $status->totalActive; echo "Total Inactive Keys: " . $status->totalInactive; foreach ($status->providers as $provider) { echo "Provider: " . $provider->id; foreach ($provider->keys as $key) { echo "Key Index: " . $key->index . " Status: " . $key->status; } } ``` ### ๐Ÿค– Manual Recovery & Ping [](#-manual-recovery--ping) You can manually trigger pings or run the recovery engine inside code: ``` // Ping a specific key $isAlive = OctopusLLM::ping('groq', 0); // returns boolean // Run the full recovery process (checks cooldowns and pings inactive keys) $report = OctopusLLM::runRecovery(); ``` --- ๐Ÿ’ป Artisan Commands ------------------ [](#-artisan-commands) Octopus LLM comes with a complete suite of Artisan command-line tools: CommandDescription`php artisan octopus:validate`Validates API keys configuration in `.env``php artisan octopus:status`Shows table of status, failure counts, and last used times for all keys (use `--json` for raw data)`php artisan octopus:benchmark`Benchmarks request latency for each provider (use `--samples=5` to customize)`php artisan octopus:test`Sends a prompt request to the gateway to test end-to-end connectivity`php artisan octopus:recover`Manually triggers the background key recovery checks--- ๐Ÿงช Testing --------- [](#-testing) Run the PHPUnit test suite to verify code correctness and coverage: ``` vendor/bin/phpunit ``` --- ๐Ÿ“„ License --------- [](#-license) The MIT License (MIT). Please see [License File](LICENSE) for more information. ### Health Score 41 โ€” FairBetter than 87% of packages Maintenance90 Actively maintained with recent releases Popularity4 Limited adoption so far Community6 Small or concentrated contributor base Maturity55 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 Unknown Total 1 Last Release 50d ago ### Community Maintainers ![](https://www.gravatar.com/avatar/b2a5835714db962ec3f24cad492e397a127fd2ff3c1a7301c35223db77f9a6ab?d=identicon)[iskandar221201](/maintainers/iskandar221201) --- Top Contributors [![iskandar221201](https://avatars.githubusercontent.com/u/85160476?v=4)](https://github.com/iskandar221201 "iskandar221201 (21 commits)") ### Code Quality TestsPHPUnit ### Embed Badge ![Health badge](/badges/octopus-llm-laravel/health.svg) ``` [![Health](https://phpackages.com/badges/octopus-llm-laravel/health.svg)](https://phpackages.com/packages/octopus-llm-laravel) ``` ### Alternatives [psalm/plugin-laravel Psalm plugin for Laravel 3345.3M347](/packages/psalm-plugin-laravel)[laravel/pulse Laravel Pulse is a real-time application performance monitoring tool and dashboard for your Laravel application. 1.7k15.1M136](/packages/laravel-pulse)[aedart/athenaeum Athenaeum is a mono repository; a collection of various PHP packages 255.2k](/packages/aedart-athenaeum)[roots/acorn Framework for Roots WordPress projects built with Laravel components. 9762.4M133](/packages/roots-acorn)[mike-bronner/laravel-model-caching Automatic caching for Eloquent models. 2.4k96.5k1](/packages/mike-bronner-laravel-model-caching)[spatie/laravel-export Create a static site bundle from a Laravel app 674146.0k6](/packages/spatie-laravel-export) PHPackages ยฉ 2026 [Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)