feat: Add an interface for the ability to process speech-to-text asynchronously

This adds the ability to be able to send a request to a provider to create a transcript where the provider will give you an id and then send a webhook to you in the future when the job is done with that id. This is just supplying the interface that a provider can utilize in the future.

Author: dcaswell

src/Audio/PendingRequest.php

@@ -19,11 +19,11 @@ class PendingRequest
     use ConfiguresProviders;
     use HasProviderOptions;
 
-    protected string|Audio $input;
+    protected string|Audio|int $input;
 
     protected string $voice;
 
-    public function withInput(string|Audio $input): self
+    public function withInput(string|Audio|int $input): self
     {
         $this->input = $input;
 
@@ -59,6 +59,28 @@ public function asText(): TextResponse
         }
     }
 
+    public function asTextProviderId(): ProviderIdResponse
+    {
+        $request = $this->toSpeechToTextRequest();
+
+        try {
+            return $this->provider->speechToTextProviderId($request);
+        } catch (RequestException $e) {
+            $this->provider->handleRequestException($request->model(), $e);
+        }
+    }
+
+    public function asTextAsync(): TextResponse
+    {
+        $request = $this->toSpeechToTextAsyncRequest();
+
+        try {
+            return $this->provider->speechToTextAsync($request);
+        } catch (RequestException $e) {
+            $this->provider->handleRequestException($request->model(), $e);
+        }
+    }
+
     protected function toTextToSpeechRequest(): TextToSpeechRequest
     {
         if (! is_string($this->input)) {
@@ -91,4 +113,20 @@ protected function toSpeechToTextRequest(): SpeechToTextRequest
             providerOptions: $this->providerOptions,
         );
     }
+
+    protected function toSpeechToTextAsyncRequest(): SpeechToTextAsyncRequest
+    {
+        if (! is_string($this->input) && ! is_int($this->input)) {
+            throw new InvalidArgumentException('Async speech-to-text requires the input be the Provider ID as a string or integer');
+        }
+
+        return new SpeechToTextAsyncRequest(
+            model: $this->model,
+            providerKey: $this->providerKey(),
+            input: $this->input,
+            clientOptions: $this->clientOptions,
+            clientRetry: $this->clientRetry,
+            providerOptions: $this->providerOptions,
+        );
+    }
 }

src/Audio/ProviderIdResponse.php

@@ -0,0 +1,16 @@
+<?php
+declare(strict_types=1);
+
+namespace Prism\Prism\Audio;
+
+use Prism\Prism\ValueObjects\Usage;
+
+readonly class ProviderIdResponse
+{
+    public function __construct(
+        public string|int $id,
+        public ?Usage $usage = null,
+        /** @var array<string,mixed> */
+        public array $additionalContent = []
+    ) {}
+}

src/Audio/SpeechToTextAsyncRequest.php

@@ -0,0 +1,56 @@
+<?php
+declare(strict_types=1);
+
+namespace Prism\Prism\Audio;
+
+use Closure;
+use Prism\Prism\Concerns\ChecksSelf;
+use Prism\Prism\Concerns\HasProviderOptions;
+use Prism\Prism\Contracts\PrismRequest;
+
+class SpeechToTextAsyncRequest implements PrismRequest
+{
+    use ChecksSelf, HasProviderOptions;
+
+    public function __construct(
+        protected string $model,
+        protected string $providerKey,
+        protected string|int $input,
+        protected array $clientOptions,
+        protected array $clientRetry,
+        array $providerOptions = [],
+    ) {
+        $this->providerOptions = $providerOptions;
+    }
+
+    /**
+     * @return array{0: array<int, int>|int, 1?: Closure|int, 2?: ?callable, 3?: bool}
+     */
+    public function clientRetry(): array
+    {
+        return $this->clientRetry;
+    }
+
+    /**
+     * @return array<string, mixed>
+     */
+    public function clientOptions(): array
+    {
+        return $this->clientOptions;
+    }
+
+    public function input(): string|int
+    {
+        return $this->input;
+    }
+
+    public function model(): string
+    {
+        return $this->model;
+    }
+
+    public function provider(): string
+    {
+        return $this->providerKey;
+    }
+}

src/Providers/Provider.php

@@ -7,6 +7,8 @@
 use Generator;
 use Illuminate\Http\Client\RequestException;
 use Prism\Prism\Audio\AudioResponse as TextToSpeechResponse;
+use Prism\Prism\Audio\ProviderIdResponse;
+use Prism\Prism\Audio\SpeechToTextAsyncRequest;
 use Prism\Prism\Audio\SpeechToTextRequest;
 use Prism\Prism\Audio\TextResponse as SpeechToTextResponse;
 use Prism\Prism\Audio\TextToSpeechRequest;
@@ -56,6 +58,16 @@ public function speechToText(SpeechToTextRequest $request): SpeechToTextResponse
         throw PrismException::unsupportedProviderAction('speechToText', class_basename($this));
     }
 
