Add support for Responses API

README.md

@@ -28,6 +28,7 @@ If you or your business relies on this package, it's important to support the de
 - [Get Started](#get-started)
 - [Usage](#usage)
   - [Models Resource](#models-resource)
+  - [Responses Resource](#responses-resource)
   - [Chat Resource](#chat-resource)
   - [Completions Resource](#completions-resource)
   - [Audio Resource](#audio-resource)
@@ -154,6 +155,215 @@ $response->deleted; // true
 $response->toArray(); // ['id' => 'curie:ft-acmeco-2021-03-03-21-44-20', ...]
 ```
 
+### `Responses` Resource
+
+#### `create`
+
+Creates a model response. Provide text or image inputs to generate text or JSON outputs. Have the model call your own custom code or use built-in tools like web search or file search to use your own data as input for the model's response.
+
+```php
+$response = $client->responses()->create([
+    'model' => 'gpt-4o-mini',
+    'tools' => [
+        [
+            'type' => 'web_search_preview'
+        ]
+    ],
+    'input' => "what was a positive news story from today?",
+    'temperature' => 0.7,
+    'max_output_tokens' => 150,
+    'tool_choice' => 'auto',
+    'parallel_tool_calls' => true,
+    'store' => true,
+    'metadata' => [
+        'user_id' => '123',
+        'session_id' => 'abc456'
+    ]
+]);
+
+$response->id; // 'resp_67ccd2bed1ec8190b14f964abc054267'
+$response->object; // 'response'
+$response->createdAt; // 1741476542
+$response->status; // 'completed'
+$response->model; // 'gpt-4o-mini'
+
+// Access output content
+foreach ($response->output as $output) {
+    $output->type; // 'message'
+    $output->id; // 'msg_67ccd2bf17f0819081ff3bb2cf6508e6'
+    $output->status; // 'completed'
+    $output->role; // 'assistant'
+
+    foreach ($output->content as $content) {
+        $content->type; // 'output_text'
+        $content->text; // The response text
+        $content->annotations; // Any annotations in the response
+    }
+}
+
+// Access usage information
+$response->usage->inputTokens; // 36
+$response->usage->outputTokens; // 87
+$response->usage->totalTokens; // 123
+
+$response->toArray(); // ['id' => 'resp_67ccd2bed1ec8190b14f964abc054267', ...]
+```
+
+#### `create streamed`
+
+When you create a Response with stream set to true, the server will emit server-sent events to the client as the Response is generated.
+
+```php
+$stream = $client->responses()->createStreamed([
+    'model' => 'gpt-4o-mini',
+    'tools' => [
+        [
+            'type' => 'web_search_preview'
+        ]
+    ],
+    'input' => "what was a positive news story from today?",
+    'stream' => true
+]);
+
+foreach ($stream as $response) {
+    $response->id; // 'resp_67ccd2bed1ec8190b14f964abc054267'
+    $response->object; // 'response'
+    $response->createdAt; // 1741476542
+
+    foreach ($response->output as $output) {
+        // Process streaming output
+        echo $output->content[0]->text;
+    }
+}
+```
+
+### `retrieve`
+
+Retrieves a model response with the given ID.
+
+```php
+$response = $client->responses()->retrieve('resp_67ccd2bed1ec8190b14f964abc054267');
+
+$response->id; // 'resp_67ccd2bed1ec8190b14f964abc054267'
+$response->object; // 'response'
+$response->createdAt; // 1741476542
+$response->status; // 'completed'
+$response->error; // null
+$response->incompleteDetails; // null
+$response->instructions; // null
+$response->maxOutputTokens; // null
+$response->model; // 'gpt-4o-2024-08-06'
+$response->parallelToolCalls; // true
+$response->previousResponseId; // null
+$response->store; // true
+$response->temperature; // 1.0
+$response->toolChoice; // 'auto'
+$response->topP; // 1.0
+$response->truncation; // 'disabled'
+
+$response->toArray(); // ['id' => 'resp_67ccd2bed1ec8190b14f964abc054267', ...]
+```
+
+### `delete`
+
+Deletes a model response with the given ID.
+
+```php
+$response = $client->responses()->delete('resp_67ccd2bed1ec8190b14f964abc054267');
+
+$response->id; // 'resp_67ccd2bed1ec8190b14f964abc054267'
+$response->object; // 'response'
+$response->deleted; // true
+
+$response->toArray(); // ['id' => 'resp_67ccd2bed1ec8190b14f964abc054267', 'deleted' => true, ...]
+```
+
+### `list`
+
+Lists input items for a response with the given ID.
+
+```php
+$response = $client->responses()->list('resp_67ccd2bed1ec8190b14f964abc054267', [
+    'limit' => 10,
+    'order' => 'desc'
+]);
+
+$response->object; // 'list'
+
+foreach ($response->data as $item) {
+    $item->type; // 'message'
+    $item->id; // Response item ID
+    $item->status; // 'completed'
+    $item->role; // 'user' or 'assistant'
+
+    foreach ($item->content as $content) {
+        $content->type; // Content type
+        $content->text; // Content text
+        $content->annotations; // Content annotations
+    }
+}
+
+$response->firstId; // First item ID in the list
+$response->lastId; // Last item ID in the list
+$response->hasMore; // Whether there are more items to fetch
+
+$response->toArray(); // ['object' => 'list', 'data' => [...], ...]
+```
+
+### `Completions` Resource
+
+#### `create`
+
+Creates a completion for the provided prompt and parameters.
+
+```php
+$response = $client->completions()->create([
+    'model' => 'gpt-3.5-turbo-instruct',
+    'prompt' => 'Say this is a test',
+    'max_tokens' => 6,
+    'temperature' => 0
+]);
+
+$response->id; // 'cmpl-uqkvlQyYK7bGYrRHQ0eXlWi7'
+$response->object; // 'text_completion'
+$response->created; // 1589478378
+$response->model; // 'gpt-3.5-turbo-instruct'
+
+foreach ($response->choices as $choice) {
+    $choice->text; // '\n\nThis is a test'
+    $choice->index; // 0
+    $choice->logprobs; // null
+    $choice->finishReason; // 'length' or null
+}
+
+$response->usage->promptTokens; // 5,
+$response->usage->completionTokens; // 6,
+$response->usage->totalTokens; // 11
+
+$response->toArray(); // ['id' => 'cmpl-uqkvlQyYK7bGYrRHQ0eXlWi7', ...]
+```
+
+#### `create streamed`
+
+Creates a streamed completion for the provided prompt and parameters.
+
+```php
+$stream = $client->completions()->createStreamed([
+        'model' => 'gpt-3.5-turbo-instruct',
+        'prompt' => 'Hi',
+        'max_tokens' => 10,
+    ]);
+
+foreach($stream as $response){
+    $response->choices[0]->text;
+}
+// 1. iteration => 'I'
+// 2. iteration => ' am'
+// 3. iteration => ' very'
+// 4. iteration => ' excited'
+// ...
+```
+
 ### `Chat` Resource
 
 #### `create`

src/Client.php

@@ -21,6 +21,7 @@
 use OpenAI\Resources\Images;
 use OpenAI\Resources\Models;
 use OpenAI\Resources\Moderations;
+use OpenAI\Resources\Responses;
 use OpenAI\Resources\Threads;
 use OpenAI\Resources\VectorStores;
 
@@ -34,6 +35,16 @@ public function __construct(private readonly TransporterContract $transporter)
         // ..
     }
 
+    /**
+     * Manage responses to assist models with tasks.
+     *
+     * @see https://platform.openai.com/docs/api-reference/responses
+     */
+    public function responses(): Responses
+    {
+        return new Responses($this->transporter);
+    }
+
     /**
      * Given a prompt, the model will return one or more predicted completions, and can also return the probabilities
      * of alternative tokens at each position.

src/Contracts/ClientContract.php

@@ -15,6 +15,7 @@
 use OpenAI\Contracts\Resources\ImagesContract;
 use OpenAI\Contracts\Resources\ModelsContract;
 use OpenAI\Contracts\Resources\ModerationsContract;
+use OpenAI\Contracts\Resources\ResponsesContract;
 use OpenAI\Contracts\Resources\ThreadsContract;
 use OpenAI\Contracts\Resources\VectorStoresContract;
 
@@ -28,6 +29,13 @@ interface ClientContract
      */
     public function completions(): CompletionsContract;
 
+    /**
+     * Manage responses to assist models with tasks.
+     *
+     * @see https://platform.openai.com/docs/api-reference/responses
+     */
+    public function responses(): ResponsesContract;
+
     /**
      * Given a chat conversation, the model will return a chat completion response.
      *

src/Contracts/Resources/ResponsesContract.php

@@ -0,0 +1,60 @@
+<?php
+
+declare(strict_types=1);
+
+namespace OpenAI\Contracts\Resources;
+
+use OpenAI\Responses\Responses\CreateResponse;
+use OpenAI\Responses\Responses\CreateStreamedResponse;
+use OpenAI\Responses\Responses\DeleteResponse;
+use OpenAI\Responses\Responses\ListInputItems;
+use OpenAI\Responses\Responses\RetrieveResponse;
+use OpenAI\Responses\StreamResponse;
+
+interface ResponsesContract
+{
+    /**
+     * Creates a model response.
+     * Provide text or image inputs to generate text or JSON outputs.
+     * Have the model call your own custom code or use built-in tools
+     * like web search or file search to use your own data as input for the model's response.
+     *
+     * @see https://platform.openai.com/docs/api-reference/responses/create
+     *
+     * @param  array<string, mixed>  $parameters
+     */
+    public function create(array $parameters): CreateResponse;
+
+    /**
+     * Create a streamed response.
+     *
+     * @see https://platform.openai.com/docs/api-reference/responses/create
+     *
+     * @param  array<string, mixed>  $parameters
+     * @return StreamResponse<CreateStreamedResponse>
+     */
+    public function createStreamed(array $parameters): StreamResponse;
+
+    /**
+     * Retrieves a model response with the given ID.
+     *
+     * @see https://platform.openai.com/docs/api-reference/responses/retrieve
+     */
+    public function retrieve(string $id): RetrieveResponse;
+
+    /**
+     * Deletes a model response with the given ID.
+     *
+     * @see https://platform.openai.com/docs/api-reference/responses/delete
+     */
+    public function delete(string $id): DeleteResponse;
+
+    /**
+     * Returns a list of input items for a given response.
+     *
+     * @see https://platform.openai.com/docs/api-reference/responses/input-items
+     *
+     * @param  array<string, mixed>  $parameters
+     */
+    public function list(string $id, array $parameters = []): ListInputItems;
+}