Add prism events

- Add Trace class that uses Laravel Context to keep track of operations stack
- Add events
- Add middlewares to trace http request and response.
- Streams are traced with a `StreamWrapper` to keep stream intact.
- Tracing of all not nested Prism operations is done in shared `PendingRequest` classes.
- Tracing of tool calls is done in `CallsTools` if called or where tools are called.
- Removed "'Maximum tool call" Exception in Anthropic Stream Handler and implemented `shouldContinue` check that does not raise an exception.
- Added `$step` property in Anthropic Stream Handler so that we are not passing `$depth` everywhere.
- Remove `isToolUseFinish` in `handleMessageStop`for ANthropic Stream Handler
- Added `Content-Type` headers for Gemini and OpenAI stream tests, `Content-type` is used in client middleware to recognize if it's a streamed response or normal.

Author: MrCrayon

src/Concerns/CallsTools.php

@@ -6,7 +6,10 @@
 
 use Illuminate\Support\ItemNotFoundException;
 use Illuminate\Support\MultipleItemsFoundException;
+use Prism\Prism\Events\ToolCallCompleted;
+use Prism\Prism\Events\ToolCallStarted;
 use Prism\Prism\Exceptions\PrismException;
+use Prism\Prism\Support\Trace;
 use Prism\Prism\Tool;
 use Prism\Prism\ValueObjects\ToolCall;
 use Prism\Prism\ValueObjects\ToolResult;
