Skip to content

Commit bd1a267

Browse files
lucianotonetlucianotonet
committed
Work in progress
1 parent 133a871 commit bd1a267

19 files changed

+660
-811
lines changed

‎.env.example‎

Lines changed: 9 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,2 +1,9 @@
1-
GROQ_API_KEY=sua_chave_api_aqui
2-
GROQ_API_BASE=https://api.groq.com/openai/v1
1+
# Chave API da Groq (necessária para testes de integração)
2+
GROQ_API_KEY=
3+
GROQ_API_BASE=
4+
5+
# Configurações opcionais
6+
GROQ_MODEL=llama3-8b-8192
7+
GROQ_TIMEOUT=30
8+
GROQ_CACHE_ENABLED=true
9+
GROQ_CACHE_TTL=3600

‎README.md‎

Lines changed: 167 additions & 128 deletions
Original file line numberDiff line numberDiff line change
@@ -1,161 +1,200 @@
11
# Groq Laravel
22

3-
![Groq Laravel](https://raw.githubusercontent.com/lucianotonet/groq-laravel/v0.0.9/docs/art.png)
3+
![Groq Laravel](./art.png)
44

5-
[![Latest Stable Version](https://poser.pugx.org/lucianotonet/groq-laravel/v)](https://packagist.org/packages/lucianotonet/groq-laravel) [![Total Downloads](https://poser.pugx.org/lucianotonet/groq-laravel/downloads)](https://packagist.org/packages/lucianotonet/groq-laravel) [![Latest Unstable Version](https://poser.pugx.org/lucianotonet/groq-laravel/v/unstable)](https://packagist.org/packages/lucianotonet/groq-laravel) [![License](https://poser.pugx.org/lucianotonet/groq-laravel/license)](https://packagist.org/packages/lucianotonet/groq-laravel) [![PHP Version Require](https://poser.pugx.org/lucianotonet/groq-laravel/require/php)](https://packagist.org/packages/lucianotonet/groq-laravel)
5+
[![Latest Stable Version](https://poser.pugx.org/lucianotonet/groq-laravel/v)](https://packagist.org/packages/lucianotonet/groq-laravel)
6+
[![Total Downloads](https://poser.pugx.org/lucianotonet/groq-laravel/downloads)](https://packagist.org/packages/lucianotonet/groq-laravel)
7+
[![License](https://poser.pugx.org/lucianotonet/groq-laravel/license)](https://packagist.org/packages/lucianotonet/groq-laravel)
68

7-
Groq Laravel is a powerful package for integrating your Laravel applications with the [Groq](https://groq.com/) API, allowing you to leverage ultra-fast AI inference speeds with some of the most popular LLMs, such as Llama3.1 or Mixtral.
8-
9-
Need a "vanilla" PHP version? Try this out: [GroqPHP](https://github.com/lucianotonet/groq-php?tab=readme-ov-file#readme)
10-
11-
## Features
12-
13-
- **Simple and Intuitive Interface:** Interact with the Groq API using the `Groq` facade, simplifying access to chat, translation, audio transcription, function call, and image analysis functionalities.
14-
- **Robust Error Handling:** Efficiently manage communication errors and responses from the Groq API, capturing specific exceptions and providing informative messages.
15-
- **Flexible Configuration:** Define multiple Groq API instances, customize request timeouts, configure caching options, and adjust the package's behavior to suit your needs.
16-
- **Detailed Practical Examples:** Explore code examples that demonstrate how to use the Groq Laravel package in real-world scenarios, including chatbots, audio transcription, and more.
17-
- **Comprehensive Testing:** Ensure the quality and reliability of the package with a suite of tests covering integration, unit testing, and configuration.
9+
A Laravel package to easily integrate your application with the Groq API, providing access to popular models like Llama3, Mixtral, and others.
1810

1911
## Installation
2012

21-
1. Install the package via Composer:
22-
23-
```bash
24-
composer require lucianotonet/groq-laravel
25-
```
13+
1. Install via Composer:
14+
```bash
15+
composer require lucianotonet/groq-laravel
16+
```
2617

2718
2. Publish the configuration file:
28-
29-
```bash
30-
php artisan vendor:publish --provider="LucianoTonet\GroqLaravel\GroqServiceProvider"
31-
```
32-
33-
3. Configure your Groq API credentials in the `.env` file:
34-
35-
```config
36-
GROQ_API_KEY=your_api_key_here
37-
```
38-
39-
## Usage
40-
41-
Here is a simple example of how to create a chat completion:
42-
43-
```php
44-
use LucianoTonet\GroqLaravel\Facades\Groq;
45-
46-
$response = Groq::chat()->completions()->create([
47-
'model' => 'llama-3.1-70b-versatile', // Check available models at console.groq.com/docs/models
48-
'messages' => [
49-
['role' => 'user', 'content' => 'Hello, how are you?'],
50-
],
51-
]);
52-
53-
$response['choices'][0]['message']['content']; // "Hey there! I'm doing great! How can I help you today?"
54-
```
19+
```bash
20+
php artisan vendor:publish --provider="LucianoTonet\GroqLaravel\GroqServiceProvider"
21+
```
22+
23+
3. Add your API key to the `.env` file:
24+
```env
25+
GROQ_API_KEY=your-api-key-here
26+
GROQ_MODEL=llama3-8b-8192 # optional, default model
27+
```
28+
29+
## Basic Usage
30+
31+
### Chat
32+
33+
```php
34+
use LucianoTonet\GroqLaravel\Facades\Groq;
35+
36+
$response = Groq::chat()->create([
37+
'messages' => [
38+
['role' => 'user', 'content' => 'Hello, how are you?']
39+
]
40+
]);
41+
42+
echo $response['choices'][0]['message']['content'];
43+
```
44+
45+
### Available Models
46+
47+
```php
48+
$models = Groq::models()->list();
49+
50+
foreach ($models['data'] as $model) {
51+
echo $model['id'] . "\n";
52+
}
53+
```
54+
55+
### Computer Vision
56+
57+
```php
58+
$response = Groq::vision()->analyze(
59+
'path/to/image.jpg',
60+
'Describe this image'
61+
);
62+
63+
echo $response['choices'][0]['message']['content'];
64+
```
65+
66+
### Audio
67+
68+
```php
69+
$response = Groq::audio()->transcribe('path/to/audio.mp3');
70+
echo $response['text'];
71+
```
72+
73+
### Batch Processing
74+
75+
```php
76+
// Upload file
77+
$file = Groq::files()->upload('data.jsonl', 'batch');
78+
79+
// Create batch
80+
$batch = Groq::batches()->create([
81+
'input_file_id' => $file->id,
82+
'endpoint' => '/v1/chat/completions'
83+
]);
84+
```
85+
86+
## Configuration
87+
88+
The package can be configured through the `config/groq.php` file. The main options are:
89+
90+
```php
91+
return [
92+
'api_key' => env('GROQ_API_KEY'),
93+
'model' => env('GROQ_MODEL', 'llama3-8b-8192'),
94+
'timeout' => env('GROQ_TIMEOUT', 30),
95+
96+
'options' => [
97+
'temperature' => 0.7,
98+
'max_tokens' => 150,
99+
'top_p' => 1.0,
100+
'frequency_penalty' => 0,
101+
'presence_penalty' => 0,
102+
],
103+
104+
'cache' => [
105+
'enabled' => true,
106+
'ttl' => 3600,
107+
],
108+
];
109+
```
110+
111+
## Runtime Configuration
112+
113+
You can change settings during runtime:
114+
115+
```php
116+
Groq::setConfig([
117+
'model' => 'mixtral-8x7b',
118+
'temperature' => 0.9,
119+
'max_tokens' => 500
120+
]);
121+
```
55122

56123
## Error Handling
57124

58-
The Groq Laravel package makes it easy to handle errors that may occur when interacting with the Groq API. Use a `try-catch` block to capture and manage exceptions:
59-
60-
```php
61-
try {
62-
$response = Groq::chat()->completions()->create([
63-
'model' => 'llama-3.1-8b-instant',
64-
// ...
65-
]);
66-
} catch (GroqException $e) {
67-
Log::error('Error in Groq API: ' . $e->getMessage());
68-
abort(500, 'Error processing your request.');
69-
}
70-
```
71-
72-
Sometimes, the Groq API fails and returns an error message in the response with a failed generation detail. In this case, you can use the `GroqException` class to get the error message:
73-
74-
```php
75-
try {
76-
$response = Groq::chat()->completions()->create([
77-
'model' => 'llama-3.1-8b-instant',
78-
// ...
79-
]);
80-
} catch (GroqException $e) {
81-
$errorMessage = $e->getFailedGeneration();
82-
// ...
83-
}
84-
```
85-
86-
## Vision API
87-
88-
The Groq Laravel package also provides access to the Groq Vision API, allowing you to analyze images and extract information from them.
89-
90-
**Example of use with image URL:**
91-
92-
```php
93-
use LucianoTonet\GroqLaravel\Facades\Groq;
94-
95-
// ...
96-
97-
$imageUrl = 'https://example.com/image.jpg'; // Replace with your image URL
98-
$prompt = 'Describe the image';
99-
100-
$response = Groq::vision()->analyze($imageUrl, $prompt);
101-
102-
$imageDescription = $response['choices'][0]['message']['content'];
103-
104-
// ... do something with the image description
105-
```
106-
107-
**Example of use with local image file:**
108-
109-
```php
110-
use LucianoTonet\GroqLaravel\Facades\Groq;
111-
112-
// ...
113-
114-
$imagePath = '/path/to/your/image.jpg'; // Replace with the actual path
115-
$prompt = 'What do you see in this image?';
125+
The package throws `GroqException` when something goes wrong:
116126

117-
$response = Groq::vision()->analyze($imagePath, $prompt);
127+
```php
128+
use LucianoTonet\GroqPHP\GroqException;
118129

119-
$imageAnalysis = $response['choices'][0]['message']['content'];
130+
try {
131+
$response = Groq::chat()->create([
132+
'messages' => [
133+
['role' => 'user', 'content' => 'Hello!']
134+
]
135+
]);
136+
} catch (GroqException $e) {
137+
echo "Error: " . $e->getMessage();
138+
}
139+
```
120140

121-
// ... do something with the image analysis
122-
```
141+
## Development
123142

124-
**Remember:**
125-
- 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 the `config/groq.php` configuration file.
126-
- The Vision API is an experimental feature and may not meet expectations, as well as not having long-term support.
143+
### Development Installation
127144

145+
1. Clone the repository
146+
```bash
147+
git clone https://github.com/lucianotonetto/groq-laravel.git
148+
cd groq-laravel
149+
```
128150

129-
## More examples
151+
2. Install dependencies
152+
```bash
153+
composer install
154+
```
130155

131-
As the GroqLaravel package is a wrapper for the GroqPHP package, you can check more examples in the [GroqPHP repository](https://github.com/lucianotonet/groq-php?tab=readme-ov-file#readme).
156+
### Running Tests
132157

158+
The package includes unit and integration tests. To run them:
133159

134-
## Testing
160+
1. Copy the example environment file:
161+
```bash
162+
cp .env.example .env
163+
```
135164

136-
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:
165+
2. Configure your Groq API key in the `.env` file (required only for integration tests):
166+
```env
167+
GROQ_API_KEY=your-api-key-here
168+
```
137169

138-
1. **Install the project dependencies:**
170+
3. Run the tests:
139171

140-
```bash
141-
composer install
142-
```
172+
- All tests:
173+
```bash
174+
composer test
175+
```
143176

144-
2. **Run the tests:**
177+
- Unit tests only:
178+
```bash
179+
vendor/bin/phpunit tests/Feature/GroqTest.php
180+
```
145181

146-
```bash
147-
vendor/bin/phpunit ./tests/Feature
148-
```
182+
- Integration tests only:
183+
```bash
184+
vendor/bin/phpunit tests/Feature/GroqIntegrationTest.php
185+
```
149186

150-
or individually:
187+
- Tests with code coverage:
188+
```bash
189+
vendor/bin/phpunit --coverage-html coverage
190+
```
151191

152-
```bash
153-
vendor/bin/phpunit ./tests/Feature/FacadeTest.php
154-
```
192+
**Note**: Unit tests don't require an API key. Integration tests will be skipped if no API key is provided.
155193

156-
## Contributing
194+
## Credits
157195

158-
Contributions are welcome! Follow the guidelines described in the [CONTRIBUTING.md](CONTRIBUTING.md) file.
196+
- [Luciano Tonet](https://github.com/lucianotonet)
197+
- [All Contributors](../../contributors)
159198

160199
## License
161200

‎docs/art.png‎ renamed to ‎art.png‎

File renamed without changes.

‎composer.json‎

Lines changed: 12 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,8 +1,8 @@
11
{
22
"name": "lucianotonet/groq-laravel",
3-
"description": "Laravel package to access Groq REST API",
3+
"description": "Laravel integration for GroqCloud",
44
"type": "library",
5-
"version": "0.0.10",
5+
"version": "0.1.2",
66
"license": "MIT",
77
"authors": [
88
{
@@ -12,7 +12,7 @@
1212
],
1313
"require": {
1414
"php": "^8.1",
15-
"lucianotonet/groq-php": "^0.0.10",
15+
"lucianotonet/groq-php": "^0.1",
1616
"illuminate/support": "*",
1717
"illuminate/contracts": "*"
1818
},
@@ -25,6 +25,15 @@
2525
"LucianoTonet\\GroqLaravel\\": "src/"
2626
}
2727
},
28+
"autoload-dev": {
29+
"psr-4": {
30+
"LucianoTonet\\GroqLaravel\\Tests\\": "tests/"
31+
}
32+
},
33+
"scripts": {
34+
"test": "vendor/bin/phpunit",
35+
"test-coverage": "vendor/bin/phpunit --coverage-html coverage"
36+
},
2837
"extra": {
2938
"laravel": {
3039
"providers": [

0 commit comments

Comments
 (0)