feat(api): Add prompt cache diagnostics

.castiron.stats.yml

@@ -1,8 +1,8 @@
 schema_version: 1
-generation_id: ccbb71a7-e6b9-472e-9074-f90d38a20b83
-openapi_spec_hash: fcdb9c99a509f5ea8b90d7abbf1dab2f
-openapi_transformed_spec_hash: dd244f7dd3ab9d18dc2c34970a39505f
-config_hash: 81fd1039eb373628d87269f065d30a69
-codegen_sha: 13f98338b1be2f5b193b52d7c78fbd6e4cc1c507
-codegen_hash: 8e662c2440506c5cb2d3c0d4c81728ffbe393ae7d007b21727225c6e21a488d2
-public_codegen_sha: 2810cd18d0c0d8651dec84d1f1482a797b476abc
+generation_id: b5786240-60e4-47c2-bf37-2a6cb529ddbc
+openapi_spec_hash: a5a64d9aaf4a4022898dd86685c102ab
+openapi_transformed_spec_hash: f7c7c9ee2566bcf8165ab87b4851a1e5
+config_hash: dfe8a20c64cc5d852e69c441cbd28ae7
+codegen_sha: 1a13a512fc70956060b400cbbe9a1628dcec197a
+codegen_hash: 87aded21d9ead45714afa6ff1e7d423a10fce956d2356ef84dce89219f44d57d
+public_codegen_sha: 54afb51353d006aa807172b636bea7b8dc4539f6

openai-java-core/src/apiCompatibility/structured-output-public-api.txt

@@ -256,6 +256,7 @@ com.openai.models.responses.StructuredResponse#_output ()Lcom/openai/core/JsonFi
 com.openai.models.responses.StructuredResponse#_parallelToolCalls ()Lcom/openai/core/JsonField;
 com.openai.models.responses.StructuredResponse#_previousResponseId ()Lcom/openai/core/JsonField;
 com.openai.models.responses.StructuredResponse#_prompt ()Lcom/openai/core/JsonField;
+com.openai.models.responses.StructuredResponse#_promptCacheDiagnostics ()Lcom/openai/core/JsonField;
 com.openai.models.responses.StructuredResponse#_promptCacheKey ()Lcom/openai/core/JsonField;
 com.openai.models.responses.StructuredResponse#_promptCacheOptions ()Lcom/openai/core/JsonField;
 com.openai.models.responses.StructuredResponse#_promptCacheRetention ()Lcom/openai/core/JsonField;
@@ -290,6 +291,7 @@ com.openai.models.responses.StructuredResponse#output ()Ljava/util/List;
 com.openai.models.responses.StructuredResponse#parallelToolCalls ()Z
 com.openai.models.responses.StructuredResponse#previousResponseId ()Ljava/util/Optional;
 com.openai.models.responses.StructuredResponse#prompt ()Ljava/util/Optional;
+com.openai.models.responses.StructuredResponse#promptCacheDiagnostics ()Ljava/util/Optional;
 com.openai.models.responses.StructuredResponse#promptCacheKey ()Ljava/util/Optional;
 com.openai.models.responses.StructuredResponse#promptCacheOptions ()Ljava/util/Optional;
 com.openai.models.responses.StructuredResponse#promptCacheRetention ()Ljava/util/Optional;

openai-java-core/src/main/kotlin/com/openai/models/beta/responses/BetaResponsesClientEvent.kt

