add kdocs + mutability

Author: CJCrafter

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

@@ -4,6 +4,7 @@ import okhttp3.OkHttpClient
 import okhttp3.Request
 import okhttp3.RequestBody
 import okhttp3.RequestBody.Companion.toRequestBody
+import org.jetbrains.annotations.ApiStatus
 
 /**
  * The Azure OpenAI API client.
@@ -16,7 +17,7 @@ import okhttp3.RequestBody.Companion.toRequestBody
  * @property apiVersion The API version to use. Defaults to 2023-03-15-preview.
  * @property modelName The model name to use. This is the name of the model deployed to Azure.
  */
-class AzureOpenAI @JvmOverloads constructor(
+class AzureOpenAI @ApiStatus.Internal constructor(
     apiKey: String,
     organization: String? = null,
     client: OkHttpClient = OkHttpClient(),

src/main/kotlin/com/cjcrafter/openai/chat/tool/ChatMessageDelta.kt

@@ -3,9 +3,16 @@ package com.cjcrafter.openai.chat.tool
 import com.cjcrafter.openai.chat.ChatUser
 import com.fasterxml.jackson.annotation.JsonProperty
 
+/**
+ * Represents the "delta," or changes of a chat message. This is used by streams
+ * stream 1 token at a time.
+ *
+ * @property role Who sent the message. Will always be [ChatUser.ASSISTANT] for the first message, then `null`
+ * @property content 1 token of the message. Will always be `null` for tool calls
+ * @property toolCalls Modifications to the tool calls. Will always be `null` when content is not `null`
+ */
 data class ChatMessageDelta(
     val role: ChatUser? = null,
     val content: String? = null,
     @JsonProperty("tool_calls") val toolCalls: List<ToolCallDelta>? = null,
-) {
-}
+)

src/main/kotlin/com/cjcrafter/openai/chat/tool/FunctionCall.kt

@@ -23,9 +23,7 @@ data class FunctionCall(
     var name: String,
     var arguments: String,
 ) {
-
-    @ApiStatus.Internal
-    fun update(delta: FunctionCallDelta) {
+    internal fun update(delta: FunctionCallDelta) {
         // The only field that updates is arguments
         arguments += delta.arguments
     }

src/main/kotlin/com/cjcrafter/openai/chat/tool/FunctionCallDelta.kt

@@ -1,7 +1,12 @@
 package com.cjcrafter.openai.chat.tool
 
-import org.jetbrains.annotations.ApiStatus
-
+/**
+ * Represents the "delta," or changes of a function call. This is used by streams
+ * to stream 1 token at a time.
+ *
+ * @property name The name of the function to call. Will always be `null` except for the first call.
+ * @property arguments 1 token of the arguments. Well be delivered as a JSON string.
+ */
 data class FunctionCallDelta(
     val name: String?,
     val arguments: String,
@@ -10,8 +15,7 @@ data class FunctionCallDelta(
     /**
      * Returns an **incomplete** function call.
      */
-    @ApiStatus.Internal
-    fun toFunctionCall(): FunctionCall {
+    internal fun toFunctionCall(): FunctionCall {
         return FunctionCall(
             name ?: throw IllegalStateException("name must be set"),
             arguments

src/main/kotlin/com/cjcrafter/openai/chat/tool/FunctionParameters.kt

@@ -11,9 +11,9 @@ package com.cjcrafter.openai.chat.tool
  * @property properties The map of method parameters.
  */
 data class FunctionParameters internal constructor(
-    val type: String = "object",
-    val properties: MutableMap<String, FunctionProperty> = mutableMapOf(),
-    val required: MutableSet<String> = mutableSetOf(),
+    var type: String = "object",
+    var properties: MutableMap<String, FunctionProperty> = mutableMapOf(),
+    var required: MutableSet<String> = mutableSetOf(),
 ) {
     /**
      * Require that the given parameter is used by ChatGPT.

src/main/kotlin/com/cjcrafter/openai/chat/tool/FunctionTool.kt

@@ -17,9 +17,9 @@ import com.cjcrafter.openai.util.RegexInternals
  * @property description A description of the function
  */
 data class FunctionTool internal constructor(
-    @FunctionTag val name: String,
-    val parameters: FunctionParameters,
-    val description: String? = null,
+    @FunctionTag var name: String,
+    var parameters: FunctionParameters,
+    var description: String? = null,
 ) : AbstractTool() {
 
     init {

src/main/kotlin/com/cjcrafter/openai/chat/tool/Tool.kt

@@ -10,6 +10,6 @@ package com.cjcrafter.openai.chat.tool
  * @property function The function. This is only used if [type] is [ToolType.FUNCTION].
  */
 data class Tool(
-    val type: ToolType,
-    val function: FunctionTool,
+    var type: ToolType,
+    var function: FunctionTool,
 )

src/main/kotlin/com/cjcrafter/openai/chat/tool/ToolCall.kt

@@ -1,13 +1,23 @@
 package com.cjcrafter.openai.chat.tool
 
-import org.jetbrains.annotations.ApiStatus
-
+/**
+ * Wraps a tool call by ChatGPT. You should check the [type] of the tool call,
+ * and handle the request. For example, if the type is [ToolType.FUNCTION], you
+ * should call the function and return the result.
+ *
+ * When making subsequent requests to chat completions, you should make sure to
+ * pass the message that contained this tool call, and the result of the tool
+ * call.
+ *
+ * @property id The id of this call. You should use this to construct a [com.cjcrafter.openai.chat.ChatUser.TOOL] message.
+ * @property type The type of tool call. Currently, the only type is [ToolType.FUNCTION].
+ * @property function The function call containing the function name and arguments.
+ */
 data class ToolCall(
     var id: String,
     var type: ToolType,
     var function: FunctionCall,
 ) {
-    @ApiStatus.Internal
     internal fun update(delta: ToolCallDelta) {
         // The only field that updates is function
         if (delta.function != null)

src/main/kotlin/com/cjcrafter/openai/chat/tool/ToolCallDelta.kt

@@ -1,15 +1,21 @@
 package com.cjcrafter.openai.chat.tool
 
-import org.jetbrains.annotations.ApiStatus
-
+/**
+ * Represents the "delta," or changes of a tool call. This is used by streams
+ * to stream 1 token at a time.
+ *
+ * @property index The index of the tool call we are modifying.
+ * @property id The tool call id used in replies. Will always be `null` except for the first call.
+ * @property type The type of tool call. Will always be `null` except for the first call.
+ * @property function The modifications to the function call.
+ */
 data class ToolCallDelta(
     val index: Int,
     val id: String? = null,
     val type: ToolType? = null,
     val function: FunctionCallDelta? = null,
 ) {
-    @ApiStatus.Internal
-    fun toToolCall() = ToolCall(
+    internal fun toToolCall() = ToolCall(
         id = id ?: throw IllegalStateException("id must be set"),
         type = type ?: throw IllegalStateException("type must be set"),
         function = function?.toFunctionCall() ?: throw IllegalStateException("function must be set"),

src/main/kotlin/com/cjcrafter/openai/chat/tool/ToolChoice.kt

@@ -3,6 +3,9 @@ package com.cjcrafter.openai.chat.tool
 import com.cjcrafter.openai.jackson.ToolChoiceDeserializer
 import com.cjcrafter.openai.jackson.ToolChoiceSerializer
 
+/**
+ * Represents the configuration for tool choice. Defaults to [Auto].
+ */
 sealed class ToolChoice {
 
     /**