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

lib/openai/models/custom_tool_input_format.rb

@@ -8,8 +8,10 @@ module CustomToolInputFormat
 
       discriminator :type
 
+      # Unconstrained free-form text.
       variant :text, -> { OpenAI::CustomToolInputFormat::Text }
 
+      # A grammar defined by the user.
       variant :grammar, -> { OpenAI::CustomToolInputFormat::Grammar }
 
       class Text < OpenAI::Internal::Type::BaseModel
@@ -20,6 +22,8 @@ class Text < OpenAI::Internal::Type::BaseModel
         required :type, const: :text
 
         # @!method initialize(type: :text)
+        #   Unconstrained free-form text.
+        #
         #   @param type [Symbol, :text] Unconstrained text format. Always `text`.
       end
 
@@ -43,6 +47,8 @@ class Grammar < OpenAI::Internal::Type::BaseModel
         required :type, const: :grammar
 
         # @!method initialize(definition:, syntax:, type: :grammar)
+        #   A grammar defined by the user.
+        #
         #   @param definition [String] The grammar definition.
         #
         #   @param syntax [Symbol, OpenAI::Models::CustomToolInputFormat::Grammar::Syntax] The syntax of the grammar definition. One of `lark` or `regex`.

lib/openai/models/image_edit_params.rb

@@ -142,7 +142,7 @@ class ImageEditParams < OpenAI::Internal::Type::BaseModel
       #
       #   @param background [Symbol, OpenAI::Models::ImageEditParams::Background, nil] Allows to set transparency for the background of the generated image(s).
       #
-      #   @param input_fidelity [Symbol, OpenAI::Models::ImageEditParams::InputFidelity, nil]
+      #   @param input_fidelity [Symbol, OpenAI::Models::ImageEditParams::InputFidelity, nil] Control how much effort the model will exert to match the style and features, es
       #
       #   @param mask [Pathname, StringIO, IO, String, OpenAI::FilePart] An additional image whose fully transparent areas (e.g. where alpha is zero) ind
       #

lib/openai/models/realtime/realtime_session_create_request.rb

@@ -98,8 +98,19 @@ class RealtimeSessionCreateRequest < OpenAI::Internal::Type::BaseModel
         optional :tracing, union: -> { OpenAI::Realtime::RealtimeTracingConfig }, nil?: true
 
         # @!attribute truncation
-        #   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.
         #
         #   @return [Symbol, OpenAI::Models::Realtime::RealtimeTruncation::RealtimeTruncationStrategy, OpenAI::Models::Realtime::RealtimeTruncationRetentionRatio, nil]
         optional :truncation, union: -> { OpenAI::Realtime::RealtimeTruncation }
@@ -130,7 +141,7 @@ class RealtimeSessionCreateRequest < OpenAI::Internal::Type::BaseModel
         #
         #   @param tracing [Symbol, :auto, OpenAI::Models::Realtime::RealtimeTracingConfig::TracingConfiguration, nil] Realtime API can write session traces to the [Traces Dashboard](/logs?api=traces
         #
-        #   @param truncation [Symbol, OpenAI::Models::Realtime::RealtimeTruncation::RealtimeTruncationStrategy, OpenAI::Models::Realtime::RealtimeTruncationRetentionRatio] Controls how the realtime conversation is truncated prior to model inference.
+        #   @param truncation [Symbol, OpenAI::Models::Realtime::RealtimeTruncation::RealtimeTruncationStrategy, OpenAI::Models::Realtime::RealtimeTruncationRetentionRatio] When the number of tokens in a conversation exceeds the model's input token limi
         #
         #   @param type [Symbol, :realtime] The type of session to create. Always `realtime` for the Realtime API.
 

lib/openai/models/realtime/realtime_session_create_response.rb

@@ -106,8 +106,19 @@ class RealtimeSessionCreateResponse < OpenAI::Internal::Type::BaseModel
         optional :tracing, union: -> { OpenAI::Realtime::RealtimeSessionCreateResponse::Tracing }, nil?: true
 
         # @!attribute truncation
-        #   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.
         #
         #   @return [Symbol, OpenAI::Models::Realtime::RealtimeTruncation::RealtimeTruncationStrategy, OpenAI::Models::Realtime::RealtimeTruncationRetentionRatio, nil]
         optional :truncation, union: -> { OpenAI::Realtime::RealtimeTruncation }
@@ -141,7 +152,7 @@ class RealtimeSessionCreateResponse < OpenAI::Internal::Type::BaseModel
         #
         #   @param tracing [Symbol, :auto, OpenAI::Models::Realtime::RealtimeSessionCreateResponse::Tracing::TracingConfiguration, nil] Realtime API can write session traces to the [Traces Dashboard](/logs?api=traces
         #
