Skip to content

Commit 41ca204

Browse files
CJCrafterCJCrafter
committed
add ChatRequest.builder() as a more stable API
1 parent 6a9b300 commit 41ca204

File tree

2 files changed

+185
-2
lines changed

2 files changed

+185
-2
lines changed

‎src/main/kotlin/com/cjcrafter/openai/chat/ChatBot.kt‎

Lines changed: 15 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -94,6 +94,21 @@ class ChatBot @JvmOverloads constructor(
9494
* not handled by the main thread. It is crucial to consider thread safety
9595
* within the context of your program.
9696
*
97+
* Usage:
98+
* ```
99+
* val messages = mutableListOf("Write a poem".toUserMessage())
100+
* val request = ChatRequest("gpt-3.5-turbo", messages)
101+
* val bot = ChatBot(/* your key */)
102+
103+
* bot.streamResponseKotlin(request) {
104+
* print(choices[0].delta)
105+
*
106+
* // when finishReason != null, this is the last message (done generating new tokens)
107+
* if (choices[0].finishReason != null)
108+
* messages.add(choices[0].message)
109+
* }
110+
* ```
111+
*
97112
* @param request The input information for ChatGPT.
98113
* @param onResponse The method to call for each chunk.
99114
* @since 1.2.0

‎src/main/kotlin/com/cjcrafter/openai/chat/ChatRequest.kt‎

Lines changed: 170 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -36,7 +36,9 @@ import com.google.gson.annotations.SerializedName
3636
* @property frequencyPenalty Prevent repeating the same text. Defaults to `0.0`.
3737
* @property logitBias Increase/Decrease the chances of a specific token to appear in generated text. Defaults to `null`.
3838
* @property user Who sent this request (for moderation).
39-
* @constructor Create a chat request
39+
* @constructor
40+
* Use [builder] instead direct instantiation. This will ensure
41+
* backwards compatibility for Java developers.
4042
* @see ChatBot.generateResponse
4143
* @see <a href="https://platform.openai.com/docs/api-reference/completions/create">Chat API Reference</a>
4244
* @see <a href="https://platform.openai.com/docs/guides/chat">Chat User Reference</a>
@@ -54,4 +56,170 @@ data class ChatRequest @JvmOverloads constructor(
5456
@field:SerializedName("frequency_penalty") var frequencyPenalty: Float? = null,
5557
@field:SerializedName("logit_bias") var logitBias: Map<String, Float>? = null,
5658
var user: String? = null
57-
)
59+
) {
60+
61+
companion object {
62+
63+
/**
64+
* A static method that provides a new [Builder] instance for the
65+
* [ChatRequest] class.
66+
*
67+
* @return a new [Builder] instance for creating a [ChatRequest] object.
68+
*/
69+
@JvmStatic
70+
fun builder(): Builder = Builder()
71+
}
72+
73+
/**
74+
* [Builder] is a helper class to build a [ChatRequest] instance with a fluent API.
75+
* It provides methods for setting the properties of the [ChatRequest] object.
76+
* The [build] method returns a new [ChatRequest] instance with the specified properties.
77+
*
78+
* Usage:
79+
* ```
80+
* val chatRequest = ChatRequest.builder()
81+
* .model("gpt-3.5-turbo")
82+
* .messages(mutableListOf("Be as helpful as possible".toSystemMessage()))
83+
* .temperature(0.7f)
84+
* .build()
85+
* ```
86+
*
87+
* @property model The model used to generate the text. Recommended: `"gpt-3.5-turbo"` (without quotes).
88+
* @property messages A mutable list of previous messages from the conversation.
89+
* @property temperature How "creative" the results are. [0.0, 2.0]. Defaults to `1.0`.
90+
* @property topP Controls how "on topic" the tokens are. Defaults to `1.0`.
91+
* @property n Controls how many responses to generate. Numbers >1 will chew through your tokens. Defaults to `1`.
92+
* @property stream true=wait until entire message is generated, false=respond procedurally. Defaults to `false`.
93+
* @property stop The sequence used to stop generating tokens. Defaults to `null`.
94+
* @property maxTokens The maximum number of tokens to use. Defaults to `infinity`.
95+
* @property presencePenalty Prevent talking about duplicate topics. Defaults to `0.0`.
96+
* @property frequencyPenalty Prevent repeating the same text. Defaults to `0.0`.
97+
* @property logitBias Increase/Decrease the chances of a specific token to appear in generated text. Defaults to `null`.
98+
* @property user Who sent this request (for moderation).
99+
*/
100+
class Builder {
101+
102+
private lateinit var model: String
103+
private lateinit var messages: MutableList<ChatMessage>
104+
private var temperature: Float? = null
105+
private var topP: Float? = null
106+
private var n: Int? = null
107+
private var stop: String? = null
108+
private var maxTokens: Int? = null
109+
private var presencePenalty: Float? = null
110+
private var frequencyPenalty: Float? = null
111+
private var logitBias: Map<String, Float>? = null
112+
private var user: String? = null
113+
114+
/**
115+
* Sets the model used to generate the text.
116+
*
117+
* @param model the model to be used, e.g., `"gpt-3.5-turbo"`
118+
* @return the [Builder] instance with the updated model property.
119+
*/
120+
fun model(model: String) = apply { this.model = model }
121+
122+
/**
123+
* Sets the messages used in the conversation.
124+
*
125+
* @param messages a mutable list of previous messages from the conversation.
126+
* @return the [Builder] instance with the updated messages property.
127+
*/
128+
fun messages(messages: MutableList<ChatMessage>) = apply { this.messages = messages }
129+
130+
/**
131+
* Sets the temperature for the generated text.
132+
*
133+
* @param temperature a float value representing how "creative" the results are, ranging from 0.0 to 2.0. Defaults to `1.0`.
134+
* @return the [Builder] instance with the updated temperature property.
135+
*/
136+
fun temperature(temperature: Float?) = apply { this.temperature = temperature }
137+
138+
/**
139+
* Sets the topP value for the generated text.
140+
*
141+
* @param topP a float value controlling how "on topic" the tokens are. Defaults to `1.0`.
142+
* @return the [Builder] instance with the updated topP property.
143+
*/
144+
fun topP(topP: Float?) = apply { this.topP = topP }
145+
146+
/**
147+
* Sets the number of responses to generate.
148+
*
149+
* @param n an integer value controlling how many responses to generate. Numbers >1 will consume more tokens. Defaults to `1`.
150+
* @return the [Builder] instance with the updated n property.
151+
*/
152+
fun n(n: Int?) = apply { this.n = n }
153+
154+
/**
155+
* Sets the stop sequence for the generated text.
156+
*
157+
* @param stop a string representing the sequence used to stop generating tokens. Defaults to `null`.
158+
* @return the [Builder] instance with the updated stop property.
159+
*/
160+
fun stop(stop: String?) = apply { this.stop = stop }
161+
162+
/**
163+
* Sets the maximum number of tokens for the generated text.
164+
*
165+
* @param maxTokens an integer value representing the maximum number of tokens to use. Defaults to `infinity`.
166+
* @return the [Builder] instance with the updated maxTokens property.
167+
*/
168+
fun maxTokens(maxTokens: Int?) = apply { this.maxTokens = maxTokens }
169+
170+
/**
171+
* Sets the presence penalty for the generated text.
172+
*
173+
* @param presencePenalty a float value to prevent talking about duplicate topics. Defaults to `0.0`.
174+
* @return the [Builder] instance with the updated presencePenalty property.
175+
*/
176+
fun presencePenalty(presencePenalty: Float?) = apply { this.presencePenalty = presencePenalty }
177+
178+
/**
179+
* Sets the frequency penalty for the generated text.
180+
*
181+
* @param frequencyPenalty a float value to prevent repeating the same text. Defaults to `0.0`.
182+
* @return the [Builder] instance with the updated frequencyPenalty property.
183+
*/
184+
fun frequencyPenalty(frequencyPenalty: Float?) = apply { this.frequencyPenalty = frequencyPenalty }
185+
186+
/**
187+
* Sets the logit bias for the generated text.
188+
*
189+
* @param logitBias a map of strings to float values to increase/decrease the chances of specific tokens appearing in the generated text. Defaults to `null`.
190+
* @return the [Builder] instance with the updated logitBias property.
191+
*/
192+
fun logitBias(logitBias: Map<String, Float>?) = apply { this.logitBias = logitBias }
193+
194+
/**
195+
* Sets the user who sent the request (for moderation purposes).
196+
*
197+
* @param user a string representing the user who sent the request
198+
* @param user a string representing the user who sent the request.
199+
* @return the [Builder] instance with the updated user property.
200+
*/
201+
fun user(user: String?) = apply { this.user = user }
202+
203+
/**
204+
* Constructs a new [ChatRequest] instance with the properties set in the [Builder].
205+
*
206+
* @return a new [ChatRequest] instance with the specified properties.
207+
*/
208+
fun build(): ChatRequest {
209+
return ChatRequest(
210+
model = model,
211+
messages = messages,
212+
temperature = temperature,
213+
topP = topP,
214+
n = n,
215+
stream = false,
216+
stop = stop,
217+
maxTokens = maxTokens,
218+
presencePenalty = presencePenalty,
219+
frequencyPenalty = frequencyPenalty,
220+
logitBias = logitBias,
221+
user = user
222+
)
223+
}
224+
}
225+
}

0 commit comments

Comments
 (0)