Fixed defect in Structure, new examples

docs/cookbook/examples/extras/llm.mdx

@@ -23,15 +23,19 @@ $loader->add('Cognesy\\Instructor\\', __DIR__ . '../../src/');
 use Cognesy\Instructor\Extras\LLM\Inference;
 use Cognesy\Instructor\Utils\Str;
 
-// simplified API, default connection for convenient ad-hoc calls
+
+
+// EXAMPLE 1: simplified API, default connection for convenient ad-hoc calls
 $answer = Inference::text('What is capital of Germany');
 
 echo "USER: What is capital of Germany\n";
 echo "ASSISTANT: $answer\n";
 assert(Str::contains($answer, 'Berlin'));
 
 
-// regular API, allows to customize inference options
+
+
+// EXAMPLE 2: regular API, allows to customize inference options
 $answer = (new Inference)
     ->withConnection('openai') // optional, default is set in /config/llm.php
     ->create(
@@ -44,7 +48,10 @@ echo "USER: What is capital of France\n";
 echo "ASSISTANT: $answer\n";
 assert(Str::contains($answer, 'Paris'));
 
-// regular API, allows to customize inference options
+
+
+
+// EXAMPLE 3: streaming response
 $stream = (new Inference)
     ->create(
         messages: [['role' => 'user', 'content' => 'Describe capital of Brasil']],

docs/cookbook/examples/extras/llm_json.mdx

@@ -35,7 +35,6 @@ $loader->add('Cognesy\\Instructor\\', __DIR__ . '../../src/');
 use Cognesy\Instructor\Enums\Mode;
 use Cognesy\Instructor\Extras\LLM\Inference;
 
-// regular API, allows to customize inference options
 $data = (new Inference)
     ->withConnection('openai') // optional, default is set in /config/llm.php
     ->create(

docs/cookbook/examples/extras/llm_json_schema.mdx

@@ -26,7 +26,6 @@ $loader->add('Cognesy\\Instructor\\', __DIR__ . '../../src/');
 
 use Cognesy\Instructor\Enums\Mode;use Cognesy\Instructor\Extras\LLM\Inference;
 
-// regular API, allows to customize inference options
 $data = (new Inference)
     ->withConnection('openai')
     ->create(

docs/cookbook/examples/extras/llm_md_json.mdx

@@ -28,7 +28,6 @@ $loader->add('Cognesy\\Instructor\\', __DIR__ . '../../src/');
 
 use Cognesy\Instructor\Enums\Mode;use Cognesy\Instructor\Extras\LLM\Inference;
 
-// regular API, allows to customize inference options
 $data = (new Inference)
     ->withConnection('openai')
     ->create(

docs/cookbook/examples/extras/llm_tools.mdx

@@ -24,7 +24,6 @@ $loader->add('Cognesy\\Instructor\\', __DIR__ . '../../src/');
 use Cognesy\Instructor\Enums\Mode;
 use Cognesy\Instructor\Extras\LLM\Inference;
 
-// regular API, allows to customize inference options
 $data = (new Inference)
     ->withConnection('openai')
     ->create(

docs/cookbook/examples/extras/schema.mdx

@@ -27,7 +27,6 @@ class City {
 
 $schema = (new SchemaFactory)->schema(City::class);
 
-// regular API, allows to customize inference options
 $data = (new Inference)
     ->withConnection('openai')
     ->create(

docs/mint.json

@@ -202,6 +202,7 @@
                 "cookbook/examples/extras/llm_md_json",
                 "cookbook/examples/extras/llm_tools",
                 "cookbook/examples/extras/schema",
+                "cookbook/examples/extras/schema",
                 "cookbook/examples/extras/transcription_to_tasks",
                 "cookbook/examples/extras/translate_ui_fields",
                 "cookbook/examples/extras/web_to_objects"

examples/A05_Extras/LLM/run.php

@@ -23,15 +23,19 @@
 use Cognesy\Instructor\Extras\LLM\Inference;
 use Cognesy\Instructor\Utils\Str;
 
-// simplified API, default connection for convenient ad-hoc calls
+
+
+// EXAMPLE 1: simplified API, default connection for convenient ad-hoc calls
 $answer = Inference::text('What is capital of Germany');
 
 echo "USER: What is capital of Germany\n";
 echo "ASSISTANT: $answer\n";
 assert(Str::contains($answer, 'Berlin'));
 
 
-// regular API, allows to customize inference options
+
+
+// EXAMPLE 2: regular API, allows to customize inference options
 $answer = (new Inference)
     ->withConnection('openai') // optional, default is set in /config/llm.php
     ->create(
@@ -44,7 +48,10 @@
 echo "ASSISTANT: $answer\n";
 assert(Str::contains($answer, 'Paris'));
 
-// regular API, allows to customize inference options
+
+
+
+// EXAMPLE 3: streaming response
 $stream = (new Inference)
     ->create(
         messages: [['role' => 'user', 'content' => 'Describe capital of Brasil']],

examples/A05_Extras/LLMJson/run.php

@@ -35,7 +35,6 @@
 use Cognesy\Instructor\Enums\Mode;
 use Cognesy\Instructor\Extras\LLM\Inference;
 
-// regular API, allows to customize inference options
 $data = (new Inference)
     ->withConnection('openai') // optional, default is set in /config/llm.php
     ->create(

examples/A05_Extras/LLMJsonSchema/run.php

@@ -26,7 +26,6 @@
 
 use Cognesy\Instructor\Enums\Mode;use Cognesy\Instructor\Extras\LLM\Inference;
 
-// regular API, allows to customize inference options
 $data = (new Inference)
     ->withConnection('openai')
     ->create(

examples/A05_Extras/LLMMdJson/run.php

@@ -28,7 +28,6 @@
 
 use Cognesy\Instructor\Enums\Mode;use Cognesy\Instructor\Extras\LLM\Inference;
 
-// regular API, allows to customize inference options
 $data = (new Inference)
     ->withConnection('openai')
     ->create(

examples/A05_Extras/LLMTools/run.php

@@ -24,7 +24,6 @@
 use Cognesy\Instructor\Enums\Mode;
 use Cognesy\Instructor\Extras\LLM\Inference;
 
-// regular API, allows to customize inference options
 $data = (new Inference)
     ->withConnection('openai')
     ->create(

examples/A05_Extras/Schema/run.php

@@ -27,7 +27,6 @@ class City {
 
 $schema = (new SchemaFactory)->schema(City::class);
 
-// regular API, allows to customize inference options
 $data = (new Inference)
     ->withConnection('openai')
     ->create(

examples/A05_Extras/SchemaDynamic/run.php

@@ -0,0 +1,60 @@
+---
+title: 'Generating JSON Schema from PHP classes'
+docname: 'schema'
+---
+
+## Overview
+
+Instructor has a built-in support for generating JSON Schema from
+dynamic objects with `Structure` class.
+
+This is useful when the data model is built during runtime or defined
+by your app users.
+
+`Structure` helps you flexibly design and modify data models that
+can change with every request or user input and allows you to generate
+JSON Schema for them.
+
+## Example
+
+```php
+<?php
+$loader = require 'vendor/autoload.php';
+$loader->add('Cognesy\\Instructor\\', __DIR__ . '../../src/');
+
+use Cognesy\Instructor\Enums\Mode;
+use Cognesy\Instructor\Extras\LLM\Inference;
+use Cognesy\Instructor\Extras\Structure\Field;
+use Cognesy\Instructor\Extras\Structure\Structure;
+
+$city = Structure::define('city', [
+    Field::string('name', 'City name')->required(),
+    Field::int('population', 'City population')->required(),
+    Field::int('founded', 'Founding year')->required(),
+]);
+
+$data = (new Inference)
+    ->withConnection('openai')
+    ->create(
+        messages: [['role' => 'user', 'content' => 'What is capital of France? \
+        Respond with JSON data.']],
+        responseFormat: [
+            'type' => 'json_schema',
+            'description' => 'City data',
+            'json_schema' => [
+                'name' => 'city_data',
+                'schema' => $city->toJsonSchema(),
+                'strict' => true,
+            ],
+        ],
+        options: ['max_tokens' => 64],
+        mode: Mode::JsonSchema,
+    )
+    ->toJson();
+
+echo "USER: What is capital of France\n";
+echo "ASSISTANT:\n";
+dump($data);
+
+?>
+```

src/Extras/Structure/Traits/Field/HandlesOptionality.php

@@ -5,7 +5,7 @@ trait HandlesOptionality
 {
     private bool $required = true;
 
-    public function required(bool $isRequired = false) : self {
+    public function required(bool $isRequired = true) : self {
         $this->required = $isRequired;
         return $this;
     }