-        #   @param truncation [Symbol, OpenAI::Models::Realtime::RealtimeTruncation::RealtimeTruncationStrategy, OpenAI::Models::Realtime::RealtimeTruncationRetentionRatio] Controls how the realtime conversation is truncated prior to model inference.
+        #   @param truncation [Symbol, OpenAI::Models::Realtime::RealtimeTruncation::RealtimeTruncationStrategy, OpenAI::Models::Realtime::RealtimeTruncationRetentionRatio] When the number of tokens in a conversation exceeds the model's input token limi
         #
         #   @param type [Symbol, :realtime] The type of session to create. Always `realtime` for the Realtime API.
 

lib/openai/models/realtime/realtime_truncation.rb

@@ -3,8 +3,19 @@
 module OpenAI
   module Models
     module Realtime
-      # 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.
       module RealtimeTruncation
         extend OpenAI::Internal::Type::Union
 

lib/openai/models/realtime/realtime_truncation_retention_ratio.rb

@@ -5,8 +5,10 @@ module Models
     module Realtime
       class RealtimeTruncationRetentionRatio < OpenAI::Internal::Type::BaseModel
         # @!attribute retention_ratio
-        #   Fraction of post-instruction conversation tokens to retain (0.0 - 1.0) when the
-        #   conversation exceeds the input token limit.
+        #   Fraction of post-instruction conversation tokens to retain (`0.0` - `1.0`) when
+        #   the conversation exceeds the input token limit. Setting this to `0.8` means that
+        #   messages will be dropped until 80% of the maximum allowed tokens are used. This
+        #   helps reduce the frequency of truncations and improve cache rates.
         #
         #   @return [Float]
         required :retention_ratio, Float
@@ -17,17 +19,49 @@ class RealtimeTruncationRetentionRatio < OpenAI::Internal::Type::BaseModel
         #   @return [Symbol, :retention_ratio]
         required :type, const: :retention_ratio
 
-        # @!method initialize(retention_ratio:, type: :retention_ratio)
+        # @!attribute token_limits
+        #   Optional custom token limits for this truncation strategy. If not provided, the
+        #   model's default token limits will be used.
+        #
+        #   @return [OpenAI::Models::Realtime::RealtimeTruncationRetentionRatio::TokenLimits, nil]
+        optional :token_limits, -> { OpenAI::Realtime::RealtimeTruncationRetentionRatio::TokenLimits }
+
+        # @!method initialize(retention_ratio:, token_limits: nil, type: :retention_ratio)
         #   Some parameter documentations has been truncated, see
         #   {OpenAI::Models::Realtime::RealtimeTruncationRetentionRatio} for more details.
         #
         #   Retain a fraction of the conversation tokens when the conversation exceeds the
         #   input token limit. This allows you to amortize truncations across multiple
         #   turns, which can help improve cached token usage.
         #
-        #   @param retention_ratio [Float] Fraction of post-instruction conversation tokens to retain (0.0 - 1.0) when the
+        #   @param retention_ratio [Float] Fraction of post-instruction conversation tokens to retain (`0.0` - `1.0`) when
+        #
+        #   @param token_limits [OpenAI::Models::Realtime::RealtimeTruncationRetentionRatio::TokenLimits] Optional custom token limits for this truncation strategy. If not provided, the
         #
         #   @param type [Symbol, :retention_ratio] Use retention ratio truncation.
+
+        # @see OpenAI::Models::Realtime::RealtimeTruncationRetentionRatio#token_limits
+        class TokenLimits < OpenAI::Internal::Type::BaseModel
+          # @!attribute post_instructions
+          #   Maximum tokens allowed in the conversation after instructions (which including
+          #   tool definitions). For example, setting this to 5,000 would mean that truncation
+          #   would occur when the conversation exceeds 5,000 tokens after instructions. This
+          #   cannot be higher than the model's context window size minus the maximum output
+          #   tokens.
+          #
+          #   @return [Integer, nil]
+          optional :post_instructions, Integer
+
+          # @!method initialize(post_instructions: nil)
+          #   Some parameter documentations has been truncated, see
+          #   {OpenAI::Models::Realtime::RealtimeTruncationRetentionRatio::TokenLimits} for
+          #   more details.
+          #
+          #   Optional custom token limits for this truncation strategy. If not provided, the
+          #   model's default token limits will be used.
+          #
+          #   @param post_instructions [Integer] Maximum tokens allowed in the conversation after instructions (which including t
+        end
       end
     end
   end

lib/openai/models/responses/file_search_tool.rb

@@ -71,6 +71,13 @@ module Filters
 
         # @see OpenAI::Models::Responses::FileSearchTool#ranking_options
         class RankingOptions < OpenAI::Internal::Type::BaseModel
