feat(anthropic): text stream support (#266)

Author: sentiasa

docs/providers/anthropic.md

@@ -246,6 +246,7 @@ foreach ($messageChunks as $messageChunk) {
 }
 ```
 
+Note that when using streaming, Anthropic does not stream citations in the same way. Instead, of building the context as above, yield text to the browser in the usual way and pair text up with the relevant footnote using the `citationIndex` on the text chunk's additionalContent parameter.
 
 ## Considerations
 ### Message Order

src/Enums/ChunkType.php

@@ -0,0 +1,12 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Prism\Prism\Enums;
+
+enum ChunkType
+{
+    case Text;
+    case Thinking;
+    case Meta;
+}

src/Providers/Anthropic/Anthropic.php

@@ -10,7 +10,7 @@
 use Prism\Prism\Contracts\Provider;
 use Prism\Prism\Embeddings\Request as EmbeddingRequest;
 use Prism\Prism\Embeddings\Response as EmbeddingResponse;
-use Prism\Prism\Exceptions\PrismException;
+use Prism\Prism\Providers\Anthropic\Handlers\Stream;
 use Prism\Prism\Providers\Anthropic\Handlers\Structured;
 use Prism\Prism\Providers\Anthropic\Handlers\Text;
 use Prism\Prism\Structured\Request as StructuredRequest;
@@ -57,7 +57,12 @@ public function structured(StructuredRequest $request): StructuredResponse
     #[\Override]
     public function stream(TextRequest $request): Generator
     {
-        throw PrismException::unsupportedProviderAction(__METHOD__, class_basename($this));
+        $handler = new Stream($this->client(
+            $request->clientOptions(),
+            $request->clientRetry()
+        ));
+
+        return $handler->handle($request);
     }
 
     #[\Override]

src/Providers/Anthropic/Concerns/HandlesResponse.php

@@ -0,0 +1,71 @@
+<?php
+
+declare(strict_types=1);
+
+namespace Prism\Prism\Providers\Anthropic\Concerns;
+
+use Illuminate\Http\Client\Response;
+use Illuminate\Support\Arr;
+use Illuminate\Support\Carbon;
+use Illuminate\Support\Str;
+use Prism\Prism\Enums\Provider;
+use Prism\Prism\Exceptions\PrismProviderOverloadedException;
+use Prism\Prism\Exceptions\PrismRateLimitedException;
+use Prism\Prism\Exceptions\PrismRequestTooLargeException;
+use Prism\Prism\ValueObjects\ProviderRateLimit;
+
+trait HandlesResponse
+{
+    protected function handleResponseExceptions(Response $response): void
+    {
+        if ($response->getStatusCode() === 429) {
+            throw PrismRateLimitedException::make(
+                rateLimits: $this->processRateLimits($response),
+                retryAfter: $response->hasHeader('retry-after')
+                    ? (int) $response->getHeader('retry-after')[0]
+                    : null
+            );
+        }
+
+        if ($response->getStatusCode() === 529) {
+            throw PrismProviderOverloadedException::make(Provider::Anthropic);
+        }
+
+        if ($response->getStatusCode() === 413) {
+            throw PrismRequestTooLargeException::make(Provider::Anthropic);
+        }
+    }
+
+    /**
+     * @return array<int, ProviderRateLimit>
+     */
+    protected function processRateLimits(Response $response): array
+    {
+        $rate_limits = [];
+
+        foreach ($response->getHeaders() as $headerName => $headerValues) {
+            if (Str::startsWith($headerName, 'anthropic-ratelimit-') === false) {
+                continue;
+            }
+
+            $limit_name = Str::of($headerName)->after('anthropic-ratelimit-')->beforeLast('-')->toString();
+            $field_name = Str::of($headerName)->afterLast('-')->toString();
+            $rate_limits[$limit_name][$field_name] = $headerValues[0];
+        }
+
+        return array_values(Arr::map($rate_limits, function ($fields, $limit_name): ProviderRateLimit {
+            $resets_at = data_get($fields, 'reset');
+
+            return new ProviderRateLimit(
+                name: $limit_name,
+                limit: data_get($fields, 'limit') !== null
+                    ? (int) data_get($fields, 'limit')
+                    : null,
+                remaining: data_get($fields, 'remaining') !== null
+                    ? (int) data_get($fields, 'remaining')
+                    : null,
+                resetsAt: data_get($fields, 'reset') !== null ? new Carbon($resets_at) : null
+            );
+        }));
+    }
+}

src/Providers/Anthropic/Handlers/AnthropicHandlerAbstract.php

@@ -7,20 +7,17 @@
 use Illuminate\Http\Client\PendingRequest;
 use Illuminate\Http\Client\Response;
 use Illuminate\Support\Arr;
-use Illuminate\Support\Carbon;
-use Illuminate\Support\Str;
 use Prism\Prism\Contracts\PrismRequest;
 use Prism\Prism\Enums\Provider;
 use Prism\Prism\Exceptions\PrismException;
-use Prism\Prism\Exceptions\PrismProviderOverloadedException;
-use Prism\Prism\Exceptions\PrismRateLimitedException;
-use Prism\Prism\Exceptions\PrismRequestTooLargeException;
+use Prism\Prism\Providers\Anthropic\Concerns\HandlesResponse;
 use Prism\Prism\Providers\Anthropic\ValueObjects\MessagePartWithCitations;
-use Prism\Prism\ValueObjects\ProviderRateLimit;
 use Throwable;
 
 abstract class AnthropicHandlerAbstract
 {
+    use HandlesResponse;
+
     protected Response $httpResponse;
 
     public function __construct(protected PendingRequest $client, protected PrismRequest $request) {}
@@ -73,22 +70,7 @@ protected function extractCitations(array $data): ?array
 
     protected function handleResponseErrors(): void
     {
-        if ($this->httpResponse->getStatusCode() === 429) {
-            throw PrismRateLimitedException::make(
-                rateLimits: array_values($this->processRateLimits()),
-                retryAfter: $this->httpResponse->hasHeader('retry-after')
-                    ? (int) $this->httpResponse->getHeader('retry-after')[0]
-                    : null
-            );
-        }
-
-        if ($this->httpResponse->getStatusCode() === 529) {
-            throw PrismProviderOverloadedException::make(Provider::Anthropic);
-        }
-
-        if ($this->httpResponse->getStatusCode() === 413) {
-            throw PrismRequestTooLargeException::make(Provider::Anthropic);
-        }
+        $this->handleResponseExceptions($this->httpResponse);
 
         $data = $this->httpResponse->json();
 
@@ -123,39 +105,4 @@ protected function extractThinking(array $data): array
             'thinking_signature' => data_get($thinking, 'signature'),
         ];
     }
-
-    /**
-     * @return ProviderRateLimit[]
-     */
-    protected function processRateLimits(): array
-    {
-        $rate_limits = [];
-
-        foreach ($this->httpResponse->getHeaders() as $headerName => $headerValues) {
-            if (Str::startsWith($headerName, 'anthropic-ratelimit-') === false) {
-                continue;
-            }
-
-            $limit_name = Str::of($headerName)->after('anthropic-ratelimit-')->beforeLast('-')->toString();
-
-            $field_name = Str::of($headerName)->afterLast('-')->toString();
-
-            $rate_limits[$limit_name][$field_name] = $headerValues[0];
-        }
-
-        return array_values(Arr::map($rate_limits, function ($fields, $limit_name): ProviderRateLimit {
-            $resets_at = data_get($fields, 'reset');
-
-            return new ProviderRateLimit(
-                name: $limit_name,
-                limit: data_get($fields, 'limit') !== null
-                    ? (int) data_get($fields, 'limit')
-                    : null,
-                remaining: data_get($fields, 'remaining') !== null
-                    ? (int) data_get($fields, 'remaining')
-                    : null,
-                resetsAt: data_get($fields, 'reset') !== null ? new Carbon($resets_at) : null
-            );
-        }));
-    }
 }