feat(api): Realtime API token_limits, Hybrid searching ranking options

Author: stainless-app[bot]

.stats.yml

@@ -1,4 +1,4 @@
 configured_endpoints: 135
-openapi_spec_url: https://storage.googleapis.com/stainless-sdk-openapi-specs/openai%2Fopenai-f68f718cd45ac3f9336603601bccc38a718af44d0b26601031de3d0a71b7ce2f.yml
-openapi_spec_hash: 1560717860bba4105936647dde8f618d
-config_hash: 50ee3382a63c021a9f821a935950e926
+openapi_spec_url: https://storage.googleapis.com/stainless-sdk-openapi-specs/openai%2Fopenai-3c5d1593d7c6f2b38a7d78d7906041465ee9d6e9022f0651e1da194654488108.yml
+openapi_spec_hash: 0a4d8ad2469823ce24a3fd94f23f1c2b
+config_hash: 032995825500a503a76da119f5354905

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

@@ -38,16 +38,20 @@ private constructor(
     private val _json: JsonValue? = null,
 ) {
 
+    /** Unconstrained free-form text. */
     fun text(): Optional<JsonValue> = Optional.ofNullable(text)
 
+    /** A grammar defined by the user. */
     fun grammar(): Optional<Grammar> = Optional.ofNullable(grammar)
 
     fun isText(): Boolean = text != null
 
     fun isGrammar(): Boolean = grammar != null
 
+    /** Unconstrained free-form text. */
     fun asText(): JsonValue = text.getOrThrow("text")
 
+    /** A grammar defined by the user. */
     fun asGrammar(): Grammar = grammar.getOrThrow("grammar")
 
     fun _json(): Optional<JsonValue> = Optional.ofNullable(_json)
@@ -130,9 +134,11 @@ private constructor(
 
     companion object {
 
+        /** Unconstrained free-form text. */
         @JvmStatic
         fun ofText() = CustomToolInputFormat(text = JsonValue.from(mapOf("type" to "text")))
 
+        /** A grammar defined by the user. */
         @JvmStatic fun ofGrammar(grammar: Grammar) = CustomToolInputFormat(grammar = grammar)
     }
 
@@ -142,8 +148,10 @@ private constructor(
      */
     interface Visitor<out T> {
 
+        /** Unconstrained free-form text. */
         fun visitText(text: JsonValue): T
 
+        /** A grammar defined by the user. */
         fun visitGrammar(grammar: Grammar): T
 
         /**
@@ -202,6 +210,7 @@ private constructor(
         }
     }
 
+    /** A grammar defined by the user. */
     class Grammar
     @JsonCreator(mode = JsonCreator.Mode.DISABLED)
     private constructor(

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

@@ -80,7 +80,9 @@ private constructor(
     fun background(): Optional<Background> = body.background()
 
     /**
-     *             Control how much effort the model will exert to match the style and features, especially facial features, of input images. This parameter is only supported for `gpt-image-1`. Unsupported for `gpt-image-1-mini`. Supports `high` and `low`. Defaults to `low`.
+     * Control how much effort the model will exert to match the style and features, especially
+     * facial features, of input images. This parameter is only supported for `gpt-image-1`.
+     * Unsupported for `gpt-image-1-mini`. Supports `high` and `low`. Defaults to `low`.
      *
      * @throws OpenAIInvalidDataException if the JSON field has an unexpected type (e.g. if the
      *   server responded with an unexpected value).
@@ -429,7 +431,9 @@ private constructor(
         }
 
         /**
-         *             Control how much effort the model will exert to match the style and features, especially facial features, of input images. This parameter is only supported for `gpt-image-1`. Unsupported for `gpt-image-1-mini`. Supports `high` and `low`. Defaults to `low`.
+         * Control how much effort the model will exert to match the style and features, especially
+         * facial features, of input images. This parameter is only supported for `gpt-image-1`.
+         * Unsupported for `gpt-image-1-mini`. Supports `high` and `low`. Defaults to `low`.
          */
         fun inputFidelity(inputFidelity: InputFidelity?) = apply {
             body.inputFidelity(inputFidelity)
@@ -903,7 +907,9 @@ private constructor(
         fun background(): Optional<Background> = background.value.getOptional("background")
 
         /**
-         *             Control how much effort the model will exert to match the style and features, especially facial features, of input images. This parameter is only supported for `gpt-image-1`. Unsupported for `gpt-image-1-mini`. Supports `high` and `low`. Defaults to `low`.
+         * Control how much effort the model will exert to match the style and features, especially
+         * facial features, of input images. This parameter is only supported for `gpt-image-1`.
+         * Unsupported for `gpt-image-1-mini`. Supports `high` and `low`. Defaults to `low`.
          *
          * @throws OpenAIInvalidDataException if the JSON field has an unexpected type (e.g. if the
          *   server responded with an unexpected value).
@@ -1297,7 +1303,10 @@ private constructor(
             }
 
             /**
-             *             Control how much effort the model will exert to match the style and features, especially facial features, of input images. This parameter is only supported for `gpt-image-1`. Unsupported for `gpt-image-1-mini`. Supports `high` and `low`. Defaults to `low`.
+             * Control how much effort the model will exert to match the style and features,
+             * especially facial features, of input images. This parameter is only supported for
+             * `gpt-image-1`. Unsupported for `gpt-image-1-mini`. Supports `high` and `low`.
+             * Defaults to `low`.
              */
             fun inputFidelity(inputFidelity: InputFidelity?) =
                 inputFidelity(MultipartField.of(inputFidelity))
@@ -1981,7 +1990,9 @@ private constructor(
     }
 
     /**
-     *             Control how much effort the model will exert to match the style and features, especially facial features, of input images. This parameter is only supported for `gpt-image-1`. Unsupported for `gpt-image-1-mini`. Supports `high` and `low`. Defaults to `low`.
+     * Control how much effort the model will exert to match the style and features, especially
+     * facial features, of input images. This parameter is only supported for `gpt-image-1`.
+     * Unsupported for `gpt-image-1-mini`. Supports `high` and `low`. Defaults to `low`.
      */
     class InputFidelity @JsonCreator private constructor(private val value: JsonField<String>) :
         Enum {

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

@@ -221,8 +221,17 @@ private constructor(
     fun tracing(): Optional<RealtimeTracingConfig> = tracing.getOptional("tracing")
 
     /**
-     * Controls how the realtime conversation is truncated prior to model inference. The default is
-     * `auto`.
+     * When the number of tokens in a conversation exceeds the model's input token limit, the
+     * conversation be truncated, meaning messages (starting from the oldest) will not be included
+     * in the model's context. A 32k context model with 4,096 max output tokens can only include
+     * 28,224 tokens in the context before truncation occurs. Clients can configure truncation
+     * behavior to truncate with a lower max token limit, which is an effective way to control token
+     * usage and cost. Truncation will reduce the number of cached tokens on the next turn (busting
+     * the cache), since messages are dropped from the beginning of the context. However, clients
+     * can also configure truncation to retain messages up to a fraction of the maximum context
+     * size, which will reduce the need for future truncations and thus improve the cache rate.
+     * Truncation can be disabled entirely, which means the server will never truncate but would
+     * instead return an error if the conversation exceeds the model's input token limit.
      *
      * @throws OpenAIInvalidDataException if the JSON field has an unexpected type (e.g. if the
      *   server responded with an unexpected value).
@@ -666,8 +675,18 @@ private constructor(
             tracing(RealtimeTracingConfig.ofTracingConfiguration(tracingConfiguration))
 
         /**
-         * Controls how the realtime conversation is truncated prior to model inference. The default
-         * is `auto`.
+         * When the number of tokens in a conversation exceeds the model's input token limit, the
+         * conversation be truncated, meaning messages (starting from the oldest) will not be
+         * included in the model's context. A 32k context model with 4,096 max output tokens can
+         * only include 28,224 tokens in the context before truncation occurs. Clients can configure
+         * truncation behavior to truncate with a lower max token limit, which is an effective way
+         * to control token usage and cost. Truncation will reduce the number of cached tokens on
+         * the next turn (busting the cache), since messages are dropped from the beginning of the
+         * context. However, clients can also configure truncation to retain messages up to a
+         * fraction of the maximum context size, which will reduce the need for future truncations
+         * and thus improve the cache rate. Truncation can be disabled entirely, which means the
+         * server will never truncate but would instead return an error if the conversation exceeds
+         * the model's input token limit.
          */
         fun truncation(truncation: RealtimeTruncation) = truncation(JsonField.of(truncation))
 

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

@@ -22,8 +22,17 @@ import java.util.Objects
 import java.util.Optional
 
 /**
- * Controls how the realtime conversation is truncated prior to model inference. The default is
- * `auto`.
+ * When the number of tokens in a conversation exceeds the model's input token limit, the
+ * conversation be truncated, meaning messages (starting from the oldest) will not be included in
+ * the model's context. A 32k context model with 4,096 max output tokens can only include 28,224
+ * tokens in the context before truncation occurs. Clients can configure truncation behavior to
+ * truncate with a lower max token limit, which is an effective way to control token usage and cost.
+ * Truncation will reduce the number of cached tokens on the next turn (busting the cache), since
+ * messages are dropped from the beginning of the context. However, clients can also configure
+ * truncation to retain messages up to a fraction of the maximum context size, which will reduce the
+ * need for future truncations and thus improve the cache rate. Truncation can be disabled entirely,
+ * which means the server will never truncate but would instead return an error if the conversation
+ * exceeds the model's input token limit.
  */
 @JsonDeserialize(using = RealtimeTruncation.Deserializer::class)
 @JsonSerialize(using = RealtimeTruncation.Serializer::class)