Skip to content

Navigation Menu

Sign in
Appearance settings

Search code, repositories, users, issues, pull requests...

Provide feedback

We read every piece of feedback, and take your input very seriously.

Saved searches

Use saved searches to filter your results more quickly
Sign up
Appearance settings

Commit 46a4734

Browse files
fix docs, address PR concerns
1 parent 0cfa9bc commit 46a4734

File tree

7 files changed

+125
-7
lines changed

7 files changed

+125
-7
lines changed

‎src/main/kotlin/com/cjcrafter/openai/assistants/AbstractAssistantBuilder.kt

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -19,6 +19,12 @@ abstract class AbstractAssistantBuilder<T> protected constructor() {
1919
protected var fileIds: MutableList<String>? = null
2020
protected var metadata: MutableMap<String, String>? = null
2121

22+
/**
23+
* The model to the [Assistant] should default to using if no model is
24+
* specified. Use [com.cjcrafter.openai.Models] to get a list of models.
25+
*
26+
* @param model The model to use
27+
*/
2228
fun model(model: String) = apply { this.model = model }
2329

2430
/**

‎src/main/kotlin/com/cjcrafter/openai/assistants/AssistantHandler.kt

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,7 @@
11
package com.cjcrafter.openai.assistants
22

3+
import org.jetbrains.annotations.Contract
4+
35
/**
46
* Represents the handler for the assistants endpoint. This class holds all the
57
* actions that can be performed on an assistant.
@@ -26,6 +28,7 @@ interface AssistantHandler {
2628
* @param assistant The assistant to retrieve
2729
* @return The new instance of the retrieved assistant
2830
*/
31+
@Contract(pure = true)
2932
fun retrieve(assistant: Assistant): Assistant = retrieve(assistant.id)
3033

3134
/**
@@ -34,6 +37,7 @@ interface AssistantHandler {
3437
* @param id The id of the assistant to retrieve
3538
* @return The assistant with the given id
3639
*/
40+
@Contract(pure = true)
3741
fun retrieve(id: String): Assistant
3842

3943
/**
@@ -59,6 +63,7 @@ interface AssistantHandler {
5963
*
6064
* @return The list of assistants
6165
*/
66+
@Contract(pure = true)
6267
fun list(): ListAssistantResponse = list(null)
6368

6469
/**
@@ -67,6 +72,7 @@ interface AssistantHandler {
6772
* @param request The query parameters
6873
* @return The list of assistants
6974
*/
75+
@Contract(pure = true)
7076
fun list(request: ListAssistantRequest?): ListAssistantResponse // Cannot use @JvmOverloads in interfaces
7177

7278
/**

‎src/main/kotlin/com/cjcrafter/openai/threads/message/CreateThreadMessageRequest.kt

Lines changed: 36 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -26,36 +26,72 @@ data class CreateThreadMessageRequest(
2626
private var fileIds: MutableList<String>? = null
2727
private var metadata: MutableMap<String, String>? = null
2828

29+
/**
30+
* Who is creating the message. This must always be [ThreadUser.USER].
31+
*
32+
* @param role The user creating the message
33+
*/
2934
fun role(role: ThreadUser) = apply {
3035
if (role != ThreadUser.USER)
3136
throw IllegalArgumentException("role must be USER")
3237

3338
this.role = role
3439
}
3540

41+
/**
42+
* The content of the message.
43+
*
44+
* @param content The content of the message
45+
*/
3646
fun content(content: String) = apply {
3747
this.content = content
3848
}
3949

50+
/**
51+
* The IDs of the files to attach to the message.
52+
*
53+
* @param fileIds The IDs of the files to attach to the message
54+
*/
4055
fun fileIds(fileIds: MutableList<String>) = apply {
4156
this.fileIds = fileIds
4257
}
4358

59+
/**
60+
* The metadata to attach to the message.
61+
*
62+
* @param metadata The metadata to attach to the message
63+
*/
4464
fun metadata(metadata: MutableMap<String, String>) = apply {
4565
BuilderHelper.assertMetadata(metadata)
4666
this.metadata = metadata
4767
}
4868

69+
/**
70+
* Adds a file to the list of files to attach to the message.
71+
*
72+
* @param file The file to attach to the message
73+
*/
4974
fun addFile(file: FileObject) = apply {
5075
if (fileIds == null) fileIds = mutableListOf()
5176
fileIds!!.add(file.id)
5277
}
5378

79+
/**
80+
* Adds a file to the list of files to attach to the message.
81+
*
82+
* @param fileId The ID of the file to attach to the message
83+
*/
5484
fun addFile(fileId: String) = apply {
5585
if (fileIds == null) fileIds = mutableListOf()
5686
fileIds!!.add(fileId)
5787
}
5888

89+
/**
90+
* Adds a metadata key-value pair to the message.
91+
*
92+
* @param key The key of the metadata
93+
* @param value The value of the metadata
94+
*/
5995
fun addMetadata(key: String, value: String) = apply {
6096
BuilderHelper.assertMetadata(key, value)
6197
if (metadata == null) metadata = mutableMapOf()

‎src/main/kotlin/com/cjcrafter/openai/threads/message/ModifyThreadMessageRequest.kt

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -34,7 +34,7 @@ data class ModifyThreadMessageRequest(
3434
* @param value The value, which must be <= 512 characters
3535
* @throws IllegalArgumentException If the key or value is too long
3636
*/
37-
fun addMetadata(key: String, value: String) {
37+
fun addMetadata(key: String, value: String) =apply{
3838
BuilderHelper.assertMetadata(key, value)
3939
if (metadata == null) metadata = mutableMapOf()
4040
BuilderHelper.tryAddMetadata(metadata!!)

‎src/main/kotlin/com/cjcrafter/openai/threads/message/TextAnnotation.kt

Lines changed: 46 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,36 +1,81 @@
11
package com.cjcrafter.openai.threads.message
22

3+
import com.cjcrafter.openai.assistants.Assistant
4+
import com.cjcrafter.openai.chat.tool.Tool.RetrievalTool
5+
import com.cjcrafter.openai.chat.tool.Tool.CodeInterpreterTool
36
import com.fasterxml.jackson.annotation.JsonProperty
47
import com.fasterxml.jackson.annotation.JsonSubTypes
58
import com.fasterxml.jackson.annotation.JsonTypeInfo
69

10+
/**
11+
* A [TextContent] created by an [Assistant] may contain annotations.
12+
*
13+
* Annotations will be present in the [TextContent.Text.value], and may look
14+
* like this:
15+
* - `【13†source】`
16+
* - `sandbox:/mnt/data/file.csv`
17+
*
18+
* You should replace the text in the message content with however you would like
19+
* to annotate your files. For example, you could replace the text with a link
20+
* to the file, or you could replace the text with the file contents.
21+
*/
722
@JsonTypeInfo(use = JsonTypeInfo.Id.NAME, include = JsonTypeInfo.As.PROPERTY, property = "type")
823
@JsonSubTypes(
924
JsonSubTypes.Type(TextAnnotation.FileCitation::class, name = "file_citation"),
1025
JsonSubTypes.Type(TextAnnotation.FilePath::class, name = "file_path"),
1126
)
1227
sealed class TextAnnotation {
1328

29+
/**
30+
* File citations are created by the [RetrievalTool] and define references
31+
* to a specific quote in a specific file that used by the [Assistant] to
32+
* generate the response.
33+
*
34+
* @property text The text in the message content that needs to be replaced
35+
* @property fileCitation The specific quote that was used in retrieval
36+
* @property startIndex The index of the first character that needs to be replaced
37+
* @property endIndex The index of the first character that does not need to be replaced
38+
*/
1439
data class FileCitation(
1540
@JsonProperty(required = true) val text: String,
1641
@JsonProperty("file_citation", required = true) val fileCitation: FileQuote,
1742
@JsonProperty("start_index", required = true) val startIndex: Int,
1843
@JsonProperty("end_index", required = true) val endIndex: Int,
1944
): TextAnnotation() {
2045

46+
/**
47+
* Holds data about the file quote generated by the retrieval tool.
48+
*
49+
* @property fileId The id of the file the quote was taken from
50+
* @property quote The quote that was used to generate the response
51+
*/
2152
data class FileQuote(
2253
@JsonProperty("file_id", required = true) val fileId: String,
2354
@JsonProperty(required = true) val quote: String,
2455
)
2556
}
2657

58+
/**
59+
* File paths are created by the [CodeInterpreterTool] and contain references
60+
* to the files generated by the tool.
61+
*
62+
* @property text The text in the message content that needs to be replaced
63+
* @property filePath The file that was generated by the code interpreter
64+
* @property startIndex The index of the first character that needs to be replaced
65+
* @property endIndex The index of the first character that does not need to be replaced
66+
*/
2767
data class FilePath(
2868
@JsonProperty(required = true) val text: String,
29-
@JsonProperty("file_citation", required = true) val filePath: FileWrapper,
69+
@JsonProperty("file_path", required = true) val filePath: FileWrapper,
3070
@JsonProperty("start_index", required = true) val startIndex: Int,
3171
@JsonProperty("end_index", required = true) val endIndex: Int,
3272
): TextAnnotation() {
3373

74+
/**
75+
* Holds data about the file generated by the code interpreter.
76+
*
77+
* @property fileId The id of the file, can be used to retrieve the file
78+
*/
3479
data class FileWrapper(
3580
@JsonProperty("file_id", required = true) val fileId: String,
3681
)

‎src/main/kotlin/com/cjcrafter/openai/threads/message/TextContent.kt

Lines changed: 14 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,11 +1,25 @@
11
package com.cjcrafter.openai.threads.message
22

3+
/**
4+
* Represents the text output of a message.
5+
*
6+
* Note that you may need to handle text annotations. Check out [TextAnnotation]
7+
* for more information.
8+
*
9+
* @property text The text content of the message
10+
*/
311
data class TextContent(
412
val text: Text
513
) : ThreadMessageContent() {
614

715
override val type = Type.TEXT
816

17+
/**
18+
* Represents the text content of a message.
19+
*
20+
* @property value The text content of the message
21+
* @property annotations The annotations of the text content
22+
*/
923
data class Text(
1024
val value: String,
1125
val annotations: List<TextAnnotation>

‎src/main/kotlin/com/cjcrafter/openai/threads/message/ThreadMessage.kt

Lines changed: 16 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -2,16 +2,27 @@ package com.cjcrafter.openai.threads.message
22

33
import com.fasterxml.jackson.annotation.JsonProperty
44

5+
/**
6+
* Represents a message in a [Thread].
7+
*
8+
* @property id The unique id of the message
9+
* @property createdAt The unix timestamp of when the message was created
10+
* @property threadId The id of the thread that this message belongs to
11+
* @property role The role of the user that created the message
12+
* @property content The content of the message
13+
* @property assistantId The id of the assistant that this message belongs to, or null
14+
* @property runId The id of the run that created this message, or null
15+
* @property fileIds The ids of the files attached to this message
16+
* @property metadata The metadata attached to this message
17+
*/
518
data class ThreadMessage(
619
@JsonProperty(required = true) val id: String,
720
@JsonProperty("created_at", required = true) val createdAt: Int,
821
@JsonProperty("thread_id", required = true) val threadId: String,
922
@JsonProperty(required = true) val role: ThreadUser,
1023
@JsonProperty(required = true) val content: List<ThreadMessageContent>,
11-
@JsonProperty("assistant_id", required =true) val assistantId: String?,
12-
@JsonProperty("run_id", required =true) val runId: String?,
24+
@JsonProperty("assistant_id") val assistantId: String?,
25+
@JsonProperty("run_id") val runId: String?,
1326
@JsonProperty("file_ids", required = true) val fileIds: List<String>,
1427
@JsonProperty(required = true) val metadata: Map<String, String>,
15-
) {
16-
17-
}
28+
)

0 commit comments

Comments
(0)

AltStyle によって変換されたページ (->オリジナル) /