Add examples folder + some improvements:

- Add support for response streaming and JSON mode. - Improve error handling with more descriptive errors. - Add usage examples. - Fix bugs related to streaming and JSON mode. - Update minimum PHP version. - Add unit tests.
lucianotonet · Apr 20, 2024 · 3bfb937 · 3bfb937
1 parent aea491d
commit 3bfb937
Show file tree

Hide file tree

Showing 15 changed files with 511 additions and 46 deletions.
diff --git a/.gitignore b/.gitignore
@@ -8,4 +8,6 @@
 *.swo
 playground/*
 .idea
-.env
+.env
+/examples/.env
+/examples/vendor/
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -1,8 +1,35 @@
+## Version 0.0.4
+
+### New Features
+
+* Examples of usage added to the examples directory.
+
+### Improvements
+
+* Error handling improved with more descriptive error messages.
+* Support for response streaming.
+* Support for stop sequence in streaming.
+* Support for JSON mode.
+
+### Bug Fixes
+
+* Fixed an error that prevented response streaming.
+* Fixed an error that prevented the use of JSON mode.
+
+### Other Changes
+
+* Minimum PHP requirement updated to 8.1.
+* Unit tests added for new features and bug fixes.
+
+## Version 0.0.3
+
+### Fixes
+- Added stream functionality + some refactors
 
 ## Version 0.0.2
 
 ### Fixes
-- Fix the error when passing the 'response_format' parameter along with 'tools', we encountered an error: "response_format` json_object cannot be combined with tool/function calling".
+- Fixed the error when passing the 'response_format' parameter along with 'tools', we encountered an error: "response_format` json_object cannot be combined with tool/function calling".
 
 ### News
 - Introduced examples and other changes:
@@ -14,4 +41,4 @@
 
 ## Version 0.0.1
 
-- First functional version.
+- First functional version.
diff --git a/README.md b/README.md
@@ -12,7 +12,6 @@ composer require lucianotonet/groq-php
 
 ## Usage
 
-<!-- prettier-ignore -->
 ```php
 use LucianoTonet\Groq;
 
@@ -23,20 +22,24 @@ $chatCompletion = $groq->chat()->completions()->create([
   'messages' => [
     [
       'role'    => 'user',
-      'content' => 'Explain the importance of low latency LLMs']
+      'content' => 'Explain the importance of low latency LLMs'
     ],
+  ]
 ]);
 
 echo $chatCompletion['choices'][0]['message']['content'];
 ```
 
+## Examples
+
+The most common usage examples is on the [examples folder](/examples).
+
 ## Handling errors
 
 When the library is unable to connect to the API,
 or if the API returns a non-success status code (i.e., 4xx or 5xx response),
 a subclass of `APIError` will be thrown:
 
-<!-- prettier-ignore -->
 ```php
 use LucianoTonet\Groq;
 
@@ -86,31 +89,29 @@ Connection errors (for example, due to a network connectivity problem), 408 Requ
 
 You can use the `maxRetries` option to configure or disable this:
 
-<!-- prettier-ignore -->
 ```php
 $groq->setOptions(['maxRetries' => 0]); // default is 2
 
 // Or, configure per-request:
 $groq->chat()->completions()->create([
-    'messages' => [
-        [
-          'role' => 'system',
-          'content' => 'You are a helpful assisstant.'
-        ],
-        [
-          'role' => 'user',
-          'content' => 'Explain the importance of low latency LLMs'
-        ]
+  'model' => 'mixtral-8x7b-32768',
+  'messages' => [
+    [
+      'role' => 'system',
+      'content' => 'You are a helpful assisstant.'
     ],
-    'model' => 'mixtral-8x7b-32768'
+    [
+      'role' => 'user',
+      'content' => 'Explain the importance of low latency LLMs'
+    ]
+  ],
 ], ['maxRetries' => 5]);
 ```
 
 ### Timeouts
 
 Requests time out after 1 minute by default. You can configure this with a `timeout` option:
 
-<!-- prettier-ignore -->
 ```php
 // Configure the default for all requests:
 $groq = new Groq([
@@ -119,6 +120,7 @@ $groq = new Groq([
 
 // Override per-request:
 $groq->chat()->completions()->create([
+  'model' => 'mixtral-8x7b-32768',
   'messages' => [
     [
       'role' => 'system', 
@@ -129,10 +131,7 @@ $groq->chat()->completions()->create([
       'content' => 'Explain the importance of low latency LLMs'
     ]
   ],
-  'model' => 'mixtral-8x7b-32768'
-], [
-  'timeout' => 5 * 1000,
-]);
+], ['timeout' => 5 * 1000]); // 5 seconds
 ```
 
 Note that requests which time out will be [retried twice by default](#retries).
@@ -141,19 +140,25 @@ Note that requests which time out will be [retried twice by default](#retries).
 
 ### Streaming
 ```php
-// Exemplo de streaming
 $stream = $groq->chat()->completions()->create([
     'model' => 'mixtral-8x7b-32768',
     'messages' => [
         [
             'role' => 'user',
             'content' => 'Explain the importance of low latency LLMs'
         ],
-    ]
-], ['stream' => true]);
+    ],
+    'stream' => true
+  ]);
 
 foreach ($stream->chunks() as $chunk) {
-    echo $chunk['choices'][0]['delta']['role'] ?? $chunk['choices'][0]['delta']['content'] ?? '';
+    if(isset($chunk['choices'][0]['delta']['role'])) {
+        echo $chunk['choices'][0]['delta']['role']; // 'assistant'
+    }
+
+    if (isset($chunk['choices'][0]['delta']['content'])) {
+        echo $chunk['choices'][0]['delta']['content']; // '
+    }
 
     ob_flush();
     flush();
@@ -162,7 +167,7 @@ foreach ($stream->chunks() as $chunk) {
 
 ### STOP sequence
 ```php
-// Exemplo com stop sequence
+// Stop sequence example
 $chatCompletion = $groq->chat()->completions()->create([
     'model' => 'mixtral-8x7b-32768',
     'messages' => [
@@ -175,26 +180,25 @@ $chatCompletion = $groq->chat()->completions()->create([
 ]);
 
 echo $chatCompletion['choices'][0]['message']['content'];
+// 1, 2, 3, 4, 5, 6
 ```
 
 ### JSON mode
 ```php
-// Exemplo de modo JSON
-$recipe = new Recipe();
 $chatCompletion = $groq->chat()->completions()->create([
     'model' => 'mixtral-8x7b-32768',
     'messages' => [
         [
             'role' => 'system',
-            'content' => "You are a recipe database that outputs recipes in JSON.\n The JSON object must use the schema: " . json_encode($recipe->getJsonSchema(), JSON_PRETTY_PRINT),
+            'content' => "You are an API and shall responde only with valid JSON.",
         ],
         [
             'role' => 'user',
-            'content' => 'Fetch a recipe for apple pie',
+            'content' => 'Explain the importance of low latency LLMs',
         ],
     ],
-    'response_format' => ['type' => 'json_object'],
-], ['stream' => false]);
+    'response_format' => ['type' => 'json_object']
+  ]);
 
 $recipe = $recipe->fromJson($chatCompletion['choices'][0]['message']['content']);
 ```
@@ -209,6 +213,4 @@ This package generally follows [SemVer](https://semver.org/spec/v2.0.0.html) con
 
 ## Requirements
 
-PHP >= 8.1
-
-
+PHP >= 8.1
diff --git a/composer.json b/composer.json
@@ -1,7 +1,7 @@
 {
     "name": "lucianotonet/groq-php",
     "description": "PHP library to provide access to the Groq REST API",
-    "version": "0.0.3",
+    "version": "0.0.4",
     "type": "package",
     "require": {
         "php": "^8.1.0",

diff --git a/examples/.env.example b/examples/.env.example
@@ -0,0 +1,2 @@
+GROQ_API_KEY=gsk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx  # Get your API key on https://console.groq.com/keys
+GROQ_API_BASE_URL=https://api.groq.com/openai/v1
diff --git a/examples/.gitignore b/examples/.gitignore
@@ -0,0 +1,10 @@
+/.phpunit.cache
+/.php-cs-fixer.cache
+/.php-cs-fixer.php
+/phpunit.xml
+/vendor/
+*.swp
+*.swo
+playground/*
+.idea
+.env
diff --git a/examples/_input.php b/examples/_input.php
@@ -0,0 +1,4 @@
+<form method="post" class="mb-10">
+    <input type="text" class="border border-black p-4 w-96" name="message" placeholder="What is the importance of low latency in LLMs?" required>
+    <button type="submit" class="bg-black text-white p-4">Send</button>
+</form>
diff --git a/examples/chat-streaming.php b/examples/chat-streaming.php
@@ -0,0 +1,32 @@
+<?php
+require __DIR__ . '/_input.php';
+
+if ($_SERVER['REQUEST_METHOD'] === 'POST') {
+    $message = $_POST['message'];
+
+    echo "<strong>user: </strong> $message <br>";
+
+    $response = $groq->chat()->completions()->create([
+        'model' => 'mixtral-8x7b-32768',
+        'messages' => [
+            [
+                'role' => 'user',
+                'content' => $message
+            ]
+        ],
+        'stream' => true
+    ]);
+
+    foreach ($response->chunks() as $chunk) {
+        if (isset($chunk['choices'][0]['delta']['role'])) {
+            echo "<strong>" . $chunk['choices'][0]['delta']['role'] . ":</strong> ";
+        }
+
+        if (isset($chunk['choices'][0]['delta']['content'])) {
+            echo $chunk['choices'][0]['delta']['content'];
+        }
+
+        ob_flush();
+        flush();
+    }
+}
diff --git a/examples/chat.php b/examples/chat.php
@@ -0,0 +1,21 @@
+<?php
+require __DIR__ . '/_input.php';
+
+if ($_SERVER['REQUEST_METHOD'] === 'POST') {
+    $message = $_POST['message'];
+
+    echo "<strong>user: </strong> $message <br>";
+
+    $response = $groq->chat()->completions()->create([
+        'model' => 'llama3-8b-8192', // llama3-8b-8192, llama2-70b-4096, mixtral-8x7b-32768, gemma-7b-it
+        'messages' => [
+            [
+                'role' => 'user',
+                'content' => $message
+            ]
+        ],
+    ]);
+
+    echo "<strong>assistant: </strong> ";
+    echo $response['choices'][0]['message']['content'];
+}
diff --git a/examples/composer.json b/examples/composer.json
@@ -0,0 +1,27 @@
+{
+    "name": "lucianotonet/example-groq-php",
+    "type": "project",  
+    "authors": [
+        {
+            "name": "Luciano Tonet",
+            "email": "[email protected]"
+        }
+    ],    
+    "require": {        
+        "vlucas/phpdotenv": "^5.6",
+        "guzzlehttp/guzzle": "^7.8",
+        "lucianotonet/groq-php": "^0.0.3"
+    },
+    "require-dev": {
+        "phpunit/phpunit": "^11.0"
+    },
+    "repositories": [
+        {
+            "type": "path",
+            "url": "../../",
+            "options": {
+                "symlink": true
+            }
+        }
+    ]
+}
Original file line number	Diff line number	Diff line change
		@@ -0,0 +1,2 @@
		GROQ_API_KEY=gsk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx # Get your API key on https://console.groq.com/keys
		GROQ_API_BASE_URL=https://api.groq.com/openai/v1