README

A professional, extensible, and scalable package for integrating the Google Gemini API into the Laravel framework.

Features

• Support for all Gemini models (gemini-pro, gemini-pro-vision, etc.)
• Capability to switch models at runtime
• Built on Laravel HTTP Client with precise error handling
• Service-oriented architecture with Dependency Injection support
• Support for Prompt Caching to save on tokens and achieve faster response times
• Input/Output token counting with cost estimation
• Support for async execution using dedicated Queues and Jobs
• Precise rate limiting control and handling of Rate Limit errors
• Facade for easy access
• Middleware for request management
• Configurable logging system
• Support for generating embeddings and calculating text similarity

Installation

You can install this package via Composer:

composer require sanjarani/gemini

Then, publish the configuration file:

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

Configuration

After publishing the configuration file, you can configure the settings in config/gemini.php. You can also use environment variables in your .env file:

GEMINI_API_KEY=your-api-key
GEMINI_DEFAULT_MODEL=gemini-pro
GEMINI_REQUEST_TIMEOUT=30
GEMINI_ENABLE_CACHE=false
GEMINI_CACHE_TTL=3600
GEMINI_ENABLE_LOGGING=false

Usage

Text Generation with Gemini Model

use Sanjarani\Gemini\Facades\Gemini;

// Simple usage
$response = Gemini::generate('Tell me about Artificial Intelligence');
echo $response->content();

// Usage with additional configuration
$response = Gemini::generate('Tell me about Artificial Intelligence', [
    'temperature' => 0.7,
    'top_p' => 0.9,
    'top_k' => 40,
    'max_tokens' => 500,
]);

Chatting with Gemini Model

use Sanjarani\Gemini\Facades\Gemini;

$messages = [
    ['role' => 'user', 'content' => 'Hello, how are you?'],
    ['role' => 'model', 'content' => 'Hello! I am doing well, how can I help you?'],
    ['role' => 'user', 'content' => 'I want to learn more about PHP programming.'],
];

$response = Gemini::chat($messages);
echo $response->content();

Using Vision Model for Image Analysis

use Sanjarani\Gemini\Facades\Gemini;

// Analyze a single image
$response = Gemini::generateFromImage(
    '/path/to/image.jpg',
    'Describe this image'
);

// Analyze multiple images
$response = Gemini::generateFromMultipleImages(
    ['/path/to/image1.jpg', '/path/to/image2.jpg'],
    'Compare these two images'
);

### Using Base64 Image
$base64Image = 'data:image/jpeg;base64,...';
$response = Gemini::generateFromBase64Image(
    $base64Image,
    'Describe this image'
);

Embeddings

// Create embedding for text
$response = Gemini::embedText('This is a sample text');
$embedding = $response->raw()['embedding']['values'];

// Create embedding for a batch of texts
$texts = ['First text', 'Second text', 'Third text'];
$response = Gemini::embedBatch($texts);

// Calculate similarity between two embeddings
$embedding1 = $response1->raw()['embedding']['values'];
$embedding2 = $response2->raw()['embedding']['values'];
$similarity = Gemini::calculateSimilarity($embedding1, $embedding2);
echo "Similarity score: {$similarity}"; // A number between 0 and 1

Runtime Model Switching

use Sanjarani\Gemini\Facades\Gemini;

$response = Gemini::setModel('gemini-ultra')
    ->generate('Write a short story');

Async Execution

use Sanjarani\Gemini\Facades\Gemini;
use App\Handlers\GeminiResponseHandler;

// Async execution with callback
Gemini::generateAsync(
    'Write an article about AI',
    [],
    GeminiResponseHandler::class,
    'handleResponse',
    ['article_id' => 123]
);

Accessing Response Data

use Sanjarani\Gemini\Facades\Gemini;

$response = Gemini::generate('Hello, how are you?');

// Access response text
echo $response->content();

// Access raw response data
$rawData = $response->raw();

// Access token usage information
$tokenUsage = $response->tokenUsage();
echo "Prompt tokens: {$tokenUsage['prompt_tokens']}\n";
echo "Completion tokens: {$tokenUsage['completion_tokens']}\n";
echo "Total tokens: {$tokenUsage['total_tokens']}\n";

// Access estimated cost
echo "Estimated cost: \${$response->estimatedCost()}\n";

// Access used model
echo "Model: {$response->model()}\n";

// Access finish reason
echo "Finish reason: {$response->finishReason()}\n";

// Check if request was successful
if ($response->successful()) {
    echo "Request was successful!\n";
}

Dependency Injection

use Sanjarani\Gemini\Contracts\TextGenerationServiceInterface;

class MyService
{
    protected $textService;
    
    public function __construct(TextGenerationServiceInterface $textService)
    {
        $this->textService = $textService;
    }
    
    public function generateContent($prompt)
    {
        return $this->textService->generate($prompt);
    }
}

Rate Limiting Middleware

In app/Http/Kernel.php:

protected $routeMiddleware = [
    // ...
    'gemini.limit' => \Sanjarani\Gemini\Middleware\GeminiRateLimitMiddleware::class,
];

In Routes:

Route::post('/generate', [GeminiController::class, 'generate'])
    ->middleware('gemini.limit:60,1'); // 60 requests per minute

Artisan Commands

Test Gemini API

php artisan gemini:test "Hello, how are you?"

Clear Gemini Cache

php artisan gemini:cache-clear

Error Handling

This package handles various errors using dedicated exceptions:

use Sanjarani\Gemini\Facades\Gemini;
use Sanjarani\Gemini\Exceptions\GeminiApiException;
use Sanjarani\Gemini\Exceptions\GeminiApiRateLimitException;
use Sanjarani\Gemini\Exceptions\GeminiModelNotFoundException;
use Sanjarani\Gemini\Exceptions\GeminiNetworkException;
use Sanjarani\Gemini\Exceptions\GeminiConfigurationException;

try {
    $response = Gemini::generate('Hello, how are you?');
} catch (GeminiApiRateLimitException $e) {
    // Handle rate limit error
    echo "Rate limit exceeded: {$e->getMessage()}";
} catch (GeminiModelNotFoundException $e) {
    // Handle model not found error
    echo "Model not found: {$e->getMessage()}";
} catch (GeminiNetworkException $e) {
    // Handle network error
    echo "Network error: {$e->getMessage()}";
} catch (GeminiConfigurationException $e) {
    // Handle configuration error
    echo "Configuration error: {$e->getMessage()}";
} catch (GeminiApiException $e) {
    // Handle other API errors
    echo "API error: {$e->getMessage()}";
}

Testing

To run tests:

composer test

Contribution

Contributions are welcome! Please run the tests before submitting a pull request.

License

This package is released under the MIT License. Please see the LICENSE file for more information.