PHPackages octopus-llm/php - 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/php ActiveLibrary[Utility & Helpers](/categories/utility) octopus-llm/php =============== OpenAI-compatible AI gateway with multi-key rotation, circuit breaker, and zero-cost free tier management. v1.0.2(1mo ago)04↓90%MITPHPPHP >=8.1 Since Jun 4Pushed 1mo agoCompare [ Source](https://github.com/iskandar221201/octopus-llm-php)[ Packagist](https://packagist.org/packages/octopus-llm/php)[ RSS](/packages/octopus-llm-php/feed)WikiDiscussions main Synced 1w ago READMEChangelog (2)Dependencies (3)Versions (9)Used By (0) Octopus LLM PHP Gateway ======================= [](#octopus-llm-php-gateway) [![Packagist Version](https://camo.githubusercontent.com/182eff1ab08431f8d4ea05db52f6ed03c6ba44dfcb8920335b7dc1f6a7ee3a75/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f762f6f63746f7075732d6c6c6d2f706870)](https://camo.githubusercontent.com/182eff1ab08431f8d4ea05db52f6ed03c6ba44dfcb8920335b7dc1f6a7ee3a75/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f762f6f63746f7075732d6c6c6d2f706870)[![PHP Version](https://camo.githubusercontent.com/427700410b07497f2e59c8f1688efe372c54f05ac82bd8b369932c519d4e2f7c/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f7068702d762f6f63746f7075732d6c6c6d2f706870)](https://camo.githubusercontent.com/427700410b07497f2e59c8f1688efe372c54f05ac82bd8b369932c519d4e2f7c/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f7068702d762f6f63746f7075732d6c6c6d2f706870)[![License](https://camo.githubusercontent.com/4d7fd2a2db5b14e31565f57d3e532a5bd58a694958a37b93ae3b765d27a316f5/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f6c2f6f63746f7075732d6c6c6d2f706870)](https://camo.githubusercontent.com/4d7fd2a2db5b14e31565f57d3e532a5bd58a694958a37b93ae3b765d27a316f5/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f6c2f6f63746f7075732d6c6c6d2f706870)[![Downloads](https://camo.githubusercontent.com/0944a87a0d49bc03cf68104fa15dcd1b6eebb8c9f00b6c5df0adf0246f7d3ef4/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f64742f6f63746f7075732d6c6c6d2f706870)](https://camo.githubusercontent.com/0944a87a0d49bc03cf68104fa15dcd1b6eebb8c9f00b6c5df0adf0246f7d3ef4/68747470733a2f2f696d672e736869656c64732e696f2f7061636b61676973742f64742f6f63746f7075732d6c6c6d2f706870) OpenAI-compatible AI gateway with multi-key rotation, circuit breaker, and zero-cost free tier management for production usage. Overview -------- [](#overview) Octopus-LLM is a robust PHP gateway that acts as a wrapper around the `openai-php/client` library. It automatically handles API key rotation using least-recently-used (LRU) patterns across multiple AI providers (like Groq, Cerebras, and OpenRouter), falls back to secondary providers if primary keys fail, protects your application using a configurable circuit breaker, and exposes events for recovery monitoring – all without needing a complicated infrastructure database. Zero-Cost Free Tier Strategy ---------------------------- [](#zero-cost-free-tier-strategy) Octopus-LLM is designed to maximize free tier API quotas across providers. With enough keys, you can run production AI workloads at zero cost: ProviderFree LimitKeys needed for ~1k req/dayGroq14,400 req/day1Cerebras~14,400 req/day1OpenRouterVaries by model1–3Register multiple free accounts → add all keys to the pool → Octopus-LLM handles rotation automatically. Installation ------------ [](#installation) You can install this package easily via Composer: ``` composer require octopus-llm/php ``` Quick Start ----------- [](#quick-start) ``` require 'vendor/autoload.php'; use OctopusLLM\Gateway\OctopusLLM; // Store your keys in .env file: // GROQ_KEYS=gsk_key1,gsk_key2,gsk_key3 // OPENROUTER_KEYS=sk-or-key1,sk-or-key2 // Initialize the Gateway config $llm = new OctopusLLM([ 'providers' => [ [ 'id' => 'groq', 'baseURL' => 'https://api.groq.com/openai/v1', 'model' => 'llama3-70b-8192', 'priority' => 1, 'keys' => explode(',', $_ENV['GROQ_KEYS'] ?? ''), 'cooldown' => 60 ], [ 'id' => 'openrouter', 'baseURL' => 'https://openrouter.ai/api/v1', 'model' => 'meta-llama/llama-3-70b-instruct', 'priority' => 2, 'keys' => explode(',', $_ENV['OPENROUTER_KEYS'] ?? ''), 'cooldown' => 120 ] ] ]); // Use it like a regular OpenAI Client try { $response = $llm->chat([ ['role' => 'system', 'content' => 'You are a helpful assistant.'], ['role' => 'user', 'content' => 'Explain PHP decorators.'] ]); echo $response->content; echo "Served by: " . $response->provider; } catch (\OctopusLLM\Gateway\Exceptions\GatewayExhaustedException $e) { echo "All providers and keys failed!"; } ``` Configuration ------------- [](#configuration) The `OctopusLLM` constructor requires an array configuration. ``` [ // Array of AI Providers 'providers' => [ [ 'id' => 'provider1', // string: Unique identifier 'baseURL' => 'https://...', // string: Provider base API URL 'model' => 'model-name', // string: Targeted internal model 'priority' => 1, // int: Lower number = higher priority 'keys' => ['key1', 'key2'], // array: API keys for this provider 'extraHeaders' => [ // array: Extra HTTP headers (optional) 'HTTP-Referer' => '...' ], 'cooldown' => 60 // int: Circuit breaker recovery timeout (optional, default: 60) ] ], // Gateway security guards (optional) 'guard' => [ 'timeoutSeconds' => 10, // Network request timeout (default: 10) 'maxInputTokens' => 4000, // Guard max input tokens (approximated) 'maxRetries' => 2, // Retries per key on 5xx errors (default: 2) 'maxOutputTokens' => 1000 // Global max generation tokens (default: 1000) ], // Recovery script configurations (optional) 'recovery' => [ 'pingTimeout' => 5 // Timeout for `runRecovery()` pings in seconds ], // Failure thresholds (optional) 'circuitBreaker' => [ 'failureThreshold' => 3 // Number of failures before marking key as inactive ], // Custom state storage (optional, default: JsonFileStorage) 'storage' => new CustomStorageImpl() ] ``` API Reference ------------- [](#api-reference) ### `chat(array $messages, array $options = []): ChatResponse` [](#chatarray-messages-array-options---chatresponse) Sends a chat request using the gateway configurations. Supports standard array options for overriding defaults (`stream`, `maxTokens`, `temperature`, `forceProvider`). ### `getStatus(): StatusResponse` [](#getstatus-statusresponse) Returns a unified DTO of all available providers, detailing active keys, inactive keys, and total stats. ### `ping(string $providerId, int $keyIndex): bool` [](#pingstring-providerid-int-keyindex-bool) Checks if a specific inactive key logic has recovered by pinging the configured `baseURL`/`models` endpoint. Returns boolean success. ### `runRecovery(): RecoveryReport` [](#runrecovery-recoveryreport) A utility method to scan all inactive keys that passed the cooldown timeframe. Automatically checks if they are recovered and re-activates them if successful. ### `on(string $event, callable $callback): self` [](#onstring-event-callable-callback-self) Attach event listeners such as when fallback happens or a key goes bad. Streaming --------- [](#streaming) You can enable native streaming via the options array, passing the `onChunk` callback: ``` $llm->chat($messages, [ 'stream' => true, 'onChunk' => function(string $chunk) { echo $chunk; // Directly stream into stdout flush(); } ]); ``` Error Handling -------------- [](#error-handling) Octopus-LLM uses explicit granular exceptions under `OctopusLLM\Gateway\Exceptions\*` namespace: - **`InputTooLongException`**: Sent payload exceeds configured `maxInputTokens`. - **`GatewayExhaustedException`**: Out of all active operational keys and Fallbacks. - **`RateLimitException`**: Handled natively by circuit breaker, but internally emitted. - **`AuthenticationException`**: Handled natively when key goes rogue. - **`CircuitOpenException`**: Prevented access due to open circuit limits. - **`ProviderException`**: Base exception layer interface. Events ------ [](#events) You can hook into real-time health events using `$llm->on(string $event, callable $callback)`: - **`key.deactivated`**: `($providerId, $keyIndex, $reason)` -> Used for tracking broken API keys. - **`key.recovered`**: `($providerId, $keyIndex)` -> Fires when a key successfully leaves the penalized box. - **`provider.exhausted`**: `($providerId)` -> Triggered when an entire provider array has failed. - **`fallback`**: `($failedProviderId, $nextProviderId)` -> When attempting automatic fallback to next priority. CI4 Integration --------------- [](#ci4-integration) If you intend to use this package with CodeIgniter 4, follow these steps: 1. **Register the Service**: Add an `octopus()` method to `app/Config/Services.php`: ``` public static function octopus(bool $getShared = true): \OctopusLLM\Gateway\OctopusLLM { if ($getShared) { return static::getSharedInstance('octopus'); } return new \OctopusLLM\Gateway\OctopusLLM([ 'providers' => [ [ 'id' => 'groq', 'baseURL' => 'https://api.groq.com/openai/v1', 'model' => 'llama-3.1-8b-instant', 'keys' => explode(',', env('GROQ_KEYS', '')), 'priority' => 1, 'cooldown' => 60, ], ], ]); } ``` 2. **Register the Recovery Command**: CI4 does not auto-discover commands from vendor packages. Create a wrapper at `app/Commands/OctopusRecover.php`: ```