@@ -25,12 +28,16 @@ protected function callTools(array $tools, array $toolCalls): array
             function (ToolCall $toolCall) use ($tools): ToolResult {
                 $tool = $this->resolveTool($toolCall->name, $tools);
 
+                Trace::begin('tool_call', fn () => event(new ToolCallStarted($toolCall->name, $toolCall->arguments())));
+
                 try {
                     $result = call_user_func_array(
                         $tool->handle(...),
                         $toolCall->arguments()
                     );
 
+                    Trace::end(fn () => event(new ToolCallCompleted(attributes: ['result' => $result])));
+
                     return new ToolResult(
                         toolCallId: $toolCall->id,
                         toolCallResultId: $toolCall->resultId,
@@ -39,6 +46,8 @@ function (ToolCall $toolCall) use ($tools): ToolResult {
                         result: $result,
                     );
                 } catch (Throwable $e) {
+                    Trace::end(fn () => event(new ToolCallCompleted(exception: $e)));
+
                     if ($e instanceof PrismException) {
                         throw $e;
                     }

src/Concerns/InitializesClient.php

@@ -5,16 +5,62 @@
 namespace Prism\Prism\Concerns;
 
 use Illuminate\Http\Client\PendingRequest;
+use Illuminate\Support\Arr;
 use Illuminate\Support\Facades\Http;
+use Illuminate\Support\Str;
+use Prism\Prism\Events\HttpRequestCompleted;
+use Prism\Prism\Events\HttpRequestStarted;
+use Prism\Prism\Http\Stream\StreamWrapper;
+use Prism\Prism\Support\Trace;
 use Psr\Http\Message\RequestInterface;
 use Psr\Http\Message\ResponseInterface;
 
 trait InitializesClient
 {
     protected function baseClient(): PendingRequest
     {
-        return Http::withRequestMiddleware(fn (RequestInterface $request): RequestInterface => $request)
-            ->withResponseMiddleware(fn (ResponseInterface $response): ResponseInterface => $response)
-            ->throw();
+        return Http::throw()
+            ->withRequestMiddleware(
+                function (RequestInterface $request): RequestInterface {
+                    Trace::begin(
+                        'http',
+                        fn () => event(new HttpRequestStarted(
+                            method: $request->getMethod(),
+                            url: (string) $request->getUri(),
+                            headers: Arr::mapWithKeys(
+                                $request->getHeaders(),
+                                fn ($value, $key) => [
+                                    $key => in_array($key, ['Authentication', 'x-api-key', 'x-goog-api-key'])
+                                        ? Str::mask($value[0], '*', 3)
+                                        : $value,
+                                ]
+                            ),
+                            attributes: json_decode((string) $request->getBody(), true),
+                        )),
+                    );
+
+                    return $request;
+                }
+            )
+            ->withResponseMiddleware(
+                function (ResponseInterface $response): ResponseInterface {
+                    if (! str_contains($response->getHeaderLine('Content-Type'), 'text/event-stream')) {
+                        Trace::end(
+                            fn () => event(new HttpRequestCompleted(
+                                statusCode: $response->getStatusCode(),
+                                headers: $response->getHeaders(),
+                                attributes: json_decode((string) $response->getBody(), true) ?? [],
+                            ))
+                        );
+
+                        return $response;
+                    }
+
+                    // Wrap the stream to enable logging preserving the stream
+                    $loggingStream = new StreamWrapper($response);
+
+                    return $response->withBody($loggingStream);
+                }
+            );
     }
 }

src/Embeddings/PendingRequest.php

@@ -7,7 +7,10 @@
 use Prism\Prism\Concerns\ConfiguresClient;
 use Prism\Prism\Concerns\ConfiguresProviders;
 use Prism\Prism\Concerns\HasProviderOptions;
+use Prism\Prism\Events\PrismRequestCompleted;
+use Prism\Prism\Events\PrismRequestStarted;
 use Prism\Prism\Exceptions\PrismException;
+use Prism\Prism\Support\Trace;
 use Throwable;
 
 class PendingRequest
@@ -69,9 +72,17 @@ public function asEmbeddings(): Response
 
         $request = $this->toRequest();
 
+        Trace::begin('embeddings', fn () => event(new PrismRequestStarted($this->providerKey(), ['request' => $request])));
+
         try {
-            return $this->provider->embeddings($request);
+            $response = $this->provider->embeddings($request);
+
+            Trace::end(fn () => event(new PrismRequestCompleted($this->providerKey(), ['response' => $response])));
+
+            return $response;
         } catch (Throwable $e) {
+            Trace::end(fn () => event(new PrismRequestCompleted(exception: $e)));
+
             $this->provider->handleRequestExceptions($request->model(), $e);
         }
     }

src/Events/HttpRequestCompleted.php

@@ -0,0 +1,21 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Prism\Prism\Events;
+
+class HttpRequestCompleted extends TraceEvent
+{
+    /**
+     * @param  array<string, mixed>  $attributes
+     * @param  string[][]  $headers
+     */
+    public function __construct(
+        public readonly int $statusCode,
+        public readonly array $headers,
+        public readonly array $attributes,
+        public readonly ?\Throwable $exception = null
+    ) {
+        parent::__construct();
+    }
+}

src/Events/HttpRequestStarted.php

@@ -0,0 +1,21 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Prism\Prism\Events;
+
+class HttpRequestStarted extends TraceEvent
+{
+    /**
+     * @param  array<string, mixed>  $attributes
+     * @param  string[][]  $headers
+     */
+    public function __construct(
+        public readonly string $method,
+        public readonly string $url,
+        public readonly array $headers,
+        public readonly array $attributes,
+    ) {
+        parent::__construct();
+    }
+}

src/Events/PrismRequestCompleted.php

@@ -0,0 +1,19 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Prism\Prism\Events;
+
+class PrismRequestCompleted extends TraceEvent
+{
+    /**
+     * @param  array<string, mixed>  $attributes
+     */
+    public function __construct(
+        public readonly string $provider = '',
+        public readonly array $attributes = [],
+        public readonly ?\Throwable $exception = null
+    ) {
+        parent::__construct();
+    }
+}

src/Events/PrismRequestStarted.php

@@ -0,0 +1,18 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Prism\Prism\Events;
+
+class PrismRequestStarted extends TraceEvent
+{
+    /**
+     * @param  array<string, mixed>  $attributes
+     */
+    public function __construct(
+        public readonly string $provider,
+        public readonly array $attributes
+    ) {
+        parent::__construct();
+    }
+}

src/Events/ToolCallCompleted.php

@@ -0,0 +1,18 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Prism\Prism\Events;
+
+class ToolCallCompleted extends TraceEvent
+{
+    /**
+     * @param  array<string, mixed>  $attributes
+     */
+    public function __construct(
+        public readonly array $attributes = [],
+        public readonly ?\Throwable $exception = null
+    ) {
+        parent::__construct();
+    }
+}

src/Events/ToolCallStarted.php

@@ -0,0 +1,18 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Prism\Prism\Events;
+
+class ToolCallStarted extends TraceEvent
+{
+    /**
+     * @param  array<string, mixed>  $attributes
+     */
+    public function __construct(
+        public readonly string $toolName,
+        public readonly array $attributes
+    ) {
+        parent::__construct();
+    }
+}

src/Events/TraceEvent.php

@@ -0,0 +1,25 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Prism\Prism\Events;
+
+use Illuminate\Foundation\Events\Dispatchable;
+use Illuminate\Queue\SerializesModels;
+use Prism\Prism\Support\Trace;
+
+/**
+ * @property-read array{traceId:string, parentTraceId:string|null, traceName:string, startTime:float, endTime:float|null}|null $trace
+ */
+class TraceEvent
+{
+    use Dispatchable, SerializesModels;
+
+    /** @var array{traceId:string, parentTraceId:string|null, traceName:string, startTime:float, endTime:float|null}|null */
+    public readonly ?array $trace;
+
+    public function __construct()
+    {
+        $this->trace = Trace::get();
+    }
+}