lucianotonet / groq-laravel
Laravel integration for GroqCloud
Installs: 4 618
Dependents: 0
Suggesters: 0
Security: 0
Stars: 24
Watchers: 3
Forks: 1
Open Issues: 0
Requires
- php: ^8.1
- illuminate/contracts: *
- illuminate/support: *
- lucianotonet/groq-php: ^0.0.10
Requires (Dev)
- orchestra/testbench: ^6.0|^7.0|^8.0
- phpunit/phpunit: ^9.0
This package is auto-updated.
Last update: 2025-04-12 23:34:59 UTC
README
A Laravel package to easily integrate your application with the Groq API, providing access to popular models like Llama3, Mixtral, and others.
Installation
- Install via Composer:
composer require lucianotonet/groq-laravel
- Publish the configuration file:
php artisan vendor:publish --provider="LucianoTonet\GroqLaravel\GroqServiceProvider"
- Add your API key to the
.env
file:
GROQ_API_KEY=your-api-key-here GROQ_MODEL=llama3-8b-8192 # optional, default model
Basic Usage
Chat
use LucianoTonet\GroqLaravel\Facades\Groq; $response = Groq::chat()->create([ 'messages' => [ ['role' => 'user', 'content' => 'Hello, how are you?'] ] ]); echo $response['choices'][0]['message']['content'];
Available Models
$models = Groq::models()->list(); foreach ($models['data'] as $model) { echo $model['id'] . "\n"; }
Computer Vision
$response = Groq::vision()->analyze( 'path/to/image.jpg', 'Describe this image' ); echo $response['choices'][0]['message']['content'];
Audio
$response = Groq::audio()->transcribe('path/to/audio.mp3'); echo $response['text'];
Batch Processing
// Upload file $file = Groq::files()->upload('data.jsonl', 'batch'); // Create batch $batch = Groq::batches()->create([ 'input_file_id' => $file->id, 'endpoint' => '/v1/chat/completions' ]);
Configuration
The package can be configured through the config/groq.php
file. The main options are:
return [ 'api_key' => env('GROQ_API_KEY'), 'model' => env('GROQ_MODEL', 'llama3-8b-8192'), 'timeout' => env('GROQ_TIMEOUT', 30), 'options' => [ 'temperature' => 0.7, 'max_tokens' => 150, 'top_p' => 1.0, 'frequency_penalty' => 0, 'presence_penalty' => 0, ], 'cache' => [ 'enabled' => true, 'ttl' => 3600, ], ];
Runtime Configuration
You can change settings during runtime:
Groq::setConfig([ 'model' => 'mixtral-8x7b', 'temperature' => 0.9, 'max_tokens' => 500 ]);
Error Handling
The package throws GroqException
when something goes wrong:
use LucianoTonet\GroqPHP\GroqException; try { $response = Groq::chat()->create([ 'messages' => [ ['role' => 'user', 'content' => 'Hello!'] ] ]); } catch (GroqException $e) { echo "Error: " . $e->getMessage(); }
Development
Development Installation
- Clone the repository
git clone https://github.com/lucianotonetto/groq-laravel.git
cd groq-laravel
- Install dependencies
composer install
Running Tests
The package includes unit and integration tests. To run them:
- Copy the example environment file:
cp .env.example .env
- Configure your Groq API key in the
.env
file (required only for integration tests):
GROQ_API_KEY=your-api-key-here
- Run the tests:
- All tests:
composer test
- Unit tests only:
vendor/bin/phpunit tests/Feature/GroqTest.php
- Integration tests only:
vendor/bin/phpunit tests/Feature/GroqIntegrationTest.php
- Tests with code coverage:
vendor/bin/phpunit --coverage-html coverage
Note: Unit tests don't require an API key. Integration tests will be skipped if no API key is provided.
Advanced Features
Vision API
The Vision API allows you to analyze images and extract information from them.
Example of use with image URL:
use LucianoTonet\GroqLaravel\Facades\Groq; // ... $imageUrl = 'https://example.com/image.jpg'; // Replace with your image URL $prompt = 'Describe the image'; $response = Groq::vision()->analyze($imageUrl, $prompt); $imageDescription = $response['choices'][0]['message']['content']; // ... do something with the image description
Example of use with local image file:
use LucianoTonet\GroqLaravel\Facades\Groq; // ... $imagePath = '/path/to/your/image.jpg'; // Replace with the actual path $prompt = 'What do you see in this image?'; $response = Groq::vision()->analyze($imagePath, $prompt); $imageAnalysis = $response['choices'][0]['message']['content']; // ... do something with the image analysis
Remember:
- The Vision API requires a model compatible with image analysis, such as
llava-v1.5-7b-4096-preview
. You can configure the default model for Vision in theconfig/groq.php
configuration file. - The Vision API is an experimental feature and may not meet expectations, as well as not having long-term support.
Audio Transcriptions
The Groq Laravel package allows you to transcribe audio using advanced models like Whisper.
Example of transcribing an audio file:
use LucianoTonet\GroqLaravel\Facades\Groq; // Basic transcription $result = Groq::transcriptions()->create([ 'file' => storage_path('app/audio/recording.mp3'), 'model' => 'whisper-large-v3' ]); echo $result['text']; // Transcribed text from the audio
Example with advanced options:
// Transcription with advanced options $result = Groq::transcriptions()->create([ 'file' => storage_path('app/audio/recording.mp3'), 'model' => 'whisper-large-v3', 'language' => 'en', // Audio language (optional) 'prompt' => 'Transcription of a business meeting', // Context to improve accuracy 'temperature' => 0.3, // Lower randomness for more accuracy 'response_format' => 'verbose_json' // Detailed format with timestamps ]); // Now you have access to timestamps and segments echo $result['text']; // Complete text foreach ($result['segments'] as $segment) { echo "From {$segment['start']} to {$segment['end']}: {$segment['text']}\n"; }
Audio Translations
The Groq Laravel package also provides support for direct audio translation to English text.
Basic example of audio translation:
use LucianoTonet\GroqLaravel\Facades\Groq; // Basic translation (always to English) $result = Groq::translations()->create([ 'file' => storage_path('app/audio/portuguese.mp3'), 'model' => 'whisper-large-v3' ]); echo $result['text']; // English text translated from the audio
Example with advanced options:
// Translation with advanced options $result = Groq::translations()->create([ 'file' => storage_path('app/audio/french.mp3'), 'model' => 'whisper-large-v3', 'prompt' => 'This is a business meeting', // Context in English 'temperature' => 0.3, // Lower randomness for more accuracy 'response_format' => 'verbose_json' // Detailed format with timestamps ]); // Now you have access to timestamps and segments in English echo $result['text']; // Complete text in English foreach ($result['segments'] as $segment) { echo "From {$segment['start']} to {$segment['end']}: {$segment['text']}\n"; }
Step-by-Step Reasoning
Groq Laravel offers support for obtaining responses with step-by-step reasoning, useful for detailed explanations, mathematical problems, or any solution that benefits from a transparent process.
Example with raw reasoning format:
use LucianoTonet\GroqLaravel\Facades\Groq; // Raw format - displays the entire reasoning process $response = Groq::reasoning()->analyze('How to solve x^2 - 9 = 0?', [ 'model' => 'llama-3.1-8b-instant', 'reasoning_format' => 'raw' ]); echo $response['choices'][0]['message']['content']; // Displays both the reasoning process and the answer
Example with parsed reasoning format:
// Parsed format - separates reasoning from the final answer $response = Groq::reasoning()->analyze('What is the capital of France?', [ 'model' => 'llama-3.1-70b-instant', 'reasoning_format' => 'parsed' ]); echo "Answer: " . $response['choices'][0]['message']['content'] . "\n"; echo "Reasoning: " . $response['choices'][0]['message']['reasoning']; // Displays the direct answer (Paris) and the reasoning separately
Example with hidden reasoning:
// Hidden format - only the final answer $response = Groq::reasoning()->analyze('Calculate the area of a circle with radius 5cm', [ 'model' => 'llama-3.1-8b-instant', 'reasoning_format' => 'hidden' ]); echo $response['choices'][0]['message']['content']; // Displays only the final answer, without the reasoning process
Advanced Completions
Groq Laravel supports advanced completion features, including image analysis and response streaming.
Example with image input:
use LucianoTonet\GroqLaravel\Facades\Groq; // Completions with image $response = Groq::completions()->create([ 'model' => 'llava-v1.5-7b-4096-preview', 'messages' => [ [ 'role' => 'user', 'content' => [ ['type' => 'text', 'text' => 'What is in this image?'], [ 'type' => 'image_url', 'image_url' => [ 'url' => 'https://example.com/image.jpg' ] ] ] ] ] ]); echo $response['choices'][0]['message']['content'];
Example with streaming:
// Completions with streaming $stream = Groq::completions()->create([ 'model' => 'llama-3.1-8b-instant', 'messages' => [ ['role' => 'user', 'content' => 'Tell a short story about a robot'] ], 'stream' => true ]); // Process the response in stream (useful for real-time interfaces) foreach ($stream->chunks() as $chunk) { if (isset($chunk['choices'][0]['delta']['content'])) { echo $chunk['choices'][0]['delta']['content']; // Send to client in real-time (in real applications) ob_flush(); flush(); } }
File Management
Groq Laravel allows you to manage files for use with the API.
use LucianoTonet\GroqLaravel\Facades\Groq; // List files $files = Groq::files()->list(); // Upload a file $file = Groq::files()->upload(storage_path('app/data/document.txt'), 'assistants'); // Retrieve file information $fileInfo = Groq::files()->retrieve($file['id']); // Delete a file Groq::files()->delete($file['id']);
More examples
As the GroqLaravel package is a wrapper for the GroqPHP package, you can check more examples in the GroqPHP repository.
Testing
Testing is an essential part of quality software development. The Groq Laravel package includes a test suite that covers integration, unit, and configuration. To run the tests, follow the steps below:
-
Install the project dependencies:
composer install
-
Run the tests:
vendor/bin/phpunit ./tests/Feature
or individually:
vendor/bin/phpunit ./tests/Feature/FacadeTest.php
Credits
Contributing
Contributions are welcome! Follow the guidelines described in the CONTRIBUTING.md file.
License
This package is open-source software licensed under the MIT license.