refactor: API alignment, beta removals, and legacy tagging (#228)

Author: aallam

CHANGELOG.md

@@ -1,3 +1,27 @@
+# Unreleased
+
+### Added
+- Introduced `Parameters.Empty` for functions without parameters.
+- Added `File.statusDetails` for retrieving file status details.
+- `HyperParams` new fields: `computeClassificationMetrics`, `classificationNClasses` and `classificationPositiveClass`.
+
+### Removed
+- Removed beta status from the chat and audio features.
+
+### Deprecated
+- `completions` is deprecated.
+- `edits` as legacy.
+
+### Breaking Changes
+- **Audio**: Updated `TranscriptionRequest`'s `responseFormat` type to `AudioResponseFormat`.
+- **Fine Tune**: set `HyperParams.learningRateMultiplier` to be non-nullable.
+- **Chat**: Multiple changes have been implemented:
+  - Modified `ChatChoice.finishReason`, `ChatChunk.finishReason`, and `Choice.finishReason` types to `FinishReason`.
+  - Set `index`, `message`, and `finishReason` fields in `ChatChoice` to be non-nullable.
+  - Set `index`, `delta`, and `finishReason` fields in `ChatChunk` to be non-nullable.
+  - Set `ChatCompletionFunction.parameters` to be non-nullable.
+  - In `FunctionCall`, set `name`, `arguments`, and `argumentsAsJson()` to be non-nullable.
+
 # 3.3.2
 > Published 21 Jul 2023
 

README.md

@@ -74,16 +74,20 @@ Use your `OpenAI` instance to make API requests. [Learn more](guides/GettingStar
 ### Supported features
 
 - [Models](guides/GettingStarted.md#models)
-- [Completions](guides/GettingStarted.md#completions)
 - [Chat](guides/GettingStarted.md#chat)
-- [Edits](guides/GettingStarted.md#edits)
 - [Images](guides/GettingStarted.md#images)
 - [Embeddings](guides/GettingStarted.md#embeddings)
 - [Files](guides/GettingStarted.md#files)
 - [Fine-tunes](guides/GettingStarted.md#fine-tunes)
 - [Moderations](guides/GettingStarted.md#moderations)
 - [Audio](guides/GettingStarted.md#audio)
 
+#### Legacy
+- [Completions](guides/GettingStarted.md#completions)
+
+#### Deprecated
+- [Edits](guides/GettingStarted.md#edits)
+
 ## 📚 Guides
 
 Get started and understand more about how to use OpenAI API client for Kotlin with these guides:

guides/ChatFunctionCall.md

@@ -112,19 +112,19 @@ Send the chat request and handle the response. If there's a function call in the
 
 ```kotlin
 val response = openAI.chatCompletion(request)
-val message = response.choices.first().message ?: error("no response found!")
+val message = response.choices.first().message
 message.functionCall?.let { functionCall ->
     val availableFunctions = mapOf("currentWeather" to ::currentWeather)
     val functionToCall = availableFunctions[functionCall.name] ?: error("Function ${functionCall.name} not found")
-    val functionArgs = functionCall.argumentsAsJson() ?: error("arguments field is missing")
+    val functionArgs = functionCall.argumentsAsJson()
     val functionResponse = functionToCall(
         functionArgs.getValue("location").jsonPrimitive.content,
         functionArgs["unit"]?.jsonPrimitive?.content ?: "fahrenheit"
     )
     chatMessages.add(
         ChatMessage(
             role = message.role,
-            content = message.content ?: "", // required to not be empty in this case
+            content = message.content.orEmpty(), // required to not be empty in this case
             functionCall = message.functionCall
         )
     )
@@ -142,7 +142,7 @@ message.functionCall?.let { functionCall ->
     }
 
     val secondResponse = openAI.chatCompletion(secondRequest)
-    println(secondResponse.choices.first().message?.content)
+    println(secondResponse.choices.first().message.content)
 } ?: println(message.content)
 ```
 
@@ -156,7 +156,6 @@ message.functionCall?.let { functionCall ->
 Below is a complete Kotlin example following the guide:
 
 ```kotlin
-import com.aallam.openai.api.BetaOpenAI
 import com.aallam.openai.api.chat.*
 import com.aallam.openai.api.model.ModelId
 import com.aallam.openai.client.OpenAI
@@ -209,11 +208,11 @@ suspend fun main() {
     }
 
     val response = openAI.chatCompletion(request)
-    val message = response.choices.first().message ?: error("no response found!")
+    val message = response.choices.first().message
     message.functionCall?.let { functionCall ->
         val availableFunctions = mapOf("currentWeather" to ::currentWeather)
         val functionToCall = availableFunctions[functionCall.name] ?: error("Function ${functionCall.name} not found")
-        val functionArgs = functionCall.argumentsAsJson() ?: error("arguments field is missing")
+        val functionArgs = functionCall.argumentsAsJson()
         val functionResponse = functionToCall(
             functionArgs.getValue("location").jsonPrimitive.content,
             functionArgs["unit"]?.jsonPrimitive?.content ?: "fahrenheit"
@@ -222,7 +221,7 @@ suspend fun main() {
         chatMessages.add(
             ChatMessage(
                 role = message.role,
-                content = message.content ?: "",
+                content = message.content.orEmpty(),
                 functionCall = message.functionCall
             )
         )
@@ -241,7 +240,7 @@ suspend fun main() {
         }
 
         val secondResponse = openAI.chatCompletion(secondRequest)
-        println(secondResponse.choices.first().message?.content)
+        println(secondResponse.choices.first().message.content)
     } ?: println(message.content)
 }
 

guides/GettingStarted.md

@@ -13,21 +13,17 @@ Use your `OpenAI` instance to make API requests.
 - [Models](#models)
   - [List models](#list-models)
   - [Retrieve a model](#retrieve-a-model)
-- [Completions](#completions)
-  - [Create completion](#create-completion)
 - [Chat](#chat)
-  - [Create chat completion](#create-chat-completion-beta)
-- [Edits](#edits)
-  - [Create edits](#create-edits)
+  - [Create chat completion](#create-chat-completion)
 - [Images](#images)
-  - [Create image](#create-image-beta)
-  - [Edit images](#edit-images-beta)
-  - [Create image variation](#create-image-variation-beta)
+  - [Create image](#create-image)
+  - [Edit images](#edit-images)
+  - [Create image variation](#create-image-variation)
 - [Embeddings](#embeddings)
   - [Create embeddings](#create-embeddings)
 - [Audio](#audio)
-  - [Create transcription](#create-transcription-beta)
-  - [Create translation](#create-translation-beta)
+  - [Create transcription](#create-transcription)
+  - [Create translation](#create-translation)
 - [Files](#files)
   - [List files](#list-files)
   - [Upload file](#upload-file)
@@ -44,6 +40,14 @@ Use your `OpenAI` instance to make API requests.
 - [Moderations](#moderations)
   - [Create moderation](#create-moderation)
 
+#### Legacy
+- [Completions](#completions)
+  - [Create completion](#create-completion-legacy)
+
+#### Deprecated
+- [Edits](#edits)
+  - [Create edits](#create-edits-deprecated)
+
 ## Models
 
 List and describe the various [models](https://platform.openai.com/docs/models) available in the API.
@@ -66,30 +70,11 @@ val id = ModelId("text-ada-001")
 val model: Model = openAI.model(id)
 ```
 
-## Completions
-
-Given a prompt, the model will return one or more predicted completions, and can also return the probabilities of alternative tokens at each position.
-
-### Create Completion
-
-Creates a completion for the provided prompt and parameters
-
-```kotlin
-val completionRequest = CompletionRequest(
-    model = ModelId("text-ada-001"),
-    prompt = "Somebody once told me the world is gonna roll me",
-    echo = true
-)
-val completion: TextCompletion = openAI.completion(completionRequest)
-// or, as flow
-val completions: Flow<TextCompletion> = openAI.completions(completionRequest)
-```
-
 ## Chat
 
 Given a chat conversation, the model will return a chat completion response.
 
-### Create chat completion `beta`
+### Create chat completion
 
 Creates a completion for the chat message.
 
@@ -112,30 +97,11 @@ val completion: ChatCompletion = openAI.chatCompletion(chatCompletionRequest)
 val completions: Flow<ChatCompletionChunk> = openAI.chatCompletions(chatCompletionRequest)
 ```
 
-## Edits
-
-Given a prompt and an instruction, the model will return an edited version of the prompt.
-
-### Create edits
-
-Creates a new edit for the provided input, instruction, and parameters.
-
-
-```kotlin
-val edit = openAI.edit(
-    request = EditsRequest(
-        model = ModelId("text-davinci-edit-001"),
-        input = "What day of the wek is it?",
-        instruction = "Fix the spelling mistakes"
-    )
-)
-```
-
 ## Images
 
 Given a prompt and/or an input image, the model will generate a new image.
 
-### Create image `beta`
+### Create image
 
 Creates an image given a prompt.
 
@@ -149,7 +115,7 @@ val images = openAI.imageURL( // or openAI.imageJSON
 )
 ````
 
-### Edit images `beta`
+### Edit images
 
 Creates an edited or extended image given an original image and a prompt.
 
@@ -165,7 +131,7 @@ val images = openAI.imageURL( // or openAI.imageJSON
 )
 ````
 
-### Create image variation `beta`
+### Create image variation
 
 Creates a variation of a given image.
 
@@ -200,7 +166,7 @@ val embeddings = openAI.embeddings(
 
 Learn how to turn audio into text.
 
-### Create transcription `Beta`
+### Create transcription
 
 Transcribes audio into the input language.
 
@@ -212,7 +178,7 @@ val request = TranscriptionRequest(
 val transcription = openAI.transcription(request)
 ```
 
-### Create translation `Beta`
+### Create translation
 
 Translates audio into English.
 
@@ -337,11 +303,11 @@ openAI.delete(fileId)
 
 ## Moderations
 
-Given a input text, outputs if the model classifies it as violating OpenAI's content policy.
+Given an input text, outputs if the model classifies it as violating OpenAI's content policy.
 
 ### Create moderation
 
-Given a input text, outputs if the model classifies it as violating OpenAI's content policy.
+Classifies if text violates OpenAI's Content Policy
 
 ````kotlin
 val moderation = openAI.moderations(
@@ -350,3 +316,44 @@ val moderation = openAI.moderations(
     )
 )
 ````
+
+---
+
+## Completions
+
+Given a prompt, the model will return one or more predicted completions, and can also return the probabilities of alternative tokens at each position.
+
+### Create Completion `legacy`
+
+Creates a completion for the provided prompt and parameters
+
+```kotlin
+val completionRequest = CompletionRequest(
+    model = ModelId("text-ada-001"),
+    prompt = "Somebody once told me the world is gonna roll me",
+    echo = true
+)
+val completion: TextCompletion = openAI.completion(completionRequest)
+// or, as flow
+val completions: Flow<TextCompletion> = openAI.completions(completionRequest)
+```
+
+---
+
+## Edits
+
+Given a prompt and an instruction, the model will return an edited version of the prompt.
+
+### Create edits `Deprecated`
+
+Creates a new edit for the provided input, instruction, and parameters.
+
+```kotlin
+val edit = openAI.edit(
+    request = EditsRequest(
+        model = ModelId("text-davinci-edit-001"),
+        input = "What day of the wek is it?",
+        instruction = "Fix the spelling mistakes"
+    )
+)
+```

openai-client/build.gradle.kts

@@ -22,6 +22,7 @@ kotlin {
                 optIn("com.aallam.openai.api.ExperimentalOpenAI")
                 optIn("com.aallam.openai.api.BetaOpenAI")
                 optIn("com.aallam.openai.api.InternalOpenAI")
+                optIn("com.aallam.openai.api.LegacyOpenAI")
             }
         }
         val commonMain by getting {

openai-client/src/commonMain/kotlin/com.aallam.openai.client/Audio.kt

@@ -11,12 +11,10 @@ public interface Audio {
     /**
      * Transcribes audio into the input language.
      */
-    @BetaOpenAI
     public suspend fun transcription(request: TranscriptionRequest): Transcription
 
     /**
      * Translates audio into English.
      */
-    @BetaOpenAI
     public suspend fun translation(request: TranslationRequest): Translation
 }

openai-client/src/commonMain/kotlin/com.aallam.openai.client/Chat.kt

@@ -14,12 +14,10 @@ public interface Chat {
     /**
      * Creates a completion for the chat message.
      */
-    @BetaOpenAI
     public suspend fun chatCompletion(request: ChatCompletionRequest): ChatCompletion
 
     /**
      * Stream variant of [chatCompletion].
      */
-    @BetaOpenAI
     public fun chatCompletions(request: ChatCompletionRequest): Flow<ChatCompletionChunk>
 }

openai-client/src/commonMain/kotlin/com.aallam.openai.client/Completions.kt

@@ -1,5 +1,6 @@
 package com.aallam.openai.client
 
+import com.aallam.openai.api.LegacyOpenAI
 import com.aallam.openai.api.completion.CompletionRequest
 import com.aallam.openai.api.completion.TextCompletion
 import kotlinx.coroutines.flow.Flow
@@ -14,10 +15,12 @@ public interface Completions {
      * This is the main endpoint of the API. Returns the predicted completion for the given prompt,
      * and can also return the probabilities of alternative tokens at each position if requested.
      */
+    @LegacyOpenAI
     public suspend fun completion(request: CompletionRequest): TextCompletion
 
     /**
      * Stream variant of [completion].
      */
+    @LegacyOpenAI
     public fun completions(request: CompletionRequest): Flow<TextCompletion>
 }

openai-client/src/commonMain/kotlin/com.aallam.openai.client/Edits.kt

@@ -11,5 +11,6 @@ public interface Edits {
     /**
      * Creates a new edit for the provided input, instruction, and parameters.
      */
+    @Deprecated("Edits is deprecated. Chat completions is the recommend replacement.")
     public suspend fun edit(request: EditsRequest): Edit
 }