openai · stainless-app · Jan 27, 2025 · Jan 26, 2025 · Jan 26, 2025 · Jan 26, 2025
@@ -1,3 +1,3 @@
 {
-  ".": "0.14.1"
+  ".": "0.15.0"
 }
@@ -1,5 +1,29 @@
 # Changelog
 
+## 0.15.0 (2025-01-27)
+
+Full Changelog: [v0.14.1...v0.15.0](https://github.com/openai/openai-java/compare/v0.14.1...v0.15.0)
+
+### Features
+
+* **client:** add `close` method ([#164](https://github.com/openai/openai-java/issues/164)) ([f32975f](https://github.com/openai/openai-java/commit/f32975f523bcab55faa54568982b884ba7d1d381))
+
+
+### Bug Fixes
+
+* **client:** make some classes and constructors non-public ([#169](https://github.com/openai/openai-java/issues/169)) ([20fb5a1](https://github.com/openai/openai-java/commit/20fb5a1eef19b59c9dd152f132e2a980d20b039d))
+
+
+### Chores
+
+* **internal:** remove some unnecessary `constructor` keywords ([20fb5a1](https://github.com/openai/openai-java/commit/20fb5a1eef19b59c9dd152f132e2a980d20b039d))
+
+
+### Documentation
+
+* `async` and `sync` method comments ([#167](https://github.com/openai/openai-java/issues/167)) ([6f11e5d](https://github.com/openai/openai-java/commit/6f11e5d88a70631f18b86c7f24e91042330f39ec))
+* add client documentation ([#166](https://github.com/openai/openai-java/issues/166)) ([4344883](https://github.com/openai/openai-java/commit/434488395fb95e59933242113b5d14b610ef5ec5))
+
 ## 0.14.1 (2025-01-25)
 
 Full Changelog: [v0.14.0...v0.14.1](https://github.com/openai/openai-java/compare/v0.14.0...v0.14.1)

@@ -9,8 +9,8 @@
 
 <!-- x-release-please-start-version -->
 
-[![Maven Central](https://img.shields.io/maven-central/v/com.openai/openai-java)](https://central.sonatype.com/artifact/com.openai/openai-java/0.14.1)
-[![javadoc](https://javadoc.io/badge2/com.openai/openai-java/0.14.1/javadoc.svg)](https://javadoc.io/doc/com.openai/openai-java/0.14.1)
+[![Maven Central](https://img.shields.io/maven-central/v/com.openai/openai-java)](https://central.sonatype.com/artifact/com.openai/openai-java/0.15.0)
+[![javadoc](https://javadoc.io/badge2/com.openai/openai-java/0.15.0/javadoc.svg)](https://javadoc.io/doc/com.openai/openai-java/0.15.0)
 
 <!-- x-release-please-end -->
 
@@ -25,7 +25,7 @@ The REST API documentation can be found on [platform.openai.com](https://platfor
 ### Gradle
 
 ```kotlin
-implementation("com.openai:openai-java:0.14.1")
+implementation("com.openai:openai-java:0.15.0")
 ```
 
 ### Maven
@@ -34,7 +34,7 @@ implementation("com.openai:openai-java:0.14.1")
 <dependency>
     <groupId>com.openai</groupId>
     <artifactId>openai-java</artifactId>
-    <version>0.14.1</version>
+    <version>0.15.0</version>
 </dependency>
 ```
 

@@ -8,7 +8,7 @@ repositories {
 
 allprojects {
     group = "com.openai"
-    version = "0.14.1" // x-release-please-version
+    version = "0.15.0" // x-release-please-version
 }
 
 subprojects {

@@ -171,7 +171,7 @@ private constructor(private val okHttpClient: okhttp3.OkHttpClient, private val
         @JvmStatic fun builder() = Builder()
     }
 
-    class Builder {
+    class Builder internal constructor() {
 
         private var baseUrl: HttpUrl? = null
         // The default timeout is 10 minutes.

@@ -24,7 +24,7 @@ class OpenAIOkHttpClient private constructor() {
         @JvmStatic fun fromEnv(): OpenAIClient = builder().fromEnv().build()
     }
 
-    class Builder {
+    class Builder internal constructor() {
 
         private var clientOptions: ClientOptions.Builder = ClientOptions.builder()
         private var baseUrl: String = ClientOptions.PRODUCTION_URL

@@ -24,7 +24,7 @@ class OpenAIOkHttpClientAsync private constructor() {
         @JvmStatic fun fromEnv(): OpenAIClientAsync = builder().fromEnv().build()
     }
 
-    class Builder {
+    class Builder internal constructor() {
 
         private var clientOptions: ClientOptions.Builder = ClientOptions.builder()
         private var baseUrl: String = ClientOptions.PRODUCTION_URL

@@ -14,8 +14,28 @@ import com.openai.services.blocking.ModelService
 import com.openai.services.blocking.ModerationService
 import com.openai.services.blocking.UploadService
 
+/**
+ * A client for interacting with the OpenAI REST API synchronously. You can also switch to
+ * asynchronous execution via the [async] method.
+ *
+ * This client performs best when you create a single instance and reuse it for all interactions
+ * with the REST API. This is because each client holds its own connection pool and thread pools.
+ * Reusing connections and threads reduces latency and saves memory. The client also handles rate
+ * limiting per client. This means that creating and using multiple instances at the same time will
+ * not respect rate limits.
+ *
+ * The threads and connections that are held will be released automatically if they remain idle. But
+ * if you are writing an application that needs to aggressively release unused resources, then you
+ * may call [close].
+ */
 interface OpenAIClient {
 
+    /**
+     * Returns a version of this client that uses asynchronous execution.
+     *
+     * The returned client shares its resources, like its connection pool and thread pools, with
+     * this client.
+     */
     fun async(): OpenAIClientAsync
 
     fun completions(): CompletionService
@@ -39,4 +59,17 @@ interface OpenAIClient {
     fun batches(): BatchService
 
     fun uploads(): UploadService
+
+    /**
+     * Closes this client, relinquishing any underlying resources.
+     *
+     * This is purposefully not inherited from [AutoCloseable] because the client is long-lived and
+     * usually should not be synchronously closed via try-with-resources.
+     *
+     * It's also usually not necessary to call this method at all. the default HTTP client
+     * automatically releases threads and connections if they remain idle, but if you are writing an
+     * application that needs to aggressively release unused resources, then you may call this
+     * method.
+     */
+    fun close()
 }
@@ -14,8 +14,28 @@ import com.openai.services.async.ModelServiceAsync
 import com.openai.services.async.ModerationServiceAsync
 import com.openai.services.async.UploadServiceAsync
 
+/**
+ * A client for interacting with the OpenAI REST API asynchronously. You can also switch to
+ * synchronous execution via the [sync] method.
+ *
+ * This client performs best when you create a single instance and reuse it for all interactions
+ * with the REST API. This is because each client holds its own connection pool and thread pools.
+ * Reusing connections and threads reduces latency and saves memory. The client also handles rate
+ * limiting per client. This means that creating and using multiple instances at the same time will
+ * not respect rate limits.
+ *
+ * The threads and connections that are held will be released automatically if they remain idle. But
+ * if you are writing an application that needs to aggressively release unused resources, then you
+ * may call [close].
+ */
 interface OpenAIClientAsync {
 
+    /**
+     * Returns a version of this client that uses synchronous execution.
+     *
+     * The returned client shares its resources, like its connection pool and thread pools, with
+     * this client.
+     */
     fun sync(): OpenAIClient
 
     fun completions(): CompletionServiceAsync
@@ -39,4 +59,17 @@ interface OpenAIClientAsync {
     fun batches(): BatchServiceAsync
 
     fun uploads(): UploadServiceAsync
+
+    /**
+     * Closes this client, relinquishing any underlying resources.
+     *
+     * This is purposefully not inherited from [AutoCloseable] because the client is long-lived and
+     * usually should not be synchronously closed via try-with-resources.
+     *
+     * It's also usually not necessary to call this method at all. the default HTTP client
+     * automatically releases threads and connections if they remain idle, but if you are writing an
+     * application that needs to aggressively release unused resources, then you may call this
+     * method.
+     */
+    fun close()
 }
@@ -27,8 +27,7 @@ import com.openai.services.async.ModerationServiceAsyncImpl
 import com.openai.services.async.UploadServiceAsync
 import com.openai.services.async.UploadServiceAsyncImpl
 
-class OpenAIClientAsyncImpl
-constructor(
+class OpenAIClientAsyncImpl(
     private val clientOptions: ClientOptions,
 ) : OpenAIClientAsync {
 
@@ -104,4 +103,6 @@ constructor(
     override fun batches(): BatchServiceAsync = batches
 
     override fun uploads(): UploadServiceAsync = uploads
+
+    override fun close() = clientOptions.httpClient.close()
 }
@@ -27,8 +27,7 @@ import com.openai.services.blocking.ModerationServiceImpl
 import com.openai.services.blocking.UploadService
 import com.openai.services.blocking.UploadServiceImpl
 
-class OpenAIClientImpl
-constructor(
+class OpenAIClientImpl(
     private val clientOptions: ClientOptions,
 ) : OpenAIClient {
 
@@ -96,4 +95,6 @@ constructor(
     override fun batches(): BatchService = batches
 
     override fun uploads(): UploadService = uploads
+
+    override fun close() = clientOptions.httpClient.close()
 }
@@ -48,7 +48,7 @@ private constructor(
         @JvmStatic fun fromEnv(): ClientOptions = builder().fromEnv().build()
     }
 
-    class Builder {
+    class Builder internal constructor() {
 
         private var httpClient: HttpClient? = null
         private var jsonMapper: JsonMapper = jsonMapper()

@@ -23,7 +23,8 @@ private constructor(
         @JvmStatic fun builder() = Builder()
     }
 
-    class Builder {
+    class Builder internal constructor() {
+
         private var responseValidation: Boolean? = null
         private var timeout: Duration? = null
 

@@ -22,7 +22,7 @@ private constructor(
         @JvmStatic fun builder() = Builder()
     }
 
-    class Builder {
+    class Builder internal constructor() {
 
         private val map: MutableMap<String, MutableList<String>> =
             TreeMap(String.CASE_INSENSITIVE_ORDER)

@@ -22,7 +22,7 @@ private constructor(
         @JvmStatic fun builder() = Builder()
     }
 
-    class Builder {
+    class Builder internal constructor() {
 
         private var method: HttpMethod? = null
         private var url: String? = null

@@ -21,7 +21,7 @@ private constructor(
         @JvmStatic fun builder() = Builder()
     }
 
-    class Builder {
+    class Builder internal constructor() {
 
         private val map: MutableMap<String, MutableList<String>> = mutableMapOf()
         private var size: Int = 0

@@ -243,7 +243,7 @@ private constructor(
         @JvmStatic fun builder() = Builder()
     }
 
-    class Builder {
+    class Builder internal constructor() {
 
         private var httpClient: HttpClient? = null
         private var clock: Clock = Clock.systemUTC()

@@ -20,7 +20,7 @@ private constructor(
         @JvmStatic fun builder() = Builder()
     }
 
-    class Builder {
+    class Builder internal constructor() {
 
         private var jsonMapper: JsonMapper? = null
         private var event: String? = null

@@ -30,7 +30,7 @@ private constructor(
         @JvmStatic fun builder() = Builder()
     }
 
-    class Builder {
+    class Builder internal constructor() {
 
         private var additionalProperties: MutableMap<String, JsonValue> = mutableMapOf()
 

@@ -149,7 +149,7 @@ private constructor(
         }
     }
 
-    class Deserializer : BaseDeserializer<Annotation>(Annotation::class) {
+    internal class Deserializer : BaseDeserializer<Annotation>(Annotation::class) {
 
         override fun ObjectCodec.deserialize(node: JsonNode): Annotation {
             val json = JsonValue.fromJsonNode(node)
@@ -174,7 +174,7 @@ private constructor(
         }
     }
 
-    class Serializer : BaseSerializer<Annotation>(Annotation::class) {
+    internal class Serializer : BaseSerializer<Annotation>(Annotation::class) {
 
         override fun serialize(
             value: Annotation,

@@ -150,7 +150,7 @@ private constructor(
         }
     }
 
-    class Deserializer : BaseDeserializer<AnnotationDelta>(AnnotationDelta::class) {
+    internal class Deserializer : BaseDeserializer<AnnotationDelta>(AnnotationDelta::class) {
 
         override fun ObjectCodec.deserialize(node: JsonNode): AnnotationDelta {
             val json = JsonValue.fromJsonNode(node)
@@ -179,7 +179,7 @@ private constructor(
         }
     }
 
-    class Serializer : BaseSerializer<AnnotationDelta>(AnnotationDelta::class) {
+    internal class Serializer : BaseSerializer<AnnotationDelta>(AnnotationDelta::class) {
 
         override fun serialize(
             value: AnnotationDelta,

@@ -261,7 +261,7 @@ private constructor(
         @JvmStatic fun builder() = Builder()
     }
 
-    class Builder {
+    class Builder internal constructor() {
 
         private var id: JsonField<String>? = null
         private var createdAt: JsonField<Long>? = null
@@ -754,7 +754,7 @@ private constructor(
             @JvmStatic fun builder() = Builder()
         }
 
-        class Builder {
+        class Builder internal constructor() {
 
             private var codeInterpreter: JsonField<CodeInterpreter> = JsonMissing.of()
             private var fileSearch: JsonField<FileSearch> = JsonMissing.of()
@@ -857,7 +857,7 @@ private constructor(
                 @JvmStatic fun builder() = Builder()
             }
 
-            class Builder {
+            class Builder internal constructor() {
 
                 private var fileIds: JsonField<MutableList<String>>? = null
                 private var additionalProperties: MutableMap<String, JsonValue> = mutableMapOf()
@@ -1001,7 +1001,7 @@ private constructor(
                 @JvmStatic fun builder() = Builder()
             }
 
-            class Builder {
+            class Builder internal constructor() {
 
                 private var vectorStoreIds: JsonField<MutableList<String>>? = null
                 private var additionalProperties: MutableMap<String, JsonValue> = mutableMapOf()

@@ -67,7 +67,7 @@ private constructor(
         @JvmStatic fun builder() = Builder()
     }
 
-    class Builder {
+    class Builder internal constructor() {
 
         private var id: JsonField<String>? = null
         private var deleted: JsonField<Boolean>? = null