implement tools

Author: CJCrafter

build.gradle.kts

@@ -20,6 +20,7 @@ repositories {
 dependencies {
     implementation("com.squareup.okhttp3:okhttp:4.9.2")
     implementation("com.google.code.gson:gson:2.10.1")
+    implementation("org.jetbrains:annotations:24.0.1")
 
     testImplementation("io.github.cdimascio:dotenv-kotlin:6.4.1")
     testImplementation("org.junit.jupiter:junit-jupiter:5.9.2")

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

@@ -1,6 +1,6 @@
 package com.cjcrafter.openai
 
-import com.cjcrafter.openai.gson.FinishReasonAdapter
+import com.google.gson.annotations.SerializedName
 
 /**
  * [FinishReason] wraps the possible reasons that a generation model may stop
@@ -15,6 +15,7 @@ enum class FinishReason {
      * completely generates its entire message, and has nothing else to add.
      * Ideally, you always want your finish reason to be [STOP].
      */
+    @SerializedName("stop")
     STOP,
 
     /**
@@ -23,33 +24,23 @@ enum class FinishReason {
      * message with finish reason [LENGTH]. Some models have a higher token
      * limit than others.
      */
+    @SerializedName("length")
     LENGTH,
 
     /**
      * Occurs due to a flag from OpenAI's content filters. This occurrence is
      * rare, and tends to happen when you blatantly violate OpenAI's terms.
      */
+    @SerializedName("content_filter")
     CONTENT_FILTER,
 
     /**
      * Occurs when the model uses one of the available tools.
      */
+    @SerializedName("tool_calls")
     TOOL_CALLS,
 
     @Deprecated("functions have been replaced by tools")
+    @SerializedName("function_call")
     FUNCTION_CALL;
-
-    companion object {
-
-        /**
-         * Returns the google gson adapter for serializing this enum to a json
-         * file. Whe
-         *
-         * @return
-         */
-        @JvmStatic
-        fun adapter() : FinishReasonAdapter {
-            return FinishReasonAdapter()
-        }
-    }
 }

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

@@ -1,93 +1,163 @@
 package com.cjcrafter.openai
 
 import com.cjcrafter.openai.chat.*
+import com.cjcrafter.openai.chat.tool.ToolChoice
 import com.cjcrafter.openai.completions.CompletionRequest
 import com.cjcrafter.openai.completions.CompletionResponse
 import com.cjcrafter.openai.completions.CompletionResponseChunk
-import com.cjcrafter.openai.exception.OpenAIError
-import com.cjcrafter.openai.gson.ChatChoiceChunkAdapter
-import com.cjcrafter.openai.gson.ChatUserAdapter
-import com.cjcrafter.openai.gson.FinishReasonAdapter
 import com.google.gson.Gson
 import com.google.gson.GsonBuilder
 import okhttp3.OkHttpClient
 
 interface OpenAI {
 
-    @Throws(OpenAIError::class)
+    /**
+     * Calls the [completions](https://platform.openai.com/docs/api-reference/completions)
+     * API endpoint. This method is blocking.
+     *
+     * Completions are considered Legacy, and OpenAI officially recommends that
+     * all developers use the **chat completion** endpoint instead. See
+     * [createChatCompletion].
+     *
+     * @param request The request to send to the API
+     * @return The response from the API
+     */
     fun createCompletion(request: CompletionRequest): CompletionResponse
 
-    @Throws(OpenAIError::class)
+    /**
+     * Calls the [completions](https://platform.openai.com/docs/api-reference/completions)
+     * API endpoint and streams each token 1 at a time for a faster response
+     * time.
+     *
+     * This method is **technically** not blocking, but the returned iterable
+     * will block until the next token is generated.
+     * ```
+     * // Each iteration of the loop will block until the next token is streamed
+     * for (chunk in openAI.streamCompletion(request)) {
+     *     // Do something with the chunk
+     * }
+     * ```
+     *
+     * Completions are considered Legacy, and OpenAI officially recommends that
+     * all developers use the **chat completion** endpoint isntead. See
+     * [streamChatCompletion].
+     *
+     * @param request The request to send to the API
+     * @return The response from the API
+     */
     fun streamCompletion(request: CompletionRequest): Iterable<CompletionResponseChunk>
 
-    @Throws(OpenAIError::class)
+    /**
+     * Calls the [chat completions](https://platform.openai.com/docs/api-reference/chat)
+     * API endpoint. This method is blocking.
+     *
+     * @param request The request to send to the API
+     * @return The response from the API
+     */
     fun createChatCompletion(request: ChatRequest): ChatResponse
 
-    @Throws(OpenAIError::class)
+    /**
+     * Calls the [chat completions](https://platform.openai.com/docs/api-reference/chat)
+     * API endpoint and streams each token 1 at a time for a faster response.
+     *
+     * This method is **technically** not blocking, but the returned iterable
+     * will block until the next token is generated.
+     * ```
+     * // Each iteration of the loop will block until the next token is streamed
+     * for (chunk in openAI.streamChatCompletion(request)) {
+     *    // Do something with the chunk
+     * }
+     * ```
+     *
+     * @param request The request to send to the API
+     * @return The response from the API
+     */
     fun streamChatCompletion(request: ChatRequest): Iterable<ChatResponseChunk>
 
-    open class Builder {
+    open class Builder internal constructor() {
         protected var apiKey: String? = null
         protected var organization: String? = null
         protected var client: OkHttpClient = OkHttpClient()
 
         fun apiKey(apiKey: String) = apply { this.apiKey = apiKey }
-
         fun organization(organization: String?) = apply { this.organization = organization }
-
         fun client(client: OkHttpClient) = apply { this.client = client }
 
         open fun build(): OpenAI {
-            checkNotNull(apiKey) { "apiKey must be defined to use OpenAI" }
-            return OpenAIImpl(apiKey!!, organization, client)
+            return OpenAIImpl(
+                apiKey ?: throw IllegalStateException("apiKey must be defined to use OpenAI"),
+                organization,
+                client
+            )
         }
     }
 
-    class AzureBuilder : Builder() {
+    class AzureBuilder internal constructor(): Builder() {
         private var azureBaseUrl: String? = null
         private var apiVersion: String? = null
         private var modelName: String? = null
 
         fun azureBaseUrl(azureBaseUrl: String) = apply { this.azureBaseUrl = azureBaseUrl }
-
         fun apiVersion(apiVersion: String) = apply { this.apiVersion = apiVersion }
-
         fun modelName(modelName: String) = apply { this.modelName = modelName }
 
         override fun build(): OpenAI {
-            checkNotNull(apiKey) { "apiKey must be defined to use OpenAI" }
-            checkNotNull(azureBaseUrl) { "azureBaseUrl must be defined for azure" }
-            checkNotNull(apiVersion) { "apiVersion must be defined for azure" }
-            checkNotNull(modelName) { "modelName must be defined for azure" }
-
-            return AzureOpenAI(apiKey!!, organization, client, azureBaseUrl!!, apiVersion!!, modelName!!)
+            return AzureOpenAI(
+                apiKey ?: throw IllegalStateException("apiKey must be defined to use OpenAI"),
+                organization,
+                client,
+                azureBaseUrl ?: throw IllegalStateException("azureBaseUrl must be defined for azure"),
+                apiVersion ?: throw IllegalStateException("apiVersion must be defined for azure"),
+                modelName ?: throw IllegalStateException("modelName must be defined for azure")
+            )
         }
     }
 
     companion object {
 
+        /**
+         * Instantiates a builder for a default OpenAI instance. For Azure's
+         * OpenAI, use [azureBuilder] instead.
+         */
         @JvmStatic
         fun builder() = Builder()
 
+        /**
+         * Instantiates a builder for an Azure OpenAI.
+         */
         @JvmStatic
         fun azureBuilder() = AzureBuilder()
 
+        /**
+         * Returns a Gson instance with the default OpenAI adapters registered.
+         * This can be used to save conversations (and other data) to file.
+         */
         @JvmStatic
         fun createGson(): Gson = createGsonBuilder().create()
 
+        /**
+         * Returns a GsonBuilder instance with the default OpenAI adapters
+         * registered.
+         */
         @JvmStatic
         fun createGsonBuilder(): GsonBuilder {
             return GsonBuilder()
-                .registerTypeAdapter(ChatUser::class.java, ChatUserAdapter())
-                .registerTypeAdapter(FinishReason::class.java, FinishReasonAdapter())
-                .registerTypeAdapter(ChatChoiceChunk::class.java, ChatChoiceChunkAdapter())
+                .serializeNulls()
+                .registerTypeAdapter(ChatChoiceChunk::class.java, ChatChoiceChunk.adapter())
+                .registerTypeAdapter(ToolChoice::class.java, ToolChoice.adapter())
         }
 
+        /**
+         * Extension function to stream a completion using kotlin coroutines.
+         */
         fun OpenAI.streamCompletion(request: CompletionRequest, consumer: (CompletionResponseChunk) -> Unit) {
             for (chunk in streamCompletion(request))
                 consumer(chunk)
         }
 
+        /**
+         * Extension function to stream a chat completion using kotlin coroutines.
+         */
         fun OpenAI.streamChatCompletion(request: ChatRequest, consumer: (ChatResponseChunk) -> Unit) {
             for (chunk in streamChatCompletion(request))
                 consumer(chunk)

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

@@ -96,7 +96,15 @@ open class OpenAIImpl @JvmOverloads constructor(
         request.stream = false // use streamChatCompletion for stream=true
         val httpRequest = buildRequest(request, CHAT_ENDPOINT)
 
-        return ChatResponse("1", 1, listOf(), ChatUsage(1, 1, 1))
+        val httpResponse = client.newCall(httpRequest).execute()
+        if (!httpResponse.isSuccessful) {
+            val json = httpResponse.body?.byteStream()?.bufferedReader()?.readText()
+            httpResponse.close()
+            throw IOException("Unexpected code $httpResponse, recieved: $json")
+        }
+
+        val json = httpResponse.body?.byteStream()?.bufferedReader() ?: throw IOException("Response body is null")
+        return gson.fromJson(json, ChatResponse::class.java)
     }
 
     override fun streamChatCompletion(request: ChatRequest): Iterable<ChatResponseChunk> {

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

@@ -1,6 +1,7 @@
 package com.cjcrafter.openai.chat
 
 import com.cjcrafter.openai.FinishReason
+import com.cjcrafter.openai.gson.ChatChoiceChunkAdapter
 import com.google.gson.JsonObject
 import com.google.gson.annotations.SerializedName
 
@@ -44,6 +45,11 @@ data class ChatChoiceChunk(
      * complete message.
      */
     fun isFinished() = finishReason != null
+
+    companion object {
+        @JvmStatic
+        fun adapter() = ChatChoiceChunkAdapter()
+    }
 }
 
 /*

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

@@ -1,5 +1,8 @@
 package com.cjcrafter.openai.chat
 
+import com.cjcrafter.openai.chat.tool.ToolCall
+import com.google.gson.annotations.SerializedName
+
 /**
  * ChatGPT's biggest innovation is its conversation memory. To remember the
  * conversation, we need to map each message to who sent it. This data class
@@ -9,7 +12,17 @@ package com.cjcrafter.openai.chat
  * @property content The string content of the message.
  * @see ChatUser
  */
-data class ChatMessage(var role: ChatUser, var content: String) {
+data class ChatMessage @JvmOverloads constructor(
+    var role: ChatUser,
+    var content: String?,
+    @field:SerializedName("tool_calls") var toolCalls: List<ToolCall>? = null,
+    @field:SerializedName("tool_call_id") var toolCallId: String? = null,
+) {
+    init {
+        if (role == ChatUser.TOOL) {
+            requireNotNull(toolCallId) { "toolCallId must be set when role is TOOL" }
+        }
+    }
 
     companion object {
 
@@ -36,5 +49,13 @@ data class ChatMessage(var role: ChatUser, var content: String) {
         fun String.toAssistantMessage(): ChatMessage {
             return ChatMessage(ChatUser.ASSISTANT, this)
         }
+
+        /**
+         * Returns a new [ChatMessage] using [ChatUser.TOOL].
+         */
+        @JvmStatic
+        fun String.toToolMessage(toolCallId: String): ChatMessage {
+            return ChatMessage(ChatUser.TOOL, this, toolCallId = toolCallId)
+        }
     }
 }