feat: Add ChatCompletions API

osugikoji · osugikoji · commit 67a810bf5cba · 2023-03-06T21:11:15.000-03:00
diff --git a/ychat/src/commonMain/kotlin/co/yml/ychat/YChat.kt b/ychat/src/commonMain/kotlin/co/yml/ychat/YChat.kt
@@ -1,5 +1,6 @@
 package co.yml.ychat
 
+import co.yml.ychat.entrypoint.features.ChatCompletions
 import co.yml.ychat.entrypoint.features.Completion
 import co.yml.ychat.entrypoint.impl.YChatImpl
 import kotlin.jvm.JvmStatic
@@ -32,6 +33,50 @@ interface YChat {
      */
     fun completion(): Completion
 
+    /**
+     * The chatCompletions api generates a list of chat completions for the given input message.
+     * It uses machine learning algorithms to generate responses that match the context or pattern
+     * provided in the input message.
+     *
+     * You can configure various parameters to customize the chat completions, such as the model to use,
+     * the number of results to generate, and the maximum number of tokens allowed for the generated answer.
+     *
+     * Example usage:
+     * ```
+     * val result = YChat.create(apiKey).chatCompletions()
+     *      .setModel("gpt-3.5-turbo")
+     *      .setResults(3)
+     *      .setMaxTokens(1024)
+     *      .execute("Hello, how are you?")
+     * ```
+     * This would generate three chat completion strings based on the input message "Hello, how are you?"
+     * using the "gpt-3.5-turbo" model, with a maximum of 1024 tokens allowed for each generated answer.
+     *
+     * You can also use the `addMessage` method to provide additional context or information to the API,
+     * which can be used to restrict the generated responses to a certain topic or context.
+     *
+     * Example usage:
+     * ```
+     * val result = YChat.create(apiKey).chatCompletions()
+     *      .setModel("gpt-3.5-turbo")
+     *      .setResults(3)
+     *      .setMaxTokens(1024)
+     *      .addMessage(
+     *          role = "assistant",
+     *          content = "You are a helpful assistant that only answers questions related to fitness"
+     *      )
+     *      .execute("What is the best exercise for building muscle?")
+     * ```
+     * This would generate three chat completion strings based on the input message "What is the
+     * best exercise for building muscle?", using the "gpt-3.5-turbo" model, with a maximum of 1024
+     * tokens allowed for each generated answer. The `addMessage` method is used to provide context
+     * to the API, restricting the generated responses to questions related to fitness, since the
+     * assistant is set to only answer questions related to that topic.
+     *
+     * @return A new instance of the `ChatCompletions` class.
+     */
+    fun chatCompletions(): ChatCompletions
+
     /**
      * Callback is an interface used for handling the results of an operation.
      * It provides two methods, `onSuccess` and `onError`, for handling the success
diff --git a/ychat/src/commonMain/kotlin/co/yml/ychat/data/api/ChatGptApi.kt b/ychat/src/commonMain/kotlin/co/yml/ychat/data/api/ChatGptApi.kt
@@ -1,10 +1,14 @@
 package co.yml.ychat.data.api
 
+import co.yml.ychat.data.dto.ChatCompletionParamsDto
+import co.yml.ychat.data.dto.ChatCompletionsDto
 import co.yml.ychat.data.dto.CompletionDto
 import co.yml.ychat.data.dto.CompletionParamsDto
 import co.yml.ychat.data.infrastructure.ApiResult
 
 internal interface ChatGptApi {
 
     suspend fun completion(paramsDto: CompletionParamsDto): ApiResult<CompletionDto>
+
+    suspend fun chatCompletions(paramsDto: ChatCompletionParamsDto): ApiResult<ChatCompletionsDto>
 }
diff --git a/ychat/src/commonMain/kotlin/co/yml/ychat/data/api/impl/ChatGptApiImpl.kt b/ychat/src/commonMain/kotlin/co/yml/ychat/data/api/impl/ChatGptApiImpl.kt
@@ -1,6 +1,8 @@
 package co.yml.ychat.data.api.impl
 
 import co.yml.ychat.data.api.ChatGptApi
+import co.yml.ychat.data.dto.ChatCompletionParamsDto
+import co.yml.ychat.data.dto.ChatCompletionsDto
 import co.yml.ychat.data.dto.CompletionDto
 import co.yml.ychat.data.dto.CompletionParamsDto
 import co.yml.ychat.data.infrastructure.ApiExecutor
@@ -16,4 +18,12 @@ internal class ChatGptApiImpl(private val apiExecutor: ApiExecutor) : ChatGptApi
             .setBody(paramsDto)
             .execute()
     }
+
+    override suspend fun chatCompletions(paramsDto: ChatCompletionParamsDto): ApiResult<ChatCompletionsDto> {
+        return apiExecutor
+            .setEndpoint("v1/chat/completions")
+            .setHttpMethod(HttpMethod.Post)
+            .setBody(paramsDto)
+            .execute()
+    }
 }
diff --git a/ychat/src/commonMain/kotlin/co/yml/ychat/data/dto/ChatCompletionParamsDto.kt b/ychat/src/commonMain/kotlin/co/yml/ychat/data/dto/ChatCompletionParamsDto.kt
@@ -0,0 +1,20 @@
+package co.yml.ychat.data.dto
+
+import kotlinx.serialization.SerialName
+import kotlinx.serialization.Serializable
+
+@Serializable
+internal data class ChatCompletionParamsDto(
+    @SerialName("model")
+    val model: String,
+    @SerialName("messages")
+    val messages: List<ChatMessageDto>,
+    @SerialName("max_tokens")
+    val maxTokens: Int,
+    @SerialName("temperature")
+    val temperature: Double,
+    @SerialName("top_p")
+    val topP: Double,
+    @SerialName("n")
+    val maxResults: Int = 1,
+)
diff --git a/ychat/src/commonMain/kotlin/co/yml/ychat/data/dto/ChatCompletionsChoiceDto.kt b/ychat/src/commonMain/kotlin/co/yml/ychat/data/dto/ChatCompletionsChoiceDto.kt
@@ -0,0 +1,14 @@
+package co.yml.ychat.data.dto
+
+import kotlinx.serialization.SerialName
+import kotlinx.serialization.Serializable
+
+@Serializable
+internal data class ChatCompletionsChoiceDto(
+    @SerialName("index")
+    val index: Int,
+    @SerialName("message")
+    val message: ChatMessageDto,
+    @SerialName("finish_reason")
+    val finishReason: String,
+)
diff --git a/ychat/src/commonMain/kotlin/co/yml/ychat/data/dto/ChatCompletionsDto.kt b/ychat/src/commonMain/kotlin/co/yml/ychat/data/dto/ChatCompletionsDto.kt
@@ -0,0 +1,16 @@
+package co.yml.ychat.data.dto
+
+import kotlinx.serialization.SerialName
+import kotlinx.serialization.Serializable
+
+@Serializable
+internal data class ChatCompletionsDto(
+    @SerialName("id")
+    val id: String,
+    @SerialName("model")
+    val model: String,
+    @SerialName("choices")
+    val choices: List<ChatCompletionsChoiceDto>,
+    @SerialName("usage")
+    val usage: UsageDto,
+)
diff --git a/ychat/src/commonMain/kotlin/co/yml/ychat/data/dto/ChatMessageDto.kt b/ychat/src/commonMain/kotlin/co/yml/ychat/data/dto/ChatMessageDto.kt
@@ -0,0 +1,12 @@
+package co.yml.ychat.data.dto
+
+import kotlinx.serialization.SerialName
+import kotlinx.serialization.Serializable
+
+@Serializable
+internal data class ChatMessageDto(
+    @SerialName("role")
+    val role: String,
+    @SerialName("content")
+    val content: String,
+)
diff --git a/ychat/src/commonMain/kotlin/co/yml/ychat/di/module/LibraryModule.kt b/ychat/src/commonMain/kotlin/co/yml/ychat/di/module/LibraryModule.kt
@@ -5,8 +5,11 @@ import co.yml.ychat.data.api.impl.ChatGptApiImpl
 import co.yml.ychat.data.infrastructure.ApiExecutor
 import co.yml.ychat.data.storage.ChatLogStorage
 import co.yml.ychat.di.provider.NetworkProvider
+import co.yml.ychat.domain.usecases.ChatCompletionsUseCase
 import co.yml.ychat.domain.usecases.CompletionUseCase
+import co.yml.ychat.entrypoint.features.ChatCompletions
 import co.yml.ychat.entrypoint.features.Completion
+import co.yml.ychat.entrypoint.impl.ChatCompletionsImpl
 import co.yml.ychat.entrypoint.impl.CompletionImpl
 import kotlinx.coroutines.Dispatchers
 import org.koin.core.module.Module
@@ -19,10 +22,12 @@ internal class LibraryModule(private val apiKey: String) {
 
     private val entrypointModule = module {
         factory<Completion> { CompletionImpl(Dispatchers.Default, get()) }
+        factory<ChatCompletions> { ChatCompletionsImpl(Dispatchers.Default, get()) }
     }
 
     private val domainModule = module {
         factory { CompletionUseCase(get(), get()) }
+        factory { ChatCompletionsUseCase(get()) }
     }
 
     private val dataModule = module {
diff --git a/ychat/src/commonMain/kotlin/co/yml/ychat/domain/mapper/ChatCompletionsMapper.kt b/ychat/src/commonMain/kotlin/co/yml/ychat/domain/mapper/ChatCompletionsMapper.kt
@@ -0,0 +1,24 @@
+package co.yml.ychat.domain.mapper
+
+import co.yml.ychat.data.dto.ChatCompletionParamsDto
+import co.yml.ychat.data.dto.ChatCompletionsDto
+import co.yml.ychat.data.dto.ChatMessageDto
+import co.yml.ychat.domain.model.ChatCompletionsParams
+import co.yml.ychat.domain.model.ChatMessage
+
+internal fun ChatCompletionsDto.toChatMessages(): List<ChatMessage> {
+    return this.choices.map {
+        ChatMessage(it.message.role, it.message.content)
+    }
+}
+
+internal fun ChatCompletionsParams.toChatCompletionParamsDto(): ChatCompletionParamsDto {
+    return ChatCompletionParamsDto(
+        model = this.model,
+        messages = this.messages.map { ChatMessageDto(it.role, it.content) },
+        maxTokens = this.maxTokens,
+        temperature = this.temperature,
+        topP = this.topP,
+        maxResults = this.maxResults,
+    )
+}
diff --git a/ychat/src/commonMain/kotlin/co/yml/ychat/domain/model/ChatCompletionsParams.kt b/ychat/src/commonMain/kotlin/co/yml/ychat/domain/model/ChatCompletionsParams.kt
@@ -0,0 +1,10 @@
+package co.yml.ychat.domain.model
+
+internal data class ChatCompletionsParams(
+    var messages: ArrayList<ChatMessage> = arrayListOf(),
+    var model: String = "gpt-3.5-turbo",
+    var maxResults: Int = 1,
+    var maxTokens: Int = 4096,
+    var temperature: Double = 1.0,
+    var topP: Double = 1.0,
+)
diff --git a/ychat/src/commonMain/kotlin/co/yml/ychat/domain/model/ChatMessage.kt b/ychat/src/commonMain/kotlin/co/yml/ychat/domain/model/ChatMessage.kt
@@ -0,0 +1,12 @@
+package co.yml.ychat.domain.model
+
+/**
+ * Represents a message in a conversation, consisting of a [role] indicating the speaker
+ * (e.g., “system”, “user” or “assistant”), and the [content] of the message sent by the speaker.
+ * @property role The role of the speaker who sends the message.
+ * @property content The content of the message sent by the speaker.
+ */
+data class ChatMessage(
+    val role: String,
+    val content: String
+)
diff --git a/ychat/src/commonMain/kotlin/co/yml/ychat/domain/usecases/ChatCompletionsUseCase.kt b/ychat/src/commonMain/kotlin/co/yml/ychat/domain/usecases/ChatCompletionsUseCase.kt
@@ -0,0 +1,16 @@
+package co.yml.ychat.domain.usecases
+
+import co.yml.ychat.data.api.ChatGptApi
+import co.yml.ychat.domain.mapper.toChatCompletionParamsDto
+import co.yml.ychat.domain.mapper.toChatMessages
+import co.yml.ychat.domain.model.ChatCompletionsParams
+import co.yml.ychat.domain.model.ChatMessage
+
+internal data class ChatCompletionsUseCase(private val chatGptApi: ChatGptApi) {
+
+    suspend fun requestChatCompletions(params: ChatCompletionsParams): List<ChatMessage> {
+        val requestDto = params.toChatCompletionParamsDto()
+        val response = chatGptApi.chatCompletions(requestDto)
+        return response.getBodyOrThrow().toChatMessages()
+    }
+}
diff --git a/ychat/src/commonMain/kotlin/co/yml/ychat/entrypoint/features/ChatCompletions.kt b/ychat/src/commonMain/kotlin/co/yml/ychat/entrypoint/features/ChatCompletions.kt
@@ -0,0 +1,84 @@
+package co.yml.ychat.entrypoint.features
+
+import co.yml.ychat.YChat
+import co.yml.ychat.data.exception.ChatGptException
+import co.yml.ychat.domain.model.ChatMessage
+import kotlin.coroutines.cancellation.CancellationException
+
+interface ChatCompletions {
+
+    /**
+     * Sets the ID of the [model] to use. The default value is "gpt-3.5-turbo".
+     *
+     * @param model ID of the model to use.
+     * @return The updated [ChatCompletions] object with the new model ID.
+     */
+    fun setModel(model: String): ChatCompletions
+
+    /**
+     * Sets the [topP] value for nucleus sampling. The default value is 1.0.
+     *
+     * @param topP An alternative to sampling with temperature, called nucleus sampling, where the model
+     * considers the results of the tokens with top_p probability mass. So 0.1 means only the tokens
+     * comprising the top 10% probability mass are considered. We generally recommend altering
+     * this or [setTemperature] but not both.
+     * @return The updated [ChatCompletions] object with the new top_p value.
+     */
+    fun setTopP(topP: Double): ChatCompletions
+
+    /**
+     * Sets the sampling [temperature] to use. The default value is 1.0.
+     *
+     * @param temperature What sampling temperature to use. Higher values means the model will take more
+     * risks. Try 0.9 for more creative applications, and 0 (argmax sampling) for ones with a
+     * well-defined answer. We generally recommend altering this or [setTopP] but not both.
+     * @return The updated [ChatCompletions] object with the new sampling temperature.
+     */
+    fun setTemperature(temperature: Double): ChatCompletions
+
+    /**
+     * Sets the number of chat completion choices to generate for each input message.
+     * The default value is 1.
+     *
+     * @param results How many chat completion choices to generate for each input message.
+     * @return The updated [ChatCompletions] object with the new number of results.
+     */
+    fun setMaxResults(results: Int): ChatCompletions
+
+    /**
+     * The default value of [tokens] is 4096.
+     *
+     * @param tokens The maximum number of tokens allowed for the generated answer.
+     * @return The updated [ChatCompletions] object with the new maximum number of tokens.
+     */
+    fun setMaxTokens(tokens: Int): ChatCompletions
+
+    /**
+     * Adds a new message to the ongoing conversation with the given [role] and [content].
+     *
+     * @param role The role of the speaker who sends the message (either “system”, “user” or “assistant”).
+     * @param content The content of the message sent by the speaker.
+     * @return The updated [ChatCompletions] object with the newly added message.
+     */
+    fun addMessage(role: String, content: String): ChatCompletions
+
+    /**
+     * Generates a list of chat completions for the given user [content].
+     *
+     * @param content The content of the user input.
+     * @return A list of chat message objects representing the possible completions.
+     * @throws CancellationException if the operation is cancelled.
+     * @throws ChatGptException if there is an error generating chat completions.
+     */
+    @Throws(CancellationException::class, ChatGptException::class)
+    suspend fun execute(content: String): List<ChatMessage>
+
+    /**
+     * Generates a list of chat completions for the given [content] message and passes it to the
+     * provided callback.
+     *
+     * @param content The content of the user input.
+     * @param callback The callback to receive the list of possible completions.
+     */
+    fun execute(content: String, callback: YChat.Callback<List<ChatMessage>>)
+}
diff --git a/ychat/src/commonMain/kotlin/co/yml/ychat/entrypoint/impl/ChatCompletionsImpl.kt b/ychat/src/commonMain/kotlin/co/yml/ychat/entrypoint/impl/ChatCompletionsImpl.kt
diff --git a/ychat/src/commonMain/kotlin/co/yml/ychat/entrypoint/impl/YChatImpl.kt b/ychat/src/commonMain/kotlin/co/yml/ychat/entrypoint/impl/YChatImpl.kt
