Add Conversations API documentation to README and integrate Conversations module in the client

Author: parterburn

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,122 @@ 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.
+
+#### Creating a Conversation
+
+To create a new conversation:
+
+```ruby
+response = client.conversations.create(
+ parameters: {
+ metadata: { purpose: "customer_support" }
+ }
+)
+conversation_id = response["id"]
+```
+
+#### Listing Conversations
+
+To list all conversations:
+
+```ruby
+response = client.conversations.list
+conversations = response["data"]
+
+# With parameters
+response = client.conversations.list(
+ parameters: { 
+ limit: 20,
+ order: "desc"
+ }
+)
+```
+
+#### 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 Messages in Conversations
+
+You can add, retrieve, and manage messages within a conversation:
+
+##### Creating a Message
+
+```ruby
+response = client.conversations.create_message(
+ conversation_id: conversation_id,
+ parameters: {
+ content: "Hello! How can I help you today?",
+ role: "assistant",
+ metadata: { message_type: "greeting" }
+ }
+)
+message_id = response["id"]
+```
+
+##### Listing Messages
+
+```ruby
+# List all messages in a conversation
+response = client.conversations.messages(conversation_id: conversation_id)
+messages = response["data"]
+
+# With parameters
+response = client.conversations.messages(
+ conversation_id: conversation_id,
+ parameters: { 
+ limit: 10,
+ order: "asc"
+ }
+)
+```
+
+##### Retrieving a Specific Message
+
+```ruby
+message = client.conversations.retrieve_message(
+ conversation_id: conversation_id,
+ message_id: message_id
+)
+```
+
+##### Deleting a Message
+
+```ruby
+response = client.conversations.delete_message(
+ conversation_id: conversation_id,
+ message_id: message_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,44 @@
+module OpenAI
+ class Conversations
+ def initialize(client:)
+ @client = client
+ end
+
+ def list(parameters: {})
+ @client.get(path: "/conversations", parameters: parameters)
+ 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
+
+ # Message operations within a conversation
+ def messages(conversation_id:, parameters: {})
+ @client.get(path: "/conversations/#{conversation_id}/messages", parameters: parameters)
+ end
+
+ def retrieve_message(conversation_id:, message_id:)
+ @client.get(path: "/conversations/#{conversation_id}/messages/#{message_id}")
+ end
+
+ def create_message(conversation_id:, parameters: {})
+ @client.json_post(path: "/conversations/#{conversation_id}/messages", parameters: parameters)
+ end
+
+ def delete_message(conversation_id:, message_id:)
+ @client.delete(path: "/conversations/#{conversation_id}/messages/#{message_id}")
+ end
+ end
+end

spec/openai/client/conversations_spec.rb

@@ -0,0 +1,203 @@
+RSpec.describe OpenAI::Client do
+ describe "#conversations" do
+ let(:conversation_id) do
+ VCR.use_cassette("#{cassette} setup") do
+ OpenAI::Client.new.conversations.create(parameters: {})["id"]
+ end
+ end
+ let(:message_id) do
+ VCR.use_cassette("#{cassette} message setup") do
+ OpenAI::Client.new.conversations.create_message(
+ conversation_id: conversation_id,
+ parameters: { content: "Hello, this is a test message" }
+ )["id"]
+ end
+ end
+
+ describe "#list" do
+ let(:cassette) { "conversations list" }
+ let(:response) { OpenAI::Client.new.conversations.list }
+
+ it "succeeds" do
+ VCR.use_cassette(cassette) do
+ expect(response["object"]).to eq("list")
+ end
+ end
+
+ context "with parameters" do
+ let(:response) do
+ OpenAI::Client.new.conversations.list(parameters: { limit: 10 })
+ end
+
+ it "succeeds with parameters" do
+ VCR.use_cassette(cassette) do
+ expect(response["object"]).to eq("list")
+ end
+ end
+ end
+ end
+
+ describe "#retrieve" do
+ let(:cassette) { "conversations retrieve" }
+ let(:response) { OpenAI::Client.new.conversations.retrieve(id: conversation_id) }
+
+ it "succeeds" do
+ VCR.use_cassette(cassette) do
+ expect(response["object"]).to eq("conversation")
+ end
+ end
+ end
+
+ describe "#create" do
+ let(:cassette) { "conversations create" }
+ let(:response) do
+ OpenAI::Client.new.conversations.create(parameters: {})
+ end
+
+ it "succeeds" do
+ VCR.use_cassette(cassette) do
+ expect(response["object"]).to eq("conversation")
+ end
+ end
+
+ context "with parameters" do
+ let(:response) do
+ OpenAI::Client.new.conversations.create(
+ parameters: { metadata: { purpose: "test" } }
+ )
+ end
+
+ it "succeeds with parameters" do
+ VCR.use_cassette(cassette) do
+ expect(response["object"]).to eq("conversation")
+ end
+ end
+ end
+ end
+
+ describe "#modify" do
+ let(:cassette) { "conversations modify" }
+ let(:response) do
+ OpenAI::Client.new.conversations.modify(
+ id: conversation_id,
+ parameters: { metadata: { modified: "true" } }
+ )
+ end
+
+ it "succeeds" do
+ VCR.use_cassette(cassette) do
+ expect(response["object"]).to eq("conversation")
+ end
+ end
+ end
+
+ describe "#delete" do
+ let(:cassette) { "conversations delete" }
+ let(:response) do
+ OpenAI::Client.new.conversations.delete(id: conversation_id)
+ end
+
+ it "succeeds" do
+ VCR.use_cassette(cassette) do
+ expect(response["object"]).to eq("conversation.deleted")
+ end
+ end
+ end
+
+ describe "#messages" do
+ let(:cassette) { "conversations messages" }
+ let(:response) do
+ OpenAI::Client.new.conversations.messages(conversation_id: conversation_id)
+ end
+
+ before { message_id }
+
+ it "succeeds" do
+ VCR.use_cassette(cassette) do
+ expect(response["object"]).to eq("list")
+ end
+ end
+
+ context "with parameters" do
+ let(:response) do
+ OpenAI::Client.new.conversations.messages(
+ conversation_id: conversation_id,
+ parameters: { limit: 5 }
+ )
+ end
+
+ it "succeeds with parameters" do
+ VCR.use_cassette(cassette) do
+ expect(response["object"]).to eq("list")
+ end
+ end
+ end
+ end
+
+ describe "#retrieve_message" do
+ let(:cassette) { "conversations retrieve message" }
+ let(:response) do
+ OpenAI::Client.new.conversations.retrieve_message(
+ conversation_id: conversation_id,
+ message_id: message_id
+ )
+ end
+
+ it "succeeds" do
+ VCR.use_cassette(cassette) do
+ expect(response["object"]).to eq("conversation.message")
+ end
+ end
+ end
+
+ describe "#create_message" do
+ let(:cassette) { "conversations create message" }
+ let(:response) do
+ OpenAI::Client.new.conversations.create_message(
+ conversation_id: conversation_id,
+ parameters: { content: "Hello, this is a test message" }
+ )
+ end
+
+ it "succeeds" do
+ VCR.use_cassette(cassette) do
+ expect(response["object"]).to eq("conversation.message")
+ end
+ end
+
+ context "with additional parameters" do
+ let(:response) do
+ OpenAI::Client.new.conversations.create_message(
+ conversation_id: conversation_id,
+ parameters: {
+ content: "Hello with metadata",
+ metadata: { test: "value" }
+ }
+ )
+ end
+
+ it "succeeds with additional parameters" do
+ VCR.use_cassette(cassette) do
+ expect(response["object"]).to eq("conversation.message")
+ end
+ end
+ end
+ end
+
+ describe "#delete_message" do
+ let(:cassette) { "conversations delete message" }
+ let(:response) do
+ OpenAI::Client.new.conversations.delete_message(
+ conversation_id: conversation_id,
+ message_id: message_id
+ )
+ end
+
+ it "succeeds" do
+ VCR.use_cassette(cassette) do
+ expect(response["object"]).to eq("conversation.message.deleted")
+ end
+ end
+ end
+ end
+end