openai 0.68.0 → 0.69.0

data/rbi/openai/models/responses/function_shell_tool.rbi

@@ -16,6 +16,18 @@ module OpenAI
         sig { returns(Symbol) }
         attr_accessor :type
 
+        # The tool invocation context(s).
+        sig do
+          returns(
+            T.nilable(
+              T::Array[
+                OpenAI::Responses::FunctionShellTool::AllowedCaller::OrSymbol
+              ]
+            )
+          )
+        end
+        attr_accessor :allowed_callers
+
         sig do
           returns(
             T.nilable(
@@ -32,6 +44,12 @@ module OpenAI
         # A tool that allows the model to execute shell commands.
         sig do
           params(
+            allowed_callers:
+              T.nilable(
+                T::Array[
+                  OpenAI::Responses::FunctionShellTool::AllowedCaller::OrSymbol
+                ]
+              ),
             environment:
               T.nilable(
                 T.any(
@@ -44,6 +62,8 @@ module OpenAI
           ).returns(T.attached_class)
         end
         def self.new(
+          # The tool invocation context(s).
+          allowed_callers: nil,
           environment: nil,
           # The type of the shell tool. Always `shell`.
           type: :shell
@@ -54,6 +74,12 @@ module OpenAI
           override.returns(
             {
               type: Symbol,
+              allowed_callers:
+                T.nilable(
+                  T::Array[
+                    OpenAI::Responses::FunctionShellTool::AllowedCaller::OrSymbol
+                  ]
+                ),
               environment:
                 T.nilable(
                   T.any(
@@ -68,6 +94,37 @@ module OpenAI
         def to_hash
         end
 
+        module AllowedCaller
+          extend OpenAI::Internal::Type::Enum
+
+          TaggedSymbol =
+            T.type_alias do
+              T.all(Symbol, OpenAI::Responses::FunctionShellTool::AllowedCaller)
+            end
+          OrSymbol = T.type_alias { T.any(Symbol, String) }
+
+          DIRECT =
+            T.let(
+              :direct,
+              OpenAI::Responses::FunctionShellTool::AllowedCaller::TaggedSymbol
+            )
+          PROGRAMMATIC =
+            T.let(
+              :programmatic,
+              OpenAI::Responses::FunctionShellTool::AllowedCaller::TaggedSymbol
+            )
+
+          sig do
+            override.returns(
+              T::Array[
+                OpenAI::Responses::FunctionShellTool::AllowedCaller::TaggedSymbol
+              ]
+            )
+          end
+          def self.values
+          end
+        end
+
         module Environment
           extend OpenAI::Internal::Type::Union
 

data/rbi/openai/models/responses/function_tool.rbi

@@ -17,7 +17,7 @@ module OpenAI
         sig { returns(T.nilable(T::Hash[Symbol, T.anything])) }
         attr_accessor :parameters
 
-        # Whether to enforce strict parameter validation. Default `true`.
+        # Whether strict parameter validation is enforced for this function tool.
         sig { returns(T.nilable(T::Boolean)) }
         attr_accessor :strict
 
@@ -25,6 +25,16 @@ module OpenAI
         sig { returns(Symbol) }
         attr_accessor :type
 
+        # The tool invocation context(s).
+        sig do
+          returns(
+            T.nilable(
+              T::Array[OpenAI::Responses::FunctionTool::AllowedCaller::OrSymbol]
+            )
+          )
+        end
+        attr_accessor :allowed_callers
+
         # Whether this function is deferred and loaded via tool search.
         sig { returns(T.nilable(T::Boolean)) }
         attr_reader :defer_loading
@@ -37,6 +47,11 @@ module OpenAI
         sig { returns(T.nilable(String)) }
         attr_accessor :description
 
+        # A JSON schema object describing the JSON value encoded in string outputs for
+        # this function.
+        sig { returns(T.nilable(T::Hash[Symbol, T.anything])) }
+        attr_accessor :output_schema
+
         # Defines a function in your own code the model can choose to call. Learn more
         # about
         # [function calling](https://platform.openai.com/docs/guides/function-calling).
@@ -45,8 +60,15 @@ module OpenAI
             name: String,
             parameters: T.nilable(T::Hash[Symbol, T.anything]),
             strict: T.nilable(T::Boolean),
+            allowed_callers:
+              T.nilable(
+                T::Array[
+                  OpenAI::Responses::FunctionTool::AllowedCaller::OrSymbol
+                ]
+              ),
             defer_loading: T::Boolean,
             description: T.nilable(String),
+            output_schema: T.nilable(T::Hash[Symbol, T.anything]),
             type: Symbol
           ).returns(T.attached_class)
         end
@@ -55,13 +77,18 @@ module OpenAI
           name:,
           # A JSON schema object describing the parameters of the function.
           parameters:,
-          # Whether to enforce strict parameter validation. Default `true`.
+          # Whether strict parameter validation is enforced for this function tool.
           strict:,
+          # The tool invocation context(s).
+          allowed_callers: nil,
           # Whether this function is deferred and loaded via tool search.
           defer_loading: nil,
           # A description of the function. Used by the model to determine whether or not to
           # call the function.
           description: nil,
+          # A JSON schema object describing the JSON value encoded in string outputs for
+          # this function.
+          output_schema: nil,
           # The type of the function tool. Always `function`.
           type: :function
         )
@@ -74,13 +101,51 @@ module OpenAI
               parameters: T.nilable(T::Hash[Symbol, T.anything]),
               strict: T.nilable(T::Boolean),
               type: Symbol,
+              allowed_callers:
+                T.nilable(
+                  T::Array[
+                    OpenAI::Responses::FunctionTool::AllowedCaller::OrSymbol
+                  ]
+                ),
               defer_loading: T::Boolean,
-              description: T.nilable(String)
+              description: T.nilable(String),
+              output_schema: T.nilable(T::Hash[Symbol, T.anything])
             }
           )
         end
         def to_hash
         end
+
+        module AllowedCaller
+          extend OpenAI::Internal::Type::Enum
+
+          TaggedSymbol =
+            T.type_alias do
+              T.all(Symbol, OpenAI::Responses::FunctionTool::AllowedCaller)
+            end
+          OrSymbol = T.type_alias { T.any(Symbol, String) }
+
+          DIRECT =
+            T.let(
+              :direct,
+              OpenAI::Responses::FunctionTool::AllowedCaller::TaggedSymbol
+            )
+          PROGRAMMATIC =
+            T.let(
+              :programmatic,
+              OpenAI::Responses::FunctionTool::AllowedCaller::TaggedSymbol
+            )
+
+          sig do
+            override.returns(
+              T::Array[
+                OpenAI::Responses::FunctionTool::AllowedCaller::TaggedSymbol
+              ]
+            )
+          end
+          def self.values
+          end
+        end
       end
     end
   end

data/rbi/openai/models/responses/input_token_count_params.rbi

@@ -125,6 +125,7 @@ module OpenAI
                 OpenAI::Responses::ToolChoiceFunction,
                 OpenAI::Responses::ToolChoiceMcp,
                 OpenAI::Responses::ToolChoiceCustom,
+                OpenAI::Responses::InputTokenCountParams::ToolChoice::SpecificProgrammaticToolCallingParam,
                 OpenAI::Responses::ToolChoiceApplyPatch,
                 OpenAI::Responses::ToolChoiceShell
               )
@@ -146,6 +147,7 @@ module OpenAI
                   OpenAI::Responses::ComputerUsePreviewTool,
                   OpenAI::Responses::Tool::Mcp,
                   OpenAI::Responses::Tool::CodeInterpreter,
+                  OpenAI::Responses::Tool::ProgrammaticToolCalling,
                   OpenAI::Responses::Tool::ImageGeneration,
                   OpenAI::Responses::Tool::LocalShell,
                   OpenAI::Responses::FunctionShellTool,
@@ -218,6 +220,7 @@ module OpenAI
                   OpenAI::Responses::ToolChoiceFunction::OrHash,
                   OpenAI::Responses::ToolChoiceMcp::OrHash,
                   OpenAI::Responses::ToolChoiceCustom::OrHash,
+                  OpenAI::Responses::InputTokenCountParams::ToolChoice::SpecificProgrammaticToolCallingParam::OrHash,
                   OpenAI::Responses::ToolChoiceApplyPatch::OrHash,
                   OpenAI::Responses::ToolChoiceShell::OrHash
                 )
@@ -232,6 +235,7 @@ module OpenAI
                     OpenAI::Responses::ComputerUsePreviewTool::OrHash,
                     OpenAI::Responses::Tool::Mcp::OrHash,
                     OpenAI::Responses::Tool::CodeInterpreter::OrHash,
+                    OpenAI::Responses::Tool::ProgrammaticToolCalling::OrHash,
                     OpenAI::Responses::Tool::ImageGeneration::OrHash,
                     OpenAI::Responses::Tool::LocalShell::OrHash,
                     OpenAI::Responses::FunctionShellTool::OrHash,
@@ -334,6 +338,7 @@ module OpenAI
                     OpenAI::Responses::ToolChoiceFunction,
                     OpenAI::Responses::ToolChoiceMcp,
                     OpenAI::Responses::ToolChoiceCustom,
+                    OpenAI::Responses::InputTokenCountParams::ToolChoice::SpecificProgrammaticToolCallingParam,
                     OpenAI::Responses::ToolChoiceApplyPatch,
                     OpenAI::Responses::ToolChoiceShell
                   )
@@ -348,6 +353,7 @@ module OpenAI
                       OpenAI::Responses::ComputerUsePreviewTool,
                       OpenAI::Responses::Tool::Mcp,
                       OpenAI::Responses::Tool::CodeInterpreter,
+                      OpenAI::Responses::Tool::ProgrammaticToolCalling,
                       OpenAI::Responses::Tool::ImageGeneration,
                       OpenAI::Responses::Tool::LocalShell,
                       OpenAI::Responses::FunctionShellTool,
@@ -643,11 +649,37 @@ module OpenAI
                 OpenAI::Responses::ToolChoiceFunction,
                 OpenAI::Responses::ToolChoiceMcp,
                 OpenAI::Responses::ToolChoiceCustom,
+                OpenAI::Responses::InputTokenCountParams::ToolChoice::SpecificProgrammaticToolCallingParam,
                 OpenAI::Responses::ToolChoiceApplyPatch,
                 OpenAI::Responses::ToolChoiceShell
               )
             end
 
+          class SpecificProgrammaticToolCallingParam < OpenAI::Internal::Type::BaseModel
+            OrHash =
+              T.type_alias do
+                T.any(
+                  OpenAI::Responses::InputTokenCountParams::ToolChoice::SpecificProgrammaticToolCallingParam,
+                  OpenAI::Internal::AnyHash
+                )
+              end
+
+            # The tool to call. Always `programmatic_tool_calling`.
+            sig { returns(Symbol) }
+            attr_accessor :type
+
+            sig { params(type: Symbol).returns(T.attached_class) }
+            def self.new(
+              # The tool to call. Always `programmatic_tool_calling`.
+              type: :programmatic_tool_calling
+            )
+            end
+
+            sig { override.returns({ type: Symbol }) }
+            def to_hash
+            end
+          end
+
           sig do
             override.returns(
               T::Array[

data/rbi/openai/models/responses/namespace_tool.rbi

@@ -107,6 +107,18 @@ module OpenAI
             sig { returns(Symbol) }
             attr_accessor :type
 
+            # The tool invocation context(s).
+            sig do
+              returns(
+                T.nilable(
+                  T::Array[
+                    OpenAI::Responses::NamespaceTool::Tool::Function::AllowedCaller::OrSymbol
+                  ]
+                )
+              )
+            end
+            attr_accessor :allowed_callers
+
             # Whether this function should be deferred and discovered via tool search.
             sig { returns(T.nilable(T::Boolean)) }
             attr_reader :defer_loading
@@ -117,17 +129,32 @@ module OpenAI
             sig { returns(T.nilable(String)) }
             attr_accessor :description
 
+            # A JSON Schema describing the JSON value encoded in string outputs for this
+            # function tool. This does not describe content-array outputs.
+            sig { returns(T.nilable(T::Hash[Symbol, T.anything])) }
+            attr_accessor :output_schema
+
             sig { returns(T.nilable(T.anything)) }
             attr_accessor :parameters
 
+            # Whether to enforce strict parameter validation. If omitted, Responses attempts
+            # to use strict validation when the schema is compatible, and falls back to
+            # non-strict validation otherwise.
             sig { returns(T.nilable(T::Boolean)) }
             attr_accessor :strict
 
             sig do
               params(
                 name: String,
+                allowed_callers:
+                  T.nilable(
+                    T::Array[
+                      OpenAI::Responses::NamespaceTool::Tool::Function::AllowedCaller::OrSymbol
+                    ]
+                  ),
                 defer_loading: T::Boolean,
                 description: T.nilable(String),
+                output_schema: T.nilable(T::Hash[Symbol, T.anything]),
                 parameters: T.nilable(T.anything),
                 strict: T.nilable(T::Boolean),
                 type: Symbol
@@ -135,10 +162,18 @@ module OpenAI
             end
             def self.new(
               name:,
+              # The tool invocation context(s).
+              allowed_callers: nil,
               # Whether this function should be deferred and discovered via tool search.
               defer_loading: nil,
               description: nil,
+              # A JSON Schema describing the JSON value encoded in string outputs for this
+              # function tool. This does not describe content-array outputs.
+              output_schema: nil,
               parameters: nil,
+              # Whether to enforce strict parameter validation. If omitted, Responses attempts
+              # to use strict validation when the schema is compatible, and falls back to
+              # non-strict validation otherwise.
               strict: nil,
               type: :function
             )
@@ -149,8 +184,15 @@ module OpenAI
                 {
                   name: String,
                   type: Symbol,
+                  allowed_callers:
+                    T.nilable(
+                      T::Array[
+                        OpenAI::Responses::NamespaceTool::Tool::Function::AllowedCaller::OrSymbol
+                      ]
+                    ),
                   defer_loading: T::Boolean,
                   description: T.nilable(String),
+                  output_schema: T.nilable(T::Hash[Symbol, T.anything]),
                   parameters: T.nilable(T.anything),
                   strict: T.nilable(T::Boolean)
                 }
@@ -158,6 +200,40 @@ module OpenAI
             end
             def to_hash
             end
+
+            module AllowedCaller
+              extend OpenAI::Internal::Type::Enum
+
+              TaggedSymbol =
+                T.type_alias do
+                  T.all(
+                    Symbol,
+                    OpenAI::Responses::NamespaceTool::Tool::Function::AllowedCaller
+                  )
+                end
+              OrSymbol = T.type_alias { T.any(Symbol, String) }
+
+              DIRECT =
+                T.let(
+                  :direct,
+                  OpenAI::Responses::NamespaceTool::Tool::Function::AllowedCaller::TaggedSymbol
+                )
+              PROGRAMMATIC =
+                T.let(
+                  :programmatic,
+                  OpenAI::Responses::NamespaceTool::Tool::Function::AllowedCaller::TaggedSymbol
+                )
+
+              sig do
+                override.returns(
+                  T::Array[
+                    OpenAI::Responses::NamespaceTool::Tool::Function::AllowedCaller::TaggedSymbol
+                  ]
+                )
+              end
+              def self.values
+              end
+            end
           end
 
           sig do

data/rbi/openai/models/responses/response.rbi

@@ -211,11 +211,31 @@ module OpenAI
         sig { params(prompt_cache_key: String).void }
         attr_writer :prompt_cache_key
 
+        # The prompt-caching options that were applied to the response. Supported for
+        # `gpt-5.6` and later models.
+        sig do
+          returns(T.nilable(OpenAI::Responses::Response::PromptCacheOptions))
+        end
+        attr_reader :prompt_cache_options
+
+        sig do
+          params(
+            prompt_cache_options:
+              OpenAI::Responses::Response::PromptCacheOptions::OrHash
+          ).void
+        end
+        attr_writer :prompt_cache_options
+
+        # Deprecated. Use `prompt_cache_options.ttl` instead.
+        #
         # The retention policy for the prompt cache. Set to `24h` to enable extended
         # prompt caching, which keeps cached prefixes active for longer, up to a maximum
         # of 24 hours.
         # [Learn more](https://platform.openai.com/docs/guides/prompt-caching#prompt-cache-retention).
-        # For `gpt-5.5`, `gpt-5.5-pro`, and future models, only `24h` is supported.
+        # This field expresses a maximum retention policy, while
+        # `prompt_cache_options.ttl` expresses a minimum cache lifetime. The two fields
+        # are independent and do not interact. For `gpt-5.5`, `gpt-5.5-pro`, and future
+        # models, only `24h` is supported.
         #
         # For older models that support both `in_memory` and `24h`, the default depends on
         # your organization's data retention policy:
@@ -364,6 +384,8 @@ module OpenAI
                   OpenAI::Responses::ResponseComputerToolCall::OrHash,
                   OpenAI::Responses::ResponseComputerToolCallOutputItem::OrHash,
                   OpenAI::Responses::ResponseReasoningItem::OrHash,
+                  OpenAI::Responses::ResponseOutputItem::Program::OrHash,
+                  OpenAI::Responses::ResponseOutputItem::ProgramOutput::OrHash,
                   OpenAI::Responses::ResponseToolSearchCall::OrHash,
                   OpenAI::Responses::ResponseToolSearchOutputItem::OrHash,
                   OpenAI::Responses::ResponseOutputItem::AdditionalTools::OrHash,
@@ -394,6 +416,7 @@ module OpenAI
                 OpenAI::Responses::ToolChoiceFunction::OrHash,
                 OpenAI::Responses::ToolChoiceMcp::OrHash,
                 OpenAI::Responses::ToolChoiceCustom::OrHash,
+                OpenAI::Responses::Response::ToolChoice::SpecificProgrammaticToolCallingParam::OrHash,
                 OpenAI::Responses::ToolChoiceApplyPatch::OrHash,
                 OpenAI::Responses::ToolChoiceShell::OrHash
               ),
@@ -406,6 +429,7 @@ module OpenAI
                   OpenAI::Responses::ComputerUsePreviewTool::OrHash,
                   OpenAI::Responses::Tool::Mcp::OrHash,
                   OpenAI::Responses::Tool::CodeInterpreter::OrHash,
+                  OpenAI::Responses::Tool::ProgrammaticToolCalling::OrHash,
                   OpenAI::Responses::Tool::ImageGeneration::OrHash,
                   OpenAI::Responses::Tool::LocalShell::OrHash,
                   OpenAI::Responses::FunctionShellTool::OrHash,
@@ -429,6 +453,8 @@ module OpenAI
             previous_response_id: T.nilable(String),
             prompt: T.nilable(OpenAI::Responses::ResponsePrompt::OrHash),
             prompt_cache_key: String,
+            prompt_cache_options:
+              OpenAI::Responses::Response::PromptCacheOptions::OrHash,
             prompt_cache_retention:
               T.nilable(
                 OpenAI::Responses::Response::PromptCacheRetention::OrSymbol
@@ -553,11 +579,19 @@ module OpenAI
           # hit rates. Replaces the `user` field.
           # [Learn more](https://platform.openai.com/docs/guides/prompt-caching).
           prompt_cache_key: nil,
+          # The prompt-caching options that were applied to the response. Supported for
+          # `gpt-5.6` and later models.
+          prompt_cache_options: nil,
+          # Deprecated. Use `prompt_cache_options.ttl` instead.
+          #
           # The retention policy for the prompt cache. Set to `24h` to enable extended
           # prompt caching, which keeps cached prefixes active for longer, up to a maximum
           # of 24 hours.
           # [Learn more](https://platform.openai.com/docs/guides/prompt-caching#prompt-cache-retention).
-          # For `gpt-5.5`, `gpt-5.5-pro`, and future models, only `24h` is supported.
+          # This field expresses a maximum retention policy, while
+          # `prompt_cache_options.ttl` expresses a minimum cache lifetime. The two fields
+          # are independent and do not interact. For `gpt-5.5`, `gpt-5.5-pro`, and future
+          # models, only `24h` is supported.
           #
           # For older models that support both `in_memory` and `24h`, the default depends on
           # your organization's data retention policy:
@@ -659,6 +693,8 @@ module OpenAI
               previous_response_id: T.nilable(String),
               prompt: T.nilable(OpenAI::Responses::ResponsePrompt),
               prompt_cache_key: String,
+              prompt_cache_options:
+                OpenAI::Responses::Response::PromptCacheOptions,
               prompt_cache_retention:
                 T.nilable(
                   OpenAI::Responses::Response::PromptCacheRetention::TaggedSymbol
@@ -819,11 +855,37 @@ module OpenAI
                 OpenAI::Responses::ToolChoiceFunction,
                 OpenAI::Responses::ToolChoiceMcp,
                 OpenAI::Responses::ToolChoiceCustom,
+                OpenAI::Responses::Response::ToolChoice::SpecificProgrammaticToolCallingParam,
                 OpenAI::Responses::ToolChoiceApplyPatch,
                 OpenAI::Responses::ToolChoiceShell
               )
             end
 
+          class SpecificProgrammaticToolCallingParam < OpenAI::Internal::Type::BaseModel
+            OrHash =
+              T.type_alias do
+                T.any(
+                  OpenAI::Responses::Response::ToolChoice::SpecificProgrammaticToolCallingParam,
+                  OpenAI::Internal::AnyHash
+                )
+              end
+
+            # The tool to call. Always `programmatic_tool_calling`.
+            sig { returns(Symbol) }
+            attr_accessor :type
+
+            sig { params(type: Symbol).returns(T.attached_class) }
+            def self.new(
+              # The tool to call. Always `programmatic_tool_calling`.
+              type: :programmatic_tool_calling
+            )
+            end
+
+            sig { override.returns({ type: Symbol }) }
+            def to_hash
+            end
+          end
+
           sig do
             override.returns(
               T::Array[OpenAI::Responses::Response::ToolChoice::Variants]
@@ -1326,11 +1388,138 @@ module OpenAI
           end
         end
 
+        class PromptCacheOptions < OpenAI::Internal::Type::BaseModel
+          OrHash =
+            T.type_alias do
+              T.any(
+                OpenAI::Responses::Response::PromptCacheOptions,
+                OpenAI::Internal::AnyHash
+              )
+            end
+
+          # Whether implicit prompt-cache breakpoints were enabled.
+          sig do
+            returns(
+              OpenAI::Responses::Response::PromptCacheOptions::Mode::TaggedSymbol
+            )
+          end
+          attr_accessor :mode
+
+          # The minimum lifetime applied to each cache breakpoint.
+          sig do
+            returns(
+              OpenAI::Responses::Response::PromptCacheOptions::Ttl::TaggedSymbol
+            )
+          end
+          attr_accessor :ttl
+
+          # The prompt-caching options that were applied to the response. Supported for
+          # `gpt-5.6` and later models.
+          sig do
+            params(
+              mode:
+                OpenAI::Responses::Response::PromptCacheOptions::Mode::OrSymbol,
+              ttl:
+                OpenAI::Responses::Response::PromptCacheOptions::Ttl::OrSymbol
+            ).returns(T.attached_class)
+          end
+          def self.new(
+            # Whether implicit prompt-cache breakpoints were enabled.
+            mode:,
+            # The minimum lifetime applied to each cache breakpoint.
+            ttl:
+          )
+          end
+
+          sig do
+            override.returns(
+              {
+                mode:
+                  OpenAI::Responses::Response::PromptCacheOptions::Mode::TaggedSymbol,
+                ttl:
+                  OpenAI::Responses::Response::PromptCacheOptions::Ttl::TaggedSymbol
+              }
+            )
+          end
+          def to_hash
+          end
+
+          # Whether implicit prompt-cache breakpoints were enabled.
+          module Mode
+            extend OpenAI::Internal::Type::Enum
+
+            TaggedSymbol =
+              T.type_alias do
+                T.all(
+                  Symbol,
+                  OpenAI::Responses::Response::PromptCacheOptions::Mode
+                )
+              end
+            OrSymbol = T.type_alias { T.any(Symbol, String) }
+
+            IMPLICIT =
+              T.let(
+                :implicit,
+                OpenAI::Responses::Response::PromptCacheOptions::Mode::TaggedSymbol
+              )
+            EXPLICIT =
+              T.let(
+                :explicit,
+                OpenAI::Responses::Response::PromptCacheOptions::Mode::TaggedSymbol
+              )
+
+            sig do
+              override.returns(
+                T::Array[
+                  OpenAI::Responses::Response::PromptCacheOptions::Mode::TaggedSymbol
+                ]
+              )
+            end
+            def self.values
+            end
+          end
+
+          # The minimum lifetime applied to each cache breakpoint.
+          module Ttl
+            extend OpenAI::Internal::Type::Enum
+
+            TaggedSymbol =
+              T.type_alias do
+                T.all(
+                  Symbol,
+                  OpenAI::Responses::Response::PromptCacheOptions::Ttl
+                )
+              end
+            OrSymbol = T.type_alias { T.any(Symbol, String) }
+
+            TTL_30M =
+              T.let(
+                :"30m",
+                OpenAI::Responses::Response::PromptCacheOptions::Ttl::TaggedSymbol
+              )
+
+            sig do
+              override.returns(
+                T::Array[
+                  OpenAI::Responses::Response::PromptCacheOptions::Ttl::TaggedSymbol
+                ]
+              )
+            end
+            def self.values
+            end
+          end
+        end
+
+        # Deprecated. Use `prompt_cache_options.ttl` instead.
+        #
         # The retention policy for the prompt cache. Set to `24h` to enable extended
         # prompt caching, which keeps cached prefixes active for longer, up to a maximum
         # of 24 hours.
         # [Learn more](https://platform.openai.com/docs/guides/prompt-caching#prompt-cache-retention).
-        # For `gpt-5.5`, `gpt-5.5-pro`, and future models, only `24h` is supported.
+        # This field expresses a maximum retention policy, while
+        # `prompt_cache_options.ttl` expresses a minimum cache lifetime. The two fields
+        # are independent and do not interact. For `gpt-5.5`, `gpt-5.5-pro`, and future
+        # models, only `24h` is supported.
         #
         # For older models that support both `in_memory` and `24h`, the default depends on
         # your organization's data retention policy: