add pure contracts to handlers

Author: CJCrafter

src/main/kotlin/com/cjcrafter/openai/OpenAI.kt

@@ -128,20 +128,44 @@ interface OpenAI {
      */
     val files: FileHandler
 
+    /**
+     * Returns the handler for the files endpoint. This method is purely
+     * syntactic sugar for Java users.
+     */
+    @Contract(pure = true)
+    fun files(): FileHandler = files
+
     /**
      * Returns the handler for the assistants endpoint. This handler can be used
      * to create, retrieve, and delete assistants.
      */
     @get:ApiStatus.Experimental
     val assistants: AssistantHandler
 
+    /**
+     * Returns the handler for the assistants endpoint. This method is purely
+     * syntactic sugar for Java users.
+     */
+    @ApiStatus.Experimental
+    @Contract(pure = true)
+    fun assistants(): AssistantHandler = assistants
+
     /**
      * Returns the handler for the threads endpoint. This handler can be used
      * to create, retrieve, and delete threads.
      */
     @get:ApiStatus.Experimental
     val threads: ThreadHandler
 
+    /**
+     * Returns the handler for the threads endpoint. This method is purely
+     * syntactic sugar for Java users.
+     */
+    @ApiStatus.Experimental
+    @Contract(pure = true)
+    fun threads(): ThreadHandler = threads
+
+
     /**
      * Constructs a default [OpenAI] instance.
      */

src/main/kotlin/com/cjcrafter/openai/assistants/AssistantHandler.kt

@@ -55,8 +55,7 @@ interface AssistantHandler {
     fun delete(id: String): AssistantDeletionStatus
 
     /**
-     * Lists assistants with default query parameters. This means that the
-     * latest 20 assistants will be returned.
+     * Lists the 20 most recent assistants.
      *
      * @return The list of assistants
      */

src/main/kotlin/com/cjcrafter/openai/files/FileHandler.kt

@@ -1,5 +1,7 @@
 package com.cjcrafter.openai.files
 
+import org.jetbrains.annotations.Contract
+
 /**
  * Represents the handler for the files endpoint. This class holds all the
  * actions that can be performed on a file.
@@ -28,6 +30,7 @@ interface FileHandler {
      * @param file The file to retrieve
      * @return The new instance of the retrieved file
      */
+    @Contract(pure = true)
     fun retrieve(file: FileObject): FileObject = retrieve(file.id)
 
     /**
@@ -36,6 +39,7 @@ interface FileHandler {
      * @param id The id of the file to retrieve
      * @return The file with the given id
      */
+    @Contract(pure = true)
     fun retrieve(id: String): FileObject
 
     /**
@@ -44,6 +48,7 @@ interface FileHandler {
      * @param file The file to retrieve the content of
      * @return The content of the file
      */
+    @Contract(pure = true)
     fun retrieveContents(file: FileObject): String = retrieveContents(file.id)
 
     /**
@@ -52,6 +57,7 @@ interface FileHandler {
      * @param id The id of the file to retrieve the content of
      * @return The content of the file
      */
+    @Contract(pure = true)
     fun retrieveContents(id: String): String
 
     /**
@@ -73,10 +79,11 @@ interface FileHandler {
     fun delete(id: String): FileDeletionStatus
 
     /**
-     * Lists files with default query parameters.
+     * Lists the 20 most recent files.
      *
      * @return The list of files
      */
+    @Contract(pure = true)
     fun list(): ListFilesResponse = list(null)
 
     /**
@@ -85,5 +92,6 @@ interface FileHandler {
      * @param request The query parameters
      * @return The list of assistants
      */
+    @Contract(pure = true)
     fun list(request: ListFilesRequest?): ListFilesResponse // Cannot use @JvmOverloads in interfaces
 }

src/main/kotlin/com/cjcrafter/openai/threads/ThreadHandler.kt

@@ -2,20 +2,25 @@ package com.cjcrafter.openai.threads
 
 import com.cjcrafter.openai.threads.message.MessageHandler
 import com.cjcrafter.openai.threads.runs.RunHandler
+import org.jetbrains.annotations.Contract
 
 /**
- * Handles all API requests involving the [Thread] object (not to be confused
- * with [java.lang.Thread]).
+ * Handler used to interact with a [Thread] objects.
  */
 interface ThreadHandler {
 
     /**
      * Creates a new empty thread.
+     *
+     * @return The created thread
      */
     fun create(): Thread = create(createThreadRequest { /* intentionally empty */ })
 
     /**
      * Creates a new thread with the given options.
+     *
+     * @param request The values of the thread to create
+     * @return The created thread
      */
     fun create(request: CreateThreadRequest): Thread
 
@@ -25,12 +30,20 @@ interface ThreadHandler {
      * This method returns a new thread object wrapper. The thread parameter is
      * used only for [Thread.id]. This method is useful for getting updated
      * information about a thread's status or values.
+     *
+     * @param thread The thread to retrieve
+     * @return The retrieved thread
      */
+    @Contract(pure = true)
     fun retrieve(thread: Thread): Thread = retrieve(thread.id)
 
     /**
      * Retrieves the thread with the given id.
+     *
+     * @param id The id of the thread to retrieve
+     * @return The retrieved thread
      */
+    @Contract(pure = true)
     fun retrieve(id: String): Thread
 
     /**
@@ -39,6 +52,9 @@ interface ThreadHandler {
      * You should **always** check the deletion status to ensure the thread was
      * deleted successfully. After confirming deletion, you should discard all
      * of your references to the thread, since they are now invalid.
+     *
+     * @param thread The thread to delete
+     * @return The deletion status
      */
     fun delete(thread: Thread): ThreadDeletionStatus = delete(thread.id)
 
@@ -48,6 +64,9 @@ interface ThreadHandler {
      * You should **always** check the deletion status to ensure the thread was
      * deleted successfully. After confirming deletion, you should discard all
      * of your references to the thread, since they are now invalid.
+     *
+     * @param id The id of the thread to delete
+     * @return The deletion status
      */
     fun delete(id: String): ThreadDeletionStatus
 
@@ -57,6 +76,10 @@ interface ThreadHandler {
      * This method returns a new thread object wrapper. The thread parameter is
      * used only for [Thread.id]. After this request, you should discard all of
      * your references to the thread, since they are now outdated.
+     *
+     * @param thread The thread to modify
+     * @param request The values to update the thread with
+     * @return The modified thread
      */
     fun modify(thread: Thread, request: ModifyThreadRequest): Thread = modify(thread.id, request)
 
@@ -65,26 +88,48 @@ interface ThreadHandler {
      *
      * This method returns a new thread object wrapper. After this request, you
      * should discard your references to the thread, since they are now outdated.
+     *
+     * @param id The id of the thread to modify
+     * @param request The values to update the thread with
+     * @return The modified thread
      */
     fun modify(id: String, request: ModifyThreadRequest): Thread
 
     /**
-     * Returns a handler for the messages endpoint for the given thread.
+     * Returns a handler for interacting with the messages in the given thread.
+     *
+     * @param thread The thread to get the messages for
+     * @return The handler for interacting with the messages
      */
+    @Contract(pure = true)
     fun messages(thread: Thread): MessageHandler = messages(thread.id)
 
     /**
-     * Returns a handler for the messages endpoint for the thread with the given id.
+     * Returns a handler for interacting with the messages in the thread with
+     * the given id.
+     *
+     * @param threadId The id of the thread to get the messages for
+     * @return The handler for interacting with the messages
      */
+    @Contract(pure = true)
     fun messages(threadId: String): MessageHandler
 
     /**
-     * Returns a handler for the runs endpoint for the given thread.
+     * Returns a handler for interacting with the runs in the given thread.
+     *
+     * @param thread The thread to get the runs for
+     * @return The handler for interacting with the runs
      */
+    @Contract(pure = true)
     fun runs(thread: Thread): RunHandler = runs(thread.id)
 
     /**
-     * Returns a handler for the runs endpoint for the thread with the given id.
+     * Returns a handler for interacting with the runs in the thread with
+     * the given id.
+     *
+     * @param threadId The id of the thread to get the runs for
+     * @return The handler for interacting with the runs
      */
+    @Contract(pure = true)
     fun runs(threadId: String): RunHandler
 }

src/main/kotlin/com/cjcrafter/openai/threads/message/MessageFileHandler.kt

@@ -1,24 +1,55 @@
 package com.cjcrafter.openai.threads.message
 
 import com.cjcrafter.openai.threads.Thread
+import org.jetbrains.annotations.Contract
 
+/**
+ * Handler used to interact with a [MessageFile] objects.
+ */
 interface MessageFileHandler {
 
     /**
-     * The id of the [Thread] that this message belongs to.
+     * The id of the [Thread] that this handler is for.
      */
     val threadId: String
 
     /**
-     * The id of this [ThreadMessage].
+     * The id of the [ThreadMessage] that this handler is for.
      */
     val messageId: String
 
+    /**
+     * Retrieves the file.
+     *
+     * @param file The file to retrieve
+     * @return The retrieved file
+     */
+    @Contract(pure = true)
     fun retrieve(file: MessageFile): MessageFile = retrieve(file.id)
 
+    /**
+     * Retrieves the file with the given id.
+     *
+     * @param fileId The id of the file to retrieve
+     * @return The retrieved file
+     */
+    @Contract(pure = true)
     fun retrieve(fileId: String): MessageFile
 
+    /**
+     * Lists the 20 most recent files in the message.
+     *
+     * @return The list of files
+     */
+    @Contract(pure = true)
     fun list(): ListMessageFilesResponse = list(null)
 
+    /**
+     * Lists the files in the message.
+     *
+     * @param request The request to use for listing the files
+     * @return The list of files
+     */
+    @Contract(pure = true)
     fun list(request: ListMessageFilesRequest? = null): ListMessageFilesResponse
 }