feat(OpenAI): add Conversation API

README.md

@@ -30,6 +30,8 @@ If you or your business relies on this package, it's important to support the de
 - [Usage](#usage)
   - [Models Resource](#models-resource)
   - [Responses Resource](#responses-resource)
+  - [Responses Conversations Resource](#responses-conversations-resource)
+  - [Responses Conversations Items Resource](#responses-conversations-items-resource)
   - [Containers Resource](#containers-resource)
   - [Containers Files Resource](#containers-files-resource)
   - [Chat Resource](#chat-resource)
@@ -310,6 +312,148 @@ $response->hasMore; // false
 $response->toArray(); // ['object' => 'list', 'data' => [...], ...]
 ```
 
+### `Responses Conversations` Resource
+
+#### `create`
+
+Create a conversation.
+
+```php
+$response = $client->responses()->conversations()->create([
+    'metadata' => ['topic' => 'demo'],
+    'items' => [
+        [
+            'type' => 'message',
+            'role' => 'user',
+            'content' => 'Hello!'
+        ],
+    ],
+]);
+
+$response->id; // 'conv_123'
+$response->object; // 'conversation'
+$response->createdAt; // 1741900000
+$response->metadata; // ['topic' => 'demo']
+
+$response->toArray(); // ['id' => 'conv_123', 'object' => 'conversation', ...]
+```
+
+#### `retrieve`
+
+Retrieve a conversation by ID.
+
+```php
+$response = $client->responses()->conversations()->retrieve('conv_123');
+
+$response->id; // 'conv_123'
+$response->object; // 'conversation'
+$response->createdAt; // 1741900000
+
+$response->toArray(); // ['id' => 'conv_123', 'object' => 'conversation', ...]
+```
+
+#### `update`
+
+Update a conversation by ID.
+
+```php
+$response = $client->responses()->conversations()->update('conv_123', [
+    'metadata' => ['foo' => 'bar'],
+]);
+
+$response->id; // 'conv_123'
+$response->metadata; // ['foo' => 'bar']
+```
+
+#### `delete`
+
+Delete a conversation by ID.
+
+```php
+$response = $client->responses()->conversations()->delete('conv_123');
+
+$response->id; // 'conv_123'
+$response->object; // 'conversation.deleted'
+$response->deleted; // true
+
+$response->toArray(); // ['id' => 'conv_123', 'object' => 'conversation.deleted', 'deleted' => true]
+```
+
+### `Responses Conversations Items` Resource
+
+#### `create`
+
+Create items for a conversation.
+
+```php
+$response = $client->responses()->conversations()->items()->create('conv_123', [
+    'items' => [
+        [
+            'type' => 'message',
+            'role' => 'user',
+            'content' => [['type' => 'input_text', 'text' => 'Hello!']],
+        ],
+        [
+            'type' => 'message',
+            'role' => 'user',
+            'content' => [['type' => 'input_text', 'text' => 'How are you?']],
+        ],
+    ],
+]);
+
+$response->object; // 'list'
+
+foreach ($response->data as $item) {
+    $item->type; // 'message'
+    $item->id; // 'msg_abc'
+    $item->status; // 'completed'
+    $item->role; // 'user'
+}
+
+$response->firstId; // 'msg_abc'
+$response->lastId; // 'msg_abc'
+$response->hasMore; // false
+
+$response->toArray(); // ['object' => 'list', 'data' => [...], ...]
+```
+
+#### `list`
+
+List items for a conversation.
+
+```php
+$response = $client->responses()->conversations()->items()->list('conv_123', [
+    'limit' => 10,
+]);
+
+$response->object; // 'list'
+```
+
+#### `retrieve`
+
+Retrieve a specific item from a conversation.
+
+```php
+$response = $client->responses()->conversations()->items()->retrieve('conv_123', 'msg_abc', [
+    'include' => ['step_details'],
+]);
+
+$response->id; // 'msg_abc'
+$response->type; // 'message'
+$response->status; // 'completed'
+```
+
+#### `delete`
+
+Delete a specific item from a conversation. Returns the updated conversation.
+
+```php
+$response = $client->responses()->conversations()->items()->delete('conv_123', 'msg_abc');
+
+$response->id; // 'conv_123'
+$response->object; // 'conversation'
+```
+
 ### `Containers` Resource
 
 #### `create`

src/Actions/Conversations/ItemObjects.php

@@ -0,0 +1,73 @@
+<?php
+
+declare(strict_types=1);
+
+namespace OpenAI\Actions\Conversations;
+
+use OpenAI\Responses\Conversations\Objects\Message;
+use OpenAI\Responses\Responses\Input\ComputerToolCallOutput;
+use OpenAI\Responses\Responses\Input\FunctionToolCallOutput;
+use OpenAI\Responses\Responses\Output\OutputCodeInterpreterToolCall;
+use OpenAI\Responses\Responses\Output\OutputComputerToolCall;
+use OpenAI\Responses\Responses\Output\OutputFileSearchToolCall;
+use OpenAI\Responses\Responses\Output\OutputFunctionToolCall;
+use OpenAI\Responses\Responses\Output\OutputImageGenerationToolCall;
+use OpenAI\Responses\Responses\Output\OutputMcpApprovalRequest;
+use OpenAI\Responses\Responses\Output\OutputMcpCall;
+use OpenAI\Responses\Responses\Output\OutputMcpListTools;
+use OpenAI\Responses\Responses\Output\OutputReasoning;
+use OpenAI\Responses\Responses\Output\OutputWebSearchToolCall;
+
+/**
+ * @phpstan-import-type MessageType from Message
+ * @phpstan-import-type ComputerToolCallOutputType from ComputerToolCallOutput
+ * @phpstan-import-type FunctionToolCallOutputType from FunctionToolCallOutput
+ * @phpstan-import-type OutputComputerToolCallType from OutputComputerToolCall
+ * @phpstan-import-type OutputFileSearchToolCallType from OutputFileSearchToolCall
+ * @phpstan-import-type OutputFunctionToolCallType from OutputFunctionToolCall
+ * @phpstan-import-type OutputReasoningType from OutputReasoning
+ * @phpstan-import-type OutputWebSearchToolCallType from OutputWebSearchToolCall
+ * @phpstan-import-type OutputMcpListToolsType from OutputMcpListTools
+ * @phpstan-import-type OutputMcpApprovalRequestType from OutputMcpApprovalRequest
+ * @phpstan-import-type OutputMcpCallType from OutputMcpCall
+ * @phpstan-import-type OutputImageGenerationToolCallType from OutputImageGenerationToolCall
+ * @phpstan-import-type OutputCodeInterpreterToolCallType from OutputCodeInterpreterToolCall
+ *
+ * @phpstan-type ItemObjectTypes MessageType|ComputerToolCallOutputType|FunctionToolCallOutputType|OutputComputerToolCallType|OutputFileSearchToolCallType|OutputFunctionToolCallType|OutputReasoningType|OutputWebSearchToolCallType|OutputMcpListToolsType|OutputMcpApprovalRequestType|OutputMcpCallType|OutputImageGenerationToolCallType|OutputCodeInterpreterToolCallType
+ * @phpstan-type ConversationItemObjectTypes array<int, ItemObjectTypes>
+ * @phpstan-type ConversationItemObjectReturnType array<int, Message|ComputerToolCallOutput|FunctionToolCallOutput|OutputComputerToolCall|OutputFileSearchToolCall|OutputWebSearchToolCall|OutputFunctionToolCall|OutputReasoning|OutputMcpListTools|OutputMcpApprovalRequest|OutputMcpCall|OutputImageGenerationToolCall|OutputCodeInterpreterToolCall>
+ */
+final class ItemObjects
+{
+    /**
+     * @param  ConversationItemObjectTypes  $outputItems
+     * @return ConversationItemObjectReturnType
+     */
+    public static function parse(array $outputItems): array
+    {
+        return array_map(
+            fn (array $item): Message|ComputerToolCallOutput|FunctionToolCallOutput|OutputComputerToolCall|OutputFileSearchToolCall|OutputWebSearchToolCall|OutputFunctionToolCall|OutputReasoning|OutputMcpListTools|OutputMcpApprovalRequest|OutputMcpCall|OutputImageGenerationToolCall|OutputCodeInterpreterToolCall => match ($item['type']) {
+                'message' => Message::from($item),
+                'file_search_call' => OutputFileSearchToolCall::from($item),
+                'function_call' => OutputFunctionToolCall::from($item),
+                'function_call_output' => FunctionToolCallOutput::from($item),
+                'web_search_call' => OutputWebSearchToolCall::from($item),
+                'computer_call' => OutputComputerToolCall::from($item),
+                'computer_call_output' => ComputerToolCallOutput::from($item),
+                'reasoning' => OutputReasoning::from($item),
+                'mcp_list_tools' => OutputMcpListTools::from($item),
+                'mcp_approval_request' => OutputMcpApprovalRequest::from($item),
+                'mcp_call' => OutputMcpCall::from($item),
+                'image_generation_call' => OutputImageGenerationToolCall::from($item),
+                'code_interpreter_call' => OutputCodeInterpreterToolCall::from($item),
+                // todo
+                // local_shell_call
+                // local_shell_call_output
+                // mcp_approval_response
+                // custom_tool_call
+                // custom_tool_call_output
+            },
+            $outputItems,
+        );
+    }
+}

src/Actions/Responses/ItemObjects.php

@@ -61,6 +61,10 @@ public static function parse(array $outputItems): array
                 'mcp_call' => OutputMcpCall::from($item),
                 'image_generation_call' => OutputImageGenerationToolCall::from($item),
                 'code_interpreter_call' => OutputCodeInterpreterToolCall::from($item),
+                // todo
+                // local_shell_call
+                // local_shell_call_output
+                // mcp_approval_response
             },
             $outputItems,
         );

src/Actions/Responses/OutputObjects.php

@@ -53,6 +53,9 @@ public static function parse(array $outputItems): array
                 'mcp_call' => OutputMcpCall::from($item),
                 'image_generation_call' => OutputImageGenerationToolCall::from($item),
                 'code_interpreter_call' => OutputCodeInterpreterToolCall::from($item),
+                // todo
+                // local_shell_call
+                // custom_tool_call
             },
             $outputItems,
         );

src/Client.php

@@ -15,6 +15,7 @@
 use OpenAI\Resources\Chat;
 use OpenAI\Resources\Completions;
 use OpenAI\Resources\Containers;
+use OpenAI\Resources\Conversations;
 use OpenAI\Resources\Edits;
 use OpenAI\Resources\Embeddings;
 use OpenAI\Resources\Files;
@@ -48,6 +49,16 @@ public function responses(): Responses
         return new Responses($this->transporter);
     }
 
+    /**
+     * Create and manage conversations to store and retrieve conversation state across Response API calls.
+     *
+     * @see https://platform.openai.com/docs/api-reference/conversations
+     */
+    public function conversations(): Conversations
+    {
+        return new Conversations($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

@@ -7,6 +7,7 @@
 use OpenAI\Contracts\Resources\BatchesContract;
 use OpenAI\Contracts\Resources\ChatContract;
 use OpenAI\Contracts\Resources\CompletionsContract;
+use OpenAI\Contracts\Resources\ConversationsContract;
 use OpenAI\Contracts\Resources\EditsContract;
 use OpenAI\Contracts\Resources\EmbeddingsContract;
 use OpenAI\Contracts\Resources\FilesContract;
@@ -37,6 +38,13 @@ public function completions(): CompletionsContract;
      */
     public function responses(): ResponsesContract;
 
+    /**
+     * Create and manage conversations to store and retrieve conversation state across Response API calls.
+     *
+     * @see https://platform.openai.com/docs/api-reference/conversations
+     */
+    public function conversations(): ConversationsContract;
+
     /**
      * Communicate with a GPT-4o class model in real time using WebRTC or WebSockets. Supports text and audio inputs and outputs, along with audio transcriptions.
      *

src/Contracts/Resources/ConversationsContract.php

@@ -0,0 +1,50 @@
+<?php
+
+declare(strict_types=1);
+
+namespace OpenAI\Contracts\Resources;
+
+use OpenAI\Responses\Conversations\ConversationDeletedResponse;
+use OpenAI\Responses\Conversations\ConversationResponse;
+
+interface ConversationsContract
+{
+    /**
+     * Create a conversation
+     *
+     * @see https://platform.openai.com/docs/api-reference/conversations/create
+     *
+     * @param  array<string, mixed>  $parameters
+     */
+    public function create(array $parameters = []): ConversationResponse;
+
+    /**
+     * Retrieve a conversation by ID
+     *
+     * @see https://platform.openai.com/docs/api-reference/conversations/retrieve
+     */
+    public function retrieve(string $conversationId): ConversationResponse;
+
+    /**
+     * Update a conversation by ID
+     *
+     * @see https://platform.openai.com/docs/api-reference/conversations/update
+     *
+     * @param  array<string, mixed>  $parameters
+     */
+    public function update(string $conversationId, array $parameters): ConversationResponse;
+
+    /**
+     * Delete a conversation by ID
+     *
+     * @see https://platform.openai.com/docs/api-reference/conversations/delete
+     */
+    public function delete(string $conversationId): ConversationDeletedResponse;
+
+    /**
+     * Manage conversation items subresource.
+     *
+     * @see https://platform.openai.com/docs/api-reference/conversations/list-items
+     */
+    public function items(): ConversationsItemsContract;
+}

src/Contracts/Resources/ConversationsItemsContract.php

@@ -0,0 +1,46 @@
+<?php
+
+declare(strict_types=1);
+
+namespace OpenAI\Contracts\Resources;
+
+use OpenAI\Responses\Conversations\ConversationItem;
+use OpenAI\Responses\Conversations\ConversationItemList;
+use OpenAI\Responses\Conversations\ConversationResponse;
+
+interface ConversationsItemsContract
+{
+    /**
+     * Create items for a conversation
+     *
+     * @see https://platform.openai.com/docs/api-reference/conversations/create-item
+     *
+     * @param  array<string, mixed>  $parameters
+     */
+    public function create(string $conversationId, array $parameters): ConversationItemList;
+
+    /**
+     * List items for a conversation
+     *
+     * @see https://platform.openai.com/docs/api-reference/conversations/list-items
+     *
+     * @param  array<string, mixed>  $parameters
+     */
+    public function list(string $conversationId, array $parameters = []): ConversationItemList;
+
+    /**
+     * Retrieve a specific item from a conversation
+     *
+     * @see https://platform.openai.com/docs/api-reference/conversations/get-item
+     *
+     * @param  array<string, mixed>  $parameters
+     */
+    public function retrieve(string $conversationId, string $itemId, array $parameters = []): ConversationItem;
+
+    /**
+     * Delete a specific item from a conversation. Returns updated Conversation.
+     *
+     * @see https://platform.openai.com/docs/api-reference/conversations/delete-item
+     */
+    public function delete(string $conversationId, string $itemId): ConversationResponse;
+}