+          # @!attribute hybrid_search
+          #   Weights that control how reciprocal rank fusion balances semantic embedding
+          #   matches versus sparse keyword matches when hybrid search is enabled.
+          #
+          #   @return [OpenAI::Models::Responses::FileSearchTool::RankingOptions::HybridSearch, nil]
+          optional :hybrid_search, -> { OpenAI::Responses::FileSearchTool::RankingOptions::HybridSearch }
+
           # @!attribute ranker
           #   The ranker to use for the file search.
           #
@@ -85,16 +92,41 @@ class RankingOptions < OpenAI::Internal::Type::BaseModel
           #   @return [Float, nil]
           optional :score_threshold, Float
 
-          # @!method initialize(ranker: nil, score_threshold: nil)
+          # @!method initialize(hybrid_search: nil, ranker: nil, score_threshold: nil)
           #   Some parameter documentations has been truncated, see
           #   {OpenAI::Models::Responses::FileSearchTool::RankingOptions} for more details.
           #
           #   Ranking options for search.
           #
+          #   @param hybrid_search [OpenAI::Models::Responses::FileSearchTool::RankingOptions::HybridSearch] Weights that control how reciprocal rank fusion balances semantic embedding matc
+          #
           #   @param ranker [Symbol, OpenAI::Models::Responses::FileSearchTool::RankingOptions::Ranker] The ranker to use for the file search.
           #
           #   @param score_threshold [Float] The score threshold for the file search, a number between 0 and 1. Numbers close
 
+          # @see OpenAI::Models::Responses::FileSearchTool::RankingOptions#hybrid_search
+          class HybridSearch < OpenAI::Internal::Type::BaseModel
+            # @!attribute embedding_weight
+            #   The weight of the embedding in the reciprocal ranking fusion.
+            #
+            #   @return [Float]
+            required :embedding_weight, Float
+
+            # @!attribute text_weight
+            #   The weight of the text in the reciprocal ranking fusion.
+            #
+            #   @return [Float]
+            required :text_weight, Float
+
+            # @!method initialize(embedding_weight:, text_weight:)
+            #   Weights that control how reciprocal rank fusion balances semantic embedding
+            #   matches versus sparse keyword matches when hybrid search is enabled.
+            #
+            #   @param embedding_weight [Float] The weight of the embedding in the reciprocal ranking fusion.
+            #
+            #   @param text_weight [Float] The weight of the text in the reciprocal ranking fusion.
+          end
+
           # The ranker to use for the file search.
           #
           # @see OpenAI::Models::Responses::FileSearchTool::RankingOptions#ranker

lib/openai/models/responses/response_output_text.rb

@@ -11,6 +11,11 @@ class ResponseOutputText < OpenAI::Internal::Type::BaseModel
         required :annotations,
                  -> { OpenAI::Internal::Type::ArrayOf[union: OpenAI::Responses::ResponseOutputText::Annotation] }
 
+        # @!attribute logprobs
+        #
+        #   @return [Array<OpenAI::Models::Responses::ResponseOutputText::Logprob>]
+        required :logprobs, -> { OpenAI::Internal::Type::ArrayOf[OpenAI::Responses::ResponseOutputText::Logprob] }
+
         # @!attribute text
         #   The text output from the model.
         #
@@ -31,20 +36,15 @@ class ResponseOutputText < OpenAI::Internal::Type::BaseModel
         #   @return [Symbol, :output_text]
         required :type, const: :output_text
 
-        # @!attribute logprobs
-        #
-        #   @return [Array<OpenAI::Models::Responses::ResponseOutputText::Logprob>, nil]
-        optional :logprobs, -> { OpenAI::Internal::Type::ArrayOf[OpenAI::Responses::ResponseOutputText::Logprob] }
-
-        # @!method initialize(annotations:, text:, logprobs: nil, type: :output_text)
+        # @!method initialize(annotations:, logprobs:, text:, type: :output_text)
         #   A text output from the model.
         #
         #   @param annotations [Array<OpenAI::Models::Responses::ResponseOutputText::Annotation::FileCitation, OpenAI::Models::Responses::ResponseOutputText::Annotation::URLCitation, OpenAI::Models::Responses::ResponseOutputText::Annotation::ContainerFileCitation, OpenAI::Models::Responses::ResponseOutputText::Annotation::FilePath>] The annotations of the text output.
         #
-        #   @param text [String] The text output from the model.
-        #
         #   @param logprobs [Array<OpenAI::Models::Responses::ResponseOutputText::Logprob>]
         #
+        #   @param text [String] The text output from the model.
+        #
         #   @param type [Symbol, :output_text] The type of the output text. Always `output_text`.
 
         # A citation to a file.