README

Laravel package for Google Gemini AI integration. It provides a small, reusable client for prompts, chat-style messages, raw payloads, normalized responses, and Laravel-friendly configuration.

Installation

composer require yasser-elgammal/laravel-gemini

Configuration

Publish the config file:

php artisan vendor:publish --tag=gemini-config

Environment variables:

GEMINI_API_KEY=
GEMINI_BASE_URL=https://generativelanguage.googleapis.com/v1beta
GEMINI_MODEL=gemini-1.5-flash
GEMINI_TIMEOUT=30
GEMINI_RETRY_TIMES=0
GEMINI_RETRY_SLEEP=100
GEMINI_TEMPERATURE=0.7
GEMINI_MAX_OUTPUT_TOKENS=2048
GEMINI_TOP_P=0.95
GEMINI_TOP_K=40

Usage

Facade:

use YasserElgammal\LaravelGemini\Facades\Gemini;

$response = Gemini::generate('Explain Laravel service providers');

Chat:

use YasserElgammal\LaravelGemini\Facades\Gemini;

$response = Gemini::chat([
    ['role' => 'user', 'content' => 'Hello Gemini'],
]);

Dependency injection:

use YasserElgammal\LaravelGemini\Contracts\GeminiClientInterface;

public function __construct(
    private GeminiClientInterface $gemini
) {}

public function handle(): void
{
    $response = $this->gemini->generate('Hello Gemini');
}

Raw payload:

$response = Gemini::raw([
    'contents' => [
        [
            'role' => 'user',
            'parts' => [
                ['text' => 'Hello'],
            ],
        ],
    ],
]);

Responses are normalized:

[
    'text' => '...',
    'raw' => [],
    'model' => 'gemini-1.5-flash',
    'usage' => [],
]

Request Options

Override the model or generation settings per request:

$response = Gemini::generate('Return JSON', [
    'model' => 'gemini-1.5-flash',
    'generation' => [
        'temperature' => 0.2,
        'max_output_tokens' => 1000,
        'response_mime_type' => 'application/json',
    ],
]);

Generation options are converted to Gemini's camelCase payload keys.

Error Handling

try {
    $response = Gemini::generate('Hello');
} catch (\YasserElgammal\LaravelGemini\Exceptions\GeminiException $exception) {
    report($exception);
}

Available exceptions:

• MissingApiKeyException
• GeminiRequestException
• InvalidGeminiResponseException

Compatibility

This package supports PHP 8.1+ and Laravel 10, 11, 12, and 13.

Testing

composer test

Or from a host Laravel project:

vendor/bin/phpunit -c packages/yasser-elgammal/laravel-gemini/phpunit.xml

License

MIT

Contributing

Pull requests are welcome! For major changes, please open an issue first to discuss what you'd like to modify.