use required=true for json properties to fail fast

Author: CJCrafter

examples/src/main/kotlin/files/Files.kt

@@ -1,13 +1,11 @@
 package files
 
 import com.cjcrafter.openai.files.FilePurpose
-import com.cjcrafter.openai.files.ListFilesRequest
-import com.cjcrafter.openai.files.fileUploadRequest
+import com.cjcrafter.openai.files.uploadFileRequest
 import com.cjcrafter.openai.files.listFilesRequest
 import com.cjcrafter.openai.openAI
 import io.github.cdimascio.dotenv.dotenv
 import java.io.File
-import java.util.Scanner
 
 // To use dotenv, you need to add the "io.github.cdimascio:dotenv-kotlin:version"
 // dependency. Then you can add a .env file in your project directory.
@@ -44,7 +42,7 @@ fun uploadFile() {
     print("Enter the file name: ")
     val fileName = readln()
     val input = File(fileName)
-    val request = fileUploadRequest {
+    val request = uploadFileRequest {
         file(input)
         purpose(FilePurpose.ASSISTANTS)
     }

src/main/kotlin/com/cjcrafter/openai/OpenAI.kt

@@ -138,7 +138,7 @@ interface OpenAI {
      * @return The OpenAI file object created
      */
     @ApiStatus.Experimental
-    fun uploadFile(request: FileUploadRequest): FileObject
+    fun uploadFile(request: UploadFileRequest): FileObject
 
     @ApiStatus.Experimental
     fun deleteFile(fileId: String): FileDeletionStatus

src/main/kotlin/com/cjcrafter/openai/OpenAIImpl.kt

@@ -13,10 +13,8 @@ import okhttp3.*
 import okhttp3.HttpUrl.Companion.toHttpUrl
 import okhttp3.MediaType.Companion.toMediaType
 import okhttp3.RequestBody.Companion.toRequestBody
-import org.intellij.lang.annotations.Language
 import org.jetbrains.annotations.ApiStatus
 import java.io.BufferedReader
-import java.io.File
 import java.io.IOException
 
 open class OpenAIImpl @ApiStatus.Internal constructor(
@@ -188,7 +186,7 @@ open class OpenAIImpl @ApiStatus.Internal constructor(
         return executeRequest(httpRequest, ListFilesResponse::class.java)
     }
 
-    override fun uploadFile(request: FileUploadRequest): FileObject {
+    override fun uploadFile(request: UploadFileRequest): FileObject {
         val httpRequest = buildMultipartRequest(FILES_ENDPOINT) {
             addFormDataPart("purpose", OpenAI.createObjectMapper().writeValueAsString(request.purpose).trim('"'))
             addFormDataPart("file", request.fileName, request.requestBody)

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

@@ -21,7 +21,7 @@ import com.fasterxml.jackson.annotation.JsonProperty
  * @see FinishReason
  */
 data class ChatChoice(
-    val index: Int,
-    val message: ChatMessage,
-    @JsonProperty("finish_reason") val finishReason: FinishReason
+    @JsonProperty(required = true) val index: Int,
+    @JsonProperty(required = true) val message: ChatMessage,
+    @JsonProperty("finish_reason", required = true) val finishReason: FinishReason
 )

src/main/kotlin/com/cjcrafter/openai/chat/ChatChoiceChunk.kt

@@ -29,9 +29,9 @@ import java.lang.IllegalArgumentException
  * @since 1.2.0
  */
 data class ChatChoiceChunk(
-    val index: Int,
-    var delta: ChatMessageDelta? = null,
-    @JsonProperty("finish_reason") var finishReason: FinishReason?
+    @JsonProperty(required = true) val index: Int,
+    @JsonProperty(required = true) var delta: ChatMessageDelta? = null,
+    @JsonProperty("finish_reason", required = true) var finishReason: FinishReason?
 ) {
     val message: ChatMessage = ChatMessage(delta?.role!!, delta?.content, delta?.toolCalls?.map { it.toToolCall() })
 

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

@@ -1,5 +1,6 @@
 package com.cjcrafter.openai.chat
 
+import com.fasterxml.jackson.annotation.JsonProperty
 import java.time.Instant
 import java.time.ZoneId
 import java.time.ZonedDateTime
@@ -17,10 +18,10 @@ import java.util.*
  * @constructor Create Chat response (for internal usage).
  */
 data class ChatResponse(
-    val id: String,
-    val created: Long,
-    val choices: List<ChatChoice>,
-    val usage: ChatUsage
+    @JsonProperty(required = true) val id: String,
+    @JsonProperty(required = true) val created: Long,
+    @JsonProperty(required = true) val choices: List<ChatChoice>,
+    @JsonProperty(required = true) val usage: ChatUsage
 ) {
 
     /**

src/main/kotlin/com/cjcrafter/openai/chat/ChatResponseChunk.kt

@@ -1,5 +1,6 @@
 package com.cjcrafter.openai.chat
 
+import com.fasterxml.jackson.annotation.JsonProperty
 import com.fasterxml.jackson.databind.JsonNode
 import com.fasterxml.jackson.databind.node.ArrayNode
 import com.fasterxml.jackson.databind.node.ObjectNode
@@ -25,9 +26,9 @@ import java.util.*
  * @since 1.2.0
  */
 data class ChatResponseChunk(
-    val id: String,
-    val created: Long,
-    val choices: List<ChatChoiceChunk>,
+    @JsonProperty(required = true) val id: String,
+    @JsonProperty(required = true) val created: Long,
+    @JsonProperty(required = true) val choices: List<ChatChoiceChunk>,
 ) {
     internal fun update(json: ObjectNode) {
         val choicesArray = json.get("choices") as? ArrayNode

src/main/kotlin/com/cjcrafter/openai/chat/ChatUsage.kt

@@ -16,7 +16,7 @@ import com.fasterxml.jackson.annotation.JsonProperty
  * @see <a href="https://platform.openai.com/docs/guides/chat/managing-tokens">Managing Tokens Guide</a>
  */
 data class ChatUsage(
-    @JsonProperty("prompt_tokens") val promptTokens: Int,
-    @JsonProperty("completion_tokens") val completionTokens: Int,
-    @JsonProperty("total_tokens") val totalTokens: Int
+    @JsonProperty("prompt_tokens", required = true) val promptTokens: Int,
+    @JsonProperty("completion_tokens", required = true) val completionTokens: Int,
+    @JsonProperty("total_tokens", required = true) val totalTokens: Int
 )

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

@@ -21,8 +21,8 @@ import com.fasterxml.jackson.annotation.JsonProperty
  * @see FinishReason
  */
 data class CompletionChoice(
-    val text: String,
-    val index: Int,
-    val logprobs: List<Float>?,
-    @JsonProperty("finish_reason") val finishReason: FinishReason
+    @JsonProperty(required = true) val text: String,
+    @JsonProperty(required = true) val index: Int,
+    @JsonProperty(required = true) val logprobs: List<Float>?,
+    @JsonProperty("finish_reason", required = true) val finishReason: FinishReason
 )

src/main/kotlin/com/cjcrafter/openai/completions/CompletionChoiceChunk.kt

@@ -21,10 +21,10 @@ import com.fasterxml.jackson.annotation.JsonProperty
  * @see FinishReason
  */
 data class CompletionChoiceChunk(
-    val text: String,
-    val index: Int,
-    val logprobs: List<Float>?,
-    @JsonProperty("finish_reason") val finishReason: FinishReason?
+    @JsonProperty(required = true) val text: String,
+    @JsonProperty(required = true) val index: Int,
+    @JsonProperty(required = true) val logprobs: List<Float>?,
+    @JsonProperty("finish_reason", required = true) val finishReason: FinishReason?
 ) {
     /**
      * Returns `true` if this message chunk is complete. Once complete, no more

src/main/kotlin/com/cjcrafter/openai/completions/CompletionResponse.kt

@@ -1,5 +1,6 @@
 package com.cjcrafter.openai.completions
 
+import com.fasterxml.jackson.annotation.JsonProperty
 import java.time.Instant
 import java.time.ZoneId
 import java.time.ZonedDateTime
@@ -18,11 +19,11 @@ import java.util.*
  * @constructor Create Completion response (for internal usage)
  */
 data class CompletionResponse(
-    val id: String,
-    val created: Long,
-    val model: String,
-    val choices: List<CompletionChoice>,
-    val usage: CompletionUsage
+    @JsonProperty(required = true) val id: String,
+    @JsonProperty(required = true) val created: Long,
+    @JsonProperty(required = true) val model: String,
+    @JsonProperty(required = true) val choices: List<CompletionChoice>,
+    @JsonProperty(required = true) val usage: CompletionUsage
 ) {
 
     /**

src/main/kotlin/com/cjcrafter/openai/completions/CompletionResponseChunk.kt

@@ -1,5 +1,6 @@
 package com.cjcrafter.openai.completions
 
+import com.fasterxml.jackson.annotation.JsonProperty
 import java.time.Instant
 import java.time.ZoneId
 import java.time.ZonedDateTime
@@ -17,10 +18,10 @@ import java.util.*
  * @constructor Create Completion response (for internal usage)
  */
 data class CompletionResponseChunk(
-    val id: String,
-    val created: Long,
-    val model: String,
-    val choices: List<CompletionChoiceChunk>,
+    @JsonProperty(required = true) val id: String,
+    @JsonProperty(required = true) val created: Long,
+    @JsonProperty(required = true) val model: String,
+    @JsonProperty(required = true) val choices: List<CompletionChoiceChunk>,
 ) {
 
     /**

src/main/kotlin/com/cjcrafter/openai/completions/CompletionUsage.kt

@@ -15,7 +15,7 @@ import com.fasterxml.jackson.annotation.JsonProperty
  * @param totalTokens      How many tokens in total.
  */
 data class CompletionUsage(
-    @JsonProperty("prompt_tokens") val promptTokens: Int,
-    @JsonProperty("completion_tokens") val completionTokens: Int,
-    @JsonProperty("total_tokens") val totalTokens: Int
+    @JsonProperty("prompt_tokens", required = true) val promptTokens: Int,
+    @JsonProperty("completion_tokens", required = true) val completionTokens: Int,
+    @JsonProperty("total_tokens", required = true) val totalTokens: Int
 )

src/main/kotlin/com/cjcrafter/openai/embeddings/Embedding.kt

@@ -1,14 +1,16 @@
 package com.cjcrafter.openai.embeddings
 
+import com.fasterxml.jackson.annotation.JsonProperty
+
 /**
  * Represents 1 embedding as a vector of floats or strings.
  *
  * @property embedding The embedding as a list of floats or strings
  * @property index The index of the embedding in the list of embeddings
  */
 data class Embedding(
-    val embedding: List<Any>,
-    val index: Int,
+    @JsonProperty(required = true) val embedding: List<Any>,
+    @JsonProperty(required = true) val index: Int,
 ) {
     /**
      * Returns the embedding as a list of floats. Make sure to use [EncodingFormat.FLOAT].

src/main/kotlin/com/cjcrafter/openai/embeddings/EmbeddingsResponse.kt

@@ -1,5 +1,7 @@
 package com.cjcrafter.openai.embeddings
 
+import com.fasterxml.jackson.annotation.JsonProperty
+
 /**
  * The API response from the [EmbeddingsRequest].
  *
@@ -8,9 +10,9 @@ package com.cjcrafter.openai.embeddings
  * @property usage How many tokens were used by the API request
  */
 data class EmbeddingsResponse(
-    val data: List<Embedding>,
-    val model: String,
-    val usage: EmbeddingsUsage,
+    @JsonProperty(required = true) val data: List<Embedding>,
+    @JsonProperty(required = true) val model: String,
+    @JsonProperty(required = true) val usage: EmbeddingsUsage,
 ) {
     /**
      * Returns the [data] at the given [index].

src/main/kotlin/com/cjcrafter/openai/embeddings/EmbeddingsUsage.kt

@@ -10,6 +10,6 @@ import com.fasterxml.jackson.annotation.JsonProperty
  * @property totalTokens The total number of tokens used
  */
 data class EmbeddingsUsage(
-    @JsonProperty("prompt_tokens") val promptTokens: Int,
-    @JsonProperty("total_tokens") val totalTokens: Int,
+    @JsonProperty("prompt_tokens", required = true) val promptTokens: Int,
+    @JsonProperty("total_tokens", required = true) val totalTokens: Int,
 )

src/main/kotlin/com/cjcrafter/openai/files/FileDeletionStatus.kt

@@ -1,12 +1,14 @@
 package com.cjcrafter.openai.files
 
+import com.fasterxml.jackson.annotation.JsonProperty
+
 /**
  * The returned result after attempting to delete a file.
  *
  * @property id The unique id of the file
  * @property deleted Whether the file was deleted
  */
 data class FileDeletionStatus(
-    val id: String,
-    val deleted: Boolean,
+    @JsonProperty(required = true) val id: String,
+    @JsonProperty(required = true) val deleted: Boolean,
 )

src/main/kotlin/com/cjcrafter/openai/files/FileObject.kt

@@ -17,11 +17,11 @@ import java.util.*
  * @constructor Create empty File object
  */
 data class FileObject(
-    val id: String,
-    val bytes: Int,
-    @JsonProperty("created_at") val createdAt: Int,
-    @JsonProperty("filename") val fileName: String,
-    val purpose: FilePurpose,
+    @JsonProperty(required = true) val id: String,
+    @JsonProperty(required = true) val bytes: Int,
+    @JsonProperty("created_at", required = true) val createdAt: Int,
+    @JsonProperty("filename", required = true) val fileName: String,
+    @JsonProperty(required = true) val purpose: FilePurpose,
 ) {
 
     /**

src/main/kotlin/com/cjcrafter/openai/files/FilePurpose.kt

@@ -8,13 +8,17 @@ import com.fasterxml.jackson.annotation.JsonProperty
 enum class FilePurpose {
 
     /**
-     * A file used to create/validate a fine-tuned model.
+     * A file used to create/validate a fine-tuned model. When uploading a file
+     * for this purpose, the uploaded file must be a `.jsonl` (JSON list) file,
+     * where each line of the file is a separate training example. No other file
+     * types are accepted.
      */
     @JsonProperty("fine-tune")
     FINE_TUNE,
 
     /**
-     * Files resulting from a fine-tuning task.
+     * Files resulting from a fine-tuning task. This is used internally by OpenAI,
+     * If you try to upload a file with this purpose, you will get an error.
      */
     @JsonProperty("fine-tune-results")
     FINE_TUNE_RESULTS,
@@ -26,7 +30,8 @@ enum class FilePurpose {
     ASSISTANTS,
 
     /**
-     * A file output from an assistant.
+     * A file output from an assistant. This is used internally by OpenAI, if
+     * you try to upload a file with this purpose, you will get an error.
      */
     @JsonProperty("assistants_output")
     ASSISTANTS_OUTPUT

src/main/kotlin/com/cjcrafter/openai/files/FileUploadRequestDsl.kt

@@ -9,6 +9,6 @@ import com.fasterxml.jackson.annotation.JsonProperty
  * @property data The list of files.
  */
 data class ListFilesResponse(
-    @JsonProperty("has_more") val hasMore: Boolean,
-    val data: List<FileObject>,
-)//: List<FileObject> by data
+    @JsonProperty("has_more", required = true) val hasMore: Boolean,
+    @JsonProperty(required = true) val data: List<FileObject>,
+)

src/main/kotlin/com/cjcrafter/openai/files/ListFilesResponse.kt

@@ -5,7 +5,7 @@ import okhttp3.RequestBody.Companion.asRequestBody
 import okhttp3.RequestBody.Companion.toRequestBody
 import java.io.InputStream
 
-data class FileUploadRequest internal constructor(
+data class UploadFileRequest internal constructor(
     var fileName: String,
     var requestBody: RequestBody,
     var purpose: FilePurpose,
@@ -21,7 +21,8 @@ data class FileUploadRequest internal constructor(
         fun purpose(purpose: FilePurpose) = apply { this.purpose = purpose }
 
         /**
-         * Uploads a java.io.File as a file.
+         * Uploads a java.io.File as a file. Note that the specific [FilePurpose]
+         * can only have specific file types.
          *
          * @param file The file to upload
          */
@@ -64,19 +65,19 @@ data class FileUploadRequest internal constructor(
             requestBody = string.toRequestBody()
         }
 
-        fun build(): FileUploadRequest {
-            return FileUploadRequest(
+        fun build(): UploadFileRequest {
+            return UploadFileRequest(
                 fileName = fileName ?: throw IllegalStateException("fileName must be defined to use FileUploadRequest"),
-                requestBody = requestBody!!,
-                purpose = purpose!!
+                requestBody = requestBody ?: throw IllegalStateException("requestBody must be defined to use FileUploadRequest"),
+                purpose = purpose ?: throw IllegalStateException("purpose must be defined to use FileUploadRequest")
             )
         }
     }
 
     companion object {
 
         /**
-         * Creates a [FileUploadRequest.Builder] to build a [FileUploadRequest].
+         * Creates a [UploadFileRequest.Builder] to build a [UploadFileRequest].
          */
         @JvmStatic
         fun builder() = Builder()

src/main/kotlin/com/cjcrafter/openai/files/FileUploadRequest.kt renamed to src/main/kotlin/com/cjcrafter/openai/files/UploadFileRequest.kt

@@ -0,0 +1,3 @@
+package com.cjcrafter.openai.files
+
+fun uploadFileRequest(block: UploadFileRequest.Builder.() -> Unit) = UploadFileRequest.builder().apply(block).build()