├── art.png
├── tests
├── fixtures
│ ├── audio.wav
│ ├── australian_shepherd_puppies.png
│ ├── batch_file_audio.jsonl
│ ├── batch_file_invalid.jsonl
│ └── batch_file.jsonl
├── ModelsTest.php
├── TestCase.php
├── ReasoningTest.php
├── AudioTest.php
├── VisionTest.php
├── BatchManagerTest.php
├── ChatTest.php
├── GroqTest.php
├── FileManagerTest.php
└── EnvironmentVariablesTest.php
├── examples
├── .env.example
├── .gitignore
├── _input.php
├── models.php
├── composer.json
├── chat.php
├── chat-streaming.php
├── vision-url.php
├── json-mode.php
├── jsonl-processing.php
├── vision-feedback.php
├── vision-simple.php
├── audio-translations.php
├── index.php
├── audio-speech.php
├── vision-multiple.php
├── tool-calling-advanced.php
├── tool-calling.php
├── reasoning.php
├── audio-transcriptions.php
└── files.php
├── .gitattributes
├── .env.example
├── .gitignore
├── src
├── Chat.php
├── Audio.php
├── Models.php
├── Stream.php
├── Reasoning.php
├── Vision.php
├── Speech.php
├── Batch.php
├── File.php
├── Translations.php
├── Transcriptions.php
├── Groq.php
├── Completions.php
├── GroqException.php
├── BatchManager.php
└── FileManager.php
├── composer.json
├── LICENSE
├── .github
└── workflows
│ └── tests.yml
└── CHANGELOG.md
/art.png:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/lucianotonet/groq-php/HEAD/art.png
--------------------------------------------------------------------------------
/tests/fixtures/audio.wav:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/lucianotonet/groq-php/HEAD/tests/fixtures/audio.wav
--------------------------------------------------------------------------------
/tests/fixtures/australian_shepherd_puppies.png:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/lucianotonet/groq-php/HEAD/tests/fixtures/australian_shepherd_puppies.png
--------------------------------------------------------------------------------
/examples/.env.example:
--------------------------------------------------------------------------------
1 | GROQ_API_KEY= # Get your API key on https://console.groq.com/keys
2 | GROQ_API_BASE=https://api.groq.com/openai/v1
3 |
4 | DEEPGRAM_API_KEY=
--------------------------------------------------------------------------------
/.gitattributes:
--------------------------------------------------------------------------------
1 | /.yarn/** linguist-vendored
2 | /.yarn/releases/* binary
3 | /.yarn/plugins/**/* binary
4 | /.pnp.* binary linguist-generated
5 |
--------------------------------------------------------------------------------
/examples/.gitignore:
--------------------------------------------------------------------------------
1 | /.phpunit.cache
2 | /.php-cs-fixer.cache
3 | /.php-cs-fixer.php
4 | /phpunit.xml
5 | /vendor/
6 | *.swp
7 | *.swo
8 | playground/*
9 | .idea
10 | .env
--------------------------------------------------------------------------------
/.env.example:
--------------------------------------------------------------------------------
1 | # Groq API Key
2 | # Get your API key from https://console.groq.com/keys
3 | GROQ_API_KEY=your_api_key_here
4 |
5 | # Optional: Custom API Base URL
6 | # GROQ_API_BASE=https://api.groq.com/openai/v1
7 |
8 | DEEPGRAM_API_KEY=
--------------------------------------------------------------------------------
/examples/_input.php:
--------------------------------------------------------------------------------
1 |
--------------------------------------------------------------------------------
/tests/fixtures/batch_file_audio.jsonl:
--------------------------------------------------------------------------------
1 | {"custom_id":"audio-request-1","method":"POST","url":"/v1/audio/transcriptions","body":{"model":"whisper-large-v3","language":"en","url":"https://github.com/lucianotonet/groq-php/raw/main/tests/fixtures/audio.wav","response_format":"verbose_json"}}
2 |
--------------------------------------------------------------------------------
/.gitignore:
--------------------------------------------------------------------------------
1 | /.phpunit.cache
2 | /.php-cs-fixer.cache
3 | /.php-cs-fixer.php
4 | /composer.lock
5 | /phpunit.xml
6 | /vendor/
7 | *.swp
8 | *.swo
9 | playground/*
10 | .idea
11 | .env
12 | /examples/.env
13 | /examples/vendor/
14 | CHANGELOG_GEN.sh
15 | .cursorrules
16 | .cursor*
17 | proj2md.py
--------------------------------------------------------------------------------
/tests/ModelsTest.php:
--------------------------------------------------------------------------------
1 | groq->models()->list();
11 |
12 | $this->assertIsArray($models);
13 | $this->assertNotEmpty($models);
14 | $this->assertArrayHasKey('data', $models);
15 | }
16 | }
--------------------------------------------------------------------------------
/src/Chat.php:
--------------------------------------------------------------------------------
1 | groq = $groq;
20 | }
21 |
22 | /**
23 | * @return Completions
24 | */
25 | public function completions(): Completions
26 | {
27 | return new Completions($this->groq);
28 | }
29 | }
--------------------------------------------------------------------------------
/examples/models.php:
--------------------------------------------------------------------------------
1 |
2 |
Available Models:
3 |
4 | models()->list();
6 | ?>
7 |
8 |
9 |
10 | -
11 |
12 | by
13 | context window:
14 |
15 |
16 |
17 |
2 | user: $message
";
10 |
11 | try {
12 | $response = $groq->chat()->completions()->create([
13 | 'model' => 'llama-3.1-8b-instant',
14 | 'messages' => [
15 | [
16 | 'role' => 'user',
17 | 'content' => $message
18 | ]
19 | ],
20 | ]);
21 |
22 | echo "
assistant: ";
23 | echo $response['choices'][0]['message']['content'];
24 | } catch (GroqException $err) {
25 | echo "
assistant:".$err->getMessage()."
";
26 |
27 | echo "
";
28 | print_r($err->getError());
29 |
30 | echo "
";
31 | }
32 | }
33 | ?>
34 |
2 | user: $message
";
10 |
11 | try {
12 | $response = $groq->chat()->completions()->create([
13 | 'model' => 'llama-3.1-8b-instant',
14 | 'messages' => [
15 | [
16 | 'role' => 'user',
17 | 'content' => $message
18 | ]
19 | ],
20 | 'stream' => true
21 | ]);
22 |
23 | foreach ($response->chunks() as $chunk) {
24 | if (isset($chunk['choices'][0]['delta']['role'])) {
25 | echo "" . $chunk['choices'][0]['delta']['role'] . ": ";
26 | }
27 |
28 | if (isset($chunk['choices'][0]['delta']['content'])) {
29 | echo $chunk['choices'][0]['delta']['content'];
30 | }
31 |
32 | // Chame ob_flush() e flush() na ordem correta
33 | ob_flush(); // Limpa o buffer de saída
34 | flush(); // Envia os dados para o cliente
35 | }
36 | } catch (\LucianoTonet\GroqPHP\GroqException $err) {
37 | echo "assistant:
Desculpe, ocorreu um erro: " . $err->getMessage() . "
";
38 | }
39 | }
40 | ?>
41 |
--------------------------------------------------------------------------------
/.github/workflows/tests.yml:
--------------------------------------------------------------------------------
1 | name: Tests
2 |
3 | on:
4 | push:
5 | branches: [ main ]
6 | pull_request:
7 | branches: [ main ]
8 | release:
9 | types: [ published ]
10 |
11 | jobs:
12 | test:
13 | runs-on: ubuntu-latest
14 | # Rodando apenas com PHP 8.2 para economizar créditos da API,
15 | # já que os testes fazem chamadas reais à API do Groq
16 | strategy:
17 | matrix:
18 | php-version: ['8.2']
19 |
20 | steps:
21 | - uses: actions/checkout@v4
22 |
23 | - name: Setup PHP
24 | uses: shivammathur/setup-php@v2
25 | with:
26 | php-version: ${{ matrix.php-version }}
27 | extensions: fileinfo, json
28 | coverage: xdebug
29 |
30 | - name: Validate composer.json
31 | run: composer validate --strict
32 |
33 | - name: Cache Composer packages
34 | id: composer-cache
35 | uses: actions/cache@v4
36 | with:
37 | path: vendor
38 | key: ${{ runner.os }}-php-${{ hashFiles('**/composer.lock') }}
39 | restore-keys: |
40 | ${{ runner.os }}-php-
41 |
42 | - name: Install dependencies
43 | run: composer install --prefer-dist --no-progress
44 |
45 | - name: Create .env file
46 | run: |
47 | echo "GROQ_API_KEY=${{ secrets.GROQ_API_KEY }}" > .env
48 | echo "GROQ_API_BASE=https://api.groq.com/openai/v1" >> .env
49 |
50 | - name: Run test suite
51 | run: composer test
52 |
--------------------------------------------------------------------------------
/src/Audio.php:
--------------------------------------------------------------------------------
1 | groq = $groq;
23 | }
24 |
25 | /**
26 | * Returns a Transcriptions object to work with audio transcriptions.
27 | *
28 | * @return Transcriptions An instance of the Transcriptions class.
29 | */
30 | public function transcriptions(): Transcriptions
31 | {
32 | return new Transcriptions($this->groq);
33 | }
34 |
35 | /**
36 | * Returns a Translations object to work with audio translations.
37 | *
38 | * @return Translations An instance of the Translations class.
39 | */
40 | public function translations(): Translations
41 | {
42 | return new Translations($this->groq);
43 | }
44 |
45 | /**
46 | * Returns a Speech object to work with text-to-speech.
47 | *
48 | * @return Speech An instance of the Speech class.
49 | */
50 | public function speech(): Speech
51 | {
52 | return new Speech($this->groq);
53 | }
54 | }
55 |
--------------------------------------------------------------------------------
/examples/vision-url.php:
--------------------------------------------------------------------------------
1 |
2 |
Prompt: $prompt";
8 |
9 | try {
10 | $response = $groq->vision()->analyze($imageUrl, $prompt);
11 |
12 | echo "
Resposta do Modelo:
";
13 | echo "
" . $response['choices'][0]['message']['content'] . "
";
14 | } catch (LucianoTonet\GroqPHP\GroqException $err) {
15 | echo "
Erro: " . $err->getMessage() . "
";
16 | }
17 | }
18 | ?>
19 |
20 |
35 |
2 | user: $message
";
9 |
10 | try {
11 | $response = $groq->chat()->completions()->create([
12 | 'model' => 'llama3-70b-8192',
13 | 'messages' => [
14 | [
15 | 'role' => 'system',
16 | 'content' => "You are an API and shall responde only with valid JSON.",
17 | ],
18 | [
19 | 'role' => 'user',
20 | 'content' => $message,
21 | ],
22 | ],
23 | 'response_format' => ['type' => 'json_object']
24 | ]);
25 | echo "
assistant: ";
26 | echo "
";
27 | echo json_encode(json_decode($response['choices'][0]['message']['content']), JSON_PRETTY_PRINT);
28 | echo "
";
29 | } catch (LucianoTonet\GroqPHP\GroqException $e) {
30 | echo "
Error: ";
31 | echo "
";
32 | echo htmlspecialchars(print_r($e->getMessage(), true));
33 | echo "
";
34 |
35 | if($e->getFailedGeneration()) {
36 | echo "
Failed Generation (invalid JSON): ";
37 | echo "
";
38 | echo htmlspecialchars(print_r($e->getFailedGeneration(), true));
39 | echo "
";
40 | }
41 | }
42 | } else {
43 | echo "
Ask anythings to simulate an API.
Results will be mocked for demo purposes.";
44 | }
45 | ?>
46 |
2 |
Prompt: $prompt";
9 | echo "
Feedback: $feedback
";
10 |
11 | try {
12 | $response = $groq->vision()->analyze($imagePath, $prompt);
13 |
14 | echo "
Resposta do Modelo:
";
15 | echo "
" . $response['choices'][0]['message']['content'] . "
";
16 |
17 | // Aqui você pode processar o feedback, se necessário
18 | } catch (LucianoTonet\GroqPHP\GroqException $err) {
19 | echo "
Erro: " . $err->getMessage() . "
";
20 | }
21 | }
22 | ?>
23 |
24 |
48 |
2 |
Prompt: $prompt";
7 |
8 | try {
9 | $tempDir = sys_get_temp_dir();
10 | $imagePath = $tempDir . '/' . basename($_FILES['image']['name']);
11 |
12 | if ($_FILES['image']['error'] !== UPLOAD_ERR_OK) {
13 | throw new Exception("Erro no upload: " . $_FILES['image']['error']);
14 | }
15 |
16 | if (!move_uploaded_file($_FILES['image']['tmp_name'], $imagePath)) {
17 | throw new Exception("Falha ao mover o arquivo para o diretório temporário.");
18 | }
19 |
20 | $response = $groq->vision()->analyze($imagePath, $prompt);
21 |
22 | echo "
Resposta do Modelo:
";
23 | echo "
" . $response['choices'][0]['message']['content'] . "
";
24 | } catch (LucianoTonet\GroqPHP\GroqException $err) {
25 | echo "
Erro Groq: " . $err->getMessage() . "
";
26 | } catch (Exception $e) {
27 | echo "
Erro: " . $e->getMessage() . "
";
28 | } finally {
29 | if (isset($imagePath) && file_exists($imagePath)) {
30 | unlink($imagePath);
31 | }
32 | }
33 | }
34 | ?>
35 |
36 |
55 |
" . htmlspecialchars($e->getMessage()) . "
";
52 | } finally {
53 | if (file_exists($newFilePath)) {
54 | unlink($newFilePath);
55 | }
56 | }
57 | }
--------------------------------------------------------------------------------
/tests/ReasoningTest.php:
--------------------------------------------------------------------------------
1 | "deepseek-r1-distill-llama-70b",
22 | 'reasoning_format' => "raw"
23 | ];
24 |
25 | try {
26 | $response = $this->groq->reasoning()->analyze($prompt, $options);
27 | } catch (GroqException $e) {
28 | $this->fail("Error in reasoning analysis: " . $e->getMessage());
29 | }
30 |
31 | $this->assertArrayHasKey('choices', $response);
32 | $this->assertNotEmpty($response['choices']);
33 | $this->assertArrayHasKey('message', $response['choices'][0]);
34 | $this->assertArrayHasKey('content', $response['choices'][0]['message']);
35 | }
36 |
37 | public function testReasoningWithCustomOptions()
38 | {
39 | $prompt = "Explain the process of photosynthesis.";
40 | $options = [
41 | 'temperature' => 0.6,
42 | 'max_completion_tokens' => 1024,
43 | 'model' => "deepseek-r1-distill-llama-70b",
44 | 'reasoning_format' => "raw"
45 | ];
46 |
47 | try {
48 | $response = $this->groq->reasoning()->analyze($prompt, $options);
49 | } catch (GroqException $e) {
50 | $this->fail("Error in reasoning with custom options: " . $e->getMessage());
51 | }
52 |
53 | $this->assertArrayHasKey('choices', $response);
54 | $this->assertNotEmpty($response['choices']);
55 | }
56 |
57 | public function testReasoningWithStreaming()
58 | {
59 | $prompt = "Explain quantum entanglement.";
60 | $options = [
61 | 'stream' => true,
62 | 'model' => "deepseek-r1-distill-llama-70b",
63 | ];
64 |
65 | try {
66 | $stream = $this->groq->reasoning()->analyze($prompt, $options);
67 | $this->assertInstanceOf(\LucianoTonet\GroqPHP\Stream::class, $stream);
68 |
69 | $hasContent = false;
70 | foreach ($stream->chunks() as $chunk) {
71 | if (isset($chunk['choices'][0]['delta']['content'])) {
72 | $hasContent = true;
73 | break;
74 | }
75 | }
76 | $this->assertTrue($hasContent);
77 | } catch (GroqException $e) {
78 | $this->fail("Error in reasoning streaming: " . $e->getMessage());
79 | }
80 | }
81 | }
--------------------------------------------------------------------------------
/examples/index.php:
--------------------------------------------------------------------------------
1 | load();
10 |
11 | try {
12 | $groq = new Groq(getenv('GROQ_API_KEY'), [
13 | 'baseUrl' => getenv('GROQ_API_BASE')
14 | ]);
15 | } catch (GroqException $e) {
16 | echo $e->getMessage();
17 | die();
18 | }
19 |
20 | $accept = isset($_SERVER['HTTP_ACCEPT']) ? $_SERVER['HTTP_ACCEPT'] : '';
21 | $accept = explode(',', $accept);
22 |
23 | if (!in_array('text/html', $accept)) {
24 | require __DIR__ . '/' . $_GET['page'] . '.php';
25 | exit;
26 | }
27 |
28 | ?>
29 |
30 |
31 |
32 |
33 |
34 |
35 |
36 |
37 |
38 | Groq PHP Examples
39 |
40 |
41 |
42 |
43 |
44 |
45 |
46 |
Examples:
47 |
62 |
63 |
Advanced:
64 |
67 |
68 |
69 |
70 |
77 |
78 |
79 |
2 | O prompt não pode estar vazio.";
10 | } else {
11 | echo "
Prompt para todas as imagens: " . htmlspecialchars($prompt) . "
";
12 |
13 | foreach ($imagePaths as $index => $imagePath) {
14 | $tempDir = sys_get_temp_dir();
15 | $tempImagePath = $tempDir . '/' . basename($_FILES['images']['name'][$index]);
16 |
17 | if ($_FILES['images']['error'][$index] !== UPLOAD_ERR_OK) {
18 | echo "
Erro no upload da imagem " . ($index + 1) . ": " . $_FILES['images']['error'][$index] . "
";
19 | continue;
20 | }
21 |
22 | if (!move_uploaded_file($imagePath, $tempImagePath)) {
23 | echo "
Falha ao mover o arquivo para o diretório temporário da imagem " . ($index + 1) . ".
";
24 | continue;
25 | }
26 |
27 | $uploadedImagePaths[] = $tempImagePath;
28 |
29 | try {
30 | $response = $groq->vision()->analyze($tempImagePath, $prompt);
31 | echo "
Resposta do Modelo para Imagem " . ($index + 1) . ":
";
32 | echo "
" . htmlspecialchars($response['choices'][0]['message']['content']) . "
";
33 | } catch (LucianoTonet\GroqPHP\GroqException $err) {
34 | echo "
Erro na análise da imagem " . ($index + 1) . ": " . htmlspecialchars($err->getMessage()) . "
";
35 | } catch (Exception $e) {
36 | echo "
Erro: " . htmlspecialchars($e->getMessage()) . "
";
37 | }
38 | }
39 | }
40 |
41 | foreach ($uploadedImagePaths as $uploadedImagePath) {
42 | if (file_exists($uploadedImagePath)) {
43 | unlink($uploadedImagePath);
44 | }
45 | }
46 | }
47 | ?>
48 |
49 |
68 |
2 | user:
$message
";
8 |
9 | function getCurrentDateTimeTool(array $parameters = []): string
10 | {
11 | $time_zone = $parameters['time_zone'] ?? 'UTC';
12 | date_default_timezone_set($time_zone);
13 | return date('Y-m-d H:i:s') . " ($time_zone)";
14 | }
15 |
16 | function getCurrentWeatherTool(array $parameters = []): string
17 | {
18 | $location = $parameters['location'] ?? 'New York';
19 | return '30°C, sunny in ' . $location; // Simulation of weather data
20 | }
21 |
22 | $messages = [
23 | [
24 | 'role' => 'system',
25 | 'content' => 'You are a helpful AI assistant. Always answer in a concise manner. Execute the functions "getCurrentDateTimeTool" or "getCurrentWeatherTool" to answer the user correctly, if needed.'
26 | ],
27 | [
28 | 'role' => 'user',
29 | 'content' => $message
30 | ]
31 | ];
32 |
33 | $tools = [
34 | [
35 | "type" => "function",
36 | "function" => [
37 | "name" => "getCurrentDateTimeTool",
38 | "description" => "Get the current time in any format supported by PHP's date() function, considering the time zone.",
39 | "parameters" => [
40 | "type" => "object",
41 | "properties" => [
42 | "time_zone" => [
43 | "type" => "string",
44 | "description" => "Time zone for which to get the time."
45 | ],
46 | ],
47 | "required" => ["time_zone"],
48 | "default" => ["time_zone" => "UTC"]
49 | ],
50 | ]
51 | ],
52 | [
53 | "type" => "function",
54 | "function" => [
55 | "name" => "getCurrentWeatherTool",
56 | "description" => "Get the current weather in a specific location.",
57 | "parameters" => [
58 | "type" => "object",
59 | "properties" => [
60 | "location" => [
61 | "type" => "string",
62 | "description" => "Location for which to get the weather."
63 | ],
64 | ],
65 | "required" => ["location"],
66 | "default" => ["location" => "New York"]
67 | ],
68 | ]
69 | ]
70 | ];
71 |
72 | try {
73 | $response = $groq->chat()->completions()->create([
74 | 'model' => 'llama3-groq-70b-8192-tool-use-preview',
75 | 'messages' => $messages,
76 | "temperature" => 0,
77 | "tool_choice" => "auto",
78 | "tools" => $tools,
79 | "parallel_tool_calls" => false
80 | ]);
81 | } catch (\LucianoTonet\GroqPHP\GroqException $err) {
82 | echo $err->getCode() . "
" . $err->getMessage() . "
" . $err->getType() . "
";
83 | print_r($err->getHeaders());
84 | echo "assistant:
Sorry, I couldn't understand your request. Please try again.
";
85 | exit;
86 | }
87 |
88 | echo "" . $response['choices'][0]['message']['role'] . ":
";
89 |
90 | if (!empty($response['choices'][0]['message']['tool_calls'])) {
91 | foreach ($response['choices'][0]['message']['tool_calls'] as $tool_call) {
92 | if ($tool_call['function']['name']) {
93 | $function_args = json_decode($tool_call['function']['arguments'], true);
94 | echo "> Calling tool...
";
95 | $function_response = $tool_call['function']['name']($function_args);
96 | echo "> Building response...
";
97 |
98 | $messages[] = [
99 | 'tool_call_id' => $tool_call['id'],
100 | 'role' => 'tool',
101 | 'name' => $tool_call['function']['name'],
102 | 'content' => $function_response,
103 | ];
104 | }
105 | }
106 |
107 | try {
108 | $response = $groq->chat()->completions()->create([
109 | 'model' => 'llama3-groq-70b-8192-tool-use-preview',
110 | // 'model' => 'llama3-70b-8192',
111 | 'messages' => $messages
112 | ]);
113 | } catch (\LucianoTonet\GroqPHP\GroqException $err) {
114 | echo $err->getCode() . "
" . $err->getMessage() . "
" . $err->getType() . "
";
115 | print_r($err->getHeaders());
116 | echo "assistant:
Sorry, I couldn't understand your request. Please try again.
";
117 | exit;
118 | }
119 | }
120 |
121 | echo $response['choices'][0]['message']['content'] . "
";
122 | } else {
123 | echo "Ask questions like \"What time is it in UTC-3?\" or \"How is the weather in London?\".
Results will be simulated for demonstration purposes.
";
124 | }
125 | ?>
126 |
--------------------------------------------------------------------------------
/tests/ChatTest.php:
--------------------------------------------------------------------------------
1 | groq->chat()->completions()->create([
16 | 'model' => 'llama-3.1-8b-instant',
17 | 'messages' => [
18 | [
19 | 'role' => 'user',
20 | 'content' => 'Hello, how are you?'
21 | ]
22 | ]
23 | ]);
24 |
25 | $this->assertArrayHasKey('choices', $response);
26 | $this->assertNotEmpty($response['choices']);
27 | $this->assertArrayHasKey('message', $response['choices'][0]);
28 | $this->assertArrayHasKey('content', $response['choices'][0]['message']);
29 | $this->assertNotEmpty($response['choices'][0]['message']['content']);
30 | }
31 |
32 | /**
33 | * Testa o chat com streaming
34 | * @covers examples/chat-streaming.php
35 | */
36 | public function testStreamingChatCompletion()
37 | {
38 | $stream = $this->groq->chat()->completions()->create([
39 | 'model' => 'llama-3.1-8b-instant',
40 | 'messages' => [
41 | [
42 | 'role' => 'user',
43 | 'content' => 'Tell me a short story'
44 | ]
45 | ],
46 | 'stream' => true
47 | ]);
48 |
49 | $contentParts = [];
50 | $roleFound = false;
51 |
52 | foreach ($stream->chunks() as $chunk) {
53 | if (isset($chunk['choices'][0]['delta']['role'])) {
54 | $roleFound = true;
55 | $this->assertEquals('assistant', $chunk['choices'][0]['delta']['role']);
56 | }
57 |
58 | if (isset($chunk['choices'][0]['delta']['content'])) {
59 | $contentParts[] = $chunk['choices'][0]['delta']['content'];
60 | }
61 | }
62 |
63 | $this->assertTrue($roleFound, 'Role "assistant" should be present in stream');
64 | $this->assertNotEmpty($contentParts, 'Stream should contain content chunks');
65 |
66 | // Junta as partes para verificar se formam uma resposta coerente
67 | $fullContent = implode('', $contentParts);
68 | $this->assertNotEmpty($fullContent);
69 | }
70 |
71 | /**
72 | * Testa o modo JSON
73 | * @covers examples/json-mode.php
74 | */
75 | public function testJsonModeCompletion()
76 | {
77 | $response = $this->groq->chat()->completions()->create([
78 | 'model' => 'llama-3.1-8b-instant',
79 | 'messages' => [
80 | ['role' => 'system', 'content' => 'You are a JSON API. You must respond with valid JSON only.'],
81 | ['role' => 'user', 'content' => 'Return a simple JSON with: name="John", age=30']
82 | ],
83 | 'response_format' => ['type' => 'json_object']
84 | ]);
85 |
86 | $this->assertArrayHasKey('choices', $response);
87 | $this->assertArrayHasKey('message', $response['choices'][0]);
88 | $this->assertArrayHasKey('content', $response['choices'][0]['message']);
89 |
90 | // Verificar se o conteúdo é um JSON válido
91 | $content = $response['choices'][0]['message']['content'];
92 | $json = json_decode($content, true);
93 | $this->assertNotNull($json);
94 | $this->assertArrayHasKey('name', $json);
95 | $this->assertArrayHasKey('age', $json);
96 | $this->assertEquals('John', $json['name']);
97 | $this->assertEquals(30, $json['age']);
98 | }
99 |
100 | /**
101 | * Testa o tratamento de erros no chat básico
102 | */
103 | public function testBasicChatError()
104 | {
105 | $this->expectException(GroqException::class);
106 |
107 | $this->groq->chat()->completions()->create([
108 | 'model' => 'llama-3.1-8b-instant',
109 | 'messages' => [] // Mensagens vazias devem gerar erro
110 | ]);
111 | }
112 |
113 | /**
114 | * Testa o tratamento de erros no streaming
115 | */
116 | public function testStreamingError()
117 | {
118 | $this->expectException(GroqException::class);
119 |
120 | $stream = $this->groq->chat()->completions()->create([
121 | 'model' => 'invalid-model',
122 | 'messages' => [
123 | ['role' => 'user', 'content' => 'Hello']
124 | ],
125 | 'stream' => true
126 | ]);
127 |
128 | iterator_to_array($stream->chunks()); // Força a execução do stream
129 | }
130 |
131 | /**
132 | * Testa o controle de buffer no streaming
133 | */
134 | public function testStreamingBufferControl()
135 | {
136 | $stream = $this->groq->chat()->completions()->create([
137 | 'model' => 'llama-3.1-8b-instant',
138 | 'messages' => [
139 | ['role' => 'user', 'content' => 'Count from 1 to 5']
140 | ],
141 | 'stream' => true
142 | ]);
143 |
144 | $chunks = [];
145 | $fullContent = '';
146 |
147 | foreach ($stream->chunks() as $chunk) {
148 | $chunks[] = $chunk;
149 | if (isset($chunk['choices'][0]['delta']['content'])) {
150 | $fullContent .= $chunk['choices'][0]['delta']['content'];
151 | }
152 | }
153 |
154 | // Verifica se recebemos chunks
155 | $this->assertNotEmpty($chunks);
156 |
157 | // Verifica a estrutura de cada chunk
158 | foreach ($chunks as $chunk) {
159 | $this->assertArrayHasKey('choices', $chunk);
160 | $this->assertArrayHasKey(0, $chunk['choices']);
161 | $this->assertArrayHasKey('delta', $chunk['choices'][0]);
162 | }
163 |
164 | // Verifica o conteúdo completo montado
165 | $this->assertStringContainsString('1', $fullContent);
166 | $this->assertStringContainsString('5', $fullContent);
167 |
168 | // Verifica se o último chunk indica fim do stream
169 | $lastChunk = end($chunks);
170 | $this->assertArrayHasKey('finish_reason', $lastChunk['choices'][0]);
171 | $this->assertEquals('stop', $lastChunk['choices'][0]['finish_reason']);
172 | }
173 | }
--------------------------------------------------------------------------------
/examples/tool-calling.php:
--------------------------------------------------------------------------------
1 |
2 | user:
";
9 | echo "$message
";
10 |
11 | function getNbaScore($teamName)
12 | {
13 | // Example dummy function hard coded to return the score of an NBA game
14 | if (strpos(strtolower($teamName), 'warriors') !== false) {
15 | return json_encode([
16 | "game_id" => "401585601",
17 | "status" => 'Final',
18 | "home_team" => "Los Angeles Lakers",
19 | "home_team_score" => 121,
20 | "away_team" => "Golden State Warriors",
21 | "away_team_score" => 128
22 | ]);
23 | } elseif (strpos(strtolower($teamName), 'lakers') !== false) {
24 | return json_encode([
25 | "game_id" => "401585601",
26 | "status" => 'Final',
27 | "home_team" => "Los Angeles Lakers",
28 | "home_team_score" => 121,
29 | "away_team" => "Golden State Warriors",
30 | "away_team_score" => 128
31 | ]);
32 | } elseif (strpos(strtolower($teamName), 'nuggets') !== false) {
33 | return json_encode([
34 | "game_id" => "401585577",
35 | "status" => 'Final',
36 | "home_team" => "Miami Heat",
37 | "home_team_score" => 88,
38 | "away_team" => "Denver Nuggets",
39 | "away_team_score" => 100
40 | ]);
41 | } elseif (strpos(strtolower($teamName), 'heat') !== false) {
42 | return json_encode([
43 | "game_id" => "401585577",
44 | "status" => 'Final',
45 | "home_team" => "Miami Heat",
46 | "home_team_score" => 88,
47 | "away_team" => "Denver Nuggets",
48 | "away_team_score" => 100
49 | ]);
50 | } else {
51 | return json_encode([
52 | "team_name" => $teamName,
53 | "score" => "unknown"
54 | ]);
55 | }
56 | }
57 |
58 | $messages = [
59 | [
60 | 'role' => 'system',
61 | 'content' => "You shall call the function 'getNbaScore' to answer questions around NBA game scores. Include the team and their opponent in your response."
62 | ],
63 | [
64 | 'role' => 'user',
65 | 'content' => $message
66 | ]
67 | ];
68 |
69 | $tools = [
70 | [
71 | 'type' => 'function',
72 | 'function' => [
73 | 'name' => 'getNbaScore',
74 | 'description' => 'Get the score for a given NBA game',
75 | 'parameters' => [
76 | 'type' => 'object',
77 | 'properties' => [
78 | "team_name" => [
79 | "type" => "string",
80 | "description" => "The name of the NBA team (e.g. 'Golden State Warriors')",
81 | ]
82 | ],
83 | "required" => ["team_name"],
84 | ],
85 | ],
86 | ]
87 | ];
88 |
89 | try {
90 | $response = $groq->chat()->completions()->create([
91 | 'model' => 'llama3-groq-70b-8192-tool-use-preview',
92 | // 'model' => 'llama3-70b-8192',
93 | 'messages' => $messages,
94 | "tool_choice" => "auto",
95 | "tools" => $tools
96 | ]);
97 | } catch (\LucianoTonet\GroqPHP\GroqException $err) {
98 | echo $err->getCode() . "
" . $err->getMessage() . "
" . $err->getType() . "
";
99 | print_r($err->getHeaders());
100 | echo "assistant:
Desculpe, não consegui entender sua solicitação. Tente novamente.
";
101 | exit;
102 | }
103 |
104 | echo "assistant: " . "
";
105 |
106 | if (isset($response['choices'][0]['message']['tool_calls'])) {
107 | $tool_calls = $response['choices'][0]['message']['tool_calls'];
108 | foreach ($tool_calls as $tool_call) {
109 | if ($tool_call['function']['name'] == 'getNbaScore') {
110 | $function_args = json_decode($tool_call['function']['arguments'], true);
111 |
112 | echo "> Calling tool..." . "
";
113 |
114 | $function_response = getNbaScore($function_args['team_name']);
115 |
116 | echo "> Building response..." . "
";
117 |
118 | $messages[] = [
119 | 'tool_call_id' => $tool_call['id'],
120 | 'role' => 'tool',
121 | 'name' => 'getNbaScore',
122 | 'content' => $function_response,
123 | ];
124 | }
125 | }
126 |
127 | try {
128 | $response = $groq->chat()->completions()->create([
129 | 'model' => 'llama3-groq-70b-8192-tool-use-preview',
130 | // 'model' => 'llama3-70b-8192',
131 | 'messages' => $messages
132 | ]);
133 | } catch (\LucianoTonet\GroqPHP\GroqException $err) {
134 | echo $err->getCode() . "
" . $err->getMessage() . "
" . $err->getType() . "
";
135 | print_r($err->getHeaders());
136 | echo "assistant:
Desculpe, não consegui entender sua solicitação. Tente novamente.
";
137 | exit;
138 | }
139 | }
140 |
141 | echo "" . $response['choices'][0]['message']['role'] . ": " . "
";
142 | echo $response['choices'][0]['message']['content'] . "
";
143 | } else {
144 | echo "Ask about NBA game scores.
Results will be mocked for demo purposes.
";
145 | }
146 | ?>
147 |
--------------------------------------------------------------------------------
/tests/GroqTest.php:
--------------------------------------------------------------------------------
1 | load();
17 | $this->groq = new Groq($_ENV['GROQ_API_KEY']);
18 | }
19 |
20 | public function testInvalidApiKey()
21 | {
22 | $groq = new Groq('invalid_api_key');
23 |
24 | $this->expectException(GroqException::class);
25 | $this->expectExceptionCode(0); // Error code will be 0 for invalid API keys
26 | $this->expectExceptionMessage('Invalid API Key'); // Error message will be 'Invalid API Key'
27 |
28 | $groq->chat()->completions()->create([
29 | 'model' => 'llama3-70b-8192',
30 | 'messages' => [
31 | ['role' => 'user', 'content' => 'Hello, world!'],
32 | ],
33 | ]);
34 | }
35 |
36 | public function testListModels()
37 | {
38 | $models = $this->groq->models()->list();
39 |
40 | $this->assertIsArray($models);
41 | $this->assertNotEmpty($models);
42 | $this->assertArrayHasKey('data', $models); // Verify that the 'data' key is present
43 | }
44 |
45 | public function testChatCompletionWithValidApiKey()
46 | {
47 | $response = $this->groq->chat()->completions()->create([
48 | 'model' => 'llama3-70b-8192',
49 | 'messages' => [
50 | ['role' => 'user', 'content' => 'Hello, world!'],
51 | ],
52 | ]);
53 |
54 | $this->assertArrayHasKey('choices', $response);
55 | $this->assertNotEmpty($response['choices']);
56 | $this->assertArrayHasKey('message', $response['choices'][0]);
57 | $this->assertArrayHasKey('content', $response['choices'][0]['message']);
58 | }
59 |
60 | // public function testAudioTranscription()
61 | // {
62 | // $audioFile = __DIR__ . '/test_audio.mp3';
63 | // $response = $this->groq->audio()->transcriptions()->create([
64 | // 'file' => $audioFile,
65 | // 'model' => 'whisper-large-v3',
66 | // 'response_format' => 'json',
67 | // ]);
68 |
69 | // $this->assertArrayHasKey('text', $response);
70 | // $this->assertNotEmpty($response['text']);
71 | // }
72 |
73 | // public function testAudioTranslation()
74 | // {
75 | // $audioFile = __DIR__ . '/test_audio.mp3';
76 | // $response = $this->groq->audio()->translations()->create([
77 | // 'file' => $audioFile,
78 | // 'model' => 'whisper-large-v3',
79 | // 'response_format' => 'json',
80 | // ]);
81 |
82 | // $this->assertArrayHasKey('text', $response);
83 | // $this->assertNotEmpty($response['text']);
84 | // }
85 |
86 | public function testSetOptions()
87 | {
88 | // Setup
89 | $initialApiKey = $_ENV['GROQ_API_KEY'];
90 | $groq = new Groq($initialApiKey);
91 |
92 | // Test setting new options
93 | $newOptions = [
94 | 'apiKey' => 'new_test_key',
95 | 'baseUrl' => 'https://test-api.groq.com',
96 | 'timeout' => 30000,
97 | 'maxRetries' => 3,
98 | 'headers' => ['X-Custom-Header' => 'test'],
99 | 'proxy' => 'http://proxy.test',
100 | 'verify' => false,
101 | 'debug' => true,
102 | 'stream' => true,
103 | 'responseFormat' => 'json'
104 | ];
105 |
106 | $groq->setOptions($newOptions);
107 |
108 | // Verify API key was updated
109 | $this->assertEquals('new_test_key', $groq->apiKey());
110 |
111 | // Get actual options
112 | $actualOptions = $groq->options;
113 |
114 | // Verify all options were set correctly
115 | $this->assertEquals($newOptions['baseUrl'], $groq->baseUrl);
116 | $this->assertEquals($newOptions['timeout'], $actualOptions['timeout']);
117 | $this->assertEquals($newOptions['maxRetries'], $actualOptions['maxRetries']);
118 | $this->assertEquals($newOptions['headers'], $actualOptions['headers']);
119 | $this->assertEquals($newOptions['proxy'], $actualOptions['proxy']);
120 | $this->assertEquals($newOptions['verify'], $actualOptions['verify']);
121 | $this->assertEquals($newOptions['debug'], $actualOptions['debug']);
122 | $this->assertEquals($newOptions['stream'], $actualOptions['stream']);
123 | $this->assertEquals($newOptions['responseFormat'], $actualOptions['responseFormat']);
124 | }
125 |
126 | public function testSetOptionsPartial()
127 | {
128 | // Setup - usar uma chave fixa para teste em vez da variável de ambiente
129 | $mockApiKey = 'test-api-key-' . uniqid();
130 | $groq = new Groq($mockApiKey, ['timeout' => 10000]);
131 |
132 | // Test setting only some options
133 | $newOptions = [
134 | 'timeout' => 20000,
135 | 'debug' => true
136 | ];
137 |
138 | $groq->setOptions($newOptions);
139 |
140 | // Create a reflection class to access private properties
141 | $reflection = new \ReflectionClass($groq);
142 | $optionsProperty = $reflection->getProperty('options');
143 | $optionsProperty->setAccessible(true);
144 |
145 | // Get actual options
146 | $actualOptions = $optionsProperty->getValue($groq);
147 |
148 | // Verify specific options were updated
149 | $this->assertEquals(20000, $actualOptions['timeout']);
150 | $this->assertEquals(true, $actualOptions['debug']);
151 |
152 | // Verify API key remained unchanged
153 | $this->assertEquals($mockApiKey, $groq->apiKey());
154 | }
155 | }
156 |
--------------------------------------------------------------------------------
/src/Batch.php:
--------------------------------------------------------------------------------
1 | validateRequiredFields($data);
41 | $this->validateStatus($data['status']);
42 | $this->validateEndpoint($data['endpoint']);
43 | $this->validateCompletionWindow($data['completion_window']);
44 |
45 | $this->data = $data;
46 | }
47 |
48 | /**
49 | * Checks if the batch is in a terminal state
50 | */
51 | public function isCompleted(): bool
52 | {
53 | return in_array($this->status, ['completed', 'failed', 'expired', 'cancelled']);
54 | }
55 |
56 | /**
57 | * Checks if the batch is still processing
58 | */
59 | public function isProcessing(): bool
60 | {
61 | return in_array($this->status, ['validating', 'in_progress', 'finalizing']);
62 | }
63 |
64 | /**
65 | * Gets the progress percentage of the batch
66 | */
67 | public function getProgress(): float
68 | {
69 | if (!isset($this->data['request_counts'])) {
70 | return 0.0;
71 | }
72 |
73 | $counts = $this->data['request_counts'];
74 | $total = $counts['total'] ?? 0;
75 |
76 | if ($total === 0) {
77 | return 0.0;
78 | }
79 |
80 | $completed = $counts['completed'] ?? 0;
81 | return round(($completed / $total) * 100, 2);
82 | }
83 |
84 | /**
85 | * Gets the error count for the batch
86 | */
87 | public function getErrorCount(): int
88 | {
89 | return $this->data['request_counts']['failed'] ?? 0;
90 | }
91 |
92 | /**
93 | * Gets the completion time in seconds
94 | */
95 | public function getCompletionTime(): ?float
96 | {
97 | if (!isset($this->data['completed_at']) || !isset($this->data['created_at'])) {
98 | return null;
99 | }
100 |
101 | return $this->data['completed_at'] - $this->data['created_at'];
102 | }
103 |
104 | /**
105 | * Gets the remaining time before expiration in seconds
106 | */
107 | public function getTimeRemaining(): ?float
108 | {
109 | if (!isset($this->data['expires_at'])) {
110 | return null;
111 | }
112 |
113 | $now = time();
114 | $expiresAt = $this->data['expires_at'];
115 |
116 | if ($expiresAt <= $now) {
117 | return 0.0;
118 | }
119 |
120 | return $expiresAt - $now;
121 | }
122 |
123 | private function validateRequiredFields(array $data): void
124 | {
125 | foreach ($this->requiredFields as $field) {
126 | if (!isset($data[$field])) {
127 | throw new GroqException(
128 | "Missing required field: {$field}",
129 | 400,
130 | 'invalid_request'
131 | );
132 | }
133 | }
134 | }
135 |
136 | private function validateStatus(string $status): void
137 | {
138 | if (!in_array($status, $this->validStatuses)) {
139 | throw new GroqException(
140 | "Invalid batch status: {$status}. Valid statuses are: " . implode(', ', $this->validStatuses),
141 | 400,
142 | 'invalid_request'
143 | );
144 | }
145 | }
146 |
147 | private function validateEndpoint(string $endpoint): void
148 | {
149 | if (!in_array($endpoint, $this->validEndpoints)) {
150 | throw new GroqException(
151 | 'Invalid endpoint. Only /v1/chat/completions is supported',
152 | 400,
153 | 'invalid_request'
154 | );
155 | }
156 | }
157 |
158 | private function validateCompletionWindow(string $window): void
159 | {
160 | if (!in_array($window, $this->validCompletionWindows)) {
161 | throw new GroqException(
162 | 'Invalid completion_window. Valid windows are: ' . implode(', ', $this->validCompletionWindows),
163 | 400,
164 | 'invalid_request'
165 | );
166 | }
167 | }
168 |
169 | public function __get(string $name)
170 | {
171 | return $this->data[$name] ?? null;
172 | }
173 |
174 | public function toArray(): array
175 | {
176 | return $this->data;
177 | }
178 |
179 | /**
180 | * Gets a summary of the batch status
181 | */
182 | public function getSummary(): array
183 | {
184 | return [
185 | 'id' => $this->id,
186 | 'status' => $this->status,
187 | 'progress' => $this->getProgress(),
188 | 'error_count' => $this->getErrorCount(),
189 | 'completion_time' => $this->getCompletionTime(),
190 | 'time_remaining' => $this->getTimeRemaining(),
191 | 'request_counts' => $this->data['request_counts'] ?? [
192 | 'total' => 0,
193 | 'completed' => 0,
194 | 'failed' => 0
195 | ],
196 | 'created_at' => $this->data['created_at'],
197 | 'completed_at' => $this->data['completed_at'] ?? null,
198 | 'expires_at' => $this->data['expires_at'] ?? null
199 | ];
200 | }
201 | }
--------------------------------------------------------------------------------
/tests/FileManagerTest.php:
--------------------------------------------------------------------------------
1 | testJsonlPath = __DIR__ . '/fixtures/batch_file.jsonl';
18 | $this->testInvalidJsonlPath = __DIR__ . '/fixtures/batch_file_invalid.jsonl';
19 | }
20 |
21 | public function testUploadFile()
22 | {
23 | $file = $this->groq->files()->upload($this->testJsonlPath, 'batch');
24 |
25 | $this->assertNotEmpty($file->id);
26 | $this->assertEquals('batch', $file->purpose);
27 | $this->assertNotEmpty($file->filename);
28 |
29 | // Limpar arquivo criado
30 | $this->groq->files()->delete($file->id);
31 | }
32 |
33 | public function testListFiles()
34 | {
35 | $files = $this->groq->files()->list('batch', ['limit' => 10]);
36 |
37 | $this->assertArrayHasKey('data', $files);
38 | $this->assertIsArray($files['data']);
39 | }
40 |
41 | public function testInvalidFileUpload()
42 | {
43 | $this->expectException(GroqException::class);
44 | $this->expectExceptionMessage('File not found');
45 | $this->groq->files()->upload('/path/to/nonexistent.jsonl', 'batch');
46 | }
47 |
48 | public function testInvalidJsonlFormat()
49 | {
50 | $this->expectException(GroqException::class);
51 | $this->expectExceptionMessage('Missing or invalid \'body\' field');
52 | $this->groq->files()->upload($this->testInvalidJsonlPath, 'batch');
53 | }
54 |
55 | public function testEmptyFile()
56 | {
57 | $emptyFile = sys_get_temp_dir() . '/empty.jsonl';
58 | file_put_contents($emptyFile, '');
59 |
60 | try {
61 | $this->expectException(GroqException::class);
62 | $this->expectExceptionMessage('File is empty');
63 | $this->groq->files()->upload($emptyFile, 'batch');
64 | } finally {
65 | unlink($emptyFile);
66 | }
67 | }
68 |
69 | public function testInvalidPurpose()
70 | {
71 | $this->expectException(GroqException::class);
72 | $this->expectExceptionMessage('Invalid purpose. Only "batch" is supported');
73 | $this->groq->files()->upload($this->testJsonlPath, 'jsonl');
74 | }
75 |
76 | public function testInvalidEndpoint()
77 | {
78 | $invalidEndpointFile = sys_get_temp_dir() . '/invalid_endpoint.jsonl';
79 | $content = json_encode([
80 | 'custom_id' => 'test-1',
81 | 'method' => 'POST',
82 | 'url' => '/v1/invalid/endpoint',
83 | 'body' => [
84 | 'model' => 'llama3-8b-8192',
85 | 'messages' => [['role' => 'user', 'content' => 'test']]
86 | ]
87 | ]) . "\n";
88 |
89 | file_put_contents($invalidEndpointFile, $content);
90 |
91 | try {
92 | $this->expectException(GroqException::class);
93 | $this->expectExceptionMessage('Invalid endpoint');
94 | $this->groq->files()->upload($invalidEndpointFile, 'batch');
95 | } finally {
96 | unlink($invalidEndpointFile);
97 | }
98 | }
99 |
100 | public function testInvalidAudioRequest()
101 | {
102 | $invalidAudioFile = sys_get_temp_dir() . '/invalid_audio.jsonl';
103 | $content = json_encode([
104 | 'custom_id' => 'audio-1',
105 | 'method' => 'POST',
106 | 'url' => '/v1/audio/transcriptions',
107 | 'body' => [
108 | 'model' => 'whisper-large-v3',
109 | 'url' => 'not-a-valid-url'
110 | ]
111 | ]) . "\n";
112 |
113 | file_put_contents($invalidAudioFile, $content);
114 |
115 | try {
116 | $this->expectException(GroqException::class);
117 | $this->expectExceptionMessage('Missing or invalid audio \'url\' field');
118 | $this->groq->files()->upload($invalidAudioFile, 'batch');
119 | } finally {
120 | unlink($invalidAudioFile);
121 | }
122 | }
123 |
124 | public function testMissingLanguageInAudioRequest()
125 | {
126 | $invalidAudioFile = sys_get_temp_dir() . '/missing_language.jsonl';
127 | $content = json_encode([
128 | 'custom_id' => 'audio-1',
129 | 'method' => 'POST',
130 | 'url' => '/v1/audio/transcriptions',
131 | 'body' => [
132 | 'model' => 'whisper-large-v3',
133 | 'url' => 'https://example.com/audio.wav'
134 | ]
135 | ]) . "\n";
136 |
137 | file_put_contents($invalidAudioFile, $content);
138 |
139 | try {
140 | $this->expectException(GroqException::class);
141 | $this->expectExceptionMessage('Missing required field \'language\'');
142 | $this->groq->files()->upload($invalidAudioFile, 'batch');
143 | } finally {
144 | unlink($invalidAudioFile);
145 | }
146 | }
147 |
148 | public function testInvalidMessagesFormat()
149 | {
150 | $invalidMessagesFile = sys_get_temp_dir() . '/invalid_messages.jsonl';
151 | $content = json_encode([
152 | 'custom_id' => 'chat-1',
153 | 'method' => 'POST',
154 | 'url' => '/v1/chat/completions',
155 | 'body' => [
156 | 'model' => 'llama3-8b-8192',
157 | 'messages' => [
158 | ['invalid_field' => 'test'] // Missing role and content
159 | ]
160 | ]
161 | ]) . "\n";
162 |
163 | file_put_contents($invalidMessagesFile, $content);
164 |
165 | try {
166 | $this->expectException(GroqException::class);
167 | $this->expectExceptionMessage('Message at index 0 is missing required fields');
168 | $this->groq->files()->upload($invalidMessagesFile, 'batch');
169 | } finally {
170 | unlink($invalidMessagesFile);
171 | }
172 | }
173 | }
--------------------------------------------------------------------------------
/src/File.php:
--------------------------------------------------------------------------------
1 | validateRequiredFields($data);
30 | $this->validatePurpose($data['purpose']);
31 |
32 | if (!isset($data['status'])) {
33 | $data['status'] = 'uploaded';
34 | } else {
35 | $this->validateStatus($data['status']);
36 | }
37 |
38 | $this->data = $data;
39 | }
40 |
41 | /**
42 | * Checks if the file is ready for use
43 | */
44 | public function isReady(): bool
45 | {
46 | return $this->status === 'processed';
47 | }
48 |
49 | /**
50 | * Checks if the file has failed processing
51 | */
52 | public function hasFailed(): bool
53 | {
54 | return in_array($this->status, ['failed', 'error']);
55 | }
56 |
57 | /**
58 | * Checks if the file is still being processed
59 | */
60 | public function isProcessing(): bool
61 | {
62 | return $this->status === 'processing';
63 | }
64 |
65 | /**
66 | * Gets the file size in bytes
67 | */
68 | public function getSize(): int
69 | {
70 | return $this->bytes;
71 | }
72 |
73 | /**
74 | * Gets the file size in a human-readable format
75 | */
76 | public function getFormattedSize(): string
77 | {
78 | $bytes = $this->bytes;
79 | $units = ['B', 'KB', 'MB', 'GB'];
80 | $factor = floor((strlen((string) $bytes) - 1) / 3);
81 |
82 | return sprintf("%.2f %s", $bytes / pow(1024, $factor), $units[$factor]);
83 | }
84 |
85 | /**
86 | * Gets the file creation time as a DateTime object
87 | */
88 | public function getCreatedAt(): \DateTime
89 | {
90 | return new \DateTime('@' . $this->created_at);
91 | }
92 |
93 | /**
94 | * Gets the time elapsed since file creation
95 | */
96 | public function getTimeElapsed(): string
97 | {
98 | $now = time();
99 | $elapsed = $now - $this->created_at;
100 |
101 | if ($elapsed < 60) {
102 | return "{$elapsed} seconds ago";
103 | }
104 |
105 | if ($elapsed < 3600) {
106 | $minutes = floor($elapsed / 60);
107 | return "{$minutes} minute" . ($minutes > 1 ? 's' : '') . " ago";
108 | }
109 |
110 | if ($elapsed < 86400) {
111 | $hours = floor($elapsed / 3600);
112 | return "{$hours} hour" . ($hours > 1 ? 's' : '') . " ago";
113 | }
114 |
115 | $days = floor($elapsed / 86400);
116 | return "{$days} day" . ($days > 1 ? 's' : '') . " ago";
117 | }
118 |
119 | /**
120 | * Gets the file extension
121 | */
122 | public function getExtension(): string
123 | {
124 | return pathinfo($this->filename, PATHINFO_EXTENSION);
125 | }
126 |
127 | /**
128 | * Gets the file name without extension
129 | */
130 | public function getBaseName(): string
131 | {
132 | return pathinfo($this->filename, PATHINFO_FILENAME);
133 | }
134 |
135 | private function validateRequiredFields(array $data): void
136 | {
137 | foreach ($this->requiredFields as $field) {
138 | if (!isset($data[$field])) {
139 | throw new GroqException(
140 | "Missing required field: {$field}",
141 | 400,
142 | 'invalid_request'
143 | );
144 | }
145 | }
146 |
147 | if (!is_int($data['bytes']) || $data['bytes'] < 0) {
148 | throw new GroqException(
149 | 'Invalid bytes value. Must be a non-negative integer.',
150 | 400,
151 | 'invalid_request'
152 | );
153 | }
154 |
155 | if (!is_int($data['created_at']) || $data['created_at'] <= 0) {
156 | throw new GroqException(
157 | 'Invalid created_at value. Must be a positive integer timestamp.',
158 | 400,
159 | 'invalid_request'
160 | );
161 | }
162 | }
163 |
164 | private function validateStatus(string $status): void
165 | {
166 | if (!in_array($status, $this->validStatuses)) {
167 | throw new GroqException(
168 | "Invalid file status: {$status}. Valid statuses are: " . implode(', ', $this->validStatuses),
169 | 400,
170 | 'invalid_request'
171 | );
172 | }
173 | }
174 |
175 | private function validatePurpose(string $purpose): void
176 | {
177 | if (!in_array($purpose, $this->validPurposes)) {
178 | throw new GroqException(
179 | "Invalid file purpose: {$purpose}. Only 'batch' is supported.",
180 | 400,
181 | 'invalid_request'
182 | );
183 | }
184 | }
185 |
186 | public function __get(string $name)
187 | {
188 | return $this->data[$name] ?? null;
189 | }
190 |
191 | public function toArray(): array
192 | {
193 | return $this->data;
194 | }
195 |
196 | /**
197 | * Gets a summary of the file
198 | */
199 | public function getSummary(): array
200 | {
201 | return [
202 | 'id' => $this->id,
203 | 'filename' => $this->filename,
204 | 'size' => $this->getFormattedSize(),
205 | 'status' => $this->status,
206 | 'purpose' => $this->purpose,
207 | 'created' => $this->getTimeElapsed(),
208 | 'extension' => $this->getExtension(),
209 | 'is_ready' => $this->isReady(),
210 | 'has_failed' => $this->hasFailed()
211 | ];
212 | }
213 | }
--------------------------------------------------------------------------------
/examples/reasoning.php:
--------------------------------------------------------------------------------
1 |
2 | $_POST['model'] ?? 'deepseek-r1-distill-llama-70b',
9 | 'temperature' => isset($_POST['temperature']) ? floatval($_POST['temperature']) : null,
10 | 'max_completion_tokens' => isset($_POST['max_completion_tokens']) ? intval($_POST['max_completion_tokens']) : null,
11 | 'top_p' => isset($_POST['top_p']) ? floatval($_POST['top_p']) : null,
12 | 'frequency_penalty' => isset($_POST['frequency_penalty']) ? floatval($_POST['frequency_penalty']) : null,
13 | 'presence_penalty' => isset($_POST['presence_penalty']) ? floatval($_POST['presence_penalty']) : null,
14 | 'reasoning_format' => $_POST['reasoning_format'] ?? 'raw'
15 | ];
16 |
17 | // Remove undefined options
18 | $options = array_filter($options, fn($value) => !is_null($value));
19 |
20 | // Add system prompt if provided
21 | if (!empty($_POST['system_prompt'])) {
22 | $options['system_prompt'] = $_POST['system_prompt'];
23 | }
24 |
25 | echo "
Prompt: " . htmlspecialchars($prompt) . "
";
26 |
27 | try {
28 | $response = $groq->reasoning()->analyze($prompt, $options);
29 |
30 | $content = $response['choices'][0]['message']['content'];
31 |
32 | if ($options['reasoning_format'] == 'parsed' && isset($response['choices'][0]['message']['reasoning'])) {
33 | $reasoning = $response['choices'][0]['message']['reasoning'];
34 | echo "
Reasoning:
";
35 | echo "
";
36 | echo '
';
37 | echo nl2br($reasoning);
38 | echo '
';
39 | echo "
";
40 | } else {
41 | $content = preg_replace(
42 | '/(
.*?<\/think>)/s',
43 | '<think>$1</think>',
44 | $content
45 | );
46 | }
47 |
48 | echo "Answer:
";
49 | echo nl2br($content);
50 | echo "Error: " . htmlspecialchars($err->getMessage()) . "
";
53 | }
54 | }
55 | ?>
56 |
57 |
116 |
--------------------------------------------------------------------------------
/src/Translations.php:
--------------------------------------------------------------------------------
1 | groq = $groq;
30 | }
31 |
32 | /**
33 | * Translation Usage
34 | * This method translates spoken words in audio or video files to the specified language.
35 | *
36 | * Optional Parameters:
37 | * - prompt: Provides context or specifies the spelling of unknown words.
38 | * - response_format: Defines the format of the response. The default is "json".
39 | * Use "verbose_json" to receive timestamps for audio segments.
40 | * Use "text" to return a text response.
41 | * vtt and srt formats are not supported.
42 | * - temperature: Specifies a value between 0 and 1 to control the variability of the translation output.
43 | *
44 | * @param array $params
45 | * @return array|string|Stream
46 | * @throws \InvalidArgumentException
47 | */
48 | public function create(array $params): array|string|Stream
49 | {
50 | $this->validateParams($params);
51 | $client = new Client();
52 | $multipart = $this->buildMultipart($params);
53 |
54 | try {
55 | $response = $client->request('POST', $this->groq->baseUrl() . '/audio/translations', [
56 | 'headers' => [
57 | 'Authorization' => 'Bearer ' . $this->groq->apiKey()
58 | ],
59 | 'multipart' => $multipart
60 | ]);
61 |
62 | return $this->handleResponse($response, $params['response_format'] ?? 'json');
63 | } catch (GuzzleException $e) {
64 | if ($e instanceof RequestException && $e->hasResponse()) {
65 | $responseBody = $e->getResponse()->getBody();
66 | $responseBodyString = $responseBody ? (string) $responseBody : 'Response body is empty or null';
67 | if (trim($responseBodyString) === '') {
68 | $responseBodyString = 'Response body is empty or null';
69 | }
70 | throw GroqException::createFromResponse($e->getResponse());
71 | } else {
72 | throw new GroqException('Unexpected error while creating translations: ' . $e->getMessage(), $e->getCode(), 'UnexpectedException', []);
73 | }
74 | }
75 | }
76 |
77 | /**
78 | * Validates the input parameters.
79 | *
80 | * @param array $params
81 | * @throws \InvalidArgumentException
82 | */
83 | private function validateParams(array $params): void
84 | {
85 | if (empty($params['file'])) {
86 | throw new \InvalidArgumentException('The "file" parameter is required.');
87 | }
88 | if (!file_exists($params['file'])) {
89 | throw new \InvalidArgumentException('The specified file does not exist.');
90 | }
91 | }
92 |
93 | /**
94 | * Builds the multipart structure for the request.
95 | *
96 | * @param array $params
97 | * @return array
98 | */
99 | private function buildMultipart(array $params): array
100 | {
101 | $multipart = [
102 | [
103 | 'name' => 'file',
104 | 'contents' => fopen($params['file'], 'r')
105 | ],
106 | [
107 | 'name' => 'model',
108 | 'contents' => $params['model'] ?? 'whisper-large-v3'
109 | ],
110 | [
111 | 'name' => 'temperature',
112 | 'contents' => $params['temperature'] ?? 0.0
113 | ],
114 | ];
115 |
116 | if (!empty($params['prompt'])) {
117 | $multipart[] = [
118 | 'name' => 'prompt',
119 | 'contents' => $params['prompt']
120 | ];
121 | }
122 |
123 | if (!empty($params['response_format'])) {
124 | $multipart[] = [
125 | 'name' => 'response_format',
126 | 'contents' => $params['response_format']
127 | ];
128 | }
129 |
130 | return $multipart;
131 | }
132 |
133 | /**
134 | * Handles the response of the request.
135 | *
136 | * @param ResponseInterface $response
137 | * @param string $responseFormat
138 | * @return array|string|Stream
139 | */
140 | private function handleResponse(ResponseInterface $response, string $responseFormat): array|string|Stream
141 | {
142 | $body = $response->getBody()->getContents();
143 |
144 | if ($responseFormat === 'text') {
145 | return $body; // Returns the body of the response directly
146 | }
147 |
148 | $data = json_decode($body, true);
149 |
150 | if (json_last_error() !== JSON_ERROR_NONE) {
151 | throw new GroqException('Error decoding the JSON response: ' . json_last_error_msg(), 0, 'JsonDecodeError');
152 | }
153 |
154 | return $data;
155 | }
156 |
157 | /**
158 | * Streams the response from the request.
159 | *
160 | * @param Request $request
161 | * @param array $options
162 | * @return Stream
163 | */
164 | private function streamResponse(Request $request, array $options): Stream
165 | {
166 | try {
167 | $client = new Client();
168 | $response = $client->send($request, array_merge($options, ['stream' => true]));
169 | return new Stream($response);
170 | } catch (RequestException $e) {
171 | $responseBody = $e->getResponse() ? $e->getResponse()->getBody() : null;
172 | $responseBodyString = $responseBody ? (string) $responseBody : 'No response body available';
173 | throw new GroqException('Failed to stream the response: ' . $responseBodyString, $e->getCode(), 'RequestException', []);
174 | } catch (GuzzleException $e) {
175 | throw new GroqException('An unexpected error occurred: ' . $e->getMessage(), $e->getCode(), 'UnexpectedException', []);
176 | }
177 | }
178 | }
179 |
--------------------------------------------------------------------------------
/examples/audio-transcriptions.php:
--------------------------------------------------------------------------------
1 |
128 |
129 | $newFilePath,
140 | 'model' => 'whisper-large-v3',
141 | 'response_format' => $_POST['response_format'] ?? 'json',
142 | 'temperature' => $_POST['temperature'] ?? 0.0,
143 | ];
144 |
145 | if (isset($_POST['language'])) {
146 | $transcriptionParams['language'] = $_POST['language'] ?? 'en';
147 | }
148 |
149 | if (isset($_POST['prompt'])) {
150 | $transcriptionParams['prompt'] = $_POST['prompt'];
151 | }
152 |
153 | $transcription = $groq->audio()->transcriptions()->create($transcriptionParams);
154 |
155 | if ($_POST['response_format'] === 'verbose_json') {
156 | // Aqui você pode processar a transcrição para incluir timestamps, se necessário
157 | echo '';
158 | echo json_encode($transcription, JSON_UNESCAPED_UNICODE | JSON_PRETTY_PRINT);
159 | echo '
';
160 | } elseif ($_POST['response_format'] === 'text') {
161 | // Retorna apenas o texto da transcrição
162 | echo '';
163 | echo $transcription ?? '';
164 | echo '
';
165 | } else {
166 | // Formato padrão é json
167 | echo '';
168 | echo json_encode($transcription, JSON_UNESCAPED_UNICODE | JSON_PRETTY_PRINT);
169 | echo '
';
170 | }
171 | } catch (LucianoTonet\GroqPHP\GroqException $e) {
172 | echo "Error:
" . htmlspecialchars($e->getMessage()) . "
";
173 | } finally {
174 | if (file_exists($newFilePath)) {
175 | unlink($newFilePath);
176 | }
177 | }
178 | }
--------------------------------------------------------------------------------
/examples/files.php:
--------------------------------------------------------------------------------
1 | files()->delete($fileId);
11 | if ($result['deleted']) {
12 | $success = "File deleted successfully.";
13 | }
14 | break;
15 |
16 | case 'download':
17 | if (!isset($_REQUEST['file_id']) || !preg_match('/^[a-zA-Z0-9\-_]+$/', $_REQUEST['file_id'])) {
18 | die('File ID is required');
19 | }
20 |
21 | $fileId = $_REQUEST['file_id'];
22 | $content = $groq->files()->download($fileId);
23 |
24 | header('Content-Type: application/x-jsonlines');
25 | header('Content-Disposition: attachment; filename="download.jsonl"');
26 | header('Content-Length: ' . strlen($content));
27 | // Prevent browser caching of sensitive data
28 | header('Cache-Control: no-store, no-cache, must-revalidate, max-age=0');
29 | header('Pragma: no-cache');
30 |
31 | echo $content;
32 | exit;
33 | }
34 | } catch (GroqException $e) {
35 | $error = $e->getMessage();
36 | }
37 | }
38 |
39 | // Handle file upload
40 | if (isset($_FILES['jsonl_file'])) {
41 | try {
42 | // Validate file size (e.g., 100MB limit)
43 | if ($_FILES['jsonl_file']['size'] > 100 * 1024 * 1024) {
44 | throw new GroqException('File size exceeds limit', 400, 'invalid_request');
45 | }
46 |
47 | // Validate file type
48 | $finfo = finfo_open(FILEINFO_MIME_TYPE);
49 | $mimeType = finfo_file($finfo, $_FILES['jsonl_file']['tmp_name']);
50 | finfo_close($finfo);
51 | if ($mimeType !== 'application/x-ndjson' && $mimeType !== 'text/plain') {
52 | throw new GroqException('Invalid file type', 400, 'invalid_request');
53 | }
54 |
55 | $tempFile = $_FILES['jsonl_file']['tmp_name'];
56 | $originalName = $_FILES['jsonl_file']['name'];
57 |
58 | $newTempFile = tempnam(sys_get_temp_dir(), 'groq_') . '.jsonl';
59 | try {
60 | if (!copy($tempFile, $newTempFile)) {
61 | throw new GroqException('Failed to process upload file', 400, 'invalid_request');
62 | }
63 |
64 | // Upload file
65 | $file = $groq->files()->upload($newTempFile, 'batch');
66 | $success = "File uploaded successfully!";
67 | } finally {
68 | // Always clean up temporary file
69 | if (file_exists($newTempFile)) {
70 | unlink($newTempFile);
71 | }
72 | }
73 | } catch (GroqException $e) {
74 | $error = $e->getMessage();
75 | }
76 | }
77 |
78 | // Get list of files
79 | try {
80 | $filesList = $groq->files()->list('batch', ['limit' => 10]);
81 | $files = $filesList['data'];
82 | } catch (GroqException $e) {
83 | $error = $e->getMessage();
84 | }
85 | ?>
86 |
87 |
88 |
89 |
92 |
93 |
94 |
95 |
98 |
99 |
100 |
101 |
102 |
Upload JSONL File
103 |
126 |
127 |
128 |
129 |
130 |
Available Files
131 |
132 |
No files available.
133 |
134 |
135 |
136 |
137 |
138 |
139 |
filename) ?>
140 |
141 |
ID: id) ?>
142 |
Size: bytes / 1024, 2) ?> KB
143 |
Created: created_at)) ?>
144 |
Status:
148 | status) ?>
149 |
150 |
151 |
152 |
153 |
169 |
170 |
171 |
172 |
173 |
174 |
175 |