feat: add threads, messsages and runs apis

CHANGELOG.md

@@ -4,9 +4,14 @@
 - **Images**: Support for model selection for `ImageCreation`, `ImageEdit` and `ImageVariations` (#257)
 - **Chat**: add tool calls (#256)
 - **Chat**: add vision feature (#258)
-- **Assistants**: add `Assistants` feature (#259)
 - **Config**: adding ktor engine config to support Kotlin Scripting (#261)
 
+#### Beta
+- **Assistants**: api implementation (#259)
+- **Threads**: api implementation (#262)
+- **Messages**: api implementation (#262)
+- **Runs**: api implementation (#262)
+
 # 3.5.1
 > Published 05 Nov 2023
 

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

@@ -54,17 +54,17 @@ public interface Assistants {
      * and [SortOrder.Descending] for descending order.
      * @param after a cursor for use in pagination. `after` 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 `after="obj_foo"` in order to fetch the next page of the list.
+     * include `after = AssistantId("obj_foo")` in order to fetch the next page of the list.
      * @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="obj_foo"` in order to fetch the previous page of the list.
+     * include `before = AssistantId("obj_foo")` in order to fetch the previous page of the list.
      */
     @BetaOpenAI
     public suspend fun assistants(
         limit: Int? = null,
         order: SortOrder? = null,
-        after: String? = null,
-        before: String? = null,
+        after: AssistantId? = null,
+        before: AssistantId? = null,
     ): List<Assistant>
 
     /**
@@ -104,17 +104,17 @@ public interface Assistants {
      * and [SortOrder.Descending] for descending order.
      * @param after a cursor for use in pagination. `after` 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 `after="obj_foo"` in order to fetch the next page of the list.
+     * include `after = FileId("obj_foo")` in order to fetch the next page of the list.
      * @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="obj_foo"` in order to fetch the previous page of the list.
+     * include `before = FileId("obj_foo")` in order to fetch the previous page of the list.
      */
     @BetaOpenAI
     public suspend fun files(
         id: AssistantId,
         limit: Int? = null,
         order: SortOrder? = null,
-        after: String? = null,
-        before: String? = null,
+        after: FileId? = null,
+        before: FileId? = null,
     ): List<AssistantFile>
 }

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

@@ -0,0 +1,104 @@
+package com.aallam.openai.client
+
+import com.aallam.openai.api.BetaOpenAI
+import com.aallam.openai.api.core.SortOrder
+import com.aallam.openai.api.file.FileId
+import com.aallam.openai.api.message.Message
+import com.aallam.openai.api.message.MessageFile
+import com.aallam.openai.api.message.MessageId
+import com.aallam.openai.api.message.MessageRequest
+import com.aallam.openai.api.thread.ThreadId
+
+/**
+ * Create messages within threads
+ */
+@BetaOpenAI
+public interface Messages {
+
+    /**
+     * Create a message.
+     *
+     * @param threadId the identifier of the thread
+     * @param message message creation request
+     */
+    @BetaOpenAI
+    public suspend fun message(threadId: ThreadId, message: MessageRequest): Message
+
+    /**
+     * Retrieve a message.
+     *
+     * @param threadId the identifier of the thread
+     * @param messageId the identifier of the message
+     */
+    @BetaOpenAI
+    public suspend fun message(threadId: ThreadId, messageId: MessageId): Message
+
+    /**
+     * Modify a message.
+     *
+     * @param threadId the identifier of the thread
+     * @param messageId the identifier of the message
+     * @param metadata set of 16 key-value pairs that can be attached to an object.
+     * This can be useful for storing additional information about the object in a structured format.
+     * Keys can be a maximum of 64 characters long, and values can be a maximum of 512 characters long.
+     */
+    @BetaOpenAI
+    public suspend fun message(threadId: ThreadId, messageId: MessageId, metadata: Map<String, String>? = null): Message
+
+    /**
+     * Returns a list of messages for a given thread.
+     *
+     * @param threadId the identifier of the thread
+     * @param limit a limit on the number of objects to be returned.
+     * The Limit can range between 1 and 100, and the default is 20.
+     * @param order sort order by the `created_at` timestamp of the objects.
+     * @param after a cursor for use in pagination. [after] 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 `after = MessageId("obj_foo")` in order to fetch the next page of the list.
+     * @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 = MessageId("obj_foo")` in order to fetch the previous page of the list.
+     */
+    @BetaOpenAI
+    public suspend fun messages(
+        threadId: ThreadId,
+        limit: Int? = null,
+        order: SortOrder? = null,
+        after: MessageId? = null,
+        before: MessageId? = null,
+    ): List<Message>
+
+    /**
+     * Retrieves a message file.
+     *
+     * @param threadId the ID of the thread to which the message and File belong
+     * @param messageId the ID of the message the file belongs to
+     * @param fileId the ID of the file being retrieved
+     */
+    @BetaOpenAI
+    public suspend fun messageFile(threadId: ThreadId, messageId: MessageId, fileId: FileId): MessageFile
+
+    /**
+     * Returns a list of message files.
+     *
+     * @param threadId the ID of the thread to which the message and File belong to
+     * @param messageId the ID of the message the file belongs to
+     * @param limit a limit on the number of objects to be returned
+     * @param order sort order by the `created_at` timestamp of the objects
+     * @param after a cursor for use in pagination. [after] 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 `after = FileId("obj_foo")` in order to fetch the next page of the list.
+     * @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.
+     */
+    @BetaOpenAI
+    public suspend fun messageFiles(
+        threadId: ThreadId,
+        messageId: MessageId,
+        limit: Int? = null,
+        order: SortOrder? = null,
+        after: FileId? = null,
+        before: FileId? = null,
+    ): List<MessageFile>
+}

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

@@ -11,7 +11,7 @@ import kotlin.time.Duration.Companion.seconds
  * OpenAI API.
  */
 public interface OpenAI : Completions, Files, Edits, Embeddings, Models, Moderations, FineTunes, Images, Chat, Audio,
-    FineTuning, Assistants, Closeable
+    FineTuning, Assistants, Threads, Closeable
 
 /**
  * Creates an instance of [OpenAI].

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

@@ -0,0 +1,126 @@
+package com.aallam.openai.client
+
+import com.aallam.openai.api.BetaOpenAI
+import com.aallam.openai.api.core.SortOrder
+import com.aallam.openai.api.core.Status
+import com.aallam.openai.api.run.*
+import com.aallam.openai.api.thread.ThreadId
+
+/**
+ * Represents an execution run on a thread.
+ */
+@BetaOpenAI
+public interface Runs {
+
+    /**
+     * Create a run.
+     *
+     * @param threadId The ID of the thread to run
+     * @param request request for a run
+     *
+     */
+    @BetaOpenAI
+    public suspend fun createRun(threadId: ThreadId, request: RunRequest): Run
+
+    /**
+     * Retrieves a run.
+     *
+     * @param threadId The ID of the thread to run
+     * @param runId The ID of the run to retrieve
+     */
+    @BetaOpenAI
+    public suspend fun retrieveRun(threadId: ThreadId, runId: RunId): Run
+
+    /**
+     * Retrieves a run.
+     *
+     * @param threadId the ID of the thread to run
+     * @param runId the ID of the run to retrieve
+     * @param metadata set of 16 key-value pairs that can be attached to an object.
+     * This can be useful for storing additional information about the object in a structured format.
+     * Keys can be a maximum of 64 characters long, and values can be a maximum of 512 characters long.
+     */
+    @BetaOpenAI
+    public suspend fun modifyRun(threadId: ThreadId, runId: RunId, metadata: Map<String, String>? = null): Run
+
+    /**
+     * Returns a list of runs belonging to a thread.
+     *
+     * @param threadId the ID of the thread the run belongs to
+     * @param order sort order by the `created_at` timestamp of the objects.
+     * @param after a cursor for use in pagination. [after] 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 `after = RunId("obj_foo")` in order to fetch the next page of the list.
+     * @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 = RunId("obj_foo")` in order to fetch the previous page of the list.
+     */
+    @BetaOpenAI
+    public suspend fun runs(
+        threadId: ThreadId,
+        limit: Int? = null,
+        order: SortOrder? = null,
+        after: RunId? = null,
+        before: RunId? = null,
+    ): List<Run>
+
+    /**
+     * When a run has the status: [Status.RequiresAction] and required action is [RequiredAction.SubmitToolOutputs],
+     * this endpoint can be used to submit the outputs from the tool calls once they're all completed.
+     * All outputs must be submitted in a single request.
+     */
+    @BetaOpenAI
+    public suspend fun submitToolOutput(threadId: ThreadId, runId: RunId, output: List<ToolOutput>): Run
+
+    /**
+     * Cancels a run that is [Status.InProgress].
+     *
+     * @param threadId the ID of the thread to which this run belongs
+     * @param runId the ID of the run to cancel
+     */
+    @BetaOpenAI
+    public suspend fun cancel(threadId: ThreadId, runId: RunId): Run
+
+    /**
+     * Create a thread and run it in one request.
+     *
+     * @param request request for a thread run
+     */
+    @BetaOpenAI
+    public suspend fun createThreadRun(request: RunRequest): Run
+
+    /**
+     * Retrieves a run step.
+     *
+     * @param threadId the ID of the thread to which the run and run step belongs
+     * @param runId the ID of the run to which the run step belongs
+     * @param stepId the ID of the run step to retrieve
+     */
+    @BetaOpenAI
+    public suspend fun runStep(threadId: ThreadId, runId: RunId, stepId: RunStepId): RunStep
+
+    /**
+     * Retrieves a run step.
+     *
+     * @param threadId the ID of the thread to which the run and run step belongs
+     * @param runId the ID of the run to which the run step belongs
+     * @param limit A limit on the number of objects to be returned.
+     * The Limit can range between 1 and 100, and the default is 20.
+     * @param order sort order by the `created_at` timestamp of the objects.
+     * @param after a cursor for use in pagination. [after] 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 `after = RunId("obj_foo")` in order to fetch the next page of the list.
+     * @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 = RunId("obj_foo")` in order to fetch the previous page of the list.
+     */
+    @BetaOpenAI
+    public suspend fun runSteps(
+        threadId: ThreadId,
+        runId: RunId,
+        limit: Int? = null,
+        order: SortOrder? = null,
+        after: RunStepId? = null,
+        before: RunStepId? = null,
+    ): List<RunStep>
+}

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

@@ -0,0 +1,48 @@
+package com.aallam.openai.client
+
+import com.aallam.openai.api.BetaOpenAI
+import com.aallam.openai.api.thread.Thread
+import com.aallam.openai.api.thread.ThreadId
+import com.aallam.openai.api.thread.ThreadRequest
+
+/**
+ * Create threads that assistants can interact with.
+ */
+@BetaOpenAI
+public interface Threads {
+
+    /**
+     * Create a thread.
+     *
+     * @param request thread creation request.
+     */
+    @BetaOpenAI
+    public suspend fun thread(request: ThreadRequest? = null): Thread
+
+    /**
+     * Retrieve a thread.
+     *
+     * @param id the identifier of the thread.
+     */
+    @BetaOpenAI
+    public suspend fun thread(id: ThreadId): Thread?
+
+    /**
+     * Modify a thread.
+     *
+     * @param id the identifier of the thread.
+     * @param metadata set of 16 key-value pairs that can be attached to an object.
+     * This can be useful for storing additional information about the object in a structured format.
+     * Keys can be a maximum of 64 characters long, and values can be a maximum of 512 characters long.
+     */
+    @BetaOpenAI
+    public suspend fun thread(id: ThreadId, metadata: Map<String, String>): Thread
+
+    /**
+     * Delete a thread.
+     *
+     * @param id the identifier of the thread.
+     */
+    @BetaOpenAI
+    public suspend fun delete(id: ThreadId): Boolean
+}