Skip to content

Commit 1405a31

Browse files
CJCrafterCJCrafter
committed
Add request/response classes for completions
1 parent de24e07 commit 1405a31

File tree

7 files changed

+387
-18
lines changed

7 files changed

+387
-18
lines changed

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

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -5,7 +5,7 @@ import com.google.gson.JsonObject
55
import com.google.gson.annotations.SerializedName
66

77
/**
8-
* The OpenAI API returns a list of [ChatChoice]. Each chat choice has a
8+
* The OpenAI API returns a list of `ChatChoice`. Each choice has a
99
* generated message ([ChatChoice.message]) and a finish reason
1010
* ([ChatChoice.finishReason]). For most use cases, you only need the generated
1111
* message.

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

Lines changed: 15 additions & 16 deletions
Original file line numberDiff line numberDiff line change
@@ -6,7 +6,7 @@ import com.google.gson.annotations.SerializedName
66
* [ChatRequest] holds the configurable options that can be sent to the OpenAI
77
* Chat API. For most use cases, you only need to set [model] and [messages].
88
* For more detailed descriptions for each option, refer to the
9-
* [Chat Uncyclo](https://platform.openai.com/docs/api-reference/chat)
9+
* [Chat Uncyclo](https://platform.openai.com/docs/api-reference/chat).
1010
*
1111
* [messages] stores **ALL** previous messages from the conversation. It is
1212
* **YOUR RESPONSIBILITY** to store and update this list for your conversations
@@ -49,7 +49,7 @@ data class ChatRequest @JvmOverloads constructor(
4949
var temperature: Float? = null,
5050
@field:SerializedName("top_p") var topP: Float? = null,
5151
var n: Int? = null,
52-
@Deprecated("Use ChatBot#streamResponse") var stream: Boolean? = null,
52+
@Deprecated("Use OpenAI#streamChatCompletion") var stream: Boolean? = null,
5353
var stop: String? = null,
5454
@field:SerializedName("max_tokens") var maxTokens: Int? = null,
5555
@field:SerializedName("presence_penalty") var presencePenalty: Float? = null,
@@ -58,20 +58,8 @@ data class ChatRequest @JvmOverloads constructor(
5858
var user: String? = null
5959
) {
6060

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-
7361
/**
74-
* [Builder] is a helper class to build a [ChatRequest] instance with a fluent API.
62+
* [Builder] is a helper class to build a [ChatRequest] instance with a stable API.
7563
* It provides methods for setting the properties of the [ChatRequest] object.
7664
* The [build] method returns a new [ChatRequest] instance with the specified properties.
7765
*
@@ -80,7 +68,6 @@ data class ChatRequest @JvmOverloads constructor(
8068
* val chatRequest = ChatRequest.builder()
8169
* .model("gpt-3.5-turbo")
8270
* .messages(mutableListOf("Be as helpful as possible".toSystemMessage()))
83-
* .temperature(0.7f)
8471
* .build()
8572
* ```
8673
*
@@ -222,4 +209,16 @@ data class ChatRequest @JvmOverloads constructor(
222209
)
223210
}
224211
}
212+
213+
companion object {
214+
215+
/**
216+
* A static method that provides a new [Builder] instance for the
217+
* [ChatRequest] class.
218+
*
219+
* @return a new [Builder] instance for creating a [ChatRequest] object.
220+
*/
221+
@JvmStatic
222+
fun builder(): Builder = Builder()
223+
}
225224
}

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

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -7,7 +7,7 @@ import java.time.ZonedDateTime
77
import java.util.*
88

99
/**
10-
* The [ChatResponse] contains all the data returned by the OpenAI Chat API.
10+
* The `ChatResponse` contains all the data returned by the OpenAI Chat API.
1111
* For most use cases, [ChatResponse.get] (passing 0 to the index argument) is
1212
* all you need.
1313
*

‎src/main/kotlin/com/cjcrafter/openai/completions/CompletionChoice.kt

Lines changed: 28 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,28 @@
1+
package com.cjcrafter.openai.completions
2+
3+
import com.cjcrafter.openai.FinishReason
4+
import com.google.gson.annotations.SerializedName
5+
6+
/**
7+
* The OpenAI API returns a list of `CompletionChoice`. Each choice has a
8+
* generated message ([CompletionChoice.text]) and a finish reason
9+
* ([CompletionChoice.finishReason]). For most use cases, you only need the
10+
* generated text.
11+
*
12+
* By default, only 1 choice is generated (since [CompletionRequest.n] == 1).
13+
* When you increase `n` or provide a list of prompts (called batching),
14+
* there will be multiple choices.
15+
*
16+
* @property text The generated text.
17+
* @property index The index in the list... This is 0 for most use cases.
18+
* @property logprobs List of logarithmic probabilities for each token in the generated text.
19+
* @property finishReason The reason the bot stopped generating tokens.
20+
* @constructor Create empty Completion choice, for internal usage.
21+
* @see FinishReason
22+
*/
23+
data class CompletionChoice(
24+
val text: String,
25+
val index: Int,
26+
val logprobs: List<Float>?,
27+
@field:SerializedName("finish_reason") val finishReason: FinishReason
28+
)

‎src/main/kotlin/com/cjcrafter/openai/completions/CompletionRequest.kt

