feat: stream responses support

src/Contracts/Stream.php

@@ -0,0 +1,13 @@
+<?php
+
+namespace OpenAI\Contracts;
+
+interface Stream
+{
+    /**
+     * Iterates over the event-stream data.
+     *
+     * @return iterable<integer, string>
+     */
+    public function read(): iterable;
+}

src/Contracts/Transporter.php

@@ -8,6 +8,7 @@
 use OpenAI\Exceptions\TransporterException;
 use OpenAI\Exceptions\UnserializableResponse;
 use OpenAI\ValueObjects\Transporter\Payload;
+use OpenAI\ValueObjects\Transporter\Response;
 
 /**
  * @internal
@@ -16,12 +17,10 @@ interface Transporter
 {
     /**
      * Sends a request to a server.
-     **
-     * @return array<array-key, mixed>
      *
      * @throws ErrorException|UnserializableResponse|TransporterException
      */
-    public function requestObject(Payload $payload): array;
+    public function requestObject(Payload $payload): Response;
 
     /**
      * Sends a content request to a server.

src/Resources/Completions.php

@@ -22,9 +22,18 @@ public function create(array $parameters): CreateResponse
     {
         $payload = Payload::create('completions', $parameters);
 
-        /** @var array{id: string, object: string, created: int, model: string, choices: array<int, array{text: string, index: int, logprobs: array{tokens: array<int, string>, token_logprobs: array<int, float>, top_logprobs: array<int, string>|null, text_offset: array<int, int>}|null, finish_reason: string}>, usage: array{prompt_tokens: int, completion_tokens: int, total_tokens: int}} $result */
-        $result = $this->transporter->requestObject($payload);
+        $response = $this->transporter->requestObject($payload);
 
-        return CreateResponse::from($result);
+        if ($response->isStream()) {
+            /** @var \Generator<integer, array{id: string, object: string, created: int, model: string, choices: array<int, array{text: string, index: int, logprobs: array{tokens: array<int, string>, token_logprobs: array<int, float>, top_logprobs: array<int, string>|null, text_offset: array<int, int>}|null, finish_reason: null}>, usage: null}> $stream */
+            $stream = $response->stream();
+
+            return CreateResponse::fromStream($stream);
+        }
+
+        /** @var array{id: string, object: string, created: int, model: string, choices: array<int, array{text: string, index: int, logprobs: array{tokens: array<int, string>, token_logprobs: array<int, float>, top_logprobs: array<int, string>|null, text_offset: array<int, int>}|null, finish_reason: string}>, usage: array{prompt_tokens: int, completion_tokens: int|null, total_tokens: int}} $object */
+        $object = $response->object();
+
+        return CreateResponse::from($object);
     }
 }

src/Resources/Edits.php

@@ -23,7 +23,7 @@ public function create(array $parameters): CreateResponse
         $payload = Payload::create('edits', $parameters);
 
         /** @var array{object: string, created: int, choices: array<int, array{text: string, index: int}>, usage: array{prompt_tokens: int, completion_tokens: int, total_tokens: int}} $result */
-        $result = $this->transporter->requestObject($payload);
+        $result = $this->transporter->requestObject($payload)->object();
 
         return CreateResponse::from($result);
     }

src/Resources/Embeddings.php

@@ -23,7 +23,7 @@ public function create(array $parameters): CreateResponse
         $payload = Payload::create('embeddings', $parameters);
 
         /** @var array{object: string, data: array<int, array{object: string, embedding: array<int, float>, index: int}>, usage: array{prompt_tokens: int, total_tokens: int}} $result */
-        $result = $this->transporter->requestObject($payload);
+        $result = $this->transporter->requestObject($payload)->object();
 
         return CreateResponse::from($result);
     }

src/Resources/Files.php

@@ -24,7 +24,7 @@ public function list(): ListResponse
         $payload = Payload::list('files');
 
         /** @var array{object: string, data: array<int, array{id: string, object: string, created_at: int, bytes: int, filename: string, purpose: string, status: string, status_details: array<array-key, mixed>|null}>} $result */
-        $result = $this->transporter->requestObject($payload);
+        $result = $this->transporter->requestObject($payload)->object();
 
         return ListResponse::from($result);
     }
@@ -39,7 +39,7 @@ public function retrieve(string $file): RetrieveResponse
         $payload = Payload::retrieve('files', $file);
 
         /** @var array{id: string, object: string, created_at: int, bytes: int, filename: string, purpose: string, status: string, status_details: array<array-key, mixed>|null} $result */
-        $result = $this->transporter->requestObject($payload);
+        $result = $this->transporter->requestObject($payload)->object();
 
         return RetrieveResponse::from($result);
     }
@@ -68,7 +68,7 @@ public function upload(array $parameters): CreateResponse
         $payload = Payload::upload('files', $parameters);
 
         /** @var array{id: string, object: string, created_at: int, bytes: int, filename: string, purpose: string, status: string, status_details: array<array-key, mixed>|null} $result */
-        $result = $this->transporter->requestObject($payload);
+        $result = $this->transporter->requestObject($payload)->object();
 
         return CreateResponse::from($result);
     }
@@ -83,7 +83,7 @@ public function delete(string $file): DeleteResponse
         $payload = Payload::delete('files', $file);
 
         /** @var array{id: string, object: string, deleted: bool} $result */
-        $result = $this->transporter->requestObject($payload);
+        $result = $this->transporter->requestObject($payload)->object();
 
         return DeleteResponse::from($result);
     }

src/Resources/FineTunes.php

@@ -27,7 +27,7 @@ public function create(array $parameters): RetrieveResponse
         $payload = Payload::create('fine-tunes', $parameters);
 
         /** @var array{id: string, object: string, model: string, created_at: int, events: array<int, array{object: string, created_at: int, level: string, message: string}>, fine_tuned_model: ?string, hyperparams: array{batch_size: ?int, learning_rate_multiplier: ?float, n_epochs: int, prompt_loss_weight: float}, organization_id: string, result_files: array<int, array{id: string, object: string, created_at: int, bytes: int, filename: string, purpose: string, status: string, status_details: array<array-key, mixed>|null}>, status: string, validation_files: array<int, array{id: string, object: string, created_at: int, bytes: int, filename: string, purpose: string, status: string, status_details: array<array-key, mixed>|null}>, training_files: array<int, array{id: string, object: string, created_at: int, bytes: int, filename: string, purpose: string, status: string, status_details: array<array-key, mixed>|null}>, updated_at: int}  $result */
-        $result = $this->transporter->requestObject($payload);
+        $result = $this->transporter->requestObject($payload)->object();
 
         return RetrieveResponse::from($result);
     }
@@ -42,7 +42,7 @@ public function list(): ListResponse
         $payload = Payload::list('fine-tunes');
 
         /** @var array{object: string, data: array<int, array{id: string, object: string, model: string, created_at: int, events: array<int, array{object: string, created_at: int, level: string, message: string}>, fine_tuned_model: ?string, hyperparams: array{batch_size: ?int, learning_rate_multiplier: ?float, n_epochs: int, prompt_loss_weight: float}, organization_id: string, result_files: array<int, array{id: string, object: string, created_at: int, bytes: int, filename: string, purpose: string, status: string, status_details: array<array-key, mixed>|null}>, status: string, validation_files: array<int, array{id: string, object: string, created_at: int, bytes: int, filename: string, purpose: string, status: string, status_details: array<array-key, mixed>|null}>, training_files: array<int, array{id: string, object: string, created_at: int, bytes: int, filename: string, purpose: string, status: string, status_details: array<array-key, mixed>|null}>, updated_at: int}>} $result */
-        $result = $this->transporter->requestObject($payload);
+        $result = $this->transporter->requestObject($payload)->object();
 
         return ListResponse::from($result);
     }
@@ -57,7 +57,7 @@ public function retrieve(string $fineTuneId): RetrieveResponse
         $payload = Payload::retrieve('fine-tunes', $fineTuneId);
 
         /** @var array{id: string, object: string, model: string, created_at: int, events: array<int, array{object: string, created_at: int, level: string, message: string}>, fine_tuned_model: ?string, hyperparams: array{batch_size: ?int, learning_rate_multiplier: ?float, n_epochs: int, prompt_loss_weight: float}, organization_id: string, result_files: array<int, array{id: string, object: string, created_at: int, bytes: int, filename: string, purpose: string, status: string, status_details: array<array-key, mixed>|null}>, status: string, validation_files: array<int, array{id: string, object: string, created_at: int, bytes: int, filename: string, purpose: string, status: string, status_details: array<array-key, mixed>|null}>, training_files: array<int, array{id: string, object: string, created_at: int, bytes: int, filename: string, purpose: string, status: string, status_details: array<array-key, mixed>|null}>, updated_at: int}  $result */
-        $result = $this->transporter->requestObject($payload);
+        $result = $this->transporter->requestObject($payload)->object();
 
         return RetrieveResponse::from($result);
     }
@@ -72,7 +72,7 @@ public function cancel(string $fineTuneId): RetrieveResponse
         $payload = Payload::cancel('fine-tunes', $fineTuneId);
 
         /** @var array{id: string, object: string, model: string, created_at: int, events: array<int, array{object: string, created_at: int, level: string, message: string}>, fine_tuned_model: ?string, hyperparams: array{batch_size: ?int, learning_rate_multiplier: ?float, n_epochs: int, prompt_loss_weight: float}, organization_id: string, result_files: array<int, array{id: string, object: string, created_at: int, bytes: int, filename: string, purpose: string, status: string, status_details: array<array-key, mixed>|null}>, status: string, validation_files: array<int, array{id: string, object: string, created_at: int, bytes: int, filename: string, purpose: string, status: string, status_details: array<array-key, mixed>|null}>, training_files: array<int, array{id: string, object: string, created_at: int, bytes: int, filename: string, purpose: string, status: string, status_details: array<array-key, mixed>|null}>, updated_at: int}  $result */
-        $result = $this->transporter->requestObject($payload);
+        $result = $this->transporter->requestObject($payload)->object();
 
         return RetrieveResponse::from($result);
     }
@@ -87,7 +87,7 @@ public function listEvents(string $fineTuneId): ListEventsResponse
         $payload = Payload::retrieve('fine-tunes', $fineTuneId, '/events');
 
         /** @var array{object: string, data: array<int, array{object: string, created_at: int, level: string, message: string}>} $result */
-        $result = $this->transporter->requestObject($payload);
+        $result = $this->transporter->requestObject($payload)->object();
 
         return ListEventsResponse::from($result);
     }

src/Resources/Images.php

@@ -25,7 +25,7 @@ public function create(array $parameters): CreateResponse
         $payload = Payload::create('images/generations', $parameters);
 
         /** @var array{created: int, data: array<int, array{url?: string, b64_json?: string}>} $result */
-        $result = $this->transporter->requestObject($payload);
+        $result = $this->transporter->requestObject($payload)->object();
 
         return CreateResponse::from($result);
     }
@@ -42,7 +42,7 @@ public function edit(array $parameters): EditResponse
         $payload = Payload::upload('images/edits', $parameters);
 
         /** @var array{created: int, data: array<int, array{url?: string, b64_json?: string}>} $result */
-        $result = $this->transporter->requestObject($payload);
+        $result = $this->transporter->requestObject($payload)->object();
 
         return EditResponse::from($result);
     }
@@ -59,7 +59,7 @@ public function variation(array $parameters): VariationResponse
         $payload = Payload::upload('images/variations', $parameters);
 
         /** @var array{created: int, data: array<int, array{url?: string, b64_json?: string}>} $result */
-        $result = $this->transporter->requestObject($payload);
+        $result = $this->transporter->requestObject($payload)->object();
 
         return VariationResponse::from($result);
     }

src/Resources/Models.php

@@ -23,7 +23,7 @@ public function list(): ListResponse
         $payload = Payload::list('models');
 
         /** @var array{object: string, data: array<int, array{id: string, object: string, created: int, owned_by: string, permission: array<int, array{id: string, object: string, created: int, allow_create_engine: bool, allow_sampling: bool, allow_logprobs: bool, allow_search_indices: bool, allow_view: bool, allow_fine_tuning: bool, organization: string, group: ?string, is_blocking: bool}>, root: string, parent: ?string}>} $result */
-        $result = $this->transporter->requestObject($payload);
+        $result = $this->transporter->requestObject($payload)->object();
 
         return ListResponse::from($result);
     }
@@ -38,7 +38,7 @@ public function retrieve(string $model): RetrieveResponse
         $payload = Payload::retrieve('models', $model);
 
         /** @var array{id: string, object: string, created: int, owned_by: string, permission: array<int, array{id: string, object: string, created: int, allow_create_engine: bool, allow_sampling: bool, allow_logprobs: bool, allow_search_indices: bool, allow_view: bool, allow_fine_tuning: bool, organization: string, group: ?string, is_blocking: bool}>, root: string, parent: ?string} $result */
-        $result = $this->transporter->requestObject($payload);
+        $result = $this->transporter->requestObject($payload)->object();
 
         return RetrieveResponse::from($result);
     }
@@ -53,7 +53,7 @@ public function delete(string $model): DeleteResponse
         $payload = Payload::delete('models', $model);
 
         /** @var array{id: string, object: string, deleted: bool} $result */
-        $result = $this->transporter->requestObject($payload);
+        $result = $this->transporter->requestObject($payload)->object();
 
         return DeleteResponse::from($result);
     }

src/Resources/Moderations.php

@@ -23,7 +23,7 @@ public function create(array $parameters): CreateResponse
         $payload = Payload::create('moderations', $parameters);
 
         /** @var array{id: string, model: string, results: array<int, array{categories: array<string, bool>, category_scores: array<string, float>, flagged: bool}>} $result */
-        $result = $this->transporter->requestObject($payload);
+        $result = $this->transporter->requestObject($payload)->object();
 
         return CreateResponse::from($result);
     }