docs: add some missing javadocs (#78)

Author: stainless-app[bot]

openai-java-core/src/main/kotlin/com/openai/models/ChatCompletionAssistantMessageParam.kt

@@ -421,6 +421,10 @@ private constructor(
         override fun toString() = "Audio{id=$id, additionalProperties=$additionalProperties}"
     }
 
+    /**
+     * The contents of the assistant message. Required unless `tool_calls` or `function_call` is
+     * specified.
+     */
     @JsonDeserialize(using = Content.Deserializer::class)
     @JsonSerialize(using = Content.Serializer::class)
     class Content
@@ -447,8 +451,12 @@ private constructor(
 
         fun isArrayOfContentParts(): Boolean = arrayOfContentParts != null
 
+        /** The contents of the assistant message. */
         fun asTextContent(): String = textContent.getOrThrow("textContent")
-
+        /**
+         * An array of content parts with a defined type. Can be one or more of type `text`, or
+         * exactly one of type `refusal`.
+         */
         fun asArrayOfContentParts(): List<ChatCompletionRequestAssistantMessageContentPart> =
             arrayOfContentParts.getOrThrow("arrayOfContentParts")
 
@@ -491,8 +499,13 @@ private constructor(
 
         companion object {
 
+            /** The contents of the assistant message. */
             @JvmStatic fun ofTextContent(textContent: String) = Content(textContent = textContent)
 
+            /**
+             * An array of content parts with a defined type. Can be one or more of type `text`, or
+             * exactly one of type `refusal`.
+             */
             @JvmStatic
             fun ofArrayOfContentParts(
                 arrayOfContentParts: List<ChatCompletionRequestAssistantMessageContentPart>
@@ -549,6 +562,7 @@ private constructor(
             }
         }
 
+        /** Learn about [text inputs](https://platform.openai.com/docs/guides/text-generation). */
         @JsonDeserialize(
             using = ChatCompletionRequestAssistantMessageContentPart.Deserializer::class
         )
@@ -576,6 +590,9 @@ private constructor(
             fun isChatCompletionContentPartRefusal(): Boolean =
                 chatCompletionContentPartRefusal != null
 
+            /**
+             * Learn about [text inputs](https://platform.openai.com/docs/guides/text-generation).
+             */
             fun asChatCompletionContentPartText(): ChatCompletionContentPartText =
                 chatCompletionContentPartText.getOrThrow("chatCompletionContentPartText")
 
@@ -638,6 +655,10 @@ private constructor(
 
             companion object {
 
+                /**
+                 * Learn about
+                 * [text inputs](https://platform.openai.com/docs/guides/text-generation).
+                 */
                 @JvmStatic
                 fun ofChatCompletionContentPartText(
                     chatCompletionContentPartText: ChatCompletionContentPartText

openai-java-core/src/main/kotlin/com/openai/models/ChatCompletionContentPart.kt

@@ -18,6 +18,7 @@ import java.util.Objects
 import java.util.Optional
 import kotlin.jvm.optionals.getOrNull
 
+/** Learn about [text inputs](https://platform.openai.com/docs/guides/text-generation). */
 @JsonDeserialize(using = ChatCompletionContentPart.Deserializer::class)
 @JsonSerialize(using = ChatCompletionContentPart.Serializer::class)
 class ChatCompletionContentPart
@@ -47,12 +48,13 @@ private constructor(
     fun isChatCompletionContentPartInputAudio(): Boolean =
         chatCompletionContentPartInputAudio != null
 
+    /** Learn about [text inputs](https://platform.openai.com/docs/guides/text-generation). */
     fun asChatCompletionContentPartText(): ChatCompletionContentPartText =
         chatCompletionContentPartText.getOrThrow("chatCompletionContentPartText")
-
+    /** Learn about [image inputs](https://platform.openai.com/docs/guides/vision). */
     fun asChatCompletionContentPartImage(): ChatCompletionContentPartImage =
         chatCompletionContentPartImage.getOrThrow("chatCompletionContentPartImage")
-
+    /** Learn about [audio inputs](https://platform.openai.com/docs/guides/audio). */
     fun asChatCompletionContentPartInputAudio(): ChatCompletionContentPartInputAudio =
         chatCompletionContentPartInputAudio.getOrThrow("chatCompletionContentPartInputAudio")
 
@@ -112,11 +114,13 @@ private constructor(
 
     companion object {
 
+        /** Learn about [text inputs](https://platform.openai.com/docs/guides/text-generation). */
         @JvmStatic
         fun ofChatCompletionContentPartText(
             chatCompletionContentPartText: ChatCompletionContentPartText
         ) = ChatCompletionContentPart(chatCompletionContentPartText = chatCompletionContentPartText)
 
+        /** Learn about [image inputs](https://platform.openai.com/docs/guides/vision). */
         @JvmStatic
         fun ofChatCompletionContentPartImage(
             chatCompletionContentPartImage: ChatCompletionContentPartImage
@@ -125,6 +129,7 @@ private constructor(
                 chatCompletionContentPartImage = chatCompletionContentPartImage
             )
 
+        /** Learn about [audio inputs](https://platform.openai.com/docs/guides/audio). */
         @JvmStatic
         fun ofChatCompletionContentPartInputAudio(
             chatCompletionContentPartInputAudio: ChatCompletionContentPartInputAudio

openai-java-core/src/main/kotlin/com/openai/models/ChatCompletionCreateParams.kt

@@ -1650,6 +1650,21 @@ constructor(
             )
     }
 
+    /**
+     * Deprecated in favor of `tool_choice`.
+     *
+     * Controls which (if any) function is called by the model.
+     *
+     * `none` means the model will not call a function and instead generates a message.
+     *
+     * `auto` means the model can pick between generating a message or calling a function.
+     *
+     * Specifying a particular function via `{"name": "my_function"}` forces the model to call that
+     * function.
+     *
+     * `none` is the default when no functions are present. `auto` is the default if functions are
+     * present.
+     */
     @JsonDeserialize(using = FunctionCall.Deserializer::class)
     @JsonSerialize(using = FunctionCall.Serializer::class)
     class FunctionCall
@@ -1675,8 +1690,15 @@ constructor(
 
         fun isFunctionCallOption(): Boolean = functionCallOption != null
 
+        /**
+         * `none` means the model will not call a function and instead generates a message. `auto`
+         * means the model can pick between generating a message or calling a function.
+         */
         fun asBehavior(): Behavior = behavior.getOrThrow("behavior")
-
+        /**
+         * Specifying a particular function via `{"name": "my_function"}` forces the model to call
+         * that function.
+         */
         fun asFunctionCallOption(): ChatCompletionFunctionCallOption =
             functionCallOption.getOrThrow("functionCallOption")
 
@@ -1710,8 +1732,16 @@ constructor(
 
         companion object {
 
+            /**
+             * `none` means the model will not call a function and instead generates a message.
+             * `auto` means the model can pick between generating a message or calling a function.
+             */
             @JvmStatic fun ofBehavior(behavior: Behavior) = FunctionCall(behavior = behavior)
 
+            /**
+             * Specifying a particular function via `{"name": "my_function"}` forces the model to
+             * call that function.
+             */
             @JvmStatic
             fun ofFunctionCallOption(functionCallOption: ChatCompletionFunctionCallOption) =
                 FunctionCall(functionCallOption = functionCallOption)
@@ -2095,6 +2125,23 @@ constructor(
         override fun toString() = "Metadata{additionalProperties=$additionalProperties}"
     }
 
+    /**
+     * An object specifying the format that the model must output.
+     *
+     * Setting to `{ "type": "json_schema", "json_schema": {...} }` enables Structured Outputs which
+     * ensures the model will match your supplied JSON schema. Learn more in the
+     * [Structured Outputs guide](https://platform.openai.com/docs/guides/structured-outputs).
+     *
+     * Setting to `{ "type": "json_object" }` enables JSON mode, which ensures the message the model
+     * generates is valid JSON.
+     *
+     * **Important:** when using JSON mode, you **must** also instruct the model to produce JSON
+     * yourself via a system or user message. Without this, the model may generate an unending
+     * stream of whitespace until the generation reaches the token limit, resulting in a
+     * long-running and seemingly "stuck" request. Also note that the message content may be
+     * partially cut off if `finish_reason="length"`, which indicates the generation exceeded
+     * `max_tokens` or the conversation exceeded the max context length.
+     */
     @JsonDeserialize(using = ResponseFormat.Deserializer::class)
     @JsonSerialize(using = ResponseFormat.Serializer::class)
     class ResponseFormat
@@ -2289,6 +2336,7 @@ constructor(
         override fun toString() = value.toString()
     }
 
+    /** Up to 4 sequences where the API will stop generating further tokens. */
     @JsonDeserialize(using = Stop.Deserializer::class)
     @JsonSerialize(using = Stop.Serializer::class)
     class Stop

openai-java-core/src/main/kotlin/com/openai/models/ChatCompletionDeveloperMessageParam.kt

@@ -160,6 +160,7 @@ private constructor(
             )
     }
 
+    /** The contents of the developer message. */
     @JsonDeserialize(using = Content.Deserializer::class)
     @JsonSerialize(using = Content.Serializer::class)
     class Content
@@ -184,8 +185,12 @@ private constructor(
 
         fun isArrayOfContentParts(): Boolean = arrayOfContentParts != null
 
+        /** The contents of the developer message. */
         fun asTextContent(): String = textContent.getOrThrow("textContent")
-
+        /**
+         * An array of content parts with a defined type. For developer messages, only type `text`
+         * is supported.
+         */
         fun asArrayOfContentParts(): List<ChatCompletionContentPartText> =
             arrayOfContentParts.getOrThrow("arrayOfContentParts")
 
@@ -229,8 +234,13 @@ private constructor(
 
         companion object {
 
+            /** The contents of the developer message. */
             @JvmStatic fun ofTextContent(textContent: String) = Content(textContent = textContent)
 
+            /**
+             * An array of content parts with a defined type. For developer messages, only type
+             * `text` is supported.
+             */
             @JvmStatic
             fun ofArrayOfContentParts(arrayOfContentParts: List<ChatCompletionContentPartText>) =
                 Content(arrayOfContentParts = arrayOfContentParts)

openai-java-core/src/main/kotlin/com/openai/models/ChatCompletionMessageParam.kt

@@ -18,6 +18,10 @@ import java.util.Objects
 import java.util.Optional
 import kotlin.jvm.optionals.getOrNull
 
+/**
+ * Developer-provided instructions that the model should follow, regardless of messages sent by the
+ * user. With o1 models and newer, `developer` messages replace the previous `system` messages.
+ */
 @JsonDeserialize(using = ChatCompletionMessageParam.Deserializer::class)
 @JsonSerialize(using = ChatCompletionMessageParam.Serializer::class)
 class ChatCompletionMessageParam
@@ -73,15 +77,23 @@ private constructor(
 
     fun isChatCompletionFunctionMessageParam(): Boolean = chatCompletionFunctionMessageParam != null
 
+    /**
+     * Developer-provided instructions that the model should follow, regardless of messages sent by
+     * the user. With o1 models and newer, `developer` messages replace the previous `system`
+     * messages.
+     */
     fun asChatCompletionDeveloperMessageParam(): ChatCompletionDeveloperMessageParam =
         chatCompletionDeveloperMessageParam.getOrThrow("chatCompletionDeveloperMessageParam")
-
+    /**
+     * Developer-provided instructions that the model should follow, regardless of messages sent by
+     * the user. With o1 models and newer, use `developer` messages for this purpose instead.
+     */
     fun asChatCompletionSystemMessageParam(): ChatCompletionSystemMessageParam =
         chatCompletionSystemMessageParam.getOrThrow("chatCompletionSystemMessageParam")
-
+    /** Messages sent by an end user, containing prompts or additional context information. */
     fun asChatCompletionUserMessageParam(): ChatCompletionUserMessageParam =
         chatCompletionUserMessageParam.getOrThrow("chatCompletionUserMessageParam")
-
+    /** Messages sent by the model in response to user messages. */
     fun asChatCompletionAssistantMessageParam(): ChatCompletionAssistantMessageParam =
         chatCompletionAssistantMessageParam.getOrThrow("chatCompletionAssistantMessageParam")
 
@@ -167,6 +179,11 @@ private constructor(
 
     companion object {
 
+        /**
+         * Developer-provided instructions that the model should follow, regardless of messages sent
+         * by the user. With o1 models and newer, `developer` messages replace the previous `system`
+         * messages.
+         */
         @JvmStatic
         fun ofChatCompletionDeveloperMessageParam(
             chatCompletionDeveloperMessageParam: ChatCompletionDeveloperMessageParam
@@ -175,6 +192,10 @@ private constructor(
                 chatCompletionDeveloperMessageParam = chatCompletionDeveloperMessageParam
             )
 
+        /**
+         * Developer-provided instructions that the model should follow, regardless of messages sent
+         * by the user. With o1 models and newer, use `developer` messages for this purpose instead.
+         */
         @JvmStatic
         fun ofChatCompletionSystemMessageParam(
             chatCompletionSystemMessageParam: ChatCompletionSystemMessageParam
@@ -183,6 +204,7 @@ private constructor(
                 chatCompletionSystemMessageParam = chatCompletionSystemMessageParam
             )
 
+        /** Messages sent by an end user, containing prompts or additional context information. */
         @JvmStatic
         fun ofChatCompletionUserMessageParam(
             chatCompletionUserMessageParam: ChatCompletionUserMessageParam
@@ -191,6 +213,7 @@ private constructor(
                 chatCompletionUserMessageParam = chatCompletionUserMessageParam
             )
 
+        /** Messages sent by the model in response to user messages. */
         @JvmStatic
         fun ofChatCompletionAssistantMessageParam(
             chatCompletionAssistantMessageParam: ChatCompletionAssistantMessageParam

openai-java-core/src/main/kotlin/com/openai/models/ChatCompletionPredictionContent.kt

@@ -153,6 +153,10 @@ private constructor(
             )
     }
 
+    /**
+     * The content that should be matched when generating a model response. If generated tokens
+     * would match this content, the entire model response can be returned much more quickly.
+     */
     @JsonDeserialize(using = Content.Deserializer::class)
     @JsonSerialize(using = Content.Serializer::class)
     class Content
@@ -181,8 +185,16 @@ private constructor(
 
         fun isArrayOfContentParts(): Boolean = arrayOfContentParts != null
 
+        /**
+         * The content used for a Predicted Output. This is often the text of a file you are
+         * regenerating with minor changes.
+         */
         fun asTextContent(): String = textContent.getOrThrow("textContent")
-
+        /**
+         * An array of content parts with a defined type. Supported options differ based on the
+         * [model](https://platform.openai.com/docs/models) being used to generate the response. Can
+         * contain text inputs.
+         */
         fun asArrayOfContentParts(): List<ChatCompletionContentPartText> =
             arrayOfContentParts.getOrThrow("arrayOfContentParts")
 
@@ -226,8 +238,17 @@ private constructor(
 
         companion object {
 
+            /**
+             * The content used for a Predicted Output. This is often the text of a file you are
+             * regenerating with minor changes.
+             */
             @JvmStatic fun ofTextContent(textContent: String) = Content(textContent = textContent)
 
+            /**
+             * An array of content parts with a defined type. Supported options differ based on the
+             * [model](https://platform.openai.com/docs/models) being used to generate the response.
+             * Can contain text inputs.
+             */
             @JvmStatic
             fun ofArrayOfContentParts(arrayOfContentParts: List<ChatCompletionContentPartText>) =
                 Content(arrayOfContentParts = arrayOfContentParts)

openai-java-core/src/main/kotlin/com/openai/models/ChatCompletionSystemMessageParam.kt

@@ -159,6 +159,7 @@ private constructor(
             )
     }
 
+    /** The contents of the system message. */
     @JsonDeserialize(using = Content.Deserializer::class)
     @JsonSerialize(using = Content.Serializer::class)
     class Content
@@ -183,8 +184,12 @@ private constructor(
 
         fun isArrayOfContentParts(): Boolean = arrayOfContentParts != null
 
+        /** The contents of the system message. */
         fun asTextContent(): String = textContent.getOrThrow("textContent")
-
+        /**
+         * An array of content parts with a defined type. For system messages, only type `text` is
+         * supported.
+         */
         fun asArrayOfContentParts(): List<ChatCompletionContentPartText> =
             arrayOfContentParts.getOrThrow("arrayOfContentParts")
 
@@ -228,8 +233,13 @@ private constructor(
 
         companion object {
 
+            /** The contents of the system message. */
             @JvmStatic fun ofTextContent(textContent: String) = Content(textContent = textContent)
 
+            /**
+             * An array of content parts with a defined type. For system messages, only type `text`
+             * is supported.
+             */
             @JvmStatic
             fun ofArrayOfContentParts(arrayOfContentParts: List<ChatCompletionContentPartText>) =
                 Content(arrayOfContentParts = arrayOfContentParts)