New example

composer.json

@@ -48,7 +48,8 @@
         "symfony/dom-crawler": "^7.1",
         "duzun/hquery": "^3.1",
         "ext-dom": "*",
-        "psy/psysh": "@stable"
+        "psy/psysh": "@stable",
+        "symfony/http-client": "^7.1"
     },
     "config": {
         "allow-plugins": {

docs/cookbook/examples/advanced/custom_validation.mdx → docs/cookbook/examples/basics/custom_validation.mdx

@@ -16,8 +16,6 @@ offers you #[Assert/Callback] annotation to build fully customized validation lo
 $loader = require 'vendor/autoload.php';
 $loader->add('Cognesy\\Instructor\\', __DIR__.'../../src/');
 
-
-use Cognesy\Instructor\Events\Request\RequestSentToLLM;
 use Cognesy\Instructor\Instructor;
 use Symfony\Component\Validator\Constraints as Assert;
 use Symfony\Component\Validator\Context\ExecutionContextInterface;

docs/cookbook/examples/basics/validation_with_llm.mdx

@@ -0,0 +1,73 @@
+---
+title: 'Validation with LLM'
+docname: 'validation_with_llm'
+---
+
+## Overview
+
+You can use LLM capability to semantically process the context to validate
+the response following natural language instructions. This way you can
+implement more complex validation logic that would be difficult (or impossible)
+to achieve using traditional, code-based validation.
+
+## Example
+
+<?php
+$loader = require 'vendor/autoload.php';
+$loader->add('Cognesy\\Instructor\\', __DIR__.'../../src/');
+
+use Cognesy\Instructor\Events\Event;
+use Cognesy\Instructor\Extras\Scalar\Scalar;
+use Cognesy\Instructor\Instructor;
+use Cognesy\Instructor\Schema\Attributes\Description;
+use Cognesy\Instructor\Utils\Str;
+use Cognesy\Instructor\Validation\Traits\ValidationMixin;
+use Cognesy\Instructor\Validation\ValidationResult;
+
+class UserDetails
+{
+    use ValidationMixin;
+
+    public string $name;
+    #[Description('User details in format: key=value')]
+    /** @var string[]  */
+    public array $details;
+
+    public function validate() : ValidationResult {
+        return match($this->hasPII()) {
+            true => ValidationResult::fieldError(
+                field: 'details',
+                value: implode('\n', $this->details),
+                message: "Details contain PII, remove it from the response."
+            ),
+            false => ValidationResult::valid(),
+        };
+    }
+
+    private function hasPII() : bool {
+        $data = implode('\n', $this->details);
+        return (new Instructor)->respond(
+            messages: "Context:\n$data\n",
+            responseModel: Scalar::boolean('hasPII', 'Does the context contain any PII?'),
+        );
+    }
+}
+
+$text = <<<TEXT
+    My name is Jason. I am is 25 years old. I am developer.
+    My phone number is +1 123 34 45 and social security number is 123-45-6789
+    TEXT;
+
+$user = (new Instructor)
+    ->wiretap(fn(Event $e) => $e->print()) // let's check the internals of Instructor processing
+    ->respond(
+        messages: $text,
+        responseModel: UserDetails::class,
+        maxRetries: 2
+    );
+
+dump($user);
+
+assert(!Str::contains(implode('\n', $user->details), '123-45-6789'));
+?>
+```

docs/mint.json

@@ -137,7 +137,9 @@
                 "cookbook/examples/basics/attributes",
                 "cookbook/examples/basics/using_config",
                 "cookbook/examples/basics/validation",
-                "cookbook/examples/basics/validation_multifield"
+                "cookbook/examples/basics/custom_validation",
+                "cookbook/examples/basics/validation_multifield",
+                "cookbook/examples/basics/validation_with_llm"
             ]
         },
         {
@@ -146,7 +148,6 @@
                 "cookbook/examples/advanced/context_cache",
                 "cookbook/examples/advanced/custom_client",
                 "cookbook/examples/advanced/custom_prompts",
-                "cookbook/examples/advanced/custom_validation",
                 "cookbook/examples/advanced/structured_input",
                 "cookbook/examples/advanced/function_calls",
                 "cookbook/examples/advanced/partials",

examples/A02_Advanced/CustomValidator/run.php → examples/A01_Basics/ValidationCustom/run.php

@@ -16,8 +16,6 @@
 $loader = require 'vendor/autoload.php';
 $loader->add('Cognesy\\Instructor\\', __DIR__.'../../src/');
 
-
-use Cognesy\Instructor\Events\Request\RequestSentToLLM;
 use Cognesy\Instructor\Instructor;
 use Symfony\Component\Validator\Constraints as Assert;
 use Symfony\Component\Validator\Context\ExecutionContextInterface;

examples/A01_Basics/ValidationWithLLM/run.php

@@ -0,0 +1,73 @@
+---
+title: 'Validation with LLM'
+docname: 'validation_with_llm'
+---
+
+## Overview
+
+You can use LLM capability to semantically process the context to validate
+the response following natural language instructions. This way you can
+implement more complex validation logic that would be difficult (or impossible)
+to achieve using traditional, code-based validation.
+
+## Example
+
+<?php
+$loader = require 'vendor/autoload.php';
+$loader->add('Cognesy\\Instructor\\', __DIR__.'../../src/');
+
+use Cognesy\Instructor\Events\Event;
+use Cognesy\Instructor\Extras\Scalar\Scalar;
+use Cognesy\Instructor\Instructor;
+use Cognesy\Instructor\Schema\Attributes\Description;
+use Cognesy\Instructor\Utils\Str;
+use Cognesy\Instructor\Validation\Traits\ValidationMixin;
+use Cognesy\Instructor\Validation\ValidationResult;
+
+class UserDetails
+{
+    use ValidationMixin;
+
+    public string $name;
+    #[Description('User details in format: key=value')]
+    /** @var string[]  */
+    public array $details;
+
+    public function validate() : ValidationResult {
+        return match($this->hasPII()) {
+            true => ValidationResult::fieldError(
+                field: 'details',
+                value: implode('\n', $this->details),
+                message: "Details contain PII, remove it from the response."
+            ),
+            false => ValidationResult::valid(),
+        };
+    }
+
+    private function hasPII() : bool {
+        $data = implode('\n', $this->details);
+        return (new Instructor)->respond(
+            messages: "Context:\n$data\n",
+            responseModel: Scalar::boolean('hasPII', 'Does the context contain any PII?'),
+        );
+    }
+}
+
+$text = <<<TEXT
+    My name is Jason. I am is 25 years old. I am developer.
+    My phone number is +1 123 34 45 and social security number is 123-45-6789
+    TEXT;
+
+$user = (new Instructor)
+    ->wiretap(fn(Event $e) => $e->print()) // let's check the internals of Instructor processing
+    ->respond(
+        messages: $text,
+        responseModel: UserDetails::class,
+        maxRetries: 2
+    );
+
+dump($user);
+
+assert(!Str::contains(implode('\n', $user->details), '123-45-6789'));
+?>
+```

notes/NOTES.md

@@ -53,7 +53,8 @@
 - Extract APIClient to a separate package?
 - Foreign client support - OpenAI PHP, Amazon Bedrock SDK, etc. - via some kind of adapters?
 - example of integration with Laravel/Livewire
-
+- Read rate limits from API responses
+- Rate limited API calls - wait for the limit to reset
 
 
 

src/Data/RequestInfo.php

@@ -28,4 +28,8 @@ class RequestInfo
     public function isStream() : bool {
         return $this->options['stream'] ?? false;
     }
+
+    public function toMessages() : array {
+        return $this->messages;
+    }
 }

src/Extras/Codebase/Actions/ExtractClasses.php

@@ -0,0 +1,28 @@
+<?php
+
+namespace Cognesy\Instructor\Extras\Codebase\Actions;
+
+use Cognesy\Instructor\Extras\Codebase\Codebase;
+use PhpParser\Node;
+use PhpParser\NodeFinder;
+
+class ExtractClasses
+{
+    private Codebase $codebase;
+
+    public function __construct(Codebase $codebase) {
+        $this->codebase = $codebase;
+    }
+
+    public function __invoke(array $ast): array {
+        $nodeFinder = new NodeFinder();
+        $classes = $nodeFinder->findInstanceOf($ast, Node\Stmt\Class_::class);
+
+        $classList = [];
+        foreach ($classes as $class) {
+            $classObject = (new MakeClass($this->codebase))($class);
+            $classList[$classObject->name] = $classObject;
+        }
+        return $classList;
+    }
+}