feature: Implements list models entrypoint

osugikoji · osugikoji · commit 259a6a642a9d · 2023-03-29T16:20:01.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
@@ -4,6 +4,7 @@ import co.yml.ychat.entrypoint.features.ChatCompletions
 import co.yml.ychat.entrypoint.features.Completion
 import co.yml.ychat.entrypoint.features.Edits
 import co.yml.ychat.entrypoint.features.ImageGenerations
+import co.yml.ychat.entrypoint.features.ListModels
 import co.yml.ychat.entrypoint.impl.YChatImpl
 import kotlin.jvm.JvmStatic
 import kotlin.jvm.Volatile
@@ -18,6 +19,19 @@ import kotlin.native.concurrent.ThreadLocal
  */
 interface YChat {
 
+    /**
+     * The listModels api lists the currently available models, and provides basic information
+     * about each one such as the owner and availability.
+     *
+     * Example usage:
+     * ```
+     * val result = YChat.create(apiKey)
+     *      .listModels()
+     *      .execute()
+     * ```
+     */
+    fun listModels(): ListModels
+
     /**
      * The completions api can be used for a wide variety of tasks. You input some text as a
      * prompt, and the model will generate a text completion that attempts to match whatever
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
@@ -8,6 +8,7 @@ import co.yml.ychat.data.dto.EditsDto
 import co.yml.ychat.data.dto.EditsParamsDto
 import co.yml.ychat.data.dto.ImageGenerationsDto
 import co.yml.ychat.data.dto.ImageGenerationsParamsDto
+import co.yml.ychat.data.dto.ModelListDto
 import co.yml.ychat.data.infrastructure.ApiResult
 
 internal interface ChatGptApi {
@@ -19,4 +20,6 @@ internal interface ChatGptApi {
     suspend fun imageGenerations(paramsDto: ImageGenerationsParamsDto): ApiResult<ImageGenerationsDto>
 
     suspend fun edits(paramsDto: EditsParamsDto): ApiResult<EditsDto>
+
+    suspend fun models(): ApiResult<ModelListDto>
 }
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
@@ -9,6 +9,7 @@ import co.yml.ychat.data.dto.EditsDto
 import co.yml.ychat.data.dto.EditsParamsDto
 import co.yml.ychat.data.dto.ImageGenerationsDto
 import co.yml.ychat.data.dto.ImageGenerationsParamsDto
+import co.yml.ychat.data.dto.ModelListDto
 import co.yml.ychat.data.infrastructure.ApiExecutor
 import co.yml.ychat.data.infrastructure.ApiResult
 import io.ktor.http.HttpMethod
@@ -46,4 +47,11 @@ internal class ChatGptApiImpl(private val apiExecutor: ApiExecutor) : ChatGptApi
             .setBody(paramsDto)
             .execute()
     }
+
+    override suspend fun models(): ApiResult<ModelListDto> {
+        return apiExecutor
+            .setEndpoint("v1/models")
+            .setHttpMethod(HttpMethod.Get)
+            .execute()
+    }
 }
diff --git a/ychat/src/commonMain/kotlin/co/yml/ychat/data/dto/ModelDto.kt b/ychat/src/commonMain/kotlin/co/yml/ychat/data/dto/ModelDto.kt
@@ -0,0 +1,14 @@
+package co.yml.ychat.data.dto
+
+import kotlinx.serialization.SerialName
+import kotlinx.serialization.Serializable
+
+@Serializable
+internal data class ModelDto(
+    @SerialName("id")
+    val id: String,
+    @SerialName("owned_by")
+    val ownedBy: String,
+    @SerialName("permission")
+    val permission: List<ModelPermissionDto>,
+)
diff --git a/ychat/src/commonMain/kotlin/co/yml/ychat/data/dto/ModelListDto.kt b/ychat/src/commonMain/kotlin/co/yml/ychat/data/dto/ModelListDto.kt
@@ -0,0 +1,10 @@
+package co.yml.ychat.data.dto
+
+import kotlinx.serialization.SerialName
+import kotlinx.serialization.Serializable
+
+@Serializable
+internal data class ModelListDto(
+    @SerialName("data")
+    val models: List<ModelDto>,
+)
diff --git a/ychat/src/commonMain/kotlin/co/yml/ychat/data/dto/ModelPermissionDto.kt b/ychat/src/commonMain/kotlin/co/yml/ychat/data/dto/ModelPermissionDto.kt
@@ -0,0 +1,26 @@
+package co.yml.ychat.data.dto
+
+import kotlinx.serialization.SerialName
+import kotlinx.serialization.Serializable
+
+@Serializable
+internal data class ModelPermissionDto(
+    @SerialName("id")
+    val id: String,
+    @SerialName("allow_create_engine")
+    val allowCreateEngine: Boolean,
+    @SerialName("allow_sampling")
+    val allowSampling: Boolean,
+    @SerialName("allow_logprobs")
+    val allowLogProbs: Boolean,
+    @SerialName("allow_search_indices")
+    val allowSearchIndices: Boolean,
+    @SerialName("allow_view")
+    val allowView: Boolean,
+    @SerialName("allow_fine_tuning")
+    val allowFineTuning: Boolean,
+    @SerialName("organization")
+    val organization: String,
+    @SerialName("is_blocking")
+    val isBlocking: Boolean,
+)
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
@@ -9,14 +9,17 @@ import co.yml.ychat.domain.usecases.ChatCompletionsUseCase
 import co.yml.ychat.domain.usecases.CompletionUseCase
 import co.yml.ychat.domain.usecases.EditsUseCase
 import co.yml.ychat.domain.usecases.ImageGenerationsUseCase
+import co.yml.ychat.domain.usecases.ListModelsUseCase
 import co.yml.ychat.entrypoint.features.ChatCompletions
 import co.yml.ychat.entrypoint.features.Completion
 import co.yml.ychat.entrypoint.features.Edits
 import co.yml.ychat.entrypoint.features.ImageGenerations
+import co.yml.ychat.entrypoint.features.ListModels
 import co.yml.ychat.entrypoint.impl.ChatCompletionsImpl
 import co.yml.ychat.entrypoint.impl.CompletionImpl
 import co.yml.ychat.entrypoint.impl.EditsImpl
 import co.yml.ychat.entrypoint.impl.ImageGenerationsImpl
+import co.yml.ychat.entrypoint.impl.ListModelsImpl
 import kotlinx.coroutines.Dispatchers
 import org.koin.core.module.Module
 import org.koin.dsl.module
@@ -27,13 +30,15 @@ internal class LibraryModule(private val apiKey: String) {
         entrypointModule + domainModule + dataModule + platformModule()
 
     private val entrypointModule = module {
+        factory<ListModels> { ListModelsImpl(Dispatchers.Default, get()) }
         factory<Completion> { CompletionImpl(Dispatchers.Default, get()) }
         factory<ChatCompletions> { ChatCompletionsImpl(Dispatchers.Default, get()) }
         factory<ImageGenerations> { ImageGenerationsImpl(Dispatchers.Default, get()) }
         factory<Edits> { EditsImpl(Dispatchers.Default, get()) }
     }
 
     private val domainModule = module {
+        factory { ListModelsUseCase(get()) }
         factory { CompletionUseCase(get(), get()) }
         factory { ChatCompletionsUseCase(get()) }
         factory { ImageGenerationsUseCase(get()) }
diff --git a/ychat/src/commonMain/kotlin/co/yml/ychat/domain/mapper/ModelMapper.kt b/ychat/src/commonMain/kotlin/co/yml/ychat/domain/mapper/ModelMapper.kt
@@ -0,0 +1,32 @@
+package co.yml.ychat.domain.mapper
+
+import co.yml.ychat.data.dto.ModelDto
+import co.yml.ychat.data.dto.ModelPermissionDto
+import co.yml.ychat.domain.model.AIModel
+import co.yml.ychat.domain.model.AIModelPermission
+
+internal fun List<ModelDto>.toModel(): List<AIModel> {
+    return this.map { it.toModel() }
+}
+
+internal fun ModelDto.toModel(): AIModel {
+    return AIModel(
+        id = this.id,
+        ownedBy = this.ownedBy,
+        permission = this.permission.map { it.toPermission() }
+    )
+}
+
+internal fun ModelPermissionDto.toPermission(): AIModelPermission {
+    return AIModelPermission(
+        id = id,
+        allowCreateEngine = allowCreateEngine,
+        allowSampling = allowSampling,
+        allowLogProbs = allowLogProbs,
+        allowSearchIndices = allowSearchIndices,
+        allowView = allowView,
+        allowFineTuning = allowFineTuning,
+        organization = organization,
+        isBlocking = isBlocking,
+    )
+}
diff --git a/ychat/src/commonMain/kotlin/co/yml/ychat/domain/model/AIModel.kt b/ychat/src/commonMain/kotlin/co/yml/ychat/domain/model/AIModel.kt
@@ -0,0 +1,14 @@
+package co.yml.ychat.domain.model
+
+/**
+ * The artificial intelligence model, providing basic information about the model such as the
+ * owner and permission.
+ * @property id The ID of the model.
+ * @property ownedBy The user or organization that owns the model.
+ * @property permission A list of permissions associated with the model.
+ */
+data class AIModel(
+    val id: String,
+    val ownedBy: String,
+    val permission: List<AIModelPermission>,
+)
diff --git a/ychat/src/commonMain/kotlin/co/yml/ychat/domain/model/AIModelPermission.kt b/ychat/src/commonMain/kotlin/co/yml/ychat/domain/model/AIModelPermission.kt
@@ -0,0 +1,25 @@
+package co.yml.ychat.domain.model
+
+/**
+ * A representation of the permissions associated with a [AIModel].
+ * @property id The ID of the permission.
+ * @property allowCreateEngine Whether the permission allows creating engines.
+ * @property allowSampling Whether the permission allows sampling from the model.
+ * @property allowLogProbs Whether the permission allows accessing log probabilities.
+ * @property allowSearchIndices Whether the permission allows accessing search indices.
+ * @property allowView Whether the permission allows viewing the model.
+ * @property allowFineTuning Whether the permission allows fine-tuning the model.
+ * @property organization The organization associated with the permission.
+ * @property isBlocking Whether the permission is currently blocking access to the model.
+ */
+data class AIModelPermission(
+    val id: String,
+    val allowCreateEngine: Boolean,
+    val allowSampling: Boolean,
+    val allowLogProbs: Boolean,
+    val allowSearchIndices: Boolean,
+    val allowView: Boolean,
+    val allowFineTuning: Boolean,
+    val organization: String,
+    val isBlocking: Boolean,
+)
diff --git a/ychat/src/commonMain/kotlin/co/yml/ychat/domain/usecases/ListModelsUseCase.kt b/ychat/src/commonMain/kotlin/co/yml/ychat/domain/usecases/ListModelsUseCase.kt
@@ -0,0 +1,13 @@
+package co.yml.ychat.domain.usecases
+
+import co.yml.ychat.data.api.ChatGptApi
+import co.yml.ychat.domain.mapper.toModel
+import co.yml.ychat.domain.model.AIModel
+
+internal data class ListModelsUseCase(private val chatGptApi: ChatGptApi) {
+
+    suspend fun getListModels(): List<AIModel> {
+        val response = chatGptApi.models()
+        return response.getBodyOrThrow().models.toModel()
+    }
+}
diff --git a/ychat/src/commonMain/kotlin/co/yml/ychat/entrypoint/features/Edits.kt b/ychat/src/commonMain/kotlin/co/yml/ychat/entrypoint/features/Edits.kt
@@ -6,18 +6,67 @@ import kotlin.coroutines.cancellation.CancellationException
 
 interface Edits {
 
+    /**
+     * Sets the input to generate edits for.
+     *
+     * @param input The input text to generate edits for.
+     * @return The updated [Edits] object with the new input text.
+     */
     fun setInput(input: String): Edits
 
+    /**
+     * Sets the number of edit results to generate. The default value is 1.
+     *
+     * @param results The number of edit results to generate.
+     * @return The updated [Edits] object with the new number of results.
+     */
     fun setResults(results: Int): Edits
 
+    /**
+     * Sets the ID of the model to use. The default value is "text-davinci-edit-001".
+     *
+     * @param model ID of the model to use.
+     * @return The updated [Edits] object with the new model ID.
+     */
     fun setModel(model: String): Edits
 
+    /**
+     * 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.
+     * @return The updated [Edits] object with the new sampling temperature.
+     */
     fun setTemperature(temperature: Double): Edits
 
+    /**
+     * 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.
+     * @return The updated [Edits] object with the new top_p value.
+     */
     fun setTopP(topP: Double): Edits
 
+    /**
+     * Generates a list of possible edits for the given instruction.
+     *
+     * @param instruction The instruction to generate edits for.
+     * @return A list of edits generated for the given instruction.
+     * @throws CancellationException if the operation is cancelled.
+     * @throws ChatGptException if there is an error generating edits.
+     */
     @Throws(CancellationException::class, ChatGptException::class)
     suspend fun execute(instruction: String): List<String>
 
+    /**
+     * Generates a list of possible edits for the given instruction and passes it to the
+     * provided callback.
+     *
+     * @param instruction The instruction to generate edits for.
+     * @param callback The callback to receive the list of possible edits.
+     */
     fun execute(instruction: String, callback: YChat.Callback<List<String>>)
 }
diff --git a/ychat/src/commonMain/kotlin/co/yml/ychat/entrypoint/features/ImageGenerations.kt b/ychat/src/commonMain/kotlin/co/yml/ychat/entrypoint/features/ImageGenerations.kt
@@ -6,14 +6,44 @@ import kotlin.coroutines.cancellation.CancellationException
 
 interface ImageGenerations {
 
+    /**
+     * Sets the number of image generation results to return. The default value is 1.
+     * @param results The number of image generation results to return.
+     * @return The updated [ImageGenerations] object with the new number of results.
+     */
     fun setResults(results: Int): ImageGenerations
 
+    /**
+     * Sets the size of the images generated (squared). Ex. 256x256, 512x512, 1024x1024.
+     * The default value is "256x256".
+     * @param size The size of the generated images.
+     * @return The updated [ImageGenerations] object with the new image size.
+     */
     fun setSize(size: String): ImageGenerations
 
+    /**
+     * Sets the format in which the generated images are returned. Must be one of url or b64_json.
+     * The default value is "url".
+     * @param responseFormat The response format of the generated images.
+     * @return The updated [ImageGenerations] object with the new response format.
+     */
     fun setResponseFormat(responseFormat: String): ImageGenerations
 
+    /**
+     * Generates a list of image generations for the given [prompt].
+     * @param prompt The prompt for generating the images.
+     * @return A list of generated image objects.
+     * @throws CancellationException if the operation is cancelled.
+     * @throws ChatGptException if there is an error generating images.
+     */
     @Throws(CancellationException::class, ChatGptException::class)
     suspend fun execute(prompt: String): List<String>
 
+    /**
+     * Generates a list of image generations for the given [prompt] and passes it to
+     * the provided [callback].
+     * @param prompt The prompt for generating the images.
+     * @param callback The callback to receive the list of generated images.
+     */
     fun execute(prompt: String, callback: YChat.Callback<List<String>>)
 }
diff --git a/ychat/src/commonMain/kotlin/co/yml/ychat/entrypoint/features/ListModels.kt b/ychat/src/commonMain/kotlin/co/yml/ychat/entrypoint/features/ListModels.kt
@@ -0,0 +1,27 @@
+package co.yml.ychat.entrypoint.features
+
+import co.yml.ychat.YChat
+import co.yml.ychat.data.exception.ChatGptException
+import co.yml.ychat.domain.model.AIModel
+import kotlin.coroutines.cancellation.CancellationException
+
+interface ListModels {
+
+    /**
+     * Retrieve a list of currently available models, and provides basic information about
+     * each one such as the owner and availability.
+     *
+     * @return A list of artificial intelligence models.
+     * @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(): List<AIModel>
+
+    /**
+     * Retrieve a list of currently available models, and passes it to the provided callback.
+     *
+     * @param callback The callback to receive the list of available models.
+     */
+    fun execute(callback: YChat.Callback<List<AIModel>>)
+}
diff --git a/ychat/src/commonMain/kotlin/co/yml/ychat/entrypoint/impl/ListModelsImpl.kt b/ychat/src/commonMain/kotlin/co/yml/ychat/entrypoint/impl/ListModelsImpl.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
