feat: add RequestOptions (#296)

Author: aallam

CHANGELOG.md

@@ -1,3 +1,8 @@
+## Unreleased
+
+### Added
+- add `RequestOptions` (#296)
+
 ## 3.6.3
 > Published 13 Jan 2024
 

gradle.properties

@@ -5,7 +5,7 @@ kotlin.js.compiler=ir
 
 # Lib
 GROUP=com.aallam.openai
-VERSION_NAME=3.6.3
+VERSION_NAME=3.7.0-SNAPSHOT
 
 # OSS
 SONATYPE_HOST=DEFAULT

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

@@ -5,6 +5,7 @@ import com.aallam.openai.api.assistant.Assistant
 import com.aallam.openai.api.assistant.AssistantFile
 import com.aallam.openai.api.assistant.AssistantId
 import com.aallam.openai.api.assistant.AssistantRequest
+import com.aallam.openai.api.core.RequestOptions
 import com.aallam.openai.api.core.SortOrder
 import com.aallam.openai.api.file.FileId
 
@@ -20,31 +21,35 @@ public interface Assistants {
      * @param request the request to create an assistant.
      */
     @BetaOpenAI
-    public suspend fun assistant(request: AssistantRequest): Assistant
+    public suspend fun assistant(request: AssistantRequest, requestOptions: RequestOptions? = null): Assistant
 
     /**
      * Retrieves an assistant.
      *
      * @param id the ID of the assistant to retrieve.
      */
     @BetaOpenAI
-    public suspend fun assistant(id: AssistantId): Assistant?
+    public suspend fun assistant(id: AssistantId, requestOptions: RequestOptions? = null): Assistant?
 
     /**
      * Update an assistant.
      *
      * @param id rhe ID of the assistant to modify.
      */
     @BetaOpenAI
-    public suspend fun assistant(id: AssistantId, request: AssistantRequest): Assistant
+    public suspend fun assistant(
+        id: AssistantId,
+        request: AssistantRequest,
+        requestOptions: RequestOptions? = null
+    ): Assistant
 
     /**
      * Delete an assistant.
      *
      * @param id ID of the assistant to delete.
      */
     @BetaOpenAI
-    public suspend fun delete(id: AssistantId): Boolean
+    public suspend fun delete(id: AssistantId, requestOptions: RequestOptions? = null): Boolean
 
     /**
      * Returns a list of assistants.
@@ -65,6 +70,7 @@ public interface Assistants {
         order: SortOrder? = null,
         after: AssistantId? = null,
         before: AssistantId? = null,
+        requestOptions: RequestOptions? = null
     ): List<Assistant>
 
     /**
@@ -75,7 +81,11 @@ public interface Assistants {
      * Useful for tools like retrieval and code interpreter that can access files.
      */
     @BetaOpenAI
-    public suspend fun createFile(assistantId: AssistantId, fileId: FileId): AssistantFile
+    public suspend fun createFile(
+        assistantId: AssistantId,
+        fileId: FileId,
+        requestOptions: RequestOptions? = null
+    ): AssistantFile
 
     /**
      * Retrieves an [AssistantFile].
@@ -84,16 +94,21 @@ public interface Assistants {
      * @param fileId the ID of the file we're getting.
      */
     @BetaOpenAI
-    public suspend fun file(assistantId: AssistantId, fileId: FileId): AssistantFile
+    public suspend fun file(
+        assistantId: AssistantId,
+        fileId: FileId,
+        requestOptions: RequestOptions? = null
+    ): AssistantFile
 
     /**
      * Delete an assistant file.
      *
      * @param assistantId the ID of the assistant that the file belongs to.
      * @param fileId the ID of the file to delete.
+     * @param requestOptions request options.
      */
     @BetaOpenAI
-    public suspend fun delete(assistantId: AssistantId, fileId: FileId): Boolean
+    public suspend fun delete(assistantId: AssistantId, fileId: FileId, requestOptions: RequestOptions? = null): Boolean
 
     /**
      * Returns a list of assistant files.
@@ -108,6 +123,7 @@ public interface Assistants {
      * @param before a cursor for use in pagination. Before is an object ID that defines your place in the list.
      * For instance, if you make a list request and receive 100 objects, ending with `obj_foo`, your subsequent call can
      * include `before = FileId("obj_foo")` in order to fetch the previous page of the list.
+     * @param requestOptions request options.
      */
     @BetaOpenAI
     public suspend fun files(
@@ -116,5 +132,6 @@ public interface Assistants {
         order: SortOrder? = null,
         after: FileId? = null,
         before: FileId? = null,
+        requestOptions: RequestOptions? = null
     ): List<AssistantFile>
 }

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

@@ -1,6 +1,7 @@
 package com.aallam.openai.client
 
 import com.aallam.openai.api.audio.*
+import com.aallam.openai.api.core.RequestOptions
 
 /**
  * Learn how to turn audio into text.
@@ -9,16 +10,28 @@ public interface Audio {
 
     /**
      * Transcribes audio into the input language.
+     *
+     * @param request transcription request.
+     * @param requestOptions request options.
      */
-    public suspend fun transcription(request: TranscriptionRequest): Transcription
+    public suspend fun transcription(
+        request: TranscriptionRequest,
+        requestOptions: RequestOptions? = null
+    ): Transcription
 
     /**
      * Translates audio into English.
+     *
+     * @param request translation request.
+     * @param requestOptions request options.
      */
-    public suspend fun translation(request: TranslationRequest): Translation
+    public suspend fun translation(request: TranslationRequest, requestOptions: RequestOptions? = null): Translation
 
     /**
      * Generates audio from the input text.
+     *
+     * @param request speech request.
+     * @param requestOptions request options.
      */
-    public suspend fun speech(request: SpeechRequest): ByteArray
+    public suspend fun speech(request: SpeechRequest, requestOptions: RequestOptions? = null): ByteArray
 }

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

@@ -3,6 +3,7 @@ package com.aallam.openai.client
 import com.aallam.openai.api.chat.ChatCompletion
 import com.aallam.openai.api.chat.ChatCompletionChunk
 import com.aallam.openai.api.chat.ChatCompletionRequest
+import com.aallam.openai.api.core.RequestOptions
 import kotlinx.coroutines.flow.Flow
 
 /**
@@ -12,11 +13,23 @@ public interface Chat {
 
     /**
      * Creates a completion for the chat message.
+     *
+     * @param request completion request.
+     * @param requestOptions request options.
      */
-    public suspend fun chatCompletion(request: ChatCompletionRequest): ChatCompletion
+    public suspend fun chatCompletion(
+        request: ChatCompletionRequest,
+        requestOptions: RequestOptions? = null
+    ): ChatCompletion
 
     /**
      * Stream variant of [chatCompletion].
+     *
+     * @param request completion request.
+     * @param requestOptions request options.
      */
-    public fun chatCompletions(request: ChatCompletionRequest): Flow<ChatCompletionChunk>
+    public fun chatCompletions(
+        request: ChatCompletionRequest,
+        requestOptions: RequestOptions? = null
+    ): Flow<ChatCompletionChunk>
 }

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

@@ -1,5 +1,6 @@
 package com.aallam.openai.client
 
+import com.aallam.openai.api.core.RequestOptions
 import com.aallam.openai.api.embedding.EmbeddingRequest
 import com.aallam.openai.api.embedding.EmbeddingResponse
 
@@ -10,6 +11,9 @@ public interface Embeddings {
 
     /**
      * Creates an embedding vector representing the input text.
+     *
+     * @param request embedding request.
+     * @param requestOptions request options.
      */
-    public suspend fun embeddings(request: EmbeddingRequest): EmbeddingResponse
+    public suspend fun embeddings(request: EmbeddingRequest, requestOptions: RequestOptions? = null): EmbeddingResponse
 }

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

@@ -1,8 +1,9 @@
 package com.aallam.openai.client
 
+import com.aallam.openai.api.core.RequestOptions
 import com.aallam.openai.api.file.File
-import com.aallam.openai.api.file.FileUpload
 import com.aallam.openai.api.file.FileId
+import com.aallam.openai.api.file.FileUpload
 
 /**
  * Files are used to upload documents that can be used across features like [Answers], [Searches], and [Classifications]
@@ -12,26 +13,40 @@ public interface Files {
     /**
      * Upload a file that contains document(s) to be used across various endpoints/features.
      * Currently, the size of all the files uploaded by one organization can be up to 1 GB.
+     *
+     * @param request file upload request.
+     * @param requestOptions request options.
      */
-    public suspend fun file(request: FileUpload): File
+    public suspend fun file(request: FileUpload, requestOptions: RequestOptions? = null): File
 
     /**
      * Returns a list of files that belong to the user's organization.
+     *
+     * @param requestOptions request options.
      */
-    public suspend fun files(): List<File>
+    public suspend fun files(requestOptions: RequestOptions? = null): List<File>
 
     /**
      * Returns information about a specific file.
+     *
+     * @param fileId the ID of the file to retrieve.
+     * @param requestOptions request options.
      */
-    public suspend fun file(fileId: FileId): File?
+    public suspend fun file(fileId: FileId, requestOptions: RequestOptions? = null): File?
 
     /**
      * Delete a file. Only owners of organizations can delete files currently.
+     *
+     * @param fileId the ID of the file to delete.
+     * @param requestOptions request options.
      */
-    public suspend fun delete(fileId: FileId): Boolean
+    public suspend fun delete(fileId: FileId, requestOptions: RequestOptions? = null): Boolean
 
     /**
      * Returns the contents of the specified [fileId].
+     *
+     * @param fileId the ID of the file to download.
+     * @param requestOptions request options.
      */
-    public suspend fun download(fileId: FileId): ByteArray
+    public suspend fun download(fileId: FileId, requestOptions: RequestOptions? = null): ByteArray
 }

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

