Example updates

docs/cookbook/examples/api_support/groq.mdx

@@ -55,19 +55,19 @@ $instructor = (new Instructor)->withClient($client);
 
 $user = $instructor
     ->respond(
-        messages: "Jason (@jxnlco) is 25 years old and is the admin of this project. He likes playing football and reading books.",
+        messages: "Jason (@jxnlco) is 25 years old. He is the admin of this project. He likes playing football and reading books.",
         responseModel: User::class,
         prompt: 'Parse the user data to JSON, respond using following JSON Schema: <|json_schema|>',
         examples: [[
             'input' => 'Ive got email Frank - their developer, who\'s 30. He asked to come back to him [email protected]. Btw, he plays on drums!',
-            'output' => ['age' => 30, 'name' => 'Frank', 'username' => '[email protected]', 'role' => 'developer', 'hobbies' => ['playing drums'],],
+            'output' => ['age' => 30, 'name' => 'Frank', 'username' => '[email protected]', 'role' => 'user', 'hobbies' => ['playing drums'],],
         ],[
-            'input' => 'We have a meeting with John, our new user. He is 30 years old - check his profile: @jx90.',
-            'output' => ['name' => 'John', 'role' => 'admin', 'hobbies' => [], 'username' => 'jx90', 'age' => 30],
+            'input' => 'We have a meeting with John, our new admin who likes surfing. He is 19 years old - check his profile: @jx90.',
+            'output' => ['name' => 'John', 'role' => 'admin', 'hobbies' => ['surfing'], 'username' => 'jx90', 'age' => 19],
         ]],
         model: 'gemma2-9b-it',
         maxRetries: 2,
-        options: ['temperature' => 0],
+        options: ['temperature' => 0.5],
         mode: Mode::Json,
     );
 

docs/cookbook/examples/api_support/openrouter.mdx

@@ -53,19 +53,20 @@ $client = new OpenRouterClient(
 /// Get Instructor with the default client component overridden with your own
 $instructor = (new Instructor)->withClient($client);
 
-$user = $instructor->respond(
-    messages: "Jason (@jxnlco) is 25 years old and is the admin of this project. He likes playing football and reading books.",
-    responseModel: User::class,
-    examples: [[
-        'input' => 'Ive got email Frank - their developer, who\'s 30. He asked to come back to him [email protected]. Btw, he plays on drums!',
-        'output' => ['age' => 30, 'name' => 'Frank', 'username' => '[email protected]', 'role' => 'developer', 'hobbies' => ['playing drums'],],
-    ],[
-        'input' => 'We have a meeting with John, our new user. He is 30 years old - check his profile: @jx90.',
-        'output' => ['name' => 'John', 'role' => 'admin', 'hobbies' => [], 'username' => 'jx90', 'age' => 30],
-    ]],
-    model: 'google/gemma-2-9b-it:free',
+$user = $instructor->withDebug()->respond(
+        messages: "Jason (@jxnlco) is 25 years old. He is the admin of this project. He likes playing football and reading books.",
+        responseModel: User::class,
+        prompt: 'Parse the user data to JSON, respond using following JSON Schema: <|json_schema|>',
+        examples: [[
+            'input' => 'Ive got email Frank - their developer, who\'s 30. He asked to come back to him [email protected]. Btw, he plays on drums!',
+            'output' => ['age' => 30, 'name' => 'Frank', 'username' => '[email protected]', 'role' => 'user', 'hobbies' => ['playing drums'],],
+        ],[
+            'input' => 'We have a meeting with John, our new admin who likes surfing. He is 19 years old - check his profile: @jig.',
+            'output' => ['age' => 19, 'name' => 'John', 'username' => 'jig', 'role' => 'admin', 'hobbies' => ['surfing'],],
+        ]],
+    model: 'microsoft/phi-3.5-mini-128k-instruct',
     //options: ['stream' => true ]
-    mode: Mode::Tools,
+    mode: Mode::Json,
 );
 
 print("Completed response model:\n\n");

docs/cookbook/examples/basics/modes.mdx

@@ -15,6 +15,8 @@ Instructor supports several ways to extract data from the response:
  - `Mode::MdJson` - uses prompting to get the language model to
    generate JSON following the schema.
 
+Note: not all modes are supported by all models or providers.
+
 Mode can be set via parameter of `Instructor::response()` or `Instructor::request()`
 methods.
 

docs/cookbook/examples/techniques/image_to_data.mdx

@@ -56,7 +56,6 @@ $receipt = (new Instructor)->respond(
     input: Image::fromFile(__DIR__ . '/receipt.png'),
     responseModel: Receipt::class,
     prompt: 'Extract structured data from the receipt.',
-    model: 'gpt-4o',
     options: ['max_tokens' => 4096]
 );
 

docs/cookbook/examples/troubleshooting/debugging.mdx

@@ -30,29 +30,31 @@ class User {
     public string $name;
 }
 
+// CASE 1 - normal flow
+
 $instructor = (new Instructor)->withClient(new OpenAIClient(
     apiKey: Env::get('OPENAI_API_KEY'), //  . 'invalid', // intentionally invalid API key
     baseUri: Env::get('OPENAI_BASE_URI'),
 ));
 
-echo "Debugging request and response:\n\n";
+echo "\n### CASE 1.1 - Debugging sync request\n\n";
 $user = $instructor->withDebug()->respond(
     messages: "Jason is 25 years old.",
     responseModel: User::class,
-    options: [ 'stream' => true ]
+    options: [ 'stream' => false ]
 );
 
 echo "\nResult:\n";
 dump($user);
 
-echo "Debugging request and response:\n\n";
+echo "\n### CASE 1.2 - Debugging streaming request\n\n";
 $user2 = $instructor->withDebug()->respond(
     messages: "Anna is 21 years old.",
     responseModel: User::class,
-    options: [ 'stream' => false ]
+    options: [ 'stream' => true ]
 );
 
-echo "\nResult 2:\n";
+echo "\nResult:\n";
 dump($user2);
 
 assert(isset($user->name));
@@ -64,5 +66,25 @@ assert(isset($user2->name));
 assert(isset($user2->age));
 assert($user2->name === 'Anna');
 assert($user2->age === 21);
+
+
+// CASE 2 - forcing API error via invalid API key
+
+$instructor = (new Instructor)->withClient(new OpenAIClient(
+    apiKey: Env::get('OPENAI_API_KEY') . 'invalid', // intentionally invalid API key
+    baseUri: Env::get('OPENAI_BASE_URI'),
+));
+
+echo "\n### CASE 2 - Debugging exception\n\n";
+try {
+    $user = $instructor->withDebug()->respond(
+        messages: "Jason is 25 years old.",
+        responseModel: User::class,
+        options: [ 'stream' => true ]
+    );
+} catch (Exception $e) {
+    echo "\nCaught it:\n";
+    dump($e);
+}
 ?>
 ```

docs/mint.json

@@ -155,6 +155,8 @@
                 "cookbook/examples/techniques/entity_relationships",
                 "cookbook/examples/techniques/handling_errors",
                 "cookbook/examples/techniques/image_to_data",
+                "cookbook/examples/techniques/image_to_data",
+                "cookbook/examples/techniques/image_to_data",
                 "cookbook/examples/techniques/limiting_lists",
                 "cookbook/examples/techniques/restate_instructions",
                 "cookbook/examples/techniques/rewrite_instructions",