Merge pull request #620 from parterburn/paul/conversations

Add Conversations API

Author: alexrudall

README.md

@@ -77,6 +77,7 @@ Stream GPT-5 chats with the Responses API, initiate Realtime WebRTC conversation
     - [Vector Store Files](#vector-store-files)
     - [Vector Store File Batches](#vector-store-file-batches)
     - [Assistants](#assistants)
+    - [Conversations](#conversations)
     - [Threads and Messages](#threads-and-messages)
     - [Runs](#runs)
       - [Create and Run](#create-and-run)
@@ -1098,6 +1099,128 @@ client.vector_store_file_batches.cancel(
 )
 ```
 
+### Conversations
+
+The Conversations API enables you to create and manage persistent conversations with your models. This is useful for maintaining conversation state across multiple interactions.
+
+**Supported Endpoints:**
+- `POST /v1/conversations` - Create a conversation
+- `GET /v1/conversations/{id}` - Retrieve a conversation  
+- `PATCH /v1/conversations/{id}` - Modify a conversation
+- `DELETE /v1/conversations/{id}` - Delete a conversation
+- `POST /v1/conversations/{id}/items` - Create items in a conversation
+- `GET /v1/conversations/{id}/items` - List items in a conversation
+- `GET /v1/conversations/{id}/items/{item_id}` - Get a specific item
+- `DELETE /v1/conversations/{id}/items/{item_id}` - Delete an item
+
+#### Creating a Conversation
+
+To create a new conversation:
+
+```ruby
+response = client.conversations.create(
+  parameters: {
+    metadata: { purpose: "customer_support" }
+  }
+)
+conversation_id = response["id"]
+```
+
+#### Retrieving a Conversation
+
+To retrieve a specific conversation:
+
+```ruby
+conversation = client.conversations.retrieve(id: conversation_id)
+```
+
+#### Modifying a Conversation
+
+To update a conversation's metadata:
+
+```ruby
+response = client.conversations.modify(
+  id: conversation_id,
+  parameters: {
+    metadata: { status: "resolved" }
+  }
+)
+```
+
+#### Deleting a Conversation
+
+To delete a conversation:
+
+```ruby
+response = client.conversations.delete(id: conversation_id)
+```
+
+#### Managing Items in Conversations
+
+You can add, retrieve, and manage items within a conversation.
+
+##### Creating Items
+
+```ruby
+# Create multiple items at once
+response = client.conversations.create_items(
+  conversation_id: conversation_id,
+  parameters: {
+    items: [
+      {
+        type: "message",
+        role: "user",
+        content: [
+          { type: "input_text", text: "Hello!" }
+        ]
+      },
+      {
+        type: "message",
+        role: "assistant",
+        content: [
+          { type: "input_text", text: "How are you?" }
+        ]
+      }
+    ]
+  }
+)
+```
+
+##### Listing Items
+
+```ruby
+# List all items in a conversation
+response = client.conversations.list_items(conversation_id: conversation_id)
+items = response["data"]
+
+# With parameters
+response = client.conversations.list_items(
+  conversation_id: conversation_id,
+  parameters: { 
+    limit: 10,
+    order: "asc"
+  }
+)
+```
+
+##### Retrieving a Specific Item
+
+```ruby
+item = client.conversations.get_item(
+  conversation_id: conversation_id,
+  item_id: item_id
+)
+```
+
+##### Deleting an Item
+
+```ruby
+response = client.conversations.delete_item(
+  conversation_id: conversation_id,
+  item_id: item_id
+)
+```
+
 ### Assistants
 
 Assistants are stateful actors that can have many conversations and use tools to perform tasks (see [Assistant Overview](https://platform.openai.com/docs/assistants/overview)).

lib/openai.rb

@@ -21,6 +21,7 @@
 require_relative "openai/version"
 require_relative "openai/batches"
 require_relative "openai/usage"
+require_relative "openai/conversations"
 
 module OpenAI
   class Error < StandardError; end

lib/openai/client.rb

@@ -105,6 +105,10 @@ def usage
       @usage ||= OpenAI::Usage.new(client: self)
     end
 
+    def conversations
+      @conversations ||= OpenAI::Conversations.new(client: self)
+    end
+
     def azure?
       @api_type&.to_sym == :azure
     end

lib/openai/conversations.rb

@@ -0,0 +1,40 @@
+module OpenAI
+  class Conversations
+    def initialize(client:)
+      @client = client
+    end
+
+    def retrieve(id:)
+      @client.get(path: "/conversations/#{id}")
+    end
+
+    def create(parameters: {})
+      @client.json_post(path: "/conversations", parameters: parameters)
+    end
+
+    def modify(id:, parameters: {})
+      @client.json_post(path: "/conversations/#{id}", parameters: parameters)
+    end
+
+    def delete(id:)
+      @client.delete(path: "/conversations/#{id}")
+    end
+
+    # Item operations within a conversation
+    def create_items(conversation_id:, parameters: {})
+      @client.json_post(path: "/conversations/#{conversation_id}/items", parameters: parameters)
+    end
+
+    def list_items(conversation_id:, parameters: {})
+      @client.get(path: "/conversations/#{conversation_id}/items", parameters: parameters)
+    end
+
+    def get_item(conversation_id:, item_id:)
+      @client.get(path: "/conversations/#{conversation_id}/items/#{item_id}")
+    end
+
+    def delete_item(conversation_id:, item_id:)
+      @client.delete(path: "/conversations/#{conversation_id}/items/#{item_id}")
+    end
+  end
+end