+    public function speechToTextProviderId(SpeechToTextRequest $request): ProviderIdResponse
+    {
+        throw PrismException::unsupportedProviderAction('speechToTextProviderId', class_basename($this));
+    }
+
+    public function speechToTextAsync(SpeechToTextAsyncRequest $request): SpeechToTextResponse
+    {
+        throw PrismException::unsupportedProviderAction('speechToTextAsync', class_basename($this));
+    }
+
     /**
      * @return Generator<StreamEvent>
      */

tests/Audio/PendingRequestTest.php

@@ -0,0 +1,52 @@
+<?php
+
+declare(strict_types=1);
+
+use Prism\Prism\Audio\PendingRequest;
+use Prism\Prism\Audio\ProviderIdResponse;
+use Prism\Prism\Audio\SpeechToTextAsyncRequest;
+use Prism\Prism\Audio\SpeechToTextRequest;
+use Prism\Prism\Providers\Provider as ProviderContract;
+use Prism\Prism\ValueObjects\Media\Audio;
+use Tests\TestDoubles\TestProvider;
+
+beforeEach(function (): void {
+    $this->pendingRequest = new PendingRequest;
+});
+
+test('it generates a provider id response for speech to text', function (): void {
+    resolve('prism-manager')->extend('test-provider', fn ($config): ProviderContract => new TestProvider);
+
+    $audio = Audio::fromUrl('https://example.com/audio.mp3', 'audio/mpeg');
+
+    $response = $this->pendingRequest
+        ->using('test-provider', 'test-model')
+        ->withInput($audio)
+        ->asTextProviderId();
+
+    $provider = $this->pendingRequest->provider();
+
+    expect($response)
+        ->toBeInstanceOf(ProviderIdResponse::class)
+        ->and($response->id)->toBe('provider-id')
+        ->and($provider->request)->toBeInstanceOf(SpeechToTextRequest::class)
+        ->and($provider->request->input())->toBe($audio);
+});
+
+test('it generates a response for async speech to text', function (): void {
+    resolve('prism-manager')->extend('test-provider', fn ($config): ProviderContract => new TestProvider);
+
+    $providerId = 'provider-id-123';
+
+    $response = $this->pendingRequest
+        ->using('test-provider', 'test-model')
+        ->withInput($providerId)
+        ->asTextAsync();
+
+    $provider = $this->pendingRequest->provider();
+
+    expect($response->text)->toBe('Async transcript')
+        ->and($provider->request)->toBeInstanceOf(SpeechToTextAsyncRequest::class)
+        ->and($provider->request->model())->toBe('test-model')
+        ->and($provider->request->input())->toBe($providerId);
+});

tests/TestDoubles/TestProvider.php

@@ -5,6 +5,10 @@
 namespace Tests\TestDoubles;
 
 use Generator;
+use Prism\Prism\Audio\ProviderIdResponse;
+use Prism\Prism\Audio\SpeechToTextAsyncRequest;
+use Prism\Prism\Audio\SpeechToTextRequest;
+use Prism\Prism\Audio\TextResponse as AudioTextResponse;
 use Prism\Prism\Embeddings\Request as EmbeddingRequest;
 use Prism\Prism\Embeddings\Response as EmbeddingResponse;
 use Prism\Prism\Enums\FinishReason;
@@ -24,15 +28,15 @@
 
 class TestProvider extends Provider
 {
-    public StructuredRequest|TextRequest|EmbeddingRequest|ImageRequest $request;
+    public StructuredRequest|TextRequest|EmbeddingRequest|ImageRequest|SpeechToTextRequest|SpeechToTextAsyncRequest $request;
 
     /** @var array<string, mixed> */
     public array $clientOptions;
 
     /** @var array<mixed> */
     public array $clientRetry;
 
-    /** @var array<int, StructuredResponse|TextResponse|EmbeddingResponse|ImageResponse> */
+    /** @var array<int, StructuredResponse|TextResponse|EmbeddingResponse|ImageResponse|AudioTextResponse|ProviderIdResponse> */
     public array $responses = [];
 
     public $callCount = 0;
@@ -115,7 +119,27 @@ public function stream(TextRequest $request): Generator
         throw PrismException::unsupportedProviderAction(__METHOD__, class_basename($this));
     }
 
-    public function withResponse(StructuredResponse|TextResponse $response): Provider
+    #[\Override]
+    public function speechToTextProviderId(SpeechToTextRequest $request): ProviderIdResponse
+    {
+        $this->callCount++;
+
+        $this->request = $request;
+
+        return $this->responses[$this->callCount - 1] ?? new ProviderIdResponse('provider-id');
+    }
+
+    #[\Override]
+    public function speechToTextAsync(SpeechToTextAsyncRequest $request): AudioTextResponse
+    {
+        $this->callCount++;
+
+        $this->request = $request;
+
+        return $this->responses[$this->callCount - 1] ?? new AudioTextResponse('Async transcript');
+    }
+
+    public function withResponse(StructuredResponse|TextResponse|EmbeddingResponse|ImageResponse|AudioTextResponse|ProviderIdResponse $response): Provider
     {
         $this->responses[] = $response;