Hook points onEvent(), wiretap(), onError() added to Instructor class

examples/Wiretap/run.php

@@ -0,0 +1,36 @@
+<?php
+
+ini_set('display_errors', 1);
+ini_set('display_startup_errors', 1);
+error_reporting(E_ALL);
+
+$loader = require 'vendor/autoload.php';
+$loader->add('Cognesy\\Instructor\\', __DIR__ . '../../src/');
+
+use Cognesy\Instructor\Instructor;
+use Symfony\Component\Validator\Constraints as Assert;
+
+enum Role : string {
+    case CEO = 'ceo';
+    case CTO = 'cto';
+    case Developer = 'developer';
+    case Other = 'other';
+}
+
+class UserDetail
+{
+    public string $name;
+    public Role $role;
+    #[Assert\Positive]
+    public int $age;
+}
+
+$user = (new Instructor)
+    ->wiretap(fn($event) => $event->print())
+    ->respond(
+        messages: [["role" => "user",  "content" => "Contact our CTO, Jason is -28 years old -- Tom"]],
+        responseModel: UserDetail::class,
+    )
+;
+
+assert($user->role == null);

src/Core/RequestHandler.php

@@ -6,10 +6,11 @@
 use Cognesy\Instructor\Contracts\CanTransformResponse;
 use Cognesy\Instructor\Events\RequestHandler\RequestSentToLLM;
 use Cognesy\Instructor\Events\RequestHandler\ResponseGenerated;
+use Cognesy\Instructor\Events\RequestHandler\ResponseGenerationFailed;
 use Cognesy\Instructor\Events\RequestHandler\ResponseModelBuilt;
 use Cognesy\Instructor\Events\RequestHandler\ResponseReceivedFromLLM;
-use Cognesy\Instructor\Events\RequestHandler\ResponseTransformationFinished;
-use Cognesy\Instructor\Events\RequestHandler\ResponseTransformationStarted;
+use Cognesy\Instructor\Events\RequestHandler\ResponseTransformed;
+use Cognesy\Instructor\Events\RequestHandler\ResponseConvertedToObject;
 use Cognesy\Instructor\Events\RequestHandler\ResponseValidationFailed;
 use Exception;
 
@@ -68,21 +69,22 @@ protected function tryRespond(
             $json = $response->toolCalls[0]->functionArguments;
             [$object, $errors] = $responseModel->toResponse($json);
             if (empty($errors)) {
+                $this->eventDispatcher->dispatch(new ResponseConvertedToObject($object));
                 if ($object instanceof CanTransformResponse) {
-                    $this->eventDispatcher->dispatch(new ResponseTransformationStarted($object));
                     $result = $object->transform();
-                    $this->eventDispatcher->dispatch(new ResponseTransformationFinished($result));
+                    $this->eventDispatcher->dispatch(new ResponseTransformed($result));
                 } else {
                     $result = $object;
                 }
                 $this->eventDispatcher->dispatch(new ResponseGenerated($result));
                 return $result;
             }
-            $this->eventDispatcher->dispatch(new ResponseValidationFailed($errors));
+            $this->eventDispatcher->dispatch(new ResponseValidationFailed($retries, $errors));
             $messages[] = ['role' => 'assistant', 'content' => $json];
             $messages[] = ['role' => 'user', 'content' => $this->retryPrompt . '\n' . $errors];
             $retries++;
         }
+        $this->eventDispatcher->dispatch(new ResponseGenerationFailed($retries, $errors));
         throw new Exception("Failed to extract data due to validation constraints: " . $errors);
     }
 }

src/Events/Event.php

@@ -1,6 +1,7 @@
 <?php
 namespace Cognesy\Instructor\Events;
 use Carbon\Carbon;
+use Cognesy\Instructor\Utils\Console;
 use Ramsey\Uuid\Uuid;
 
 abstract class Event
@@ -14,71 +15,36 @@ public function __construct()
         $this->createdAt = Carbon::now();
     }
 
