Docs updates

docs/data_model.md

@@ -1,78 +1,5 @@
 ## Specifying Data Model
 
-### Scalar Values
-
-Instructor can extract scalar values from text and assign them to your response model's properties.
-
-### Example: String result
-
-```php
-<?php
-
-$value = (new Instructor)->respond(
-    messages: "His name is Jason, he is 28 years old.",
-    responseModel: Scalar::string(name: 'firstName'),
-);
-// expect($value)->toBeString();
-// expect($value)->toBe("Jason");
-```
-
-### Example: Integer result
-
-```php
-<?php
-
-$value = (new Instructor)->respond(
-    messages: "His name is Jason, he is 28 years old.",
-    responseModel: Scalar::integer('age'),
-);
-// expect($value)->toBeInt();
-// expect($value)->toBe(28);
-```
-
-### Example: Boolean result
-
-```php
-<?php
-
-$age = (new Instructor)->respond(
-    messages: "His name is Jason, he is 28 years old.",
-    responseModel: Scalar::boolean(name: 'isAdult'),
-);
-// expect($age)->toBeBool();
-// expect($age)->toBe(true);
-```
-
-### Example: Float result
-
-```php
-<?php
-
-$value = (new Instructor)->respond(
-    messages: "His name is Jason, he is 28 years old and his 100m sprint record is 11.6 seconds.",
-    responseModel: Scalar::float(name: 'recordTime'),
-);
-// expect($value)->toBeFloat();
-// expect($value)->toBe(11.6);
-```
-
-### Example: Select one of the options
-
-```php
-<?php
-
-$age = (new Instructor)->respond(
-    messages: "His name is Dietmar, he is 28 years old and he lives in Germany.",
-    responseModel: Scalar::select(
-        options: ['US citizen', 'Canada citizen', 'other'],
-        name: 'citizenshipGroup'
-    ),
-);
-// expect($age)->toBeString();
-// expect($age)->toBe('other');
-```
-
-
 ### Type Hints
 
 Use PHP type hints to specify the type of extracted data.
@@ -224,3 +151,77 @@ Using PHP DocBlocks instructions is not required, but sometimes you may want to
         public string $context;
     }
 ```
+
+## Scalar Values
+
+Instructor can extract scalar values from text and assign them to your response model's properties.
+
+### Example: String result
+
+```php
+<?php
+
+$value = (new Instructor)->respond(
+    messages: "His name is Jason, he is 28 years old.",
+    responseModel: Scalar::string(name: 'firstName'),
+);
+// expect($value)->toBeString();
+// expect($value)->toBe("Jason");
+```
+
+### Example: Integer result
+
+```php
+<?php
+
+$value = (new Instructor)->respond(
+    messages: "His name is Jason, he is 28 years old.",
+    responseModel: Scalar::integer('age'),
+);
+// expect($value)->toBeInt();
+// expect($value)->toBe(28);
+```
+
+### Example: Boolean result
+
+```php
+<?php
+
+$age = (new Instructor)->respond(
+    messages: "His name is Jason, he is 28 years old.",
+    responseModel: Scalar::boolean(name: 'isAdult'),
+);
+// expect($age)->toBeBool();
+// expect($age)->toBe(true);
+```
+
+### Example: Float result
+
+```php
+<?php
+
+$value = (new Instructor)->respond(
+    messages: "His name is Jason, he is 28 years old and his 100m sprint record is 11.6 seconds.",
+    responseModel: Scalar::float(name: 'recordTime'),
+);
+// expect($value)->toBeFloat();
+// expect($value)->toBe(11.6);
+```
+
+### Example: Select one of the options
+
+```php
+<?php
+
+$age = (new Instructor)->respond(
+    messages: "His name is Dietmar, he is 28 years old and he lives in Germany.",
+    responseModel: Scalar::select(
+        options: ['US citizen', 'Canada citizen', 'other'],
+        name: 'citizenshipGroup'
+    ),
+);
+// expect($age)->toBeString();
+// expect($age)->toBe('other');
+```
+
+

docs/usage.md

@@ -44,3 +44,56 @@ var_dump($person);
 !!! note
 
     Currently, Instructor for PHP only supports classes / objects as response models. In case you want to extract simple types or arrays, you need to wrap them in a class.
+
+## Shortcuts
+
+### String as Input
+
+You can provide a string instead of an array of messages. This is useful when you want to extract data from a single block of text and want to keep your code simple.
+
+```php
+use Cognesy/Instructor;
+
+$value = (new Instructor)->respond(
+    messages: "His name is Jason, he is 28 years old.",
+    responseModel: Person::class,
+);
+```
+
+
+### Extracting Scalar Values
+
+Sometimes we just want to get quick results without defining a class for the response model, especially if we're trying to get a straight, simple answer in a form of string, integer, boolean or float. Instructor provides a simplified API for such cases.
+
+```php
+use Cognesy/Instructor;
+
+$value = (new Instructor)->respond(
+    messages: "His name is Jason, he is 28 years old.",
+    responseModel: Scalar::integer('age'),
+);
+
+var_dump($value);
+// int(28)
+```
+
+In this example, we're extracting a single integer value from the text. You can also use `Scalar::string()`, `Scalar::boolean()` and `Scalar::float()` to extract other types of values.
+
+Additionally, you can use Scalar adapter to extract one of the provided options.
+
+```php
+use Cognesy/Instructor;
+
+$value = (new Instructor)->respond(
+    messages: "His name is Jason, he currently plays Doom Eternal.",
+    responseModel: Scalar::select(
+        name: 'activityType',
+        options: ['work', 'entertainment', 'sport', 'other']
+    ),
+);
+
+var_dump($value);
+// string(4) "entertainment"
+```
+
+NOTE: Currently Scalar::select() always returns strings and its ```options``` parameter only accepts string values.