@@ -1,7 +1,11 @@
 package com.aallam.openai.client
 
 import com.aallam.openai.api.core.PaginatedList
-import com.aallam.openai.api.finetuning.*
+import com.aallam.openai.api.core.RequestOptions
+import com.aallam.openai.api.finetuning.FineTuningId
+import com.aallam.openai.api.finetuning.FineTuningJob
+import com.aallam.openai.api.finetuning.FineTuningJobEvent
+import com.aallam.openai.api.finetuning.FineTuningRequest
 
 /**
  * Manage fine-tuning jobs to tailor a model to your specific training data.
@@ -11,42 +15,53 @@ public interface FineTuning {
     /**
      * Creates a job that fine-tunes a specified model from a given dataset.
      *
-     * Response includes details of the enqueued job including job status and the name of the fine-tuned models once complete.
+     * The response includes details of the enqueued job including job status and the name of the fine-tuned models once complete.
+     *
+     * @param request fine-tuning request.
+     * @param requestOptions request options.
      */
-    public suspend fun fineTuningJob(request: FineTuningRequest): FineTuningJob
+    public suspend fun fineTuningJob(request: FineTuningRequest, requestOptions: RequestOptions? = null): FineTuningJob
 
     /**
      * List your organization's fine-tuning jobs.
      *
      * @param after Identifier for the last job from the previous pagination request.
      * @param limit Number of fine-tuning jobs to retrieve.
+     * @param requestOptions request options.
      */
