Skip to content

Commit d9acfa7

Browse files
parterburnparterburn
committed
Add Conversations API documentation to README and integrate Conversations module in the client
1 parent 98f3a9a commit d9acfa7

File tree

5 files changed

+369
-0
lines changed

5 files changed

+369
-0
lines changed

‎README.md‎

Lines changed: 117 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -77,6 +77,7 @@ Stream GPT-5 chats with the Responses API, initiate Realtime WebRTC conversation
7777
- [Vector Store Files](#vector-store-files)
7878
- [Vector Store File Batches](#vector-store-file-batches)
7979
- [Assistants](#assistants)
80+
- [Conversations](#conversations)
8081
- [Threads and Messages](#threads-and-messages)
8182
- [Runs](#runs)
8283
- [Create and Run](#create-and-run)
@@ -1098,6 +1099,122 @@ client.vector_store_file_batches.cancel(
10981099
)
10991100
```
11001101

1102+
### Conversations
1103+
1104+
The Conversations API enables you to create and manage persistent conversations with your models. This is useful for maintaining conversation state across multiple interactions.
1105+
1106+
#### Creating a Conversation
1107+
1108+
To create a new conversation:
1109+
1110+
```ruby
1111+
response = client.conversations.create(
1112+
parameters: {
1113+
metadata: { purpose: "customer_support" }
1114+
}
1115+
)
1116+
conversation_id = response["id"]
1117+
```
1118+
1119+
#### Listing Conversations
1120+
1121+
To list all conversations:
1122+
1123+
```ruby
1124+
response = client.conversations.list
1125+
conversations = response["data"]
1126+
1127+
# With parameters
1128+
response = client.conversations.list(
1129+
parameters: {
1130+
limit: 20,
1131+
order: "desc"
1132+
}
1133+
)
1134+
```
1135+
1136+
#### Retrieving a Conversation
1137+
1138+
To retrieve a specific conversation:
1139+
1140+
```ruby
1141+
conversation = client.conversations.retrieve(id: conversation_id)
1142+
```
1143+
1144+
#### Modifying a Conversation
1145+
1146+
To update a conversation's metadata:
1147+
1148+
```ruby
1149+
response = client.conversations.modify(
1150+
id: conversation_id,
1151+
parameters: {
1152+
metadata: { status: "resolved" }
1153+
}
1154+
)
1155+
```
1156+
1157+
#### Deleting a Conversation
1158+
1159+
To delete a conversation:
1160+
1161+
```ruby
1162+
response = client.conversations.delete(id: conversation_id)
1163+
```
1164+
1165+
#### Managing Messages in Conversations
1166+
1167+
You can add, retrieve, and manage messages within a conversation:
1168+
1169+
##### Creating a Message
1170+
1171+
```ruby
1172+
response = client.conversations.create_message(
1173+
conversation_id: conversation_id,
1174+
parameters: {
1175+
content: "Hello! How can I help you today?",
1176+
role: "assistant",
1177+
metadata: { message_type: "greeting" }
1178+
}
1179+
)
1180+
message_id = response["id"]
1181+
```
1182+
1183+
##### Listing Messages
1184+
1185+
```ruby
1186+
# List all messages in a conversation
1187+
response = client.conversations.messages(conversation_id: conversation_id)
1188+
messages = response["data"]
1189+
1190+
# With parameters
1191+
response = client.conversations.messages(
1192+
conversation_id: conversation_id,
1193+
parameters: {
1194+
limit: 10,
1195+
order: "asc"
1196+
}
1197+
)
1198+
```
1199+
1200+
##### Retrieving a Specific Message
1201+
1202+
```ruby
1203+
message = client.conversations.retrieve_message(
1204+
conversation_id: conversation_id,
1205+
message_id: message_id
1206+
)
1207+
```
1208+
1209+
##### Deleting a Message
1210+
1211+
```ruby
1212+
response = client.conversations.delete_message(
1213+
conversation_id: conversation_id,
1214+
message_id: message_id
1215+
)
1216+
```
1217+
11011218
### Assistants
11021219

11031220
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‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -21,6 +21,7 @@
2121
require_relative "openai/version"
2222
require_relative "openai/batches"
2323
require_relative "openai/usage"
24+
require_relative "openai/conversations"
2425

2526
module OpenAI
2627
class Error < StandardError; end

‎lib/openai/client.rb‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -105,6 +105,10 @@ def usage
105105
@usage ||= OpenAI::Usage.new(client: self)
106106
end
107107

108+
def conversations
109+
@conversations ||= OpenAI::Conversations.new(client: self)
110+
end
111+
108112
def azure?
109113
@api_type&.to_sym == :azure
110114
end

‎lib/openai/conversations.rb‎

Lines changed: 44 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,44 @@
1+
module OpenAI
2+
class Conversations
3+
def initialize(client:)
4+
@client = client
5+
end
6+
7+
def list(parameters: {})
8+
@client.get(path: "/conversations", parameters: parameters)
9+
end
10+
11+
def retrieve(id:)
12+
@client.get(path: "/conversations/#{id}")
13+
end
14+
15+
def create(parameters: {})
16+
@client.json_post(path: "/conversations", parameters: parameters)
17+
end
18+
19+
def modify(id:, parameters: {})
20+
@client.json_post(path: "/conversations/#{id}", parameters: parameters)
21+
end
22+
23+
def delete(id:)
24+
@client.delete(path: "/conversations/#{id}")
25+
end
26+
27+
# Message operations within a conversation
28+
def messages(conversation_id:, parameters: {})
29+
@client.get(path: "/conversations/#{conversation_id}/messages", parameters: parameters)
30+
end
31+
32+
def retrieve_message(conversation_id:, message_id:)
33+
@client.get(path: "/conversations/#{conversation_id}/messages/#{message_id}")
34+
end
35+
36+
def create_message(conversation_id:, parameters: {})
37+
@client.json_post(path: "/conversations/#{conversation_id}/messages", parameters: parameters)
38+
end
39+
40+
def delete_message(conversation_id:, message_id:)
41+
@client.delete(path: "/conversations/#{conversation_id}/messages/#{message_id}")
42+
end
43+
end
44+
end

‎spec/openai/client/conversations_spec.rb‎

Lines changed: 203 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,203 @@
1+
RSpec.describe OpenAI::Client do
2+
describe "#conversations" do
3+
let(:conversation_id) do
4+
VCR.use_cassette("#{cassette} setup") do
5+
OpenAI::Client.new.conversations.create(parameters: {})["id"]
6+
end
7+
end
8+
let(:message_id) do
9+
VCR.use_cassette("#{cassette} message setup") do
10+
OpenAI::Client.new.conversations.create_message(
11+
conversation_id: conversation_id,
12+
parameters: { content: "Hello, this is a test message" }
13+
)["id"]
14+
end
15+
end
16+
17+
describe "#list" do
18+
let(:cassette) { "conversations list" }
19+
let(:response) { OpenAI::Client.new.conversations.list }
20+
21+
it "succeeds" do
22+
VCR.use_cassette(cassette) do
23+
expect(response["object"]).to eq("list")
24+
end
25+
end
26+
27+
context "with parameters" do
28+
let(:response) do
29+
OpenAI::Client.new.conversations.list(parameters: { limit: 10 })
30+
end
31+
32+
it "succeeds with parameters" do
33+
VCR.use_cassette(cassette) do
34+
expect(response["object"]).to eq("list")
35+
end
36+
end
37+
end
38+
end
39+
40+
describe "#retrieve" do
41+
let(:cassette) { "conversations retrieve" }
42+
let(:response) { OpenAI::Client.new.conversations.retrieve(id: conversation_id) }
43+
44+
it "succeeds" do
45+
VCR.use_cassette(cassette) do
46+
expect(response["object"]).to eq("conversation")
47+
end
48+
end
49+
end
50+
51+
describe "#create" do
52+
let(:cassette) { "conversations create" }
53+
let(:response) do
54+
OpenAI::Client.new.conversations.create(parameters: {})
55+
end
56+
57+
it "succeeds" do
58+
VCR.use_cassette(cassette) do
59+
expect(response["object"]).to eq("conversation")
60+
end
61+
end
62+
63+
context "with parameters" do
64+
let(:response) do
65+
OpenAI::Client.new.conversations.create(
66+
parameters: { metadata: { purpose: "test" } }
67+
)
68+
end
69+
70+
it "succeeds with parameters" do
71+
VCR.use_cassette(cassette) do
72+
expect(response["object"]).to eq("conversation")
73+
end
74+
end
75+
end
76+
end
77+
78+
describe "#modify" do
79+
let(:cassette) { "conversations modify" }
80+
let(:response) do
81+
OpenAI::Client.new.conversations.modify(
82+
id: conversation_id,
83+
parameters: { metadata: { modified: "true" } }
84+
)
85+
end
86+
87+
it "succeeds" do
88+
VCR.use_cassette(cassette) do
89+
expect(response["object"]).to eq("conversation")
90+
end
91+
end
92+
end
93+
94+
describe "#delete" do
95+
let(:cassette) { "conversations delete" }
96+
let(:response) do
97+
OpenAI::Client.new.conversations.delete(id: conversation_id)
98+
end
99+
100+
it "succeeds" do
101+
VCR.use_cassette(cassette) do
102+
expect(response["object"]).to eq("conversation.deleted")
103+
end
104+
end
105+
end
106+
107+
describe "#messages" do
108+
let(:cassette) { "conversations messages" }
109+
let(:response) do
110+
OpenAI::Client.new.conversations.messages(conversation_id: conversation_id)
111+
end
112+
113+
before { message_id }
114+
115+
it "succeeds" do
116+
VCR.use_cassette(cassette) do
117+
expect(response["object"]).to eq("list")
118+
end
119+
end
120+
121+
context "with parameters" do
122+
let(:response) do
123+
OpenAI::Client.new.conversations.messages(
124+
conversation_id: conversation_id,
125+
parameters: { limit: 5 }
126+
)
127+
end
128+
129+
it "succeeds with parameters" do
130+
VCR.use_cassette(cassette) do
131+
expect(response["object"]).to eq("list")
132+
end
133+
end
134+
end
135+
end
136+
137+
describe "#retrieve_message" do
138+
let(:cassette) { "conversations retrieve message" }
139+
let(:response) do
140+
OpenAI::Client.new.conversations.retrieve_message(
141+
conversation_id: conversation_id,
142+
message_id: message_id
143+
)
144+
end
145+
146+
it "succeeds" do
147+
VCR.use_cassette(cassette) do
148+
expect(response["object"]).to eq("conversation.message")
149+
end
150+
end
151+
end
152+
153+
describe "#create_message" do
154+
let(:cassette) { "conversations create message" }
155+
let(:response) do
156+
OpenAI::Client.new.conversations.create_message(
157+
conversation_id: conversation_id,
158+
parameters: { content: "Hello, this is a test message" }
159+
)
160+
end
161+
162+
it "succeeds" do
163+
VCR.use_cassette(cassette) do
164+
expect(response["object"]).to eq("conversation.message")
165+
end
166+
end
167+
168+
context "with additional parameters" do
169+
let(:response) do
170+
OpenAI::Client.new.conversations.create_message(
171+
conversation_id: conversation_id,
172+
parameters: {
173+
content: "Hello with metadata",
174+
metadata: { test: "value" }
175+
}
176+
)
177+
end
178+
179+
it "succeeds with additional parameters" do
180+
VCR.use_cassette(cassette) do
181+
expect(response["object"]).to eq("conversation.message")
182+
end
183+
end
184+
end
185+
end
186+
187+
describe "#delete_message" do
188+
let(:cassette) { "conversations delete message" }
189+
let(:response) do
190+
OpenAI::Client.new.conversations.delete_message(
191+
conversation_id: conversation_id,
192+
message_id: message_id
193+
)
194+
end
195+
196+
it "succeeds" do
197+
VCR.use_cassette(cassette) do
198+
expect(response["object"]).to eq("conversation.message.deleted")
199+
end
200+
end
201+
end
202+
end
203+
end

0 commit comments

Comments
 (0)