Skip to content

Navigation Menu

Sign in
Appearance settings

Search code, repositories, users, issues, pull requests...

Provide feedback

We read every piece of feedback, and take your input very seriously.

Saved searches

Use saved searches to filter your results more quickly
Sign up
Appearance settings

Commit e461e67

Browse files
add pure contracts to handlers
1 parent 7153e2e commit e461e67

File tree

9 files changed

+265
-20
lines changed

9 files changed

+265
-20
lines changed

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

Lines changed: 24 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -128,20 +128,44 @@ interface OpenAI {
128128
*/
129129
val files: FileHandler
130130

131+
/**
132+
* Returns the handler for the files endpoint. This method is purely
133+
* syntactic sugar for Java users.
134+
*/
135+
@Contract(pure = true)
136+
fun files(): FileHandler = files
137+
131138
/**
132139
* Returns the handler for the assistants endpoint. This handler can be used
133140
* to create, retrieve, and delete assistants.
134141
*/
135142
@get:ApiStatus.Experimental
136143
val assistants: AssistantHandler
137144

145+
/**
146+
* Returns the handler for the assistants endpoint. This method is purely
147+
* syntactic sugar for Java users.
148+
*/
149+
@ApiStatus.Experimental
150+
@Contract(pure = true)
151+
fun assistants(): AssistantHandler = assistants
152+
138153
/**
139154
* Returns the handler for the threads endpoint. This handler can be used
140155
* to create, retrieve, and delete threads.
141156
*/
142157
@get:ApiStatus.Experimental
143158
val threads: ThreadHandler
144159

160+
/**
161+
* Returns the handler for the threads endpoint. This method is purely
162+
* syntactic sugar for Java users.
163+
*/
164+
@ApiStatus.Experimental
165+
@Contract(pure = true)
166+
fun threads(): ThreadHandler = threads
167+
168+
145169
/**
146170
* Constructs a default [OpenAI] instance.
147171
*/

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

Lines changed: 1 addition & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -55,8 +55,7 @@ interface AssistantHandler {
5555
fun delete(id: String): AssistantDeletionStatus
5656

5757
/**
58-
* Lists assistants with default query parameters. This means that the
59-
* latest 20 assistants will be returned.
58+
* Lists the 20 most recent assistants.
6059
*
6160
* @return The list of assistants
6261
*/

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

Lines changed: 9 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,7 @@
11
package com.cjcrafter.openai.files
22

3+
import org.jetbrains.annotations.Contract
4+
35
/**
46
* Represents the handler for the files endpoint. This class holds all the
57
* actions that can be performed on a file.
@@ -28,6 +30,7 @@ interface FileHandler {
2830
* @param file The file to retrieve
2931
* @return The new instance of the retrieved file
3032
*/
33+
@Contract(pure = true)
3134
fun retrieve(file: FileObject): FileObject = retrieve(file.id)
3235

3336
/**
@@ -36,6 +39,7 @@ interface FileHandler {
3639
* @param id The id of the file to retrieve
3740
* @return The file with the given id
3841
*/
42+
@Contract(pure = true)
3943
fun retrieve(id: String): FileObject
4044

4145
/**
@@ -44,6 +48,7 @@ interface FileHandler {
4448
* @param file The file to retrieve the content of
4549
* @return The content of the file
4650
*/
51+
@Contract(pure = true)
4752
fun retrieveContents(file: FileObject): String = retrieveContents(file.id)
4853

4954
/**
@@ -52,6 +57,7 @@ interface FileHandler {
5257
* @param id The id of the file to retrieve the content of
5358
* @return The content of the file
5459
*/
60+
@Contract(pure = true)
5561
fun retrieveContents(id: String): String
5662

5763
/**
@@ -73,10 +79,11 @@ interface FileHandler {
7379
fun delete(id: String): FileDeletionStatus
7480

7581
/**
76-
* Lists files with default query parameters.
82+
* Lists the 20 most recent files.
7783
*
7884
* @return The list of files
7985
*/
86+
@Contract(pure = true)
8087
fun list(): ListFilesResponse = list(null)
8188

8289
/**
@@ -85,5 +92,6 @@ interface FileHandler {
8592
* @param request The query parameters
8693
* @return The list of assistants
8794
*/
95+
@Contract(pure = true)
8896
fun list(request: ListFilesRequest?): ListFilesResponse // Cannot use @JvmOverloads in interfaces
8997
}

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

Lines changed: 51 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -2,20 +2,25 @@ package com.cjcrafter.openai.threads
22

33
import com.cjcrafter.openai.threads.message.MessageHandler
44
import com.cjcrafter.openai.threads.runs.RunHandler
5+
import org.jetbrains.annotations.Contract
56

67
/**
7-
* Handles all API requests involving the [Thread] object (not to be confused
8-
* with [java.lang.Thread]).
8+
* Handler used to interact with a [Thread] objects.
99
*/
1010
interface ThreadHandler {
1111

1212
/**
1313
* Creates a new empty thread.
14+
*
15+
* @return The created thread
1416
*/
1517
fun create(): Thread = create(createThreadRequest { /* intentionally empty */ })
1618

1719
/**
1820
* Creates a new thread with the given options.
21+
*
22+
* @param request The values of the thread to create
23+
* @return The created thread
1924
*/
2025
fun create(request: CreateThreadRequest): Thread
2126

@@ -25,12 +30,20 @@ interface ThreadHandler {
2530
* This method returns a new thread object wrapper. The thread parameter is
2631
* used only for [Thread.id]. This method is useful for getting updated
2732
* information about a thread's status or values.
33+
*
34+
* @param thread The thread to retrieve
35+
* @return The retrieved thread
2836
*/
37+
@Contract(pure = true)
2938
fun retrieve(thread: Thread): Thread = retrieve(thread.id)
3039

3140
/**
3241
* Retrieves the thread with the given id.
42+
*
43+
* @param id The id of the thread to retrieve
44+
* @return The retrieved thread
3345
*/
46+
@Contract(pure = true)
3447
fun retrieve(id: String): Thread
3548

3649
/**
@@ -39,6 +52,9 @@ interface ThreadHandler {
3952
* You should **always** check the deletion status to ensure the thread was
4053
* deleted successfully. After confirming deletion, you should discard all
4154
* of your references to the thread, since they are now invalid.
55+
*
56+
* @param thread The thread to delete
57+
* @return The deletion status
4258
*/
4359
fun delete(thread: Thread): ThreadDeletionStatus = delete(thread.id)
4460

@@ -48,6 +64,9 @@ interface ThreadHandler {
4864
* You should **always** check the deletion status to ensure the thread was
4965
* deleted successfully. After confirming deletion, you should discard all
5066
* of your references to the thread, since they are now invalid.
67+
*
68+
* @param id The id of the thread to delete
69+
* @return The deletion status
5170
*/
5271
fun delete(id: String): ThreadDeletionStatus
5372

@@ -57,6 +76,10 @@ interface ThreadHandler {
5776
* This method returns a new thread object wrapper. The thread parameter is
5877
* used only for [Thread.id]. After this request, you should discard all of
5978
* your references to the thread, since they are now outdated.
79+
*
80+
* @param thread The thread to modify
81+
* @param request The values to update the thread with
82+
* @return The modified thread
6083
*/
6184
fun modify(thread: Thread, request: ModifyThreadRequest): Thread = modify(thread.id, request)
6285

@@ -65,26 +88,48 @@ interface ThreadHandler {
6588
*
6689
* This method returns a new thread object wrapper. After this request, you
6790
* should discard your references to the thread, since they are now outdated.
91+
*
92+
* @param id The id of the thread to modify
93+
* @param request The values to update the thread with
94+
* @return The modified thread
6895
*/
6996
fun modify(id: String, request: ModifyThreadRequest): Thread
7097

7198
/**
72-
* Returns a handler for the messages endpoint for the given thread.
99+
* Returns a handler for interacting with the messages in the given thread.
100+
*
101+
* @param thread The thread to get the messages for
102+
* @return The handler for interacting with the messages
73103
*/
104+
@Contract(pure = true)
74105
fun messages(thread: Thread): MessageHandler = messages(thread.id)
75106

76107
/**
77-
* Returns a handler for the messages endpoint for the thread with the given id.
108+
* Returns a handler for interacting with the messages in the thread with
109+
* the given id.
110+
*
111+
* @param threadId The id of the thread to get the messages for
112+
* @return The handler for interacting with the messages
78113
*/
114+
@Contract(pure = true)
79115
fun messages(threadId: String): MessageHandler
80116

81117
/**
82-
* Returns a handler for the runs endpoint for the given thread.
118+
* Returns a handler for interacting with the runs in the given thread.
119+
*
120+
* @param thread The thread to get the runs for
121+
* @return The handler for interacting with the runs
83122
*/
123+
@Contract(pure = true)
84124
fun runs(thread: Thread): RunHandler = runs(thread.id)
85125

86126
/**
87-
* Returns a handler for the runs endpoint for the thread with the given id.
127+
* Returns a handler for interacting with the runs in the thread with
128+
* the given id.
129+
*
130+
* @param threadId The id of the thread to get the runs for
131+
* @return The handler for interacting with the runs
88132
*/
133+
@Contract(pure = true)
89134
fun runs(threadId: String): RunHandler
90135
}
Lines changed: 33 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,24 +1,55 @@
11
package com.cjcrafter.openai.threads.message
22

33
import com.cjcrafter.openai.threads.Thread
4+
import org.jetbrains.annotations.Contract
45

6+
/**
7+
* Handler used to interact with a [MessageFile] objects.
8+
*/
59
interface MessageFileHandler {
610

711
/**
8-
* The id of the [Thread] that this message belongs to.
12+
* The id of the [Thread] that this handler is for.
913
*/
1014
val threadId: String
1115

1216
/**
13-
* The id of this [ThreadMessage].
17+
* The id of the [ThreadMessage] that this handler is for.
1418
*/
1519
val messageId: String
1620

21+
/**
22+
* Retrieves the file.
23+
*
24+
* @param file The file to retrieve
25+
* @return The retrieved file
26+
*/
27+
@Contract(pure = true)
1728
fun retrieve(file: MessageFile): MessageFile = retrieve(file.id)
1829

30+
/**
31+
* Retrieves the file with the given id.
32+
*
33+
* @param fileId The id of the file to retrieve
34+
* @return The retrieved file
35+
*/
36+
@Contract(pure = true)
1937
fun retrieve(fileId: String): MessageFile
2038

39+
/**
40+
* Lists the 20 most recent files in the message.
41+
*
42+
* @return The list of files
43+
*/
44+
@Contract(pure = true)
2145
fun list(): ListMessageFilesResponse = list(null)
2246

47+
/**
48+
* Lists the files in the message.
49+
*
50+
* @param request The request to use for listing the files
51+
* @return The list of files
52+
*/
53+
@Contract(pure = true)
2354
fun list(request: ListMessageFilesRequest? = null): ListMessageFilesResponse
2455
}

0 commit comments

Comments
(0)

AltStyle によって変換されたページ (->オリジナル) /