feat(OpenAI): add Response retrieve streamed (#713)

* Retrieve streamed response

* Ensure the stream parameter is a string for retrieval

* Allow setting stream parameter to different value

* Added interface methods

* Added docs

* Added test

* Fix docblocks

* Stream parameter is string

* Fixed mock

Author: boboldehampsink

README.md

@@ -303,6 +303,20 @@ $response->truncation; // 'disabled'
 $response->toArray(); // ['id' => 'resp_67ccd2bed1ec8190b14f964abc054267', ...]
 ```
 
+#### `retrieve streamed`
+
+When you retrieve a Response with stream set to true, the server will emit server-sent events to the client as the Response is generated. All events and their payloads can be found in [OpenAI docs](https://platform.openai.com/docs/api-reference/responses-streaming).
+
+```php
+$stream = $client->responses()->retrieveStreamed('resp_67ccd2bed1ec8190b14f964abc054267', [
+    'starting_after' => '2',
+]);
+
+foreach ($stream as $response) {
+    $response->event; // 'response.created'
+}
+```
+
 #### `cancel`
 
 Cancel a model response (background request) with the given ID.

src/Contracts/Resources/ResponsesContract.php

@@ -42,6 +42,16 @@ public function createStreamed(array $parameters): StreamResponse;
      */
     public function retrieve(string $id): RetrieveResponse;
 
+    /**
+     * Retrieves a streamed response.
+     *
+     * @see https://platform.openai.com/docs/api-reference/responses/retrieve
+     *
+     * @param  array<string, mixed>  $parameters
+     * @return StreamResponse<CreateStreamedResponse>
+     */
+    public function retrieveStreamed(string $id, array $parameters = []): StreamResponse;
+
     /**
      * Cancels a model response with the given ID. Must be marked as 'background' to be cancellable.
      *

src/Resources/Concerns/Streamable.php

@@ -9,13 +9,13 @@ trait Streamable
     /**
      * @param  array<string, mixed>  $parameters
      */
-    private function ensureNotStreamed(array $parameters, string $fallbackFunction = 'createStreamed'): void
+    private function ensureNotStreamed(array $parameters, string $fallbackFunction = 'createStreamed', mixed $streamValue = true): void
     {
         if (! isset($parameters['stream'])) {
             return;
         }
 
-        if ($parameters['stream'] !== true) {
+        if ($parameters['stream'] !== $streamValue) {
             return;
         }
 
@@ -28,9 +28,9 @@ private function ensureNotStreamed(array $parameters, string $fallbackFunction =
      * @param  array<string, mixed>  $parameters
      * @return array<string, mixed>
      */
-    private function setStreamParameter(array $parameters): array
+    private function setStreamParameter(array $parameters, mixed $streamValue = true): array
     {
-        $parameters['stream'] = true;
+        $parameters['stream'] = $streamValue;
 
         return $parameters;
     }

src/Resources/Responses.php

@@ -80,6 +80,26 @@ public function retrieve(string $id): RetrieveResponse
         return RetrieveResponse::from($response->data(), $response->meta());
     }
 
+    /**
+     * When you retrieve a Response with stream set to true,
+     * the server will emit server-sent events to the client as the Response is resumed.
+     *
+     * @see https://platform.openai.com/docs/api-reference/responses-streaming
+     *
+     * @param  array<string, mixed>  $parameters
+     * @return StreamResponse<CreateStreamedResponse>
+     */
+    public function retrieveStreamed(string $id, array $parameters = []): StreamResponse
+    {
+        $parameters = $this->setStreamParameter($parameters, 'true'); // Ensure the parameter is a string for retrieval
+
+        $payload = Payload::retrieve('responses', $id, parameters: $parameters);
+
+        $response = $this->transporter->requestStream($payload);
+
+        return new StreamResponse(CreateStreamedResponse::class, $response);
+    }
+
     /**
      * Cancels a model response with the given ID. Must be marked as 'background' to be cancellable.
      *

src/Testing/Resources/ResponsesTestResource.php

@@ -40,6 +40,11 @@ public function retrieve(string $id): RetrieveResponse
         return $this->record(__FUNCTION__, func_get_args());
     }
 
+    public function retrieveStreamed(string $id, array $parameters = []): StreamResponse
+    {
+        return $this->record(__FUNCTION__, func_get_args());
+    }
+
     public function list(string $id, array $parameters = []): ListInputItems
     {
         return $this->record(__FUNCTION__, func_get_args());

tests/Resources/Responses.php

@@ -316,6 +316,74 @@
         ->toBeInstanceOf(MetaInformation::class);
 });
 
+test('retrieve streamed', function () {
+    $response = new Response(
+        headers: metaHeaders(),
+        body: new Stream(responseCompletionStream()),
+    );
+
+    $client = mockStreamClient('GET', 'responses/resp_67ccf18ef5fc8190b16dbee19bc54e5f087bb177ab789d5c', [
+        'starting_after' => '2',
+        'stream' => 'true',
+    ], $response);
+
+    $result = $client->responses()->retrieveStreamed('resp_67ccf18ef5fc8190b16dbee19bc54e5f087bb177ab789d5c', [
+        'starting_after' => '2',
+    ]);
+
+    expect($result)
+        ->toBeInstanceOf(StreamResponse::class)
+        ->toBeInstanceOf(IteratorAggregate::class);
+
+    expect($result->getIterator())
+        ->toBeInstanceOf(Iterator::class);
+
+    $current = $result->getIterator()->current();
+    expect($current)
+        ->toBeInstanceOf(CreateStreamedResponse::class);
+    expect($current->event)
+        ->toBe('response.created');
+    expect($current->response)
+        ->toBeInstanceOf(StreamedResponse::class);
+    expect($current->response->response)
+        ->toBeInstanceOf(CreateResponse::class);
+    expect($current->response->response->id)
+        ->toBe('resp_67ccf18ef5fc8190b16dbee19bc54e5f087bb177ab789d5c');
+    expect($current->response->response->object)
+        ->toBe('response');
+    expect($current->response->response->createdAt)
+        ->toBe(1741484430);
+    expect($current->response->response->status)
+        ->toBe('in_progress');
+    expect($current->response->response->error)
+        ->toBeNull();
+    expect($current->response->response->incompleteDetails)
+        ->toBeNull();
+    expect($current->response->response->instructions)
+        ->toBeNull();
+    expect($current->response->response->maxOutputTokens)
+        ->toBeNull();
+    expect($current->response->response->model)
+        ->toBe('gpt-4o-2024-08-06');
+    expect($current->response->response->output)
+        ->toBeArray();
+    expect($current->response->response->output)
+        ->toHaveCount(0);
+    expect($current->response->response->parallelToolCalls)
+        ->toBeTrue();
+    expect($current->response->response->previousResponseId)
+        ->toBeNull();
+    expect($current->response->response->temperature)
+        ->toBe(1.0);
+    expect($current->response->response->toolChoice)
+        ->toBe('auto');
+    expect($current->response->response->topP)
+        ->toBe(1.0);
+
+    expect($result->meta())
+        ->toBeInstanceOf(MetaInformation::class);
+});
+
 test('cancel', function () {
     $client = mockClient('POST', 'responses/resp_67ccf18ef5fc8190b16dbee19bc54e5f087bb177ab789d5c/cancel', [
     ], \OpenAI\ValueObjects\Transporter\Response::from(retrieveResponseResource(), metaHeaders()));