fix docs, address PR concerns

Author: CJCrafter

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

@@ -19,6 +19,12 @@ abstract class AbstractAssistantBuilder<T> protected constructor() {
     protected var fileIds: MutableList<String>? = null
     protected var metadata: MutableMap<String, String>? = null
 
+    /**
+     * The model to the [Assistant] should default to using if no model is
+     * specified. Use [com.cjcrafter.openai.Models] to get a list of models.
+     *
+     * @param model The model to use
+     */
     fun model(model: String) = apply { this.model = model }
 
     /**

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

@@ -1,5 +1,7 @@
 package com.cjcrafter.openai.assistants
 
+import org.jetbrains.annotations.Contract
+
 /**
  * Represents the handler for the assistants endpoint. This class holds all the
  * actions that can be performed on an assistant.
@@ -26,6 +28,7 @@ interface AssistantHandler {
      * @param assistant The assistant to retrieve
      * @return The new instance of the retrieved assistant
      */
+    @Contract(pure = true)
     fun retrieve(assistant: Assistant): Assistant = retrieve(assistant.id)
 
     /**
@@ -34,6 +37,7 @@ interface AssistantHandler {
      * @param id The id of the assistant to retrieve
      * @return The assistant with the given id
      */
+    @Contract(pure = true)
     fun retrieve(id: String): Assistant
 
     /**
@@ -59,6 +63,7 @@ interface AssistantHandler {
      *
      * @return The list of assistants
      */
+    @Contract(pure = true)
     fun list(): ListAssistantResponse = list(null)
 
     /**
@@ -67,6 +72,7 @@ interface AssistantHandler {
      * @param request The query parameters
      * @return The list of assistants
      */
+    @Contract(pure = true)
     fun list(request: ListAssistantRequest?): ListAssistantResponse // Cannot use @JvmOverloads in interfaces
 
     /**

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

@@ -26,36 +26,72 @@ data class CreateThreadMessageRequest(
         private var fileIds: MutableList<String>? = null
         private var metadata: MutableMap<String, String>? = null
 
+        /**
+         * Who is creating the message. This must always be [ThreadUser.USER].
+         *
+         * @param role The user creating the message
+         */
         fun role(role: ThreadUser) = apply {
             if (role != ThreadUser.USER)
                 throw IllegalArgumentException("role must be USER")
 
             this.role = role
         }
 
+        /**
+         * The content of the message.
+         *
+         * @param content The content of the message
+         */
         fun content(content: String) = apply {
             this.content = content
         }
 
+        /**
+         * The IDs of the files to attach to the message.
+         *
+         * @param fileIds The IDs of the files to attach to the message
+         */
         fun fileIds(fileIds: MutableList<String>) = apply {
             this.fileIds = fileIds
         }
 
+        /**
+         * The metadata to attach to the message.
+         *
+         * @param metadata The metadata to attach to the message
+         */
         fun metadata(metadata: MutableMap<String, String>) = apply {
             BuilderHelper.assertMetadata(metadata)
             this.metadata = metadata
         }
 
+        /**
+         * Adds a file to the list of files to attach to the message.
+         *
+         * @param file The file to attach to the message
+         */
         fun addFile(file: FileObject) = apply {
             if (fileIds == null) fileIds = mutableListOf()
             fileIds!!.add(file.id)
         }
 
+        /**
+         * Adds a file to the list of files to attach to the message.
+         *
+         * @param fileId The ID of the file to attach to the message
+         */
         fun addFile(fileId: String) = apply {
             if (fileIds == null) fileIds = mutableListOf()
             fileIds!!.add(fileId)
         }
 
+        /**
+         * Adds a metadata key-value pair to the message.
+         *
+         * @param key The key of the metadata
+         * @param value The value of the metadata
+         */
         fun addMetadata(key: String, value: String) = apply {
             BuilderHelper.assertMetadata(key, value)
             if (metadata == null) metadata = mutableMapOf()

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

@@ -34,7 +34,7 @@ data class ModifyThreadMessageRequest(
          * @param value The value, which must be <= 512 characters
          * @throws IllegalArgumentException If the key or value is too long
          */
-        fun addMetadata(key: String, value: String) {
+        fun addMetadata(key: String, value: String) = apply {
             BuilderHelper.assertMetadata(key, value)
             if (metadata == null) metadata = mutableMapOf()
             BuilderHelper.tryAddMetadata(metadata!!)

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

@@ -1,36 +1,81 @@
 package com.cjcrafter.openai.threads.message
 
+import com.cjcrafter.openai.assistants.Assistant
+import com.cjcrafter.openai.chat.tool.Tool.RetrievalTool
+import com.cjcrafter.openai.chat.tool.Tool.CodeInterpreterTool
 import com.fasterxml.jackson.annotation.JsonProperty
 import com.fasterxml.jackson.annotation.JsonSubTypes
 import com.fasterxml.jackson.annotation.JsonTypeInfo
 
+/**
+ * A [TextContent] created by an [Assistant] may contain annotations.
+ *
+ * Annotations will be present in the [TextContent.Text.value], and may look
+ * like this:
+ * - `【13†source】`
+ * - `sandbox:/mnt/data/file.csv`
+ *
+ * You should replace the text in the message content with however you would like
+ * to annotate your files. For example, you could replace the text with a link
+ * to the file, or you could replace the text with the file contents.
+ */
 @JsonTypeInfo(use = JsonTypeInfo.Id.NAME, include = JsonTypeInfo.As.PROPERTY, property = "type")
 @JsonSubTypes(
     JsonSubTypes.Type(TextAnnotation.FileCitation::class, name = "file_citation"),
     JsonSubTypes.Type(TextAnnotation.FilePath::class, name = "file_path"),
 )
 sealed class TextAnnotation {
 
+    /**
+     * File citations are created by the [RetrievalTool] and define references
+     * to a specific quote in a specific file that used by the [Assistant] to
+     * generate the response.
+     *
+     * @property text The text in the message content that needs to be replaced
+     * @property fileCitation The specific quote that was used in retrieval
+     * @property startIndex The index of the first character that needs to be replaced
+     * @property endIndex The index of the first character that does not need to be replaced
+     */
     data class FileCitation(
         @JsonProperty(required = true) val text: String,
         @JsonProperty("file_citation", required = true) val fileCitation: FileQuote,
         @JsonProperty("start_index", required = true) val startIndex: Int,
         @JsonProperty("end_index", required = true) val endIndex: Int,
     ): TextAnnotation() {
 
+        /**
+         * Holds data about the file quote generated by the retrieval tool.
+         *
+         * @property fileId The id of the file the quote was taken from
+         * @property quote The quote that was used to generate the response
+         */
         data class FileQuote(
             @JsonProperty("file_id", required = true) val fileId: String,
             @JsonProperty(required = true) val quote: String,
         )
     }
 
+    /**
+     * File paths are created by the [CodeInterpreterTool] and contain references
+     * to the files generated by the tool.
+     *
+     * @property text The text in the message content that needs to be replaced
+     * @property filePath The file that was generated by the code interpreter
+     * @property startIndex The index of the first character that needs to be replaced
+     * @property endIndex The index of the first character that does not need to be replaced
+     */
     data class FilePath(
         @JsonProperty(required = true) val text: String,
-        @JsonProperty("file_citation", required = true) val filePath: FileWrapper,
+        @JsonProperty("file_path", required = true) val filePath: FileWrapper,
         @JsonProperty("start_index", required = true) val startIndex: Int,
         @JsonProperty("end_index", required = true) val endIndex: Int,
     ): TextAnnotation() {
 
+        /**
+         * Holds data about the file generated by the code interpreter.
+         *
+         * @property fileId The id of the file, can be used to retrieve the file
+         */
         data class FileWrapper(
             @JsonProperty("file_id", required = true) val fileId: String,
         )

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

@@ -1,11 +1,25 @@
 package com.cjcrafter.openai.threads.message
 
+/**
+ * Represents the text output of a message.
+ *
+ * Note that you may need to handle text annotations. Check out [TextAnnotation]
+ * for more information.
+ *
+ * @property text The text content of the message
+ */
 data class TextContent(
     val text: Text
 ) : ThreadMessageContent() {
 
     override val type = Type.TEXT
 
+    /**
+     * Represents the text content of a message.
+     *
+     * @property value The text content of the message
+     * @property annotations The annotations of the text content
+     */
     data class Text(
         val value: String,
         val annotations: List<TextAnnotation>

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

@@ -2,16 +2,27 @@ package com.cjcrafter.openai.threads.message
 
 import com.fasterxml.jackson.annotation.JsonProperty
 
+/**
+ * Represents a message in a [Thread].
+ *
+ * @property id The unique id of the message
+ * @property createdAt The unix timestamp of when the message was created
+ * @property threadId The id of the thread that this message belongs to
+ * @property role The role of the user that created the message
+ * @property content The content of the message
+ * @property assistantId The id of the assistant that this message belongs to, or null
+ * @property runId The id of the run that created this message, or null
+ * @property fileIds The ids of the files attached to this message
+ * @property metadata The metadata attached to this message
+ */
 data class ThreadMessage(
     @JsonProperty(required = true) val id: String,
     @JsonProperty("created_at", required = true) val createdAt: Int,
     @JsonProperty("thread_id", required = true) val threadId: String,
     @JsonProperty(required = true) val role: ThreadUser,
     @JsonProperty(required = true) val content: List<ThreadMessageContent>,
-    @JsonProperty("assistant_id", required = true) val assistantId: String?,
-    @JsonProperty("run_id", required = true) val runId: String?,
+    @JsonProperty("assistant_id") val assistantId: String?,
+    @JsonProperty("run_id") val runId: String?,
     @JsonProperty("file_ids", required = true) val fileIds: List<String>,
     @JsonProperty(required = true) val metadata: Map<String, String>,
-) {
-
-}
+)