LLM Providers

The LaraUtilX package provides a unified interface for interacting with multiple Large Language Model (LLM) providers. Choose between OpenAI's GPT models, Google's Gemini models, or Anthropic's Claude models through a consistent API.

Supported Providers

  1. OpenAIProvider: Interact with OpenAI's GPT models (GPT-3.5, GPT-4, etc.)
  2. GeminiProvider: Interact with Google's Gemini models (Gemini 2.0 Flash, etc.)
  3. ClaudeProvider: Interact with Anthropic's Claude models (Claude 3.5 Sonnet, etc.)

All providers support:

  • All major chat parameters (temperature, max tokens, top-p, etc.)
  • Automatic retry logic with configurable delays
  • Structured responses with usage metadata
  • JSON mode for structured output
  • Unified interface for easy provider switching

Methods

  1. generateResponse( string $modelName, array $messages, ?float $temperature = null, ?int $maxTokens = null, ?array $stop = null, ?float $topP = null, ?float $frequencyPenalty = null, ?float $presencePenalty = null, ?array $logitBias = null, ?string $user = null, ?bool $jsonMode = false, bool $fullResponse = false ): Response
    • Generates a chat completion using the specified model and parameters.

Usage

1. Using the Unified Interface

The provider is auto-bound to the LLMProviderInterface, so you can inject it anywhere in your Laravel app:

use LaraUtilX\LLMProviders\Contracts\LLMProviderInterface;

class MyController extends Controller
{
    public function ask(LLMProviderInterface $llm)
    {
        $response = $llm->generateResponse(
            'gpt-5.6-terra', // or 'gemini-3.6-flash' or 'claude-sonnet-5'
            [
                ['role' => 'user', 'content' => 'What is Laravel?']
            ]
        );

        return $response->getContent();
    }
}

2. Constructor Injection

use LaraUtilX\LLMProviders\Contracts\LLMProviderInterface;

class MyController extends Controller
{
    private LLMProviderInterface $llm;

    public function __construct(LLMProviderInterface $llm)
    {
        $this->llm = $llm;
    }

    public function ask()
    {
        $response = $this->llm->generateResponse(
            'gpt-5.6-terra',
            [
                ['role' => 'user', 'content' => 'What is Laravel?']
            ]
        );

        return $response->getContent();
    }
}

3. Generic LLM Test Endpoint

public function testLLM(Request $request)
{
    $provider = config('lara-util-x.llm.default_provider', 'openai');
    $model = match($provider) {
        'gemini' => config('lara-util-x.gemini.default_model', 'gemini-3.6-flash'),
        'claude' => config('lara-util-x.claude.default_model', 'claude-sonnet-5'),
        default => config('lara-util-x.openai.default_model', 'gpt-5.6-terra')
    };

    $prompt = $request->input('prompt', 'Say hello in one short sentence.');
    $temperature = $request->input('temperature');
    $maxTokens = $request->input('max_tokens');
    $jsonMode = filter_var($request->input('json_mode', false), FILTER_VALIDATE_BOOL);

    $messages = [
        ['role' => 'user', 'content' => $prompt]
    ];

    $response = $this->llm->generateResponse(
        modelName: $model,
        messages: $messages,
        temperature: $temperature !== null ? (float) $temperature : null,
        maxTokens: $maxTokens !== null ? (int) $maxTokens : null,
        jsonMode: $jsonMode,
        fullResponse: true
    );

    return response()->json([
        'provider' => $provider,
        'model' => $response->getModel() ?? $model,
        'content' => $response->getContent(),
        'usage' => $response->getUsage(),
    ]);
}

4. Customizing Parameters

You can use all supported chat parameters:

$response = $llm->generateResponse(
    'gpt-5.6-terra', // or 'gemini-3.6-flash' or 'claude-sonnet-5'
    [
        ['role' => 'user', 'content' => 'Tell me a joke.']
    ],
    temperature: 0.8,
    maxTokens: 100,
    stop: ['\n'],
    topP: 1.0,
    frequencyPenalty: 0,
    presencePenalty: 0,
    logitBias: null,
    user: 'user-123',
    jsonMode: false,
    fullResponse: true
);

