Modifief Anthropic: from XML to JSON; initial work on agents; code cl…

…eanup

composer.json

@@ -57,6 +57,8 @@
         "league/flysystem": "^3.0",
         "psr/container": "^2.0",
         "symfony/yaml": "^7.0",
-        "phpdocumentor/reflection-docblock": "^5.4"
+        "phpdocumentor/reflection-docblock": "^5.4",
+        "symfony/type-info": "7.1.x-dev",
+        "phpstan/phpdoc-parser": "^1.29"
     }
 }

docs/hub/basics/basic_via_mixin.md

@@ -1,33 +1,41 @@
-# Basic use with HandlesExtraction trait
+# Basic use with HandlesSelfExtraction trait
 
-Instructor provides `HandlesExtraction` trait that you can use to enable
+Instructor provides `HandlesSelfExtraction` trait that you can use to enable
 extraction capabilities directly on class via static `extract()` method.
 
 `extract()` method returns an instance of the class with the data extracted
 using the Instructor.
 
 `extract()` method has following signature (you can also find it in the
-`CanHandleExtraction` interface):
+`CanSelfExtract` interface):
 
 ```php
+...
 static public function extract(
     string|array $messages, // (required) The message(s) to extract data from
     string $model = '',     // (optional) The model to use for extraction (otherwise - use default)
     int $maxRetries = 2,    // (optional) The number of retries in case of validation failure
     array $options = [],    // (optional) Additional data to pass to the Instructor or LLM API
+    array $examples = [],   // (optional) Examples to include in the prompt
+    string $toolName = '',  // (optional) The name of the tool call - used to add semantic information for LLM
+    string $toolDescription = '', // (optional) The description of the tool call - as above
+    string $prompt = '',    // (optional) The prompt to use for extraction
+    string $retryPrompt = '', // (optional) The prompt to use in case of validation failure
+    Mode $mode = Mode::Tools, // (optional) The mode to use for extraction
     Instructor $instructor = null // (optional) The Instructor instance to use for extraction
 ) : static;
+...
 ```
 
 ```php
 <?php
 $loader = require 'vendor/autoload.php';
 $loader->add('Cognesy\\Instructor\\', __DIR__ . '../../src/');
 
-use Cognesy\Instructor\Extras\Mixin\HandlesExtraction;
+use Cognesy\Instructor\Extras\Mixin\HandlesSelfExtraction;
 
 class User {
-    use HandlesExtraction;
+    use HandlesSelfExtraction;
 
     public int $age;
     public string $name;

examples/01_Basics/BasicViaMixin/run.php

@@ -1,20 +1,26 @@
-# Basic use with HandlesExtraction trait
+# Basic use with HandlesSelfExtraction trait
 
-Instructor provides `HandlesExtraction` trait that you can use to enable
+Instructor provides `HandlesSelfExtraction` trait that you can use to enable
 extraction capabilities directly on class via static `extract()` method.
 
 `extract()` method returns an instance of the class with the data extracted
 using the Instructor.
 
 `extract()` method has following signature (you can also find it in the
-`CanHandleExtraction` interface):
+`CanSelfExtract` interface):
 
 ```php
 static public function extract(
     string|array $messages, // (required) The message(s) to extract data from
     string $model = '',     // (optional) The model to use for extraction (otherwise - use default)
     int $maxRetries = 2,    // (optional) The number of retries in case of validation failure
     array $options = [],    // (optional) Additional data to pass to the Instructor or LLM API
+    array $examples = [],   // (optional) Examples to include in the prompt
+    string $toolName = '',  // (optional) The name of the tool call - used to add semantic information for LLM
+    string $toolDescription = '', // (optional) The description of the tool call - as above
+    string $prompt = '',    // (optional) The prompt to use for extraction
+    string $retryPrompt = '', // (optional) The prompt to use in case of validation failure
+    Mode $mode = Mode::Tools, // (optional) The mode to use for extraction
     Instructor $instructor = null // (optional) The Instructor instance to use for extraction
 ) : static;
 ```
@@ -24,10 +30,10 @@ static public function extract(
 $loader = require 'vendor/autoload.php';
 $loader->add('Cognesy\\Instructor\\', __DIR__ . '../../src/');
 
-use Cognesy\Instructor\Extras\Mixin\HandlesExtraction;
+use Cognesy\Instructor\Extras\Mixin\HandlesSelfExtraction;
 
 class User {
-    use HandlesExtraction;
+    use HandlesSelfExtraction;
 
     public int $age;
     public string $name;

examples/01_Basics/ComplexObjectExtractionAnthropic/run.php

@@ -115,7 +115,7 @@ enum StakeholderRole: string {
     ->request(
         messages: $report,
         responseModel: Sequence::of(ProjectEvent::class),
-        model: 'claude-3-opus-20240229',
+        model: 'claude-3-haiku-20240307',
         mode: Mode::Json,
         options: [
             'max_tokens' => 2048,

examples/02_Advanced/Structures/run.php

@@ -58,6 +58,6 @@ enum Role : string {
 print("Age: " . $person->age . "\n");
 print("Address / city: " . $person->address->city . "\n");
 print("Address / ZIP: " . $person->address->zip . "\n");
-print("Role: " . $person->role . "\n");
+print("Role: " . $person->role->value . "\n");
 ?>
 ```