-    public suspend fun fineTuningJobs(after: String? = null, limit: Int? = null): List<FineTuningJob>
+    public suspend fun fineTuningJobs(
+        after: String? = null,
+        limit: Int? = null,
+        requestOptions: RequestOptions? = null
+    ): List<FineTuningJob>
 
     /**
      * Get info about a fine-tuning job.
      *
      * @param id The ID of the fine-tuning job.
+     * @param requestOptions request options.
      */
-    public suspend fun fineTuningJob(id: FineTuningId): FineTuningJob?
+    public suspend fun fineTuningJob(id: FineTuningId, requestOptions: RequestOptions? = null): FineTuningJob?
 
     /**
      * Immediately cancel a fine-tune job.
      *
      * @param id The ID of the fine-tuning job to cancel.
+     * @param requestOptions request options.
      */
-    public suspend fun cancel(id: FineTuningId): FineTuningJob?
+    public suspend fun cancel(id: FineTuningId, requestOptions: RequestOptions? = null): FineTuningJob?
 
     /**
      * Get status updates for a fine-tuning job.
      *
      * @param id The ID of the fine-tuning job to get events for.
      * @param after Identifier for the last event from the previous pagination request.
      * @param limit Number of events to retrieve.
+     * @param requestOptions request options.
      */
     public suspend fun fineTuningEvents(
         id: FineTuningId,
         after: String? = null,
-        limit: Int? = null
+        limit: Int? = null, requestOptions: RequestOptions? = null
     ): PaginatedList<FineTuningJobEvent>
 }