README

A resilient, provider-agnostic LLM gateway for Laravel applications.

Designed for production AI chat systems—including WhatsApp bots, Messenger bots, customer support assistants, and web chat applications—the package protects your application from upstream AI failures such as rate limits (429), service overloads (503), network timeouts, and provider-specific API quirks.

Features

• 🚀 Driver-based architecture – Easily switch between AI providers (Gemini, OpenAI, and future drivers) without changing your application code.
• 🛡️ Built-in resilience – Automatic retries, timeout handling, and graceful degradation.
• 🔄 Gemini role collapsing – Merges consecutive conversation roles to satisfy Gemini's strict message schema.
• ⚡ Graceful fallbacks – Handles rate limits, temporary outages, and empty AI responses without crashing your application.
• 🕒 Chronological history builder – Prevents conversation ordering issues caused by identical timestamps or UUID-based primary keys.
• 🔌 Laravel native – Dependency Injection, Service Container binding, configuration publishing, and zero boilerplate integration.

Requirements

• PHP 8.2+
• Laravel 11+

Installation

Install the package via Composer:

composer require tawshiqulislam/laravel-llm-failover

Publish the Configuration

Publish the configuration file:

php artisan vendor:publish --tag="llm-failover-config"

This will create:

config/llm-failover.php

The published configuration allows your application to map drivers to your environment variables.

Environment Configuration

Add the following variables to your project's .env file.

Required

These values are required for the package to function.

LLM_DEFAULT_DRIVER=gemini

GEMINI_API_KEY=your_actual_gemini_api_key

Optional

These values already have sensible defaults but can be overridden.

# AI model
GEMINI_DEFAULT_MODEL=gemini-2.5-flash

# Gemini API endpoint
GEMINI_BASE_URL=https://generativelanguage.googleapis.com/v1beta/models

# Maximum output tokens
GEMINI_MAX_OUTPUT_TOKENS=1000

# Temperature (0.0 - 2.0)
GEMINI_TEMPERATURE=0.7

Default Configuration

The published configuration looks like this:

return [

    'default' => env('LLM_DEFAULT_DRIVER', 'gemini'),

    'drivers' => [

        'gemini' => [
            'api_key' => env('GEMINI_API_KEY'),
            'base_url' => env(
                'GEMINI_BASE_URL',
                'https://generativelanguage.googleapis.com/v1beta/models'
            ),
            'default_model' => env('GEMINI_DEFAULT_MODEL', 'gemini-2.5-flash'),
            'max_output_tokens' => env('GEMINI_MAX_OUTPUT_TOKENS', 1000),
            'temperature' => env('GEMINI_TEMPERATURE', 0.7),
        ],

        'openai' => [
            'api_key' => env('OPENAI_API_KEY'),
        ],

    ],

];

What's Next?

After installation you can:

• Inject the LlmDriverInterface
• Send chat conversations to your preferred LLM provider
• Build chronological conversation histories using the included trait
• Easily swap providers through configuration

Documentation for usage examples will be added in future releases.

License

The MIT License (MIT).