How ferdiunal/laravel-ai-router works
Laravel AI Router is a Laravel AI text provider that accepts application prompts, selects eligible local provider keys and models, calls an upstream adapter, and returns text or stream events while recording usage. Separate operational workflows manage keys, custom provider definitions, model discovery and selection, and usage retention. The README documents structured output, tool calls, failover, and model-cache features; unsampled implementation details are represented only where their owning modules are supported by the tree.
Main entry points: LaravelAiRouterTextGateway.php Text gateway · ModelRouter.php Model router · ProviderAdapterRegistry.php Adapter registry · CloudflareWorkersAiAdapter.php Cloudflare adapter
Components 32
Text routing
- AI text provider
src/LaravelAiRouterProvider.php - Text gateway
src/Gateway/LaravelAiRouterTextGateway.php - Model router
src/Routing/ModelRouter.php - Rate windows
src/Routing/RateLimitWindowRepository.php
Providers and models
- Adapter registry
src/Adapters/ProviderAdapterRegistry.php - Adapter contract
src/Adapters/Contracts/ProviderAdapter.php - Google adapter
src/Adapters/GoogleAiStudioAdapter.php - OpenAI-compatible
src/Adapters/OpenAiCompatibleAdapter.php - Cloudflare adapter
src/Adapters/CloudflareWorkersAiAdapter.php - Provider catalog
src/Catalog/ProviderCatalog.php - Model catalog
src/Catalog/ModelCatalog.php
Provider operations
- Key management
src/Services/ProviderKeyManager.php - Definition management
src/Services/ProviderDefinitionManager.php - Model discovery
src/Services/ProviderSyncService.php - Model cache service
src/Services/ProviderModelCacheService.php - Model selection
src/Services/ProviderModelSelectionManager.php - Key commands
src/Console/Commands/ProviderAddCommand.php - Definition commands
src/Console/Commands/ProviderDefinitionAddCommand.php - Sync command
src/Console/Commands/ProviderSyncCommand.php
Local state
- Usage logger
src/Services/UsageLogger.php - Usage analytics
src/Services/UsageAnalyticsRepository.php - Storage pruner
src/Services/StoragePruner.php - Provider keys
src/Models/LaravelAiRouterProviderKey.php - Custom definitions
src/Models/LaravelAiRouterProviderDefinition.php - Routable models
src/Models/LaravelAiRouterModel.php - Fallback metadata
src/Models/LaravelAiRouterFallback.php - Available-model cache
src/Models/LaravelAiRouterProviderModelCache.php - Rate-window records
src/Models/LaravelAiRouterRateWindow.php - Request records
src/Models/LaravelAiRouterRequest.php
Other components
- Laravel application
- AI providers
- Artisan user
Connections 39
- Laravel application → AI text provider: uses provider
- AI text provider → Text gateway: generates text
- Text gateway → Model router: selects route
- Model router → Rate windows: checks limits
- Model router → Provider keys: reads keys
- Model router → Routable models: reads models
- Model router → Fallback metadata: reads fallbacks
- Model router → Available-model cache: reads candidates
- Text gateway → Adapter registry: resolves adapter
- Adapter registry → Adapter contract: provides adapters
- Text gateway → Google adapter: dispatches requests
- Text gateway → OpenAI-compatible: dispatches requests
- Text gateway → Cloudflare adapter: dispatches requests
- Google adapter → AI providers: sends requests
- OpenAI-compatible → AI providers: sends requests
- Cloudflare adapter → OpenAI-compatible: delegates requests
- Cloudflare adapter → AI providers: discovers models
- Provider catalog → Adapter registry: defines providers
- Model catalog → Routable models: seeds catalog
- Text gateway → Rate windows: records usage
- Text gateway → Usage logger: logs requests
- Usage logger → Request records: writes records
- Usage logger → Usage analytics: updates analytics
- Rate windows → Rate-window records: reads and writes
- Artisan user → Key commands: manages keys
- Artisan user → Definition commands: manages definitions
- Artisan user → Sync command: syncs models
- Key commands → Key management: invokes
- Definition commands → Definition management: invokes
- Sync command → Model discovery: invokes
- Key management → Provider keys: writes keys
- Key management → Model cache service: refreshes models
- Definition management → Custom definitions: writes definitions
- Model discovery → Adapter registry: discovers through
- Model discovery → Model cache service: refreshes cache
- Model cache service → Available-model cache: writes cache
- Model selection → Available-model cache: updates selection
- Storage pruner → Request records: prunes records
- Storage pruner → Rate-window records: prunes windows