@@ -5591,16 +5591,30 @@ private constructor(
         class PromptCacheOptions
         @JsonCreator(mode = JsonCreator.Mode.DISABLED)
         private constructor(
+            private val comparisonResponseId: JsonField<String>,
             private val mode: JsonField<Mode>,
             private val ttl: JsonField<Ttl>,
             private val additionalProperties: MutableMap<String, JsonValue>,
         ) {
 
             @JsonCreator
             private constructor(
+                @JsonProperty("comparison_response_id")
+                @ExcludeMissing
+                comparisonResponseId: JsonField<String> = JsonMissing.of(),
                 @JsonProperty("mode") @ExcludeMissing mode: JsonField<Mode> = JsonMissing.of(),
                 @JsonProperty("ttl") @ExcludeMissing ttl: JsonField<Ttl> = JsonMissing.of(),
-            ) : this(mode, ttl, mutableMapOf())
+            ) : this(comparisonResponseId, mode, ttl, mutableMapOf())
+
+            /**
+             * The ID of a response to compare when diagnosing prompt cache reuse. Supplying this
+             * field requests prompt cache diagnostics when the feature is enabled.
+             *
+             * @throws OpenAIInvalidDataException if the JSON field has an unexpected type (e.g. if
+             *   the server responded with an unexpected value).
+             */
+            fun comparisonResponseId(): Optional<String> =
+                comparisonResponseId.getOptional("comparison_response_id")
 
             /**
              * Controls whether OpenAI automatically creates an implicit cache breakpoint. Defaults
@@ -5625,6 +5639,16 @@ private constructor(
              */
             fun ttl(): Optional<Ttl> = ttl.getOptional("ttl")
 
+            /**
+             * Returns the raw JSON value of [comparisonResponseId].
+             *
+             * Unlike [comparisonResponseId], this method doesn't throw if the JSON field has an
+             * unexpected type.
+             */
+            @JsonProperty("comparison_response_id")
+            @ExcludeMissing
+            fun _comparisonResponseId(): JsonField<String> = comparisonResponseId
+
             /**
              * Returns the raw JSON value of [mode].
              *
@@ -5662,17 +5686,44 @@ private constructor(
             /** A builder for [PromptCacheOptions]. */
             class Builder internal constructor() {
 
+                private var comparisonResponseId: JsonField<String> = JsonMissing.of()
                 private var mode: JsonField<Mode> = JsonMissing.of()
                 private var ttl: JsonField<Ttl> = JsonMissing.of()
                 private var additionalProperties: MutableMap<String, JsonValue> = mutableMapOf()
 
                 @JvmSynthetic
                 internal fun from(promptCacheOptions: PromptCacheOptions) = apply {
+                    comparisonResponseId = promptCacheOptions.comparisonResponseId
                     mode = promptCacheOptions.mode
                     ttl = promptCacheOptions.ttl
                     additionalProperties = promptCacheOptions.additionalProperties.toMutableMap()
                 }
 
+                /**
+                 * The ID of a response to compare when diagnosing prompt cache reuse. Supplying
+                 * this field requests prompt cache diagnostics when the feature is enabled.
+                 */
+                fun comparisonResponseId(comparisonResponseId: String?) =
+                    comparisonResponseId(JsonField.ofNullable(comparisonResponseId))
+
+                /**
+                 * Alias for calling [Builder.comparisonResponseId] with
+                 * `comparisonResponseId.orElse(null)`.
+                 */
+                fun comparisonResponseId(comparisonResponseId: Optional<String>) =
+                    comparisonResponseId(comparisonResponseId.getOrNull())
+
+                /**
+                 * Sets [Builder.comparisonResponseId] to an arbitrary JSON value.
+                 *
+                 * You should usually call [Builder.comparisonResponseId] with a well-typed [String]
+                 * value instead. This method is primarily for setting the field to an undocumented
+                 * or not yet supported value.
+                 */
+                fun comparisonResponseId(comparisonResponseId: JsonField<String>) = apply {
+                    this.comparisonResponseId = comparisonResponseId
+                }
+
                 /**
                  * Controls whether OpenAI automatically creates an implicit cache breakpoint.
                  * Defaults to `implicit`. With `implicit`, OpenAI creates one implicit breakpoint
@@ -5736,7 +5787,12 @@ private constructor(
                  * Further updates to this [Builder] will not mutate the returned instance.
                  */
                 fun build(): PromptCacheOptions =
-                    PromptCacheOptions(mode, ttl, additionalProperties.toMutableMap())
+                    PromptCacheOptions(
+                        comparisonResponseId,
+                        mode,
+                        ttl,
+                        additionalProperties.toMutableMap(),
+                    )
             }
 
             private var validated: Boolean = false
@@ -5756,6 +5812,7 @@ private constructor(
                     return@apply
                 }
 
+                comparisonResponseId()
                 mode().ifPresent { it.validate() }
                 ttl().ifPresent { it.validate() }
                 validated = true
@@ -5777,7 +5834,8 @@ private constructor(
              */
             @JvmSynthetic
             internal fun validity(): Int =
-                (mode.asKnown().getOrNull()?.validity() ?: 0) +
+                (if (comparisonResponseId.asKnown().isPresent) 1 else 0) +
+                    (mode.asKnown().getOrNull()?.validity() ?: 0) +
                     (ttl.asKnown().getOrNull()?.validity() ?: 0)
 
             /**
@@ -6073,17 +6131,20 @@ private constructor(
                 }
 
                 return other is PromptCacheOptions &&
+                    comparisonResponseId == other.comparisonResponseId &&
                     mode == other.mode &&
                     ttl == other.ttl &&
                     additionalProperties == other.additionalProperties
             }
 
-            private val hashCode: Int by lazy { Objects.hash(mode, ttl, additionalProperties) }
+            private val hashCode: Int by lazy {
+                Objects.hash(comparisonResponseId, mode, ttl, additionalProperties)
+            }
 
             override fun hashCode(): Int = hashCode
 
             override fun toString() =
-                "PromptCacheOptions{mode=$mode, ttl=$ttl, additionalProperties=$additionalProperties}"
+                "PromptCacheOptions{comparisonResponseId=$comparisonResponseId, mode=$mode, ttl=$ttl, additionalProperties=$additionalProperties}"
         }
 
         /**

openai-java-core/src/main/kotlin/com/openai/models/beta/responses/ResponseCompactParams.kt

@@ -132,12 +132,12 @@ private constructor(
      * to '[flex](https://platform.openai.com/docs/guides/flex-processing)', then the request will
      * be processed with the Flex Processing service tier. - To opt-in to
      * [Fast mode](/api/docs/guides/fast-mode) at the request level, include the `service_tier=fast`
-     * or `service_tier=priority` parameter for Responses or Chat Completions. The response will
-     * show `service_tier=priority` regardless of if you specify `service_tier=fast` or `priority`
-     * in your request. - When not set, the default behavior is 'auto'. When the `service_tier`
-     * parameter is set, the response body will include the `service_tier` value based on the
-     * processing mode actually used to serve the request. This response value may be different from
-     * the value set in the parameter.
+     * or `service_tier=priority` parameter for Responses or Chat Completions. For models with a
+     * dedicated Fast tier, either value resolves to `service_tier=fast`; for other models, either
+     * value resolves to `service_tier=priority`. - When not set, the default behavior is 'auto'.
+     * When the `service_tier` parameter is set, the response body will include the `service_tier`
+     * value based on the processing mode actually used to serve the request. This response value
+     * may be different from the value set in the parameter.
      *
      * @throws OpenAIInvalidDataException if the JSON field has an unexpected type (e.g. if the
      *   server responded with an unexpected value).
@@ -455,11 +455,12 @@ private constructor(
          * then the request will be processed with the Flex Processing service tier. - To opt-in to
          * [Fast mode](/api/docs/guides/fast-mode) at the request level, include the
          * `service_tier=fast` or `service_tier=priority` parameter for Responses or Chat
-         * Completions. The response will show `service_tier=priority` regardless of if you specify
-         * `service_tier=fast` or `priority` in your request. - When not set, the default behavior
-         * is 'auto'. When the `service_tier` parameter is set, the response body will include the
-         * `service_tier` value based on the processing mode actually used to serve the request.
-         * This response value may be different from the value set in the parameter.
+         * Completions. For models with a dedicated Fast tier, either value resolves to
+         * `service_tier=fast`; for other models, either value resolves to
+         * `service_tier=priority`. - When not set, the default behavior is 'auto'. When the
+         * `service_tier` parameter is set, the response body will include the `service_tier` value
+         * based on the processing mode actually used to serve the request. This response value may
+         * be different from the value set in the parameter.
          */
         fun serviceTier(serviceTier: ServiceTier?) = apply { body.serviceTier(serviceTier) }
 
@@ -761,11 +762,12 @@ private constructor(
          * then the request will be processed with the Flex Processing service tier. - To opt-in to
          * [Fast mode](/api/docs/guides/fast-mode) at the request level, include the
          * `service_tier=fast` or `service_tier=priority` parameter for Responses or Chat
-         * Completions. The response will show `service_tier=priority` regardless of if you specify
-         * `service_tier=fast` or `priority` in your request. - When not set, the default behavior
-         * is 'auto'. When the `service_tier` parameter is set, the response body will include the
-         * `service_tier` value based on the processing mode actually used to serve the request.
-         * This response value may be different from the value set in the parameter.
+         * Completions. For models with a dedicated Fast tier, either value resolves to
+         * `service_tier=fast`; for other models, either value resolves to
+         * `service_tier=priority`. - When not set, the default behavior is 'auto'. When the
+         * `service_tier` parameter is set, the response body will include the `service_tier` value
+         * based on the processing mode actually used to serve the request. This response value may
+         * be different from the value set in the parameter.
          *
          * @throws OpenAIInvalidDataException if the JSON field has an unexpected type (e.g. if the
          *   server responded with an unexpected value).
@@ -1089,12 +1091,12 @@ private constructor(
              * will be processed with the Flex Processing service tier. - To opt-in to
              * [Fast mode](/api/docs/guides/fast-mode) at the request level, include the
              * `service_tier=fast` or `service_tier=priority` parameter for Responses or Chat
-             * Completions. The response will show `service_tier=priority` regardless of if you
-             * specify `service_tier=fast` or `priority` in your request. - When not set, the
-             * default behavior is 'auto'. When the `service_tier` parameter is set, the response
-             * body will include the `service_tier` value based on the processing mode actually used
-             * to serve the request. This response value may be different from the value set in the
-             * parameter.
+             * Completions. For models with a dedicated Fast tier, either value resolves to
+             * `service_tier=fast`; for other models, either value resolves to
+             * `service_tier=priority`. - When not set, the default behavior is 'auto'. When the
+             * `service_tier` parameter is set, the response body will include the `service_tier`
+             * value based on the processing mode actually used to serve the request. This response
+             * value may be different from the value set in the parameter.
              */
             fun serviceTier(serviceTier: ServiceTier?) =
                 serviceTier(JsonField.ofNullable(serviceTier))
@@ -2872,12 +2874,12 @@ private constructor(
      * to '[flex](https://platform.openai.com/docs/guides/flex-processing)', then the request will
      * be processed with the Flex Processing service tier. - To opt-in to
      * [Fast mode](/api/docs/guides/fast-mode) at the request level, include the `service_tier=fast`
-     * or `service_tier=priority` parameter for Responses or Chat Completions. The response will
-     * show `service_tier=priority` regardless of if you specify `service_tier=fast` or `priority`
-     * in your request. - When not set, the default behavior is 'auto'. When the `service_tier`
-     * parameter is set, the response body will include the `service_tier` value based on the
-     * processing mode actually used to serve the request. This response value may be different from
-     * the value set in the parameter.
+     * or `service_tier=priority` parameter for Responses or Chat Completions. For models with a
+     * dedicated Fast tier, either value resolves to `service_tier=fast`; for other models, either
+     * value resolves to `service_tier=priority`. - When not set, the default behavior is 'auto'.
+     * When the `service_tier` parameter is set, the response body will include the `service_tier`
+     * value based on the processing mode actually used to serve the request. This response value
+     * may be different from the value set in the parameter.
      */
     class ServiceTier @JsonCreator private constructor(private val value: JsonField<String>) :
         Enum {