fix(api): correct some Responses types (#328)

Author: stainless-app[bot]

.stats.yml

@@ -1,2 +1,2 @@
 configured_endpoints: 78
-openapi_spec_url: https://storage.googleapis.com/stainless-sdk-openapi-specs/openai%2Fopenai-c8579861bc21d4d2155a5b9e8e7d54faee8083730673c4d32cbbe573d7fb4116.yml
+openapi_spec_url: https://storage.googleapis.com/stainless-sdk-openapi-specs/openai%2Fopenai-f763c1a35c8b9b02f1e31b9b2e09e21f98bfe8413e5079c86cbb07da2dd7779b.yml

openai-java-core/src/main/kotlin/com/openai/models/Reasoning.kt

@@ -12,7 +12,6 @@ import com.openai.core.JsonField
 import com.openai.core.JsonMissing
 import com.openai.core.JsonValue
 import com.openai.core.NoAutoDetect
-import com.openai.core.checkRequired
 import com.openai.core.immutableEmptyMap
 import com.openai.core.toImmutable
 import com.openai.errors.OpenAIInvalidDataException
@@ -52,7 +51,7 @@ private constructor(
     fun effort(): Optional<ReasoningEffort> = Optional.ofNullable(effort.getNullable("effort"))
 
     /**
-     * **o-series models only**
+     * **computer_use_preview only**
      *
      * A summary of the reasoning performed by the model. This can be useful for debugging and
      * understanding the model's reasoning process. One of `concise` or `detailed`.
@@ -99,21 +98,14 @@ private constructor(
 
     companion object {
 
-        /**
-         * Returns a mutable builder for constructing an instance of [Reasoning].
-         *
-         * The following fields are required:
-         * ```java
-         * .effort()
-         * ```
-         */
+        /** Returns a mutable builder for constructing an instance of [Reasoning]. */
         @JvmStatic fun builder() = Builder()
     }
 
     /** A builder for [Reasoning]. */
     class Builder internal constructor() {
 
-        private var effort: JsonField<ReasoningEffort>? = null
+        private var effort: JsonField<ReasoningEffort> = JsonMissing.of()
         private var generateSummary: JsonField<GenerateSummary> = JsonMissing.of()
         private var additionalProperties: MutableMap<String, JsonValue> = mutableMapOf()
 
@@ -147,7 +139,7 @@ private constructor(
         fun effort(effort: JsonField<ReasoningEffort>) = apply { this.effort = effort }
 
         /**
-         * **o-series models only**
+         * **computer_use_preview only**
          *
          * A summary of the reasoning performed by the model. This can be useful for debugging and
          * understanding the model's reasoning process. One of `concise` or `detailed`.
@@ -193,24 +185,13 @@ private constructor(
          * Returns an immutable instance of [Reasoning].
          *
          * Further updates to this [Builder] will not mutate the returned instance.
-         *
-         * The following fields are required:
-         * ```java
-         * .effort()
-         * ```
-         *
-         * @throws IllegalStateException if any required field is unset.
          */
         fun build(): Reasoning =
-            Reasoning(
-                checkRequired("effort", effort),
-                generateSummary,
-                additionalProperties.toImmutable(),
-            )
+            Reasoning(effort, generateSummary, additionalProperties.toImmutable())
     }
 
     /**
-     * **o-series models only**
+     * **computer_use_preview only**
      *
      * A summary of the reasoning performed by the model. This can be useful for debugging and
      * understanding the model's reasoning process. One of `concise` or `detailed`.

openai-java-core/src/main/kotlin/com/openai/models/batches/BatchCreateParams.kt

@@ -41,9 +41,10 @@ private constructor(
     fun completionWindow(): CompletionWindow = body.completionWindow()
 
     /**
-     * The endpoint to be used for all requests in the batch. Currently `/v1/chat/completions`,
-     * `/v1/embeddings`, and `/v1/completions` are supported. Note that `/v1/embeddings` batches are
-     * also restricted to a maximum of 50,000 embedding inputs across all requests in the batch.
+     * The endpoint to be used for all requests in the batch. Currently `/v1/responses`,
+     * `/v1/chat/completions`, `/v1/embeddings`, and `/v1/completions` are supported. Note that
+     * `/v1/embeddings` batches are also restricted to a maximum of 50,000 embedding inputs across
+     * all requests in the batch.
      *
      * @throws OpenAIInvalidDataException if the JSON field has an unexpected type or is
      *   unexpectedly missing or null (e.g. if the server responded with an unexpected value).
@@ -150,10 +151,10 @@ private constructor(
         fun completionWindow(): CompletionWindow = completionWindow.getRequired("completion_window")
 
         /**
-         * The endpoint to be used for all requests in the batch. Currently `/v1/chat/completions`,
-         * `/v1/embeddings`, and `/v1/completions` are supported. Note that `/v1/embeddings` batches
-         * are also restricted to a maximum of 50,000 embedding inputs across all requests in the
-         * batch.
+         * The endpoint to be used for all requests in the batch. Currently `/v1/responses`,
+         * `/v1/chat/completions`, `/v1/embeddings`, and `/v1/completions` are supported. Note that
+         * `/v1/embeddings` batches are also restricted to a maximum of 50,000 embedding inputs
+         * across all requests in the batch.
          *
          * @throws OpenAIInvalidDataException if the JSON field has an unexpected type or is
          *   unexpectedly missing or null (e.g. if the server responded with an unexpected value).
@@ -294,7 +295,7 @@ private constructor(
             }
 
             /**
-             * The endpoint to be used for all requests in the batch. Currently
+             * The endpoint to be used for all requests in the batch. Currently `/v1/responses`,
              * `/v1/chat/completions`, `/v1/embeddings`, and `/v1/completions` are supported. Note
              * that `/v1/embeddings` batches are also restricted to a maximum of 50,000 embedding
              * inputs across all requests in the batch.
@@ -469,10 +470,10 @@ private constructor(
         }
 
         /**
-         * The endpoint to be used for all requests in the batch. Currently `/v1/chat/completions`,
-         * `/v1/embeddings`, and `/v1/completions` are supported. Note that `/v1/embeddings` batches
-         * are also restricted to a maximum of 50,000 embedding inputs across all requests in the
-         * batch.
+         * The endpoint to be used for all requests in the batch. Currently `/v1/responses`,
+         * `/v1/chat/completions`, `/v1/embeddings`, and `/v1/completions` are supported. Note that
+         * `/v1/embeddings` batches are also restricted to a maximum of 50,000 embedding inputs
+         * across all requests in the batch.
          */
         fun endpoint(endpoint: Endpoint) = apply { body.endpoint(endpoint) }
 
@@ -768,9 +769,10 @@ private constructor(
     }
 
     /**
-     * The endpoint to be used for all requests in the batch. Currently `/v1/chat/completions`,
-     * `/v1/embeddings`, and `/v1/completions` are supported. Note that `/v1/embeddings` batches are
-     * also restricted to a maximum of 50,000 embedding inputs across all requests in the batch.
+     * The endpoint to be used for all requests in the batch. Currently `/v1/responses`,
+     * `/v1/chat/completions`, `/v1/embeddings`, and `/v1/completions` are supported. Note that
+     * `/v1/embeddings` batches are also restricted to a maximum of 50,000 embedding inputs across
+     * all requests in the batch.
      */
     class Endpoint @JsonCreator private constructor(private val value: JsonField<String>) : Enum {
 
@@ -786,6 +788,8 @@ private constructor(
 
         companion object {
 
+            @JvmField val V1_RESPONSES = of("/v1/responses")
+
             @JvmField val V1_CHAT_COMPLETIONS = of("/v1/chat/completions")
 
             @JvmField val V1_EMBEDDINGS = of("/v1/embeddings")
@@ -797,6 +801,7 @@ private constructor(
 
         /** An enum containing [Endpoint]'s known values. */
         enum class Known {
+            V1_RESPONSES,
             V1_CHAT_COMPLETIONS,
             V1_EMBEDDINGS,
             V1_COMPLETIONS,
@@ -812,6 +817,7 @@ private constructor(
          * - It was constructed with an arbitrary value using the [of] method.
          */
         enum class Value {
+            V1_RESPONSES,
             V1_CHAT_COMPLETIONS,
             V1_EMBEDDINGS,
             V1_COMPLETIONS,
@@ -828,6 +834,7 @@ private constructor(
          */
         fun value(): Value =
             when (this) {
+                V1_RESPONSES -> Value.V1_RESPONSES
                 V1_CHAT_COMPLETIONS -> Value.V1_CHAT_COMPLETIONS
                 V1_EMBEDDINGS -> Value.V1_EMBEDDINGS
                 V1_COMPLETIONS -> Value.V1_COMPLETIONS
@@ -845,6 +852,7 @@ private constructor(
          */
         fun known(): Known =
             when (this) {
+                V1_RESPONSES -> Known.V1_RESPONSES
                 V1_CHAT_COMPLETIONS -> Known.V1_CHAT_COMPLETIONS
                 V1_EMBEDDINGS -> Known.V1_EMBEDDINGS
                 V1_COMPLETIONS -> Known.V1_COMPLETIONS

openai-java-core/src/main/kotlin/com/openai/models/chat/completions/ChatCompletionChunk.kt

@@ -121,9 +121,12 @@ private constructor(
 
     /**
      * An optional field that will only be present when you set `stream_options: {"include_usage":
-     * true}` in your request. When present, it contains a null value except for the last chunk
+     * true}` in your request. When present, it contains a null value **except for the last chunk**
      * which contains the token usage statistics for the entire request.
      *
+     * **NOTE:** If the stream is interrupted or cancelled, you may not receive the final usage
+     * chunk which contains the total token usage for the request.
+     *
      * @throws OpenAIInvalidDataException if the JSON field has an unexpected type (e.g. if the
      *   server responded with an unexpected value).
      */
@@ -371,13 +374,13 @@ private constructor(
 
         /**
          * An optional field that will only be present when you set `stream_options:
-         * {"include_usage": true}` in your request. When present, it contains a null value except
-         * for the last chunk which contains the token usage statistics for the entire request.
+         * {"include_usage": true}` in your request. When present, it contains a null value **except
+         * for the last chunk** which contains the token usage statistics for the entire request.
+         *
+         * **NOTE:** If the stream is interrupted or cancelled, you may not receive the final usage
+         * chunk which contains the total token usage for the request.
          */
-        fun usage(usage: CompletionUsage?) = usage(JsonField.ofNullable(usage))
-
-        /** Alias for calling [Builder.usage] with `usage.orElse(null)`. */
-        fun usage(usage: Optional<CompletionUsage>) = usage(usage.getOrNull())
+        fun usage(usage: CompletionUsage) = usage(JsonField.of(usage))
 
         /**
          * Sets [Builder.usage] to an arbitrary JSON value.

openai-java-core/src/main/kotlin/com/openai/models/chat/completions/ChatCompletionContentPart.kt

@@ -421,9 +421,9 @@ private constructor(
             @JsonProperty("file_id")
             @ExcludeMissing
             private val fileId: JsonField<String> = JsonMissing.of(),
-            @JsonProperty("file_name")
+            @JsonProperty("filename")
             @ExcludeMissing
-            private val fileName: JsonField<String> = JsonMissing.of(),
+            private val filename: JsonField<String> = JsonMissing.of(),
             @JsonAnySetter
             private val additionalProperties: Map<String, JsonValue> = immutableEmptyMap(),
         ) {
@@ -451,8 +451,7 @@ private constructor(
              * @throws OpenAIInvalidDataException if the JSON field has an unexpected type (e.g. if
              *   the server responded with an unexpected value).
              */
-            fun fileName(): Optional<String> =
-                Optional.ofNullable(fileName.getNullable("file_name"))
+            fun filename(): Optional<String> = Optional.ofNullable(filename.getNullable("filename"))
 
             /**
              * Returns the raw JSON value of [fileData].
@@ -470,12 +469,12 @@ private constructor(
             @JsonProperty("file_id") @ExcludeMissing fun _fileId(): JsonField<String> = fileId
 
             /**
-             * Returns the raw JSON value of [fileName].
+             * Returns the raw JSON value of [filename].
              *
-             * Unlike [fileName], this method doesn't throw if the JSON field has an unexpected
+             * Unlike [filename], this method doesn't throw if the JSON field has an unexpected
              * type.
              */
-            @JsonProperty("file_name") @ExcludeMissing fun _fileName(): JsonField<String> = fileName
+            @JsonProperty("filename") @ExcludeMissing fun _filename(): JsonField<String> = filename
 
             @JsonAnyGetter
             @ExcludeMissing
@@ -490,7 +489,7 @@ private constructor(
 
                 fileData()
                 fileId()
-                fileName()
+                filename()
                 validated = true
             }
 
@@ -507,14 +506,14 @@ private constructor(
 
                 private var fileData: JsonField<String> = JsonMissing.of()
                 private var fileId: JsonField<String> = JsonMissing.of()
-                private var fileName: JsonField<String> = JsonMissing.of()
+                private var filename: JsonField<String> = JsonMissing.of()
                 private var additionalProperties: MutableMap<String, JsonValue> = mutableMapOf()
 
                 @JvmSynthetic
                 internal fun from(fileObject: FileObject) = apply {
                     fileData = fileObject.fileData
                     fileId = fileObject.fileId
-                    fileName = fileObject.fileName
+                    filename = fileObject.filename
                     additionalProperties = fileObject.additionalProperties.toMutableMap()
                 }
 
@@ -546,16 +545,16 @@ private constructor(
                 fun fileId(fileId: JsonField<String>) = apply { this.fileId = fileId }
 
                 /** The name of the file, used when passing the file to the model as a string. */
-                fun fileName(fileName: String) = fileName(JsonField.of(fileName))
+                fun filename(filename: String) = filename(JsonField.of(filename))
 
                 /**
-                 * Sets [Builder.fileName] to an arbitrary JSON value.
+                 * Sets [Builder.filename] to an arbitrary JSON value.
                  *
-                 * You should usually call [Builder.fileName] with a well-typed [String] value
+                 * You should usually call [Builder.filename] with a well-typed [String] value
                  * instead. This method is primarily for setting the field to an undocumented or not
                  * yet supported value.
                  */
-                fun fileName(fileName: JsonField<String>) = apply { this.fileName = fileName }
+                fun filename(filename: JsonField<String>) = apply { this.filename = filename }
 
                 fun additionalProperties(additionalProperties: Map<String, JsonValue>) = apply {
                     this.additionalProperties.clear()
@@ -585,25 +584,25 @@ private constructor(
                  * Further updates to this [Builder] will not mutate the returned instance.
                  */
                 fun build(): FileObject =
-                    FileObject(fileData, fileId, fileName, additionalProperties.toImmutable())
+                    FileObject(fileData, fileId, filename, additionalProperties.toImmutable())
             }
 
             override fun equals(other: Any?): Boolean {
                 if (this === other) {
                     return true
                 }
 
-                return /* spotless:off */ other is FileObject && fileData == other.fileData && fileId == other.fileId && fileName == other.fileName && additionalProperties == other.additionalProperties /* spotless:on */
+                return /* spotless:off */ other is FileObject && fileData == other.fileData && fileId == other.fileId && filename == other.filename && additionalProperties == other.additionalProperties /* spotless:on */
             }
 
             /* spotless:off */
-            private val hashCode: Int by lazy { Objects.hash(fileData, fileId, fileName, additionalProperties) }
+            private val hashCode: Int by lazy { Objects.hash(fileData, fileId, filename, additionalProperties) }
             /* spotless:on */
 
             override fun hashCode(): Int = hashCode
 
             override fun toString() =
-                "FileObject{fileData=$fileData, fileId=$fileId, fileName=$fileName, additionalProperties=$additionalProperties}"
+                "FileObject{fileData=$fileData, fileId=$fileId, filename=$filename, additionalProperties=$additionalProperties}"
         }
 
         override fun equals(other: Any?): Boolean {

openai-java-core/src/main/kotlin/com/openai/models/chat/completions/ChatCompletionStreamOptions.kt

@@ -31,8 +31,11 @@ private constructor(
     /**
      * If set, an additional chunk will be streamed before the `data: [DONE]` message. The `usage`
      * field on this chunk shows the token usage statistics for the entire request, and the
-     * `choices` field will always be an empty array. All other chunks will also include a `usage`
-     * field, but with a null value.
+     * `choices` field will always be an empty array.
+     *
+     * All other chunks will also include a `usage` field, but with a null value. **NOTE:** If the
+     * stream is interrupted, you may not receive the final usage chunk which contains the total
+     * token usage for the request.
      *
      * @throws OpenAIInvalidDataException if the JSON field has an unexpected type (e.g. if the
      *   server responded with an unexpected value).
@@ -89,8 +92,11 @@ private constructor(
         /**
          * If set, an additional chunk will be streamed before the `data: [DONE]` message. The
          * `usage` field on this chunk shows the token usage statistics for the entire request, and
-         * the `choices` field will always be an empty array. All other chunks will also include a
-         * `usage` field, but with a null value.
+         * the `choices` field will always be an empty array.
+         *
+         * All other chunks will also include a `usage` field, but with a null value. **NOTE:** If
+         * the stream is interrupted, you may not receive the final usage chunk which contains the
+         * total token usage for the request.
          */
         fun includeUsage(includeUsage: Boolean) = includeUsage(JsonField.of(includeUsage))