src-hub/Commands/RunOneExample.php

@@ -34,7 +34,7 @@ public function execute(array $params = []) {
     }
 
     public function run(Example $example) : void {
-        Cli::outln("Executing all examples...", [Color::BOLD, Color::YELLOW]);
+        Cli::outln("Executing example: {$example->group}/{$example->name}", [Color::BOLD, Color::YELLOW]);
         $timeStart = microtime(true);
         $this->runner->runSingle($example);
         $timeEnd = microtime(true);

src/Clients/Anthropic/AnthropicApiRequest.php

@@ -4,6 +4,7 @@
 
 use Cognesy\Instructor\ApiClient\Requests\ApiRequest;
 use Cognesy\Instructor\Schema\Factories\SchemaBuilder;
+use JetBrains\PhpStorm\Deprecated;
 use Override;
 
 class AnthropicApiRequest extends ApiRequest
@@ -13,28 +14,32 @@ class AnthropicApiRequest extends ApiRequest
     use Traits\HandlesTools;
 
     protected string $defaultEndpoint = '/messages';
+
+    #[Deprecated]
     protected string $xmlLineSeparator = "";
 
     /////////////////////////////////////////////////////////////////////////////////////////////////
 
     #[Override]
     protected function defaultBody(): array {
         $body = array_filter(array_merge([
-            'system' => $this->getSystemInstruction(),
+            //'system' => $this->getSystemInstruction(),
             'messages' => $this->messages(),
             'model' => $this->model,
         ], $this->options));
         return $body;
     }
 
+    #[Deprecated]
     protected function getSystemInstruction() : string {
         $tool = $this->getToolSchema();
-        $schema = (new SchemaBuilder)->fromArray($tool);
+        $schema = (new SchemaBuilder)->fromJsonSchema($tool, 'extract_data', 'Extract data from chat content');
         $xmlSchema = $schema->toXml();
         $system = $this->instructions()."\nHere are the tools available:\n".$this->xmlToolSchema($xmlSchema);
         return $system;
     }
 
+    #[Deprecated]
     protected function instructions() : string {
         $lines = [
             "In this environment you have access to a set of tools you can use to answer the user's question.\n",
@@ -52,6 +57,7 @@ protected function instructions() : string {
         return implode($this->xmlLineSeparator, $lines);
     }
 
+    #[Deprecated]
     private function xmlToolSchema(string $xmlSchema) : string {
         $lines = [
             '<tools>',