-    public function __toString(): string
-    {
-        return $this->short();
+    public function toLog(): string {
+        return $this->logFormat((string) $this);
     }
 
-    protected function format(string $message): string
-    {
-        return $this->short($message);
+    public function toConsole(): string {
+        $message = (string) $this;
+        $message = str_replace("\n", ' ', $message);
+        return $this->consoleFormat($message);
     }
 
-    private function long(string $message): string
-    {
-        $shortId = substr($this->eventId, -4);
+    public function print(): void {
+        echo $this->toConsole()."\n";
+    }
+
+    private function logFormat(string $message): string {
         $class = (new \ReflectionClass($this))->getName();
-        $segments = explode('\\', $class);
-        $eventName = $segments[count($segments) - 1];
-        $eventGroup = $segments[count($segments) - 2];
-        $source = "...\\{$eventGroup}\\{$eventName}";
-        return "({$shortId}) {$this->createdAt->format('Y-m-d H:i:s v')}ms [$source] : $message";
+        return "({$this->eventId}) {$this->createdAt->format('Y-m-d H:i:s v')}ms [$class] - $message";
     }
 
-    private function short(string $message = '') : string {
+    private function consoleFormat(string $message = '') : string {
         $segments = explode('\\', (new \ReflectionClass($this))->getName());
         $eventName = array_pop($segments);
         $eventGroup = implode('\\', $segments);
-        return $this->columns([
+        return Console::columns([
             [7, '(.'.substr($this->eventId, -4).')'],
-            [5, $this->createdAt->format('v').'ms'],
-            [15, "{$eventGroup}\\", STR_PAD_LEFT],
-            [20, "{$eventName}", STR_PAD_LEFT],
+            [14, $this->createdAt->format('H:i:s v').'ms'],
+            //[15, "{$eventGroup}\\", STR_PAD_LEFT],
+            [24, "{$eventName}"],
             '-',
             [-1, $message],
-        ]);
-    }
-
-    private function columns(array $columns): string {
-        $terminalWidth = 140;
-        $message = '';
-        foreach ($columns as $row) {
-            if (is_string($row)) {
-                $message .= $row;
-            } else {
-                if ($row[0] == -1) {
-                    $row[0] = $terminalWidth - strlen($message);
-                }
-                $message .= $this->toColumn(
-                    chars: $row[0],
-                    text: $row[1],
-                    align: $row[2]??STR_PAD_RIGHT
-                );
-            }
-            $message .= ' ';
-        }
-        return trim($message);
-    }
-
-    private function toColumn(int $chars, mixed $text, int $align): string {
-        $short = ($align == STR_PAD_LEFT)
-            ? substr($text, -$chars)
-            : substr($text, 0, $chars);
-        if ($text != $short) {
-            $short = ($align == STR_PAD_LEFT)
-                ? '…'.substr($short,1)
-                : substr($short, 0, -1).'…';
-        }
-        return str_pad($short, $chars, ' ', $align);
+        ], 140);
     }
 }

src/Events/Instructor/ErrorRaised.php

@@ -0,0 +1,21 @@
+<?php
+
+namespace Cognesy\Instructor\Events\Instructor;
+
+use Cognesy\Instructor\Events\Event;
+use Throwable;
+
+class ErrorRaised extends Event
+{
+    public function __construct(
+        public Throwable $e
+    )
+    {
+        parent::__construct();
+    }
+
+    public function __toString(): string
+    {
+        return $this->e->getMessage();
+    }
+}

src/Events/Instructor/RequestReceived.php

@@ -15,6 +15,6 @@ public function __construct(
 
     public function __toString(): string
     {
-        return $this->format(json_encode($this->request));
+        return json_encode($this->request);
     }
 }

src/Events/Instructor/ResponseSent.php

@@ -14,6 +14,6 @@ public function __construct(
 
     public function __toString(): string
     {
-        return $this->format(json_encode($this->response));
+        return json_encode($this->response);
     }
 }

src/Events/LLM/ChunkReceived.php

@@ -13,6 +13,6 @@ public function __construct(
 
     public function __toString(): string
     {
-        return $this->format($this->chunk);
+        return $this->chunk;
     }
 }

src/Events/LLM/PartialJsonReceived.php

@@ -13,6 +13,6 @@ public function __construct(
 
     public function __toString(): string
     {
-        return $this->format($this->partialJson);
+        return $this->partialJson;
     }
 }

src/Events/LLM/RequestSent.php

@@ -13,6 +13,6 @@ public function __construct(
 
     public function __toString(): string
     {
-        return $this->format(json_encode($this->request));
+        return json_encode($this->request);
     }
 }

src/Events/LLM/ResponseReceived.php

@@ -13,6 +13,6 @@ public function __construct(
 
     public function __toString(): string
     {
-        return $this->format(json_encode($this->response));
+        return json_encode($this->response);
     }
 }

src/Events/LLM/StreamedResponseFinished.php

@@ -15,6 +15,6 @@ public function __construct(
 
     public function __toString(): string
     {
-        return $this->format(json_encode($this->lastResponse));
+        return json_encode($this->lastResponse);
     }
 }

src/Events/LLM/StreamedResponseReceived.php

@@ -13,6 +13,6 @@ public function __construct(
 
     public function __toString(): string
     {
-        return $this->format(json_encode($this->response));
+        return json_encode($this->response);
     }
 }

src/Events/RequestHandler/RequestSentToLLM.php

@@ -24,12 +24,12 @@ public function __construct(
 
     public function __toString(): string
     {
-        return $this->format(json_encode([
+        return json_encode([
             'messages' => $this->messages,
             'tool' => $this->responseModel->functionName,
             'tools' => $this->responseModel->functionCall,
             'model' => $this->request->model,
             'options' => $this->request->options
-        ]));
+        ]);
     }
 }

src/Events/RequestHandler/ResponseTransformationStarted.php → src/Events/RequestHandler/ResponseConvertedToObject.php

@@ -4,7 +4,7 @@
 
 use Cognesy\Instructor\Events\Event;
 
-class ResponseTransformationStarted extends Event
+class ResponseConvertedToObject extends Event
 {
     public function __construct(
         public mixed $object
@@ -14,6 +14,6 @@ public function __construct(
 
     public function __toString(): string
     {
-        return $this->format(json_encode($this->object));
+        return json_encode($this->object);
     }
 }

src/Events/RequestHandler/ResponseGenerated.php

@@ -6,10 +6,6 @@
 
 class ResponseGenerated extends Event
 {
-
-    /**
-     * @param mixed $response
-     */
     public function __construct(
         public mixed $response
     )
@@ -19,6 +15,6 @@ public function __construct(
 
     public function __toString(): string
     {
-        return $this->format(json_encode($this->response));
+        return json_encode($this->response);
     }
 }

src/Events/RequestHandler/ResponseGenerationFailed.php

@@ -0,0 +1,24 @@
+<?php
+namespace Cognesy\Instructor\Events\RequestHandler;
+
+use Cognesy\Instructor\Events\Event;
+
+class ResponseGenerationFailed extends Event
+{
+    public function __construct(
+        public int $retries,
+        public string $errors
+    )
+    {
+        parent::__construct();
+    }
+
+    public function __toString(): string
+    {
+        return json_encode([
+            'retries' => $this->retries,
+            'errors' => $this->errors
+        ]);
+    }
+}
+

src/Events/RequestHandler/ResponseModelBuilt.php

@@ -16,6 +16,6 @@ public function __construct(
 
     public function __toString(): string
     {
-        return $this->format(json_encode($this->requestedModel));
+        return json_encode($this->requestedModel);
     }
 }

src/Events/RequestHandler/ResponseReceivedFromLLM.php

@@ -14,8 +14,6 @@ public function __construct(
 
     public function __toString(): string
     {
-        return $this->format(json_encode(
-            $this->response
-        ));
+        return json_encode($this->response);
     }
 }

src/Events/RequestHandler/ResponseTransformationFinished.php → src/Events/RequestHandler/ResponseTransformed.php

@@ -4,7 +4,7 @@
 
 use Cognesy\Instructor\Events\Event;
 
-class ResponseTransformationFinished extends Event
+class ResponseTransformed extends Event
 {
     public function __construct(
         public mixed $result
@@ -14,6 +14,6 @@ public function __construct(
 
     public function __toString(): string
     {
-        return $this->format(json_encode($this->result));
+        return json_encode($this->result);
     }
 }