Skip to content

Commit b55e165

Browse files
jbeckwith-oaijbeckwith-oai
authored
feat(api): add prompt-cache prewarming (#1017)
## Summary Adds a prewarm option to stable and beta Responses prompt-cache builders. ## Changes - Expose the prewarm boolean option for Responses prompt caching - Preserve omission and explicit false values without changing other request options Co-authored-by: jbeckwith-oai <269036200+jbeckwith-oai@users.noreply.github.com>
1 parent 6c24e36 commit b55e165

14 files changed

Lines changed: 203 additions & 18 deletions

File tree

‎.castiron.stats.yml‎

Lines changed: 6 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -1,8 +1,8 @@
11
schema_version: 1
2-
generation_id: 27acda4f-e808-4172-b0be-79b85bdc2464
3-
openapi_spec_hash: 4a1df412f60140287d03f567949777a2
4-
openapi_transformed_spec_hash: 29daece792ba6ce4f97119152a249111
2+
generation_id: e1459de0-7296-4286-a0e9-70d9cf3cbc66
3+
openapi_spec_hash: 39af599b4d1aa3c30800e1262ba9696a
4+
openapi_transformed_spec_hash: 7e6b5702577c8876fe0aec86326ea4a8
55
config_hash: 6b3cc69eb8ac6b5a19e4f865bb7e93fa
6-
codegen_sha: f260b915259e89234cdf7381248f2f35bbe709d2
7-
codegen_hash: b52fabcb6050a68daf882317bf7a9ae0d3ecd69eade80c14b99b47cd5da181e9
8-
public_codegen_sha: 7690e944406fa7982e36a763a0a6632413c58ed6
6+
codegen_sha: 023c228c74c0b7bfaa934c3b3709821bbfae3dec
7+
codegen_hash: e4e4a0e129b97287ab79d7a523334642e9b12e96d1d48171103929b19aa0fbba
8+
public_codegen_sha: 5f25ff2ebe071d9aef4969a09d74e91ef6158064

‎api_reference/openapi.transformed.yml‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -70030,6 +70030,9 @@ components:
7003070030
mode:
7003170031
$ref: '#/components/schemas/PromptCacheModeEnum'
7003270032
description: Controls whether OpenAI automatically creates an implicit cache breakpoint. Defaults to `implicit`. With `implicit`, OpenAI creates one implicit breakpoint and writes up to the latest three explicit breakpoints in the request. With `explicit`, OpenAI does not create an implicit breakpoint and writes up to the latest four explicit breakpoints. If there are no explicit breakpoints, the request does not use prompt caching.
70033+
prewarm:
70034+
type: boolean
70035+
description: Prepares the prompt cache without generating output. Defaults to `false`. When set to `true`, overrides the `generate` field to `false`.
7003370036
comparison_response_id:
7003470037
anyOf:
7003570038
- type: string
@@ -94439,6 +94442,9 @@ components:
9443994442
mode:
9444094443
$ref: '#/components/schemas/BetaPromptCacheModeEnum'
9444194444
description: Controls whether OpenAI automatically creates an implicit cache breakpoint. Defaults to `implicit`. With `implicit`, OpenAI creates one implicit breakpoint and writes up to the latest three explicit breakpoints in the request. With `explicit`, OpenAI does not create an implicit breakpoint and writes up to the latest four explicit breakpoints. If there are no explicit breakpoints, the request does not use prompt caching.
94445+
prewarm:
94446+
type: boolean
94447+
description: Prepares the prompt cache without generating output. Defaults to `false`. When set to `true`, overrides the `generate` field to `false`.
9444294448
comparison_response_id:
9444394449
anyOf:
9444494450
- type: string

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

Lines changed: 44 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -5618,6 +5618,7 @@ private constructor(
56185618
private constructor(
56195619
private val comparisonResponseId: JsonField<String>,
56205620
private val mode: JsonField<Mode>,
5621+
private val prewarm: JsonField<Boolean>,
56215622
private val ttl: JsonField<Ttl>,
56225623
private val additionalProperties: MutableMap<String, JsonValue>,
56235624
) {
@@ -5628,8 +5629,11 @@ private constructor(
56285629
@ExcludeMissing
56295630
comparisonResponseId: JsonField<String> = JsonMissing.of(),
56305631
@JsonProperty("mode") @ExcludeMissing mode: JsonField<Mode> = JsonMissing.of(),
5632+
@JsonProperty("prewarm")
5633+
@ExcludeMissing
5634+
prewarm: JsonField<Boolean> = JsonMissing.of(),
56315635
@JsonProperty("ttl") @ExcludeMissing ttl: JsonField<Ttl> = JsonMissing.of(),
5632-
) : this(comparisonResponseId, mode, ttl, mutableMapOf())
5636+
) : this(comparisonResponseId, mode, prewarm, ttl, mutableMapOf())
56335637

56345638
/**
56355639
* The ID of a response to compare when diagnosing prompt cache reuse. Supplying this
@@ -5654,6 +5658,15 @@ private constructor(
56545658
*/
56555659
fun mode(): Optional<Mode> = mode.getOptional("mode")
56565660

5661+
/**
5662+
* Prepares the prompt cache without generating output. Defaults to `false`. When set to
5663+
* `true`, overrides the `generate` field to `false`.
5664+
*
5665+
* @throws OpenAIInvalidDataException if the JSON field has an unexpected type (e.g. if
5666+
* the server responded with an unexpected value).
5667+
*/
5668+
fun prewarm(): Optional<Boolean> = prewarm.getOptional("prewarm")
5669+
56575670
/**
56585671
* The minimum lifetime applied to every implicit and explicit cache breakpoint written
56595672
* by the request. Defaults to `30m`, which is currently the only supported value. The
@@ -5681,6 +5694,13 @@ private constructor(
56815694
*/
56825695
@JsonProperty("mode") @ExcludeMissing fun _mode(): JsonField<Mode> = mode
56835696

5697+
/**
5698+
* Returns the raw JSON value of [prewarm].
5699+
*
5700+
* Unlike [prewarm], this method doesn't throw if the JSON field has an unexpected type.
5701+
*/
5702+
@JsonProperty("prewarm") @ExcludeMissing fun _prewarm(): JsonField<Boolean> = prewarm
5703+
56845704
/**
56855705
* Returns the raw JSON value of [ttl].
56865706
*
@@ -5713,13 +5733,15 @@ private constructor(
57135733

57145734
private var comparisonResponseId: JsonField<String> = JsonMissing.of()
57155735
private var mode: JsonField<Mode> = JsonMissing.of()
5736+
private var prewarm: JsonField<Boolean> = JsonMissing.of()
57165737
private var ttl: JsonField<Ttl> = JsonMissing.of()
57175738
private var additionalProperties: MutableMap<String, JsonValue> = mutableMapOf()
57185739

57195740
@JvmSynthetic
57205741
internal fun from(promptCacheOptions: PromptCacheOptions) = apply {
57215742
comparisonResponseId = promptCacheOptions.comparisonResponseId
57225743
mode = promptCacheOptions.mode
5744+
prewarm = promptCacheOptions.prewarm
57235745
ttl = promptCacheOptions.ttl
57245746
additionalProperties = promptCacheOptions.additionalProperties.toMutableMap()
57255747
}
@@ -5768,6 +5790,21 @@ private constructor(
57685790
*/
57695791
fun mode(mode: JsonField<Mode>) = apply { this.mode = mode }
57705792

5793+
/**
5794+
* Prepares the prompt cache without generating output. Defaults to `false`. When
5795+
* set to `true`, overrides the `generate` field to `false`.
5796+
*/
5797+
fun prewarm(prewarm: Boolean) = prewarm(JsonField.of(prewarm))
5798+
5799+
/**
5800+
* Sets [Builder.prewarm] to an arbitrary JSON value.
5801+
*
5802+
* You should usually call [Builder.prewarm] with a well-typed [Boolean] value
5803+
* instead. This method is primarily for setting the field to an undocumented or not
5804+
* yet supported value.
5805+
*/
5806+
fun prewarm(prewarm: JsonField<Boolean>) = apply { this.prewarm = prewarm }
5807+
57715808
/**
57725809
* The minimum lifetime applied to every implicit and explicit cache breakpoint
57735810
* written by the request. Defaults to `30m`, which is currently the only supported
@@ -5815,6 +5852,7 @@ private constructor(
58155852
PromptCacheOptions(
58165853
comparisonResponseId,
58175854
mode,
5855+
prewarm,
58185856
ttl,
58195857
additionalProperties.toMutableMap(),
58205858
)
@@ -5839,6 +5877,7 @@ private constructor(
58395877

58405878
comparisonResponseId()
58415879
mode().ifPresent { it.validate() }
5880+
prewarm()
58425881
ttl().ifPresent { it.validate() }
58435882
validated = true
58445883
}
@@ -5861,6 +5900,7 @@ private constructor(
58615900
internal fun validity(): Int =
58625901
(if (comparisonResponseId.asKnown().isPresent) 1 else 0) +
58635902
(mode.asKnown().getOrNull()?.validity() ?: 0) +
5903+
(if (prewarm.asKnown().isPresent) 1 else 0) +
58645904
(ttl.asKnown().getOrNull()?.validity() ?: 0)
58655905

58665906
/**
@@ -6158,18 +6198,19 @@ private constructor(
61586198
return other is PromptCacheOptions &&
61596199
comparisonResponseId == other.comparisonResponseId &&
61606200
mode == other.mode &&
6201+
prewarm == other.prewarm &&
61616202
ttl == other.ttl &&
61626203
additionalProperties == other.additionalProperties
61636204
}
61646205

61656206
private val hashCode: Int by lazy {
6166-
Objects.hash(comparisonResponseId, mode, ttl, additionalProperties)
6207+
Objects.hash(comparisonResponseId, mode, prewarm, ttl, additionalProperties)
61676208
}
61686209

61696210
override fun hashCode(): Int = hashCode
61706211

61716212
override fun toString() =
6172-
"PromptCacheOptions{comparisonResponseId=$comparisonResponseId, mode=$mode, ttl=$ttl, additionalProperties=$additionalProperties}"
6213+
"PromptCacheOptions{comparisonResponseId=$comparisonResponseId, mode=$mode, prewarm=$prewarm, ttl=$ttl, additionalProperties=$additionalProperties}"
61736214
}
61746215

61756216
/**

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

Lines changed: 42 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -6858,6 +6858,7 @@ private constructor(
68586858
private constructor(
68596859
private val comparisonResponseId: JsonField<String>,
68606860
private val mode: JsonField<Mode>,
6861+
private val prewarm: JsonField<Boolean>,
68616862
private val ttl: JsonField<Ttl>,
68626863
private val additionalProperties: MutableMap<String, JsonValue>,
68636864
) {
@@ -6868,8 +6869,9 @@ private constructor(
68686869
@ExcludeMissing
68696870
comparisonResponseId: JsonField<String> = JsonMissing.of(),
68706871
@JsonProperty("mode") @ExcludeMissing mode: JsonField<Mode> = JsonMissing.of(),
6872+
@JsonProperty("prewarm") @ExcludeMissing prewarm: JsonField<Boolean> = JsonMissing.of(),
68716873
@JsonProperty("ttl") @ExcludeMissing ttl: JsonField<Ttl> = JsonMissing.of(),
6872-
) : this(comparisonResponseId, mode, ttl, mutableMapOf())
6874+
) : this(comparisonResponseId, mode, prewarm, ttl, mutableMapOf())
68736875

68746876
/**
68756877
* The ID of a response to compare when diagnosing prompt cache reuse. Supplying this field
@@ -6893,6 +6895,15 @@ private constructor(
68936895
*/
68946896
fun mode(): Optional<Mode> = mode.getOptional("mode")
68956897

6898+
/**
6899+
* Prepares the prompt cache without generating output. Defaults to `false`. When set to
6900+
* `true`, overrides the `generate` field to `false`.
6901+
*
6902+
* @throws OpenAIInvalidDataException if the JSON field has an unexpected type (e.g. if the
6903+
* server responded with an unexpected value).
6904+
*/
6905+
fun prewarm(): Optional<Boolean> = prewarm.getOptional("prewarm")
6906+
68966907
/**
68976908
* The minimum lifetime applied to every implicit and explicit cache breakpoint written by
68986909
* the request. Defaults to `30m`, which is currently the only supported value. The backend
@@ -6920,6 +6931,13 @@ private constructor(
69206931
*/
69216932
@JsonProperty("mode") @ExcludeMissing fun _mode(): JsonField<Mode> = mode
69226933

6934+
/**
6935+
* Returns the raw JSON value of [prewarm].
6936+
*
6937+
* Unlike [prewarm], this method doesn't throw if the JSON field has an unexpected type.
6938+
*/
6939+
@JsonProperty("prewarm") @ExcludeMissing fun _prewarm(): JsonField<Boolean> = prewarm
6940+
69236941
/**
69246942
* Returns the raw JSON value of [ttl].
69256943
*
@@ -6950,13 +6968,15 @@ private constructor(
69506968

69516969
private var comparisonResponseId: JsonField<String> = JsonMissing.of()
69526970
private var mode: JsonField<Mode> = JsonMissing.of()
6971+
private var prewarm: JsonField<Boolean> = JsonMissing.of()
69536972
private var ttl: JsonField<Ttl> = JsonMissing.of()
69546973
private var additionalProperties: MutableMap<String, JsonValue> = mutableMapOf()
69556974

69566975
@JvmSynthetic
69576976
internal fun from(promptCacheOptions: PromptCacheOptions) = apply {
69586977
comparisonResponseId = promptCacheOptions.comparisonResponseId
69596978
mode = promptCacheOptions.mode
6979+
prewarm = promptCacheOptions.prewarm
69606980
ttl = promptCacheOptions.ttl
69616981
additionalProperties = promptCacheOptions.additionalProperties.toMutableMap()
69626982
}
@@ -7005,6 +7025,21 @@ private constructor(
70057025
*/
70067026
fun mode(mode: JsonField<Mode>) = apply { this.mode = mode }
70077027

7028+
/**
7029+
* Prepares the prompt cache without generating output. Defaults to `false`. When set to
7030+
* `true`, overrides the `generate` field to `false`.
7031+
*/
7032+
fun prewarm(prewarm: Boolean) = prewarm(JsonField.of(prewarm))
7033+
7034+
/**
7035+
* Sets [Builder.prewarm] to an arbitrary JSON value.
7036+
*
7037+
* You should usually call [Builder.prewarm] with a well-typed [Boolean] value instead.
7038+
* This method is primarily for setting the field to an undocumented or not yet
7039+
* supported value.
7040+
*/
7041+
fun prewarm(prewarm: JsonField<Boolean>) = apply { this.prewarm = prewarm }
7042+
70087043
/**
70097044
* The minimum lifetime applied to every implicit and explicit cache breakpoint written
70107045
* by the request. Defaults to `30m`, which is currently the only supported value. The
@@ -7049,6 +7084,7 @@ private constructor(
70497084
PromptCacheOptions(
70507085
comparisonResponseId,
70517086
mode,
7087+
prewarm,
70527088
ttl,
70537089
additionalProperties.toMutableMap(),
70547090
)
@@ -7072,6 +7108,7 @@ private constructor(
70727108

70737109
comparisonResponseId()
70747110
mode().ifPresent { it.validate() }
7111+
prewarm()
70757112
ttl().ifPresent { it.validate() }
70767113
validated = true
70777114
}
@@ -7094,6 +7131,7 @@ private constructor(
70947131
internal fun validity(): Int =
70957132
(if (comparisonResponseId.asKnown().isPresent) 1 else 0) +
70967133
(mode.asKnown().getOrNull()?.validity() ?: 0) +
7134+
(if (prewarm.asKnown().isPresent) 1 else 0) +
70977135
(ttl.asKnown().getOrNull()?.validity() ?: 0)
70987136

70997137
/**
@@ -7384,18 +7422,19 @@ private constructor(
73847422
return other is PromptCacheOptions &&
73857423
comparisonResponseId == other.comparisonResponseId &&
73867424
mode == other.mode &&
7425+
prewarm == other.prewarm &&
73877426
ttl == other.ttl &&
73887427
additionalProperties == other.additionalProperties
73897428
}
73907429

73917430
private val hashCode: Int by lazy {
7392-
Objects.hash(comparisonResponseId, mode, ttl, additionalProperties)
7431+
Objects.hash(comparisonResponseId, mode, prewarm, ttl, additionalProperties)
73937432
}
73947433

73957434
override fun hashCode(): Int = hashCode
73967435

73977436
override fun toString() =
7398-
"PromptCacheOptions{comparisonResponseId=$comparisonResponseId, mode=$mode, ttl=$ttl, additionalProperties=$additionalProperties}"
7437+
"PromptCacheOptions{comparisonResponseId=$comparisonResponseId, mode=$mode, prewarm=$prewarm, ttl=$ttl, additionalProperties=$additionalProperties}"
73997438
}
74007439

74017440
/**

0 commit comments

Comments
 (0)