Configuration

All configurations are present in config/lara-util-x.php:

'llm' => [
    'default_provider' => env('LLM_DEFAULT_PROVIDER', 'openai'),
],

'openai' => [
    'api_key' => env('OPENAI_API_KEY'),
    'max_retries' => env('OPENAI_MAX_RETRIES', 3),
    'retry_delay' => env('OPENAI_RETRY_DELAY', 2),
    'default_model' => env('OPENAI_DEFAULT_MODEL', 'gpt-5.6-terra'),
    'default_temperature' => env('OPENAI_DEFAULT_TEMPERATURE', 0.7),
    'default_max_tokens' => env('OPENAI_DEFAULT_MAX_TOKENS', 300),
    'default_top_p' => env('OPENAI_DEFAULT_TOP_P', 1.0),
],

'gemini' => [
    'api_key' => env('GEMINI_API_KEY'),
    'max_retries' => env('GEMINI_MAX_RETRIES', 3),
    'retry_delay' => env('GEMINI_RETRY_DELAY', 2),
    'base_url' => env('GEMINI_BASE_URL', 'https://generativelanguage.googleapis.com/v1beta'),
    'default_model' => env('GEMINI_DEFAULT_MODEL', 'gemini-3.6-flash'),
    'default_temperature' => env('GEMINI_DEFAULT_TEMPERATURE', 0.7),
    'default_max_tokens' => env('GEMINI_DEFAULT_MAX_TOKENS', 300),
    'default_top_p' => env('GEMINI_DEFAULT_TOP_P', 1.0),
],

'claude' => [
    'api_key' => env('CLAUDE_API_KEY'),
    'max_retries' => env('CLAUDE_MAX_RETRIES', 3),
    'retry_delay' => env('CLAUDE_RETRY_DELAY', 2),
    'base_url' => env('CLAUDE_BASE_URL', 'https://api.anthropic.com'),
    'default_model' => env('CLAUDE_DEFAULT_MODEL', 'claude-sonnet-5'),
    'default_temperature' => env('CLAUDE_DEFAULT_TEMPERATURE', 1.0),
    'default_max_tokens' => env('CLAUDE_DEFAULT_MAX_TOKENS', 1024),
    'default_top_p' => env('CLAUDE_DEFAULT_TOP_P', 1.0),
],

Add your API keys to your .env file:

OPENAI_API_KEY=sk-...
GEMINI_API_KEY=...
CLAUDE_API_KEY=sk-ant-...
LLM_DEFAULT_PROVIDER=openai

Provider Selection

Switch between providers via configuration:

// Use OpenAI
LLM_DEFAULT_PROVIDER=openai

// Use Gemini
LLM_DEFAULT_PROVIDER=gemini

// Use Claude
LLM_DEFAULT_PROVIDER=claude

Result

The method returns a response instance (either OpenAIResponse, GeminiResponse, or ClaudeResponse), which provides:

  • getContent(): The generated text from the model.
  • getModel(): The model used for the response.
  • getUsage(): Token usage information.
  • getRawResponse(): The full raw response object from the provider.

Example:

$content = $response->getContent();
$model = $response->getModel();
$usage = $response->getUsage();

Success Result:

  • The response contains the generated content and, if fullResponse is true, metadata such as model and usage.

Failure Result:

  • If the request fails, an exception is thrown. The provider will retry the request up to the configured number of times before failing.

Error Handling

  • Both providers automatically retry failed requests up to max_retries.
  • If all retries fail, an exception is thrown. You should catch exceptions in your controller or service.
  • Retry delays are configurable per provider.

Extending

To add support for other LLM providers:

  • Implement the LLMProviderInterface in your own provider class.
  • Bind your provider in the service provider if you want to swap implementations.
  • Follow the same response pattern for consistency.

This unified system simplifies the process of interacting with multiple LLM providers, providing a convenient, robust, and extensible way to generate AI-powered completions in your Laravel application.

Changes in v1.5.4

OpenAI requires an extra package

openai-php/client is not bundled, because most applications use only one provider. Since OpenAI is the default, a fresh install previously failed with a bare "class not found" when the interface was resolved.

Install it when you use that provider:

composer require openai-php/client

Or point LLM_DEFAULT_PROVIDER at a provider that needs no extra dependency:

LLM_DEFAULT_PROVIDER=claude

The provider now raises an error naming the package and the alternatives rather than a class-not-found from the container.

Claude default model

The default was claude-3-5-sonnet-20241022, retired in October 2025, so every call with default configuration failed. It now defaults to claude-sonnet-5, overridable with CLAUDE_DEFAULT_MODEL.

System prompts work across providers

Anthropic takes the system prompt as a top-level parameter rather than a message role, so passing OpenAI-style messages through unchanged broke as soon as a system prompt was involved. System messages are now lifted out of the conversation automatically for Claude. Gemini had the same problem until v1.5.7; see below.

$response = app(LLMProviderInterface::class)->generateResponse(
    config('lara-util-x.claude.default_model'),
    [
        ['role' => 'system', 'content' => 'You are terse.'],
        ['role' => 'user', 'content' => 'Summarise this order.'],
    ]
);

Multiple system messages are joined; when there are none, no system key is sent.

Changes in v1.5.7

Retired default models

Two default models had been shut down by their vendors:

Provider Old default Shut down New default
OpenAI gpt-3.5-turbo Oct 23, 2026 gpt-5.6-terra
Gemini gemini-2.0-flash Jun 1, 2026 gemini-3.6-flash

The package does not apply default_model on its own; it takes effect when you pass config('lara-util-x.<provider>.default_model'), as the examples on this page do. If you pinned a retired model in .env, update it there as well, since the new default only applies when the variable is unset.

The same messages now work with all three providers

Gemini only accepts user and model as content roles, so a system message was rejected outright. System messages are now sent as Gemini's systemInstruction, matching what Claude has done since v1.5.4. One message array now works unchanged across OpenAI, Gemini, and Claude:

$response = app(LLMProviderInterface::class)->generateResponse(
    config('lara-util-x.gemini.default_model'),
    [
        ['role' => 'system', 'content' => 'You are terse.'],
        ['role' => 'user', 'content' => 'Summarise this order.'],
    ]
);

The v1.5.4 notes above said this already worked across all three providers. That was true for OpenAI and Claude, but not for Gemini.

JSON mode on Gemini

jsonMode: true previously had no effect on Gemini. It now sets responseMimeType to application/json.

Token limits on OpenAI

Reasoning models, including the GPT-5 family default, reject max_tokens. The $maxTokens argument is now sent as max_completion_tokens, which every current chat model accepts.

Errors and retries

Failures that cannot succeed on a retry, such as a bad key or an unknown model, are no longer retried. Only rate limits (429), timeouts (408), and server errors (5xx) are. A missing model names the setting to change:

Gemini model [gemini-2.0-flash] was not found. It may have been retired;
set GEMINI_DEFAULT_MODEL to a current model.

Claude and Gemini raise LaraUtilX\LLMProviders\Exceptions\LLMRequestException, which exposes the HTTP status and an isRetryable() check. It extends RuntimeException, so existing catch blocks keep working. OpenAI continues to throw the client library's own ErrorException.

Other changes

  • The Gemini API key is sent in the x-goog-api-key header instead of the URL, keeping it out of proxy logs and error messages.
  • Claude collects every text block in a response rather than only the first.
  • openai-php/client 0.13 and later require PHP 8.2, so PHP 8.1 users of the OpenAI provider are limited to older client releases.