Lines changed: 255 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,255 @@
1+
package com.cjcrafter.openai.completions
2+
3+
import com.google.gson.annotations.SerializedName
4+
5+
/**
6+
* `CompletionRequest` holds the configurable options that can be sent to the OpenAI
7+
* Completions API. For most use cases, you only need to set [model] and [prompt].
8+
* For more detailed descriptions for each option, refer to the
9+
* [Completions Uncyclo](https://platform.openai.com/docs/api-reference/completions/create).
10+
*
11+
* [prompt] can be either a singular `String`, a `List<String>`, or a `String[]`.
12+
* Providing multiple prompts is called [batching](https://platform.openai.com/docs/guides/rate-limits/batching-requests),
13+
* and it can be used to reduce rate limit errors. This will cause the [CompletionResponse]
14+
* to have multiple choices.
15+
*
16+
* You should not set [stream]. The stream option is handled using []
17+
*
18+
* @property model ID of the model to use.
19+
* @property prompt The prompt(s) to generate completions for (either a `String`, `List<String>`, or `String[]`)
20+
* @property suffix The suffix that comes after a completion of inserted text.
21+
* @property maxTokens The maximum number of tokens to generate in the completion.
22+
* @property temperature What sampling temperature to use, between 0 and 2.
23+
* @property topP An alternative to sampling with temperature, called nucleus sampling, where the model considers the results of the tokens with top_p probability mass.
24+
* @property n How many completions to generate for each prompt.
25+
* @property stream Whether to stream back partial progress.
26+
* @property logprobs Include the log probabilities on the logprobs most likely tokens, as well the chosen tokens.
27+
* @property echo Echo back the prompt in addition to the completion.
28+
* @property stop Up to 4 sequences where the API will stop generating further tokens.
29+
* @property presencePenalty Number between -2.0 and 2.0. Positive values penalize new tokens based on whether they appear in the text so far, increasing the model's likelihood to talk about new topics.
30+
* @property frequencyPenalty Number between -2.0 and 2.0. Positive values penalize new tokens based on their existing frequency in the text so far, decreasing the model's likelihood to repeat the same line verbatim.
31+
* @property bestOf Generates best_of completions server-side and returns the "best" (the one with the highest log probability per token).
32+
* @property logitBias Modify the likelihood of specified tokens appearing in the completion.
33+
* @property user A unique identifier representing your end-user, which can help OpenAI to monitor and detect abuse.
34+
* @constructor Create a CompletionRequest instance. Recommend using [builder] instead.
35+
*/
36+
data class CompletionRequest @JvmOverloads constructor(
37+
val model: String,
38+
val prompt: Any,
39+
val suffix: String? = null,
40+
@field:SerializedName("max_tokens") val maxTokens: Int? = null,
41+
val temperature: Number? = null,
42+
@field:SerializedName("top_p") val topP: Number? = null,
43+
val n: Int? = null,
44+
@Deprecated("Use OpenAI#streamCompletion") val stream: Boolean? = null,
45+
val logprobs: Int? = null,
46+
val echo: Boolean? = null,
47+
val stop: Any? = null,
48+
@field:SerializedName("presence_penalty") val presencePenalty: Number? = null,
49+
@field:SerializedName("frequency_penalty") val frequencyPenalty: Number? = null,
50+
@field:SerializedName("best_of") val bestOf: Int? = null,
51+
@field:SerializedName("logit_bias") val logitBias: Map<String, Int>? = null,
52+
val user: String? = null
53+
) {
54+
55+
/**
56+
* `Builder` is a helper class to build a [CompletionRequest] instance with a
57+
* stable API. It provides methods for setting the properties fo the [CompletionRequest]
58+
* object. The [build] method returns a new [CompletionRequest] instance with the
59+
* specified properties.
60+
*
61+
* Usage:
62+
* ```
63+
* val completionRequest = CompletionRequest.builder()
64+
* .model("davinci")
65+
* .prompt("The wheels on the bus go")
66+
* .build()
67+
* ```
68+
*/
69+
class Builder {
70+
private var model: String? = null
71+
private var prompt: Any? = null
72+
private var suffix: String? = null
73+
private var maxTokens: Int? = null
74+
private var temperature: Number? = null
75+
private var topP: Number? = null
76+
private var n: Int? = null
77+
private var stream: Boolean? = null
78+
private var logprobs: Int? = null
79+
private var echo: Boolean? = null
80+
private var stop: Any? = null
81+
private var presencePenalty: Number? = null
82+
private var frequencyPenalty: Number? = null
83+
private var bestOf: Int? = null
84+
private var logitBias: Map<String, Int>? = null
85+
private var user: String? = null
86+
87+
/**
88+
* Sets the model for the CompletionRequest.
89+
* @param model The ID of the model to use.
90+
* @return The updated Builder instance.
91+
*/
92+
fun model(model: String) = apply { this.model = model }
93+
94+
/**
95+
* Sets the prompt for the CompletionRequest.
96+
* @param prompt The prompt to generate completions for, encoded as a string.
97+
* @return The updated Builder instance.
98+
*/
99+
fun prompt(prompt: String?) = apply { this.prompt = prompt }
100+
101+
/**
102+
* Sets the list of prompts for the CompletionRequest.
103+
* @param prompts The prompts to generate completions for, encoded as a list of strings.
104+
* @return The updated Builder instance.
105+
*/
106+
fun prompts(prompts: List<String>?) = apply { this.prompt = prompts }
107+
108+
/**
109+
* Sets the array of prompts for the CompletionRequest.
110+
* @param prompts The prompts to generate completions for, encoded as an array of strings.
111+
* @return The updated Builder instance.
112+
*/
113+
fun prompts(prompts: Array<String>?) = apply { this.prompt = prompts }
114+
115+
/**
116+
* Sets the suffix for the CompletionRequest.
117+
* @param suffix The suffix that comes after a completion of inserted text.
118+
* @return The updated Builder instance.
119+
*/
120+
fun suffix(suffix: String?) = apply { this.suffix = suffix }
121+
122+
/**
123+
* Sets the maximum number of tokens for the CompletionRequest.
124+
* @param maxTokens The maximum number of tokens to generate in the completion.
125+
* @return The updated Builder instance.
126+
*/
127+
fun maxTokens(maxTokens: Int?) = apply { this.maxTokens = maxTokens }
128+
129+
/**
130+
* Sets the temperature for the CompletionRequest.
131+
* @param temperature What sampling temperature to use, between 0 and 2.
132+
* @return The updated Builder instance.
133+
*/
134+
fun temperature(temperature: Number?) = apply { this.temperature = temperature }
135+
136+
/**
137+
* Sets the top_p for the CompletionRequest.
138+
* @param topP An alternative to sampling with temperature, called nucleus sampling.
139+
* @return The updated Builder instance.
140+
*/
141+
fun topP(topP: Number?) = apply { this.topP = topP }
142+
143+
/**
144+
* Sets the number of completions for the CompletionRequest.
145+
* @param n How many completions to generate for each prompt.
146+
* @return The updated Builder instance.
147+
*/
148+
fun n(n: Int?) = apply { this.n = n }
149+
150+
/**
151+
* Sets the stream option for the CompletionRequest.
152+
* @param stream Whether to stream back partial progress.
153+
* @return The updated Builder instance.
154+
*/
155+
fun stream(stream: Boolean?) = apply { this.stream = stream }
156+
157+
/**
158+
* Sets the logprobs for the CompletionRequest.
159+
* @param logprobs Include the log probabilities on the logprobs most likely tokens, as well as the chosen tokens.
160+
* @return The updated Builder instance.
161+
*/
162+
fun logprobs(logprobs: Int?) = apply { this.logprobs = logprobs }
163+
164+
/**
165+
* Sets the echo option for the CompletionRequest.
166+
* @param echo Echo back the prompt in addition to the completion.
167+
* @return The updated Builder instance.
168+
*/
169+
fun echo(echo: Boolean?) = apply { this.echo = echo }
170+
171+
/**
172+
* Sets the stop sequences for the CompletionRequest.
173+
* @param stop Up to 4 sequences where the API will stop generating further tokens.
174+
* @return The updated Builder instance.
175+
*/
176+
fun stop(stop: Any?) = apply { this.stop = stop }
177+
178+
/**
179+
* Sets the presence penalty for the CompletionRequest.
180+
* @param presencePenalty Number between -2.0 and 2.0 for penalizing new tokens based on whether they appear in the text so far.
181+
* @return The updated Builder instance.
182+
*/
183+
fun presencePenalty(presencePenalty: Number?) = apply { this.presencePenalty = presencePenalty }
184+
185+
/**
186+
* Sets the frequency penalty for the CompletionRequest.
187+
* @param frequencyPenalty Number between -2.0 and 2.0 for penalizing new tokens based on their existing frequency in the text so far.
188+
* @return The updated Builder instance.
189+
*/
190+
fun frequencyPenalty(frequencyPenalty: Number?) = apply { this.frequencyPenalty = frequencyPenalty }
191+
192+
/**
193+
* Sets the best_of option for the CompletionRequest.
194+
* @param bestOf Generates best_of completions server-side and returns the "best" (the one with the highest log probability per token).
195+
* @return The updated Builder instance.
196+
*/
197+
fun bestOf(bestOf: Int?) = apply { this.bestOf = bestOf }
198+
199+
/**
200+
* Sets the logit bias for the CompletionRequest.
201+
* @param logitBias Modify the likelihood of specified tokens appearing in the completion.
202+
* @return The updated Builder instance.
203+
*/
204+
fun logitBias(logitBias: Map<String, Int>?) = apply { this.logitBias = logitBias }
205+
206+
/**
207+
* Sets the user identifier for the CompletionRequest.
208+
* @param user A unique identifier representing your end-user, which can help OpenAI to monitor and detect abuse.
209+
* @return The updated Builder instance.
210+
*/
211+
fun user(user: String?) = apply { this.user = user }
212+
213+
/**
214+
* Builds the CompletionRequest instance with the provided parameters.
215+
*
216+
* @return The constructed CompletionRequest instance.
217+
*/
218+
fun build(): CompletionRequest {
219+
require(model != null) { "Set CompletionRequest.Builder#model(String) before building" }
220+
require(prompt != null) { "Set CompletionRequest.Builder#prompt(String) before building" }
221+
222+
return CompletionRequest(
223+
model = model!!,
224+
prompt = prompt!!,
225+
suffix = suffix,
226+
maxTokens = maxTokens,
227+
temperature = temperature,
228+
topP = topP,
229+
n = n,
230+
stream = stream,
231+
logprobs = logprobs,
232+
echo = echo,
233+
stop = stop,
234+
presencePenalty = presencePenalty,
235+
frequencyPenalty = frequencyPenalty,
236+
bestOf = bestOf,
237+
logitBias = logitBias,
238+
user = user
239+
)
240+
}
241+
}
242+
243+
companion object {
244+
245+
/**
246+
* A static method that provides a new [Builder] instance for the
247+
* [CompletionRequest] class.
248+
*
249+
* @return a new [Builder] instance for creating a [CompletionRequest] object.
250+
*/
251+
@JvmStatic
252+
fun builder(): Builder = Builder()
253+
}
254+
}
255+

0 commit comments

Comments
 (0)