openai 0.92.0 → 0.93.0

data/sig/openai/models/beta/beta_responses_client_event.rbs

@@ -50,102 +50,593 @@ module OpenAI
           }
 
         class ResponseCreate < OpenAI::Internal::Type::BaseModel
+          # The type of the client event. Always `response.create`.
           attr_accessor type: :"response.create"
 
+          # Whether to run the model response in the background.
+          # [Learn more](https://developers.openai.com/api/docs/guides/background).
           attr_accessor background: bool?
 
+          # Context management configuration for this request.
           attr_accessor context_management: ::Array[OpenAI::Beta::BetaResponsesClientEvent::ResponseCreate::ContextManagement]?
 
+          # The conversation that this response belongs to. Items from this conversation are
+          # prepended to `input_items` for this response request. Input items and output
+          # items from this response are automatically added to this conversation after this
+          # response completes.
           attr_accessor conversation: OpenAI::Models::Beta::BetaResponsesClientEvent::ResponseCreate::conversation?
 
+          # Specify additional output data to include in the model response. Currently
+          # supported values are:
+          #
+          # - `web_search_call.action.sources`: Include the sources of the web search tool
+          #   call.
+          # - `code_interpreter_call.outputs`: Includes the outputs of python code execution
+          #   in code interpreter tool call items.
+          # - `computer_call_output.output.image_url`: Include image urls from the computer
+          #   call output.
+          # - `file_search_call.results`: Include the search results of the file search tool
+          #   call.
+          # - `message.input_image.image_url`: Include image urls from the input message.
+          # - `message.output_text.logprobs`: Include logprobs with assistant messages.
+          # - `reasoning.encrypted_content`: Includes an encrypted version of reasoning
+          #   tokens in reasoning item outputs. This enables reasoning items to be used in
+          #   multi-turn conversations when using the Responses API statelessly (like when
+          #   the `store` parameter is set to `false`, or when an organization is enrolled
+          #   in the zero data retention program).
           attr_accessor include: ::Array[OpenAI::Models::Beta::beta_response_includable]?
 
+          # Text, image, or file inputs to the model, used to generate a response.
+          #
+          # Learn more:
+          #
+          # - [Text inputs and outputs](https://developers.openai.com/api/docs/guides/text)
+          # - [Image inputs](https://developers.openai.com/api/docs/guides/images-vision)
+          # - [File inputs](https://developers.openai.com/api/docs/guides/file-inputs)
+          # - [Conversation state](https://developers.openai.com/api/docs/guides/conversation-state)
+          # - [Function calling](https://developers.openai.com/api/docs/guides/function-calling)
           attr_reader input: OpenAI::Models::Beta::BetaResponsesClientEvent::ResponseCreate::input?
 
+          # Text, image, or file inputs to the model, used to generate a response.
+          #
+          # Learn more:
+          #
+          # - [Text inputs and outputs](https://developers.openai.com/api/docs/guides/text)
+          # - [Image inputs](https://developers.openai.com/api/docs/guides/images-vision)
+          # - [File inputs](https://developers.openai.com/api/docs/guides/file-inputs)
+          # - [Conversation state](https://developers.openai.com/api/docs/guides/conversation-state)
+          # - [Function calling](https://developers.openai.com/api/docs/guides/function-calling)
           def input=: (
             OpenAI::Models::Beta::BetaResponsesClientEvent::ResponseCreate::input
           ) -> OpenAI::Models::Beta::BetaResponsesClientEvent::ResponseCreate::input
 
+          # A system (or developer) message inserted into the model's context.
+          #
+          # When using along with `previous_response_id`, the instructions from a previous
+          # response will not be carried over to the next response. This makes it simple to
+          # swap out system (or developer) messages in new responses.
           attr_accessor instructions: String?
 
+          # An upper bound for the number of tokens that can be generated for a response,
+          # including visible output tokens and
+          # [reasoning tokens](https://developers.openai.com/api/docs/guides/reasoning).
           attr_accessor max_output_tokens: Integer?
 
+          # The maximum number of total calls to built-in tools that can be processed in a
+          # response. This maximum number applies across all built-in tool calls, not per
+          # individual tool. Any further attempts to call a tool by the model will be
+          # ignored.
           attr_accessor max_tool_calls: Integer?
 
+          # Set of 16 key-value pairs that can be attached to an object. This can be useful
+          # for storing additional information about the object in a structured format, and
+          # querying for objects via API or the dashboard.
+          #
+          # Keys are strings with a maximum length of 64 characters. Values are strings with
+          # a maximum length of 512 characters.
           attr_accessor metadata: ::Hash[Symbol, String]?
 
+          # Model ID used to generate the response, like `gpt-6-astra`. OpenAI offers a wide
+          # range of models with different capabilities, performance characteristics, and
+          # price points. Refer to the
+          # [model guide](https://developers.openai.com/api/docs/models) to browse and
+          # compare available models.
           attr_reader model: OpenAI::Models::Beta::BetaResponsesClientEvent::ResponseCreate::model?
 
+          # Model ID used to generate the response, like `gpt-6-astra`. OpenAI offers a wide
+          # range of models with different capabilities, performance characteristics, and
+          # price points. Refer to the
+          # [model guide](https://developers.openai.com/api/docs/models) to browse and
+          # compare available models.
           def model=: (
             OpenAI::Models::Beta::BetaResponsesClientEvent::ResponseCreate::model
           ) -> OpenAI::Models::Beta::BetaResponsesClientEvent::ResponseCreate::model
 
+          # Configuration for running moderation on the input and output of this response.
           attr_accessor moderation: OpenAI::Beta::BetaResponsesClientEvent::ResponseCreate::Moderation?
 
+          # Configuration for server-hosted multi-agent execution.
           attr_accessor multi_agent: OpenAI::Beta::BetaResponsesClientEvent::ResponseCreate::MultiAgent?
 
+          # Whether to allow the model to run tool calls in parallel.
           attr_accessor parallel_tool_calls: bool?
 
+          # The unique ID of the previous response to the model. Use this to create
+          # multi-turn conversations. Learn more about
+          # [conversation state](https://developers.openai.com/api/docs/guides/conversation-state).
+          # Cannot be used in conjunction with `conversation`.
           attr_accessor previous_response_id: String?
 
+          # Reference to a prompt template and its variables.
+          # [Learn more](https://developers.openai.com/api/docs/guides/text?api-mode=responses#version-prompts-in-code).
           attr_accessor prompt: OpenAI::Beta::BetaResponsePrompt?
 
+          # Used by OpenAI to cache responses for similar requests to optimize your cache
+          # hit rates. Replaces the `user` field.
+          # [Learn more](https://developers.openai.com/api/docs/guides/prompt-caching).
           attr_accessor prompt_cache_key: String?
 
+          # Options for prompt caching. Supported for `gpt-5.6` and later models. By
+          # default, OpenAI automatically chooses one implicit cache breakpoint. You can add
+          # explicit breakpoints to content blocks with `prompt_cache_breakpoint`. Each
+          # request can write up to four breakpoints. For cache matching, OpenAI considers
+          # up to the latest 80 breakpoints in the conversation, without a content-block
+          # lookback limit. Set `mode` to `explicit` to disable the implicit breakpoint. The
+          # `ttl` defaults to `30m`, which is currently the only supported value. See the
+          # [prompt caching guide](https://developers.openai.com/api/docs/guides/prompt-caching)
+          # for current details.
           attr_reader prompt_cache_options: OpenAI::Beta::BetaResponsesClientEvent::ResponseCreate::PromptCacheOptions?
 
+          # Options for prompt caching. Supported for `gpt-5.6` and later models. By
+          # default, OpenAI automatically chooses one implicit cache breakpoint. You can add
+          # explicit breakpoints to content blocks with `prompt_cache_breakpoint`. Each
+          # request can write up to four breakpoints. For cache matching, OpenAI considers
+          # up to the latest 80 breakpoints in the conversation, without a content-block
+          # lookback limit. Set `mode` to `explicit` to disable the implicit breakpoint. The
+          # `ttl` defaults to `30m`, which is currently the only supported value. See the
+          # [prompt caching guide](https://developers.openai.com/api/docs/guides/prompt-caching)
+          # for current details.
           def prompt_cache_options=: (
             OpenAI::Beta::BetaResponsesClientEvent::ResponseCreate::PromptCacheOptions
           ) -> OpenAI::Beta::BetaResponsesClientEvent::ResponseCreate::PromptCacheOptions
 
+          # 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://developers.openai.com/api/docs/guides/prompt-caching#prompt-cache-retention).
+          # 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:
+          #
+          # - Organizations without ZDR enabled default to `24h`.
+          # - Organizations with ZDR enabled default to `in_memory` when
+          #   `prompt_cache_retention` is not specified.
           attr_accessor prompt_cache_retention: OpenAI::Models::Beta::BetaResponsesClientEvent::ResponseCreate::prompt_cache_retention?
 
+          # Configuration options for
+          # [reasoning models](https://developers.openai.com/api/docs/guides/reasoning).
           attr_accessor reasoning: OpenAI::Beta::BetaResponsesClientEvent::ResponseCreate::Reasoning?
 
+          # A stable identifier used to help detect users of your application that may be
+          # violating OpenAI's usage policies. The IDs should be a string that uniquely
+          # identifies each user, with a maximum length of 64 characters. We recommend
+          # hashing their username or email address, in order to avoid sending us any
+          # identifying information.
+          # [Learn more](https://developers.openai.com/api/docs/guides/safety-best-practices#implement-safety-identifiers).
           attr_accessor safety_identifier: String?
 
+          # Specifies the processing type used for serving the request.
+          #
+          # - If set to 'auto', then the request will be processed with the service tier
+          #   configured in the Project settings. Unless otherwise configured, the Project
+          #   will use 'default'.
+          # - If set to 'default', then the request will be processed with the standard
+          #   pricing and performance for the selected model.
+          # - If set to
+          #   '[flex](https://developers.openai.com/api/docs/guides/flex-processing)', then
+          #   the request will be processed with the Flex Processing service tier.
+          # - To opt-in to
+          #   [Fast mode](https://developers.openai.com/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.
+          # - If set to 'ultrafast', then the request will be processed with the
+          #   access-controlled Ultrafast Processing service tier. This tier is currently
+          #   available for `gpt-5.6-sol`; a response served through it will show
+          #   `service_tier=ultrafast`.
+          # - 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.
           attr_accessor service_tier: OpenAI::Models::Beta::BetaResponsesClientEvent::ResponseCreate::service_tier?
 
+          # Whether to store the generated model response for later retrieval via API.
+          # Defaults to true when omitted. If set to true, response data will be stored for
+          # at least 30 days, subject to the
+          # [data retention exceptions](https://developers.openai.com/api/docs/guides/your-data#v1responses).
           attr_accessor store: bool?
 
+          # If set to true, the model response data will be streamed to the client as it is
+          # generated using
+          # [server-sent events](https://developer.mozilla.org/en-US/docs/Web/API/Server-sent_events/Using_server-sent_events#Event_stream_format).
+          # See the
+          # [Streaming section below](https://developers.openai.com/api/reference/resources/responses/streaming-events)
+          # for more information.
           attr_accessor stream: bool?
 
+          # The WebSocket lane for this response. Requests with the same `stream_id` are
+          # processed FIFO, and events for the response echo the same `stream_id`.
+          #
+          # `stream_id` controls routing; `previous_response_id` controls conversation
+          # lineage, so a new lane can fork from a response created on another lane.
           attr_reader stream_id: String?
 
+          # The WebSocket lane for this response. Requests with the same `stream_id` are
+          # processed FIFO, and events for the response echo the same `stream_id`.
+          #
+          # `stream_id` controls routing; `previous_response_id` controls conversation
+          # lineage, so a new lane can fork from a response created on another lane.
           def stream_id=: (String) -> String
 
+          # Options for streaming responses. Only set this when you set `stream: true`.
           attr_accessor stream_options: OpenAI::Beta::BetaResponsesClientEvent::ResponseCreate::StreamOptions?
 
+          # What sampling temperature to use, between 0 and 2. Higher values like 0.8 will
+          # make the output more random, while lower values like 0.2 will make it more
+          # focused and deterministic. We generally recommend altering this or `top_p` but
+          # not both.
           attr_accessor temperature: Float?
 
+          # Configuration options for a text response from the model. Can be plain text or
+          # structured JSON data. Learn more:
+          #
+          # - [Text inputs and outputs](https://developers.openai.com/api/docs/guides/text)
+          # - [Structured Outputs](https://developers.openai.com/api/docs/guides/structured-outputs)
           attr_reader text: OpenAI::Beta::BetaResponseTextConfig?
 
+          # Configuration options for a text response from the model. Can be plain text or
+          # structured JSON data. Learn more:
+          #
+          # - [Text inputs and outputs](https://developers.openai.com/api/docs/guides/text)
+          # - [Structured Outputs](https://developers.openai.com/api/docs/guides/structured-outputs)
           def text=: (
             OpenAI::Beta::BetaResponseTextConfig
           ) -> OpenAI::Beta::BetaResponseTextConfig
 
+          # How the model should select which tool (or tools) to use when generating a
+          # response. See the `tools` parameter to see how to specify which tools the model
+          # can call.
           attr_reader tool_choice: OpenAI::Models::Beta::BetaResponsesClientEvent::ResponseCreate::tool_choice?
 
+          # How the model should select which tool (or tools) to use when generating a
+          # response. See the `tools` parameter to see how to specify which tools the model
+          # can call.
           def tool_choice=: (
             OpenAI::Models::Beta::BetaResponsesClientEvent::ResponseCreate::tool_choice
           ) -> OpenAI::Models::Beta::BetaResponsesClientEvent::ResponseCreate::tool_choice
 
+          # An array of tools the model may call while generating a response. You can
+          # specify which tool to use by setting the `tool_choice` parameter.
+          #
+          # We support the following categories of tools:
+          #
+          # - **Built-in tools**: Tools that are provided by OpenAI that extend the model's
+          #   capabilities, like
+          #   [web search](https://developers.openai.com/api/docs/guides/tools-web-search)
+          #   or
+          #   [file search](https://developers.openai.com/api/docs/guides/tools-file-search).
+          #   Learn more about
+          #   [built-in tools](https://developers.openai.com/api/docs/guides/tools).
+          # - **MCP Tools**: Integrations with third-party systems via custom MCP servers or
+          #   predefined connectors such as Google Drive and SharePoint. Learn more about
+          #   [MCP Tools](https://developers.openai.com/api/docs/guides/tools-connectors-mcp).
+          # - **Function calls (custom tools)**: Functions that are defined by you, enabling
+          #   the model to call your own code with strongly typed arguments and outputs.
+          #   Learn more about
+          #   [function calling](https://developers.openai.com/api/docs/guides/function-calling).
+          #   You can also use custom tools to call your own code.
           attr_reader tools: ::Array[OpenAI::Models::Beta::beta_tool]?
 
+          # An array of tools the model may call while generating a response. You can
+          # specify which tool to use by setting the `tool_choice` parameter.
+          #
+          # We support the following categories of tools:
+          #
+          # - **Built-in tools**: Tools that are provided by OpenAI that extend the model's
+          #   capabilities, like
+          #   [web search](https://developers.openai.com/api/docs/guides/tools-web-search)
+          #   or
+          #   [file search](https://developers.openai.com/api/docs/guides/tools-file-search).
+          #   Learn more about
+          #   [built-in tools](https://developers.openai.com/api/docs/guides/tools).
+          # - **MCP Tools**: Integrations with third-party systems via custom MCP servers or
+          #   predefined connectors such as Google Drive and SharePoint. Learn more about
+          #   [MCP Tools](https://developers.openai.com/api/docs/guides/tools-connectors-mcp).
+          # - **Function calls (custom tools)**: Functions that are defined by you, enabling
+          #   the model to call your own code with strongly typed arguments and outputs.
+          #   Learn more about
+          #   [function calling](https://developers.openai.com/api/docs/guides/function-calling).
+          #   You can also use custom tools to call your own code.
           def tools=: (
             ::Array[OpenAI::Models::Beta::beta_tool]
           ) -> ::Array[OpenAI::Models::Beta::beta_tool]
 
+          # An integer between 0 and 20 specifying the maximum number of most likely tokens
+          # to return at each token position, each with an associated log probability. In
+          # some cases, the number of returned tokens may be fewer than requested.
           attr_accessor top_logprobs: Integer?
 
+          # An alternative to sampling with temperature, called nucleus sampling, where the
+          # model considers the results of the tokens with top_p probability mass. So 0.1
+          # means only the tokens comprising the top 10% probability mass are considered.
+          #
+          # We generally recommend altering this or `temperature` but not both.
           attr_accessor top_p: Float?
 
+          # The truncation strategy to use for the model response.
+          #
+          # - `auto`: If the input to this Response exceeds the model's context window size,
+          #   the model will truncate the response to fit the context window by dropping
+          #   items from the beginning of the conversation.
+          # - `disabled` (default): If the input size will exceed the context window size
+          #   for a model, the request will fail with a 400 error.
           attr_accessor truncation: OpenAI::Models::Beta::BetaResponsesClientEvent::ResponseCreate::truncation?
 
+          # This field is being replaced by `safety_identifier` and `prompt_cache_key`. Use
+          # `prompt_cache_key` instead to maintain caching optimizations. A stable
+          # identifier for your end-users. Used to boost cache hit rates by better bucketing
+          # similar requests and to help OpenAI detect and prevent abuse.
+          # [Learn more](https://developers.openai.com/api/docs/guides/safety-best-practices#implement-safety-identifiers).
           attr_reader user: String?
 
+          # This field is being replaced by `safety_identifier` and `prompt_cache_key`. Use
+          # `prompt_cache_key` instead to maintain caching optimizations. A stable
+          # identifier for your end-users. Used to boost cache hit rates by better bucketing
+          # similar requests and to help OpenAI detect and prevent abuse.
+          # [Learn more](https://developers.openai.com/api/docs/guides/safety-best-practices#implement-safety-identifiers).
           def user=: (String) -> String
 
+          # @param background
+          #   Whether to run the model response in the background.
+          #   [Learn more](https://developers.openai.com/api/docs/guides/background).
+          # @param context_management
+          #   Context management configuration for this request.
+          # @param conversation
+          #   The conversation that this response belongs to. Items from this conversation are
+          #   prepended to `input_items` for this response request. Input items and output
+          #   items from this response are automatically added to this conversation after this
+          #   response completes.
+          # @param include
+          #   Specify additional output data to include in the model response. Currently
+          #   supported values are:
+          #
+          #   - `web_search_call.action.sources`: Include the sources of the web search tool
+          #     call.
+          #   - `code_interpreter_call.outputs`: Includes the outputs of python code execution
+          #     in code interpreter tool call items.
+          #   - `computer_call_output.output.image_url`: Include image urls from the computer
+          #     call output.
+          #   - `file_search_call.results`: Include the search results of the file search tool
+          #     call.
+          #   - `message.input_image.image_url`: Include image urls from the input message.
+          #   - `message.output_text.logprobs`: Include logprobs with assistant messages.
+          #   - `reasoning.encrypted_content`: Includes an encrypted version of reasoning
+          #     tokens in reasoning item outputs. This enables reasoning items to be used in
+          #     multi-turn conversations when using the Responses API statelessly (like when
+          #     the `store` parameter is set to `false`, or when an organization is enrolled
+          #     in the zero data retention program).
+          # @param input
+          #   Text, image, or file inputs to the model, used to generate a response.
+          #
+          #   Learn more:
+          #
+          #   - [Text inputs and outputs](https://developers.openai.com/api/docs/guides/text)
+          #   - [Image inputs](https://developers.openai.com/api/docs/guides/images-vision)
+          #   - [File inputs](https://developers.openai.com/api/docs/guides/file-inputs)
+          #   - [Conversation state](https://developers.openai.com/api/docs/guides/conversation-state)
+          #   - [Function calling](https://developers.openai.com/api/docs/guides/function-calling)
+          # @param instructions
+          #   A system (or developer) message inserted into the model's context.
+          #
+          #   When using along with `previous_response_id`, the instructions from a previous
+          #   response will not be carried over to the next response. This makes it simple to
+          #   swap out system (or developer) messages in new responses.
+          # @param max_output_tokens
+          #   An upper bound for the number of tokens that can be generated for a response,
+          #   including visible output tokens and
+          #   [reasoning tokens](https://developers.openai.com/api/docs/guides/reasoning).
+          # @param max_tool_calls
+          #   The maximum number of total calls to built-in tools that can be processed in a
+          #   response. This maximum number applies across all built-in tool calls, not per
+          #   individual tool. Any further attempts to call a tool by the model will be
+          #   ignored.
+          # @param metadata
+          #   Set of 16 key-value pairs that can be attached to an object. This can be useful
+          #   for storing additional information about the object in a structured format, and
+          #   querying for objects via API or the dashboard.
+          #
+          #   Keys are strings with a maximum length of 64 characters. Values are strings with
+          #   a maximum length of 512 characters.
+          # @param model
+          #   Model ID used to generate the response, like `gpt-6-astra`. OpenAI offers a wide
+          #   range of models with different capabilities, performance characteristics, and
+          #   price points. Refer to the
+          #   [model guide](https://developers.openai.com/api/docs/models) to browse and
+          #   compare available models.
+          # @param moderation
+          #   Configuration for running moderation on the input and output of this response.
+          # @param multi_agent
+          #   Configuration for server-hosted multi-agent execution.
+          # @param parallel_tool_calls
+          #   Whether to allow the model to run tool calls in parallel.
+          # @param previous_response_id
+          #   The unique ID of the previous response to the model. Use this to create
+          #   multi-turn conversations. Learn more about
+          #   [conversation state](https://developers.openai.com/api/docs/guides/conversation-state).
+          #   Cannot be used in conjunction with `conversation`.
+          # @param prompt
+          #   Reference to a prompt template and its variables.
+          #   [Learn more](https://developers.openai.com/api/docs/guides/text?api-mode=responses#version-prompts-in-code).
+          # @param prompt_cache_key
+          #   Used by OpenAI to cache responses for similar requests to optimize your cache
+          #   hit rates. Replaces the `user` field.
+          #   [Learn more](https://developers.openai.com/api/docs/guides/prompt-caching).
+          # @param prompt_cache_options
+          #   Options for prompt caching. Supported for `gpt-5.6` and later models. By
+          #   default, OpenAI automatically chooses one implicit cache breakpoint. You can add
+          #   explicit breakpoints to content blocks with `prompt_cache_breakpoint`. Each
+          #   request can write up to four breakpoints. For cache matching, OpenAI considers
+          #   up to the latest 80 breakpoints in the conversation, without a content-block
+          #   lookback limit. Set `mode` to `explicit` to disable the implicit breakpoint. The
+          #   `ttl` defaults to `30m`, which is currently the only supported value. See the
+          #   [prompt caching guide](https://developers.openai.com/api/docs/guides/prompt-caching)
+          #   for current details.
+          # @param prompt_cache_retention
+          #   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://developers.openai.com/api/docs/guides/prompt-caching#prompt-cache-retention).
+          #   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:
+          #
+          #   - Organizations without ZDR enabled default to `24h`.
+          #   - Organizations with ZDR enabled default to `in_memory` when
+          #     `prompt_cache_retention` is not specified.
+          # @param reasoning
+          #   Configuration options for
+          #   [reasoning models](https://developers.openai.com/api/docs/guides/reasoning).
+          # @param safety_identifier
+          #   A stable identifier used to help detect users of your application that may be
+          #   violating OpenAI's usage policies. The IDs should be a string that uniquely
+          #   identifies each user, with a maximum length of 64 characters. We recommend
+          #   hashing their username or email address, in order to avoid sending us any
+          #   identifying information.
+          #   [Learn more](https://developers.openai.com/api/docs/guides/safety-best-practices#implement-safety-identifiers).
+          # @param service_tier
+          #   Specifies the processing type used for serving the request.
+          #
+          #   - If set to 'auto', then the request will be processed with the service tier
+          #     configured in the Project settings. Unless otherwise configured, the Project
+          #     will use 'default'.
+          #   - If set to 'default', then the request will be processed with the standard
+          #     pricing and performance for the selected model.
+          #   - If set to
+          #     '[flex](https://developers.openai.com/api/docs/guides/flex-processing)', then
+          #     the request will be processed with the Flex Processing service tier.
+          #   - To opt-in to
+          #     [Fast mode](https://developers.openai.com/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.
+          #   - If set to 'ultrafast', then the request will be processed with the
+          #     access-controlled Ultrafast Processing service tier. This tier is currently
+          #     available for `gpt-5.6-sol`; a response served through it will show
+          #     `service_tier=ultrafast`.
+          #   - 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.
+          # @param store
+          #   Whether to store the generated model response for later retrieval via API.
+          #   Defaults to true when omitted. If set to true, response data will be stored for
+          #   at least 30 days, subject to the
+          #   [data retention exceptions](https://developers.openai.com/api/docs/guides/your-data#v1responses).
+          # @param stream
+          #   If set to true, the model response data will be streamed to the client as it is
+          #   generated using
+          #   [server-sent events](https://developer.mozilla.org/en-US/docs/Web/API/Server-sent_events/Using_server-sent_events#Event_stream_format).
+          #   See the
+          #   [Streaming section below](https://developers.openai.com/api/reference/resources/responses/streaming-events)
+          #   for more information.
+          # @param stream_id
+          #   The WebSocket lane for this response. Requests with the same `stream_id` are
+          #   processed FIFO, and events for the response echo the same `stream_id`.
+          #
+          #   `stream_id` controls routing; `previous_response_id` controls conversation
+          #   lineage, so a new lane can fork from a response created on another lane.
+          # @param stream_options
+          #   Options for streaming responses. Only set this when you set `stream: true`.
+          # @param temperature
+          #   What sampling temperature to use, between 0 and 2. Higher values like 0.8 will
+          #   make the output more random, while lower values like 0.2 will make it more
+          #   focused and deterministic. We generally recommend altering this or `top_p` but
+          #   not both.
+          # @param text
+          #   Configuration options for a text response from the model. Can be plain text or
+          #   structured JSON data. Learn more:
+          #
+          #   - [Text inputs and outputs](https://developers.openai.com/api/docs/guides/text)
+          #   - [Structured Outputs](https://developers.openai.com/api/docs/guides/structured-outputs)
+          # @param tool_choice
+          #   How the model should select which tool (or tools) to use when generating a
+          #   response. See the `tools` parameter to see how to specify which tools the model
+          #   can call.
+          # @param tools
+          #   An array of tools the model may call while generating a response. You can
+          #   specify which tool to use by setting the `tool_choice` parameter.
+          #
+          #   We support the following categories of tools:
+          #
+          #   - **Built-in tools**: Tools that are provided by OpenAI that extend the model's
+          #     capabilities, like
+          #     [web search](https://developers.openai.com/api/docs/guides/tools-web-search)
+          #     or
+          #     [file search](https://developers.openai.com/api/docs/guides/tools-file-search).
+          #     Learn more about
+          #     [built-in tools](https://developers.openai.com/api/docs/guides/tools).
+          #   - **MCP Tools**: Integrations with third-party systems via custom MCP servers or
+          #     predefined connectors such as Google Drive and SharePoint. Learn more about
+          #     [MCP Tools](https://developers.openai.com/api/docs/guides/tools-connectors-mcp).
+          #   - **Function calls (custom tools)**: Functions that are defined by you, enabling
+          #     the model to call your own code with strongly typed arguments and outputs.
+          #     Learn more about
+          #     [function calling](https://developers.openai.com/api/docs/guides/function-calling).
+          #     You can also use custom tools to call your own code.
+          # @param top_logprobs
+          #   An integer between 0 and 20 specifying the maximum number of most likely tokens
+          #   to return at each token position, each with an associated log probability. In
+          #   some cases, the number of returned tokens may be fewer than requested.
+          # @param top_p
+          #   An alternative to sampling with temperature, called nucleus sampling, where the
+          #   model considers the results of the tokens with top_p probability mass. So 0.1
+          #   means only the tokens comprising the top 10% probability mass are considered.
+          #
+          #   We generally recommend altering this or `temperature` but not both.
+          # @param truncation
+          #   The truncation strategy to use for the model response.
+          #
+          #   - `auto`: If the input to this Response exceeds the model's context window size,
+          #     the model will truncate the response to fit the context window by dropping
+          #     items from the beginning of the conversation.
+          #   - `disabled` (default): If the input size will exceed the context window size
+          #     for a model, the request will fail with a 400 error.
+          # @param user
+          #   This field is being replaced by `safety_identifier` and `prompt_cache_key`. Use
+          #   `prompt_cache_key` instead to maintain caching optimizations. A stable
+          #   identifier for your end-users. Used to boost cache hit rates by better bucketing
+          #   similar requests and to help OpenAI detect and prevent abuse.
+          #   [Learn more](https://developers.openai.com/api/docs/guides/safety-best-practices#implement-safety-identifiers).
+          # @param type
+          #   The type of the client event. Always `response.create`.
           def initialize: (
             ?background: bool?,
             ?context_management: ::Array[OpenAI::Beta::BetaResponsesClientEvent::ResponseCreate::ContextManagement]?,
@@ -224,10 +715,16 @@ module OpenAI
             { type: String, ?compact_threshold: Integer? }
 
           class ContextManagement < OpenAI::Internal::Type::BaseModel
+            # The context management entry type. Currently only 'compaction' is supported.
             attr_accessor type: String
 
+            # Token threshold at which compaction should be triggered for this entry.
             attr_accessor compact_threshold: Integer?
 
+            # @param type
+            #   The context management entry type. Currently only 'compaction' is supported.
+            # @param compact_threshold
+            #   Token threshold at which compaction should be triggered for this entry.
             def initialize: (type: String, ?compact_threshold: Integer?) -> void
 
             def to_hash: -> { type: String, ?compact_threshold: Integer? }
@@ -271,6 +768,7 @@ module OpenAI
             | :"gpt-5.1"
             | :"gpt-5.1-2025-11-13"
             | :"gpt-5.1-codex"
+            | :"gpt-5.1-mini"
             | :"gpt-5.1-chat-latest"
             | :"gpt-5"
             | :"gpt-5-mini"
@@ -336,7 +834,6 @@ module OpenAI
             | :"gpt-3.5-turbo-1106"
             | :"gpt-3.5-turbo-0125"
             | :"gpt-3.5-turbo-16k-0613"
-            | :"gpt-5.1-mini"
             | :"o1-pro"
             | :"o1-pro-2025-03-19"
             | :"o3-pro"
@@ -383,6 +880,7 @@ module OpenAI
             GPT_5_1: :"gpt-5.1"
             GPT_5_1_2025_11_13: :"gpt-5.1-2025-11-13"
             GPT_5_1_CODEX: :"gpt-5.1-codex"
+            GPT_5_1_MINI: :"gpt-5.1-mini"
             GPT_5_1_CHAT_LATEST: :"gpt-5.1-chat-latest"
             GPT_5: :"gpt-5"
             GPT_5_MINI: :"gpt-5-mini"
@@ -448,7 +946,6 @@ module OpenAI
             GPT_3_5_TURBO_1106: :"gpt-3.5-turbo-1106"
             GPT_3_5_TURBO_0125: :"gpt-3.5-turbo-0125"
             GPT_3_5_TURBO_16K_0613: :"gpt-3.5-turbo-16k-0613"
-            GPT_5_1_MINI: :"gpt-5.1-mini"
             O1_PRO: :"o1-pro"
             O1_PRO_2025_03_19: :"o1-pro-2025-03-19"
             O3_PRO: :"o3-pro"
@@ -477,10 +974,18 @@ module OpenAI
             }
 
           class Moderation < OpenAI::Internal::Type::BaseModel
+            # The moderation model to use for moderated completions, e.g.
+            # 'omni-moderation-latest'.
             attr_accessor model: String
 
+            # The policy to apply to moderated response input and output.
             attr_accessor policy: OpenAI::Beta::BetaResponsesClientEvent::ResponseCreate::Moderation::Policy?
 
+            # @param model
+            #   The moderation model to use for moderated completions, e.g.
+            #   'omni-moderation-latest'.
+            # @param policy
+            #   The policy to apply to moderated response input and output.
             def initialize: (
               model: String,
               ?policy: OpenAI::Beta::BetaResponsesClientEvent::ResponseCreate::Moderation::Policy?
@@ -498,10 +1003,16 @@ module OpenAI
               }
 
             class Policy < OpenAI::Internal::Type::BaseModel
+              # The moderation policy for the response input.
               attr_accessor input: OpenAI::Beta::BetaResponsesClientEvent::ResponseCreate::Moderation::Policy::Input?
 
+              # The moderation policy for the response output.
               attr_accessor output: OpenAI::Beta::BetaResponsesClientEvent::ResponseCreate::Moderation::Policy::Output?
 
+              # @param input
+              #   The moderation policy for the response input.
+              # @param output
+              #   The moderation policy for the response output.
               def initialize: (
                 ?input: OpenAI::Beta::BetaResponsesClientEvent::ResponseCreate::Moderation::Policy::Input?,
                 ?output: OpenAI::Beta::BetaResponsesClientEvent::ResponseCreate::Moderation::Policy::Output?
@@ -574,12 +1085,34 @@ module OpenAI
             { enabled: bool, ?max_concurrent_subagents: Integer }
 
           class MultiAgent < OpenAI::Internal::Type::BaseModel
+            # Whether to enable server-hosted multi-agent execution for this response.
             attr_accessor enabled: bool
 
+            # `max_concurrent_subagents` sets the maximum number of subagents that can be
+            # active simultaneously across the entire agent tree. It includes all
+            # descendants—children, grandchildren, and deeper subagents—but excludes the root
+            # agent. The API does not impose a fixed upper bound on this setting. The default
+            # is `3`, which is recommended for most workloads. Multi-agent runs also have no
+            # fixed limit on tree depth or the total number of subagents created during a run.
             attr_reader max_concurrent_subagents: Integer?
 
+            # `max_concurrent_subagents` sets the maximum number of subagents that can be
+            # active simultaneously across the entire agent tree. It includes all
+            # descendants—children, grandchildren, and deeper subagents—but excludes the root
+            # agent. The API does not impose a fixed upper bound on this setting. The default
+            # is `3`, which is recommended for most workloads. Multi-agent runs also have no
+            # fixed limit on tree depth or the total number of subagents created during a run.
             def max_concurrent_subagents=: (Integer) -> Integer
 
+            # @param enabled
+            #   Whether to enable server-hosted multi-agent execution for this response.
+            # @param max_concurrent_subagents
+            #   `max_concurrent_subagents` sets the maximum number of subagents that can be
+            #   active simultaneously across the entire agent tree. It includes all
+            #   descendants—children, grandchildren, and deeper subagents—but excludes the root
+            #   agent. The API does not impose a fixed upper bound on this setting. The default
+            #   is `3`, which is recommended for most workloads. Multi-agent runs also have no
+            #   fixed limit on tree depth or the total number of subagents created during a run.
             def initialize: (
               enabled: bool,
               ?max_concurrent_subagents: Integer
@@ -600,24 +1133,65 @@ module OpenAI
             }
 
           class PromptCacheOptions < OpenAI::Internal::Type::BaseModel
+            # The ID of a response to compare when diagnosing prompt cache reuse. Supplying
+            # this field requests prompt cache diagnostics when the feature is enabled.
             attr_accessor comparison_response_id: String?
 
+            # 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.
             attr_reader mode: OpenAI::Models::Beta::BetaResponsesClientEvent::ResponseCreate::PromptCacheOptions::mode?
 
+            # 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.
             def mode=: (
               OpenAI::Models::Beta::BetaResponsesClientEvent::ResponseCreate::PromptCacheOptions::mode
             ) -> OpenAI::Models::Beta::BetaResponsesClientEvent::ResponseCreate::PromptCacheOptions::mode
 
+            # Prepares the prompt cache without generating output. Defaults to `false`. When
+            # set to `true`, overrides the `generate` field to `false`.
             attr_reader prewarm: bool?
 
+            # Prepares the prompt cache without generating output. Defaults to `false`. When
+            # set to `true`, overrides the `generate` field to `false`.
             def prewarm=: (bool) -> bool
 
+            # The minimum lifetime applied to every implicit and explicit cache breakpoint
+            # written by the request. Defaults to `30m`, which is currently the only supported
+            # value. The backend may retain cache entries for longer.
             attr_reader ttl: OpenAI::Models::Beta::BetaResponsesClientEvent::ResponseCreate::PromptCacheOptions::ttl?
 
+            # The minimum lifetime applied to every implicit and explicit cache breakpoint
+            # written by the request. Defaults to `30m`, which is currently the only supported
+            # value. The backend may retain cache entries for longer.
             def ttl=: (
               OpenAI::Models::Beta::BetaResponsesClientEvent::ResponseCreate::PromptCacheOptions::ttl
             ) -> OpenAI::Models::Beta::BetaResponsesClientEvent::ResponseCreate::PromptCacheOptions::ttl
 
+            # @param comparison_response_id
+            #   The ID of a response to compare when diagnosing prompt cache reuse. Supplying
+            #   this field requests prompt cache diagnostics when the feature is enabled.
+            # @param mode
+            #   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.
+            # @param prewarm
+            #   Prepares the prompt cache without generating output. Defaults to `false`. When
+            #   set to `true`, overrides the `generate` field to `false`.
+            # @param ttl
+            #   The minimum lifetime applied to every implicit and explicit cache breakpoint
+            #   written by the request. Defaults to `30m`, which is currently the only supported
+            #   value. The backend may retain cache entries for longer.
             def initialize: (
               ?comparison_response_id: String?,
               ?mode: OpenAI::Models::Beta::BetaResponsesClientEvent::ResponseCreate::PromptCacheOptions::mode,
@@ -675,20 +1249,80 @@ module OpenAI
             }
 
           class Reasoning < OpenAI::Internal::Type::BaseModel
+            # Controls which reasoning items are rendered back to the model on later turns. If
+            # omitted or set to `auto`, the model determines the context mode. The `gpt-5.6`
+            # model family defaults to `all_turns`; earlier models default to `current_turn`.
+            #
+            # When returned on a response, this is the effective reasoning context mode used
+            # for the response.
             attr_accessor context: OpenAI::Models::Beta::BetaResponsesClientEvent::ResponseCreate::Reasoning::context?
 
+            # Constrains effort on reasoning for reasoning models. Currently supported values
+            # are `none`, `minimal`, `low`, `medium`, `high`, `xhigh`, and `max`. Reducing
+            # reasoning effort can result in faster responses and fewer tokens used on
+            # reasoning in a response. Not all reasoning models support every value. See the
+            # [reasoning guide](https://developers.openai.com/api/docs/guides/reasoning) for
+            # model-specific support.
             attr_accessor effort: OpenAI::Models::Beta::BetaResponsesClientEvent::ResponseCreate::Reasoning::effort?
 
+            # **Deprecated:** use `summary` instead.
+            #
+            # A summary of the reasoning performed by the model. This can be useful for
+            # debugging and understanding the model's reasoning process. One of `auto`,
+            # `concise`, or `detailed`.
             attr_accessor generate_summary: OpenAI::Models::Beta::BetaResponsesClientEvent::ResponseCreate::Reasoning::generate_summary?
 
+            # Controls the reasoning execution mode for the request.
+            #
+            # When returned on a response, this is the effective execution mode.
             attr_reader mode: OpenAI::Models::Beta::BetaResponsesClientEvent::ResponseCreate::Reasoning::mode?
 
+            # Controls the reasoning execution mode for the request.
+            #
+            # When returned on a response, this is the effective execution mode.
             def mode=: (
               OpenAI::Models::Beta::BetaResponsesClientEvent::ResponseCreate::Reasoning::mode
             ) -> OpenAI::Models::Beta::BetaResponsesClientEvent::ResponseCreate::Reasoning::mode
 
+            # A summary of the reasoning performed by the model. This can be useful for
+            # debugging and understanding the model's reasoning process. One of `auto`,
+            # `concise`, or `detailed`.
+            #
+            # `concise` is supported for `computer-use-preview` models and all reasoning
+            # models after `gpt-5`.
             attr_accessor summary: OpenAI::Models::Beta::BetaResponsesClientEvent::ResponseCreate::Reasoning::summary?
 
+            # @param context
+            #   Controls which reasoning items are rendered back to the model on later turns. If
+            #   omitted or set to `auto`, the model determines the context mode. The `gpt-5.6`
+            #   model family defaults to `all_turns`; earlier models default to `current_turn`.
+            #
+            #   When returned on a response, this is the effective reasoning context mode used
+            #   for the response.
+            # @param effort
+            #   Constrains effort on reasoning for reasoning models. Currently supported values
+            #   are `none`, `minimal`, `low`, `medium`, `high`, `xhigh`, and `max`. Reducing
+            #   reasoning effort can result in faster responses and fewer tokens used on
+            #   reasoning in a response. Not all reasoning models support every value. See the
+            #   [reasoning guide](https://developers.openai.com/api/docs/guides/reasoning) for
+            #   model-specific support.
+            # @param generate_summary
+            #   **Deprecated:** use `summary` instead.
+            #
+            #   A summary of the reasoning performed by the model. This can be useful for
+            #   debugging and understanding the model's reasoning process. One of `auto`,
+            #   `concise`, or `detailed`.
+            # @param mode
+            #   Controls the reasoning execution mode for the request.
+            #
+            #   When returned on a response, this is the effective execution mode.
+            # @param summary
+            #   A summary of the reasoning performed by the model. This can be useful for
+            #   debugging and understanding the model's reasoning process. One of `auto`,
+            #   `concise`, or `detailed`.
+            #
+            #   `concise` is supported for `computer-use-preview` models and all reasoning
+            #   models after `gpt-5`.
             def initialize: (
               ?context: OpenAI::Models::Beta::BetaResponsesClientEvent::ResponseCreate::Reasoning::context?,
               ?effort: OpenAI::Models::Beta::BetaResponsesClientEvent::ResponseCreate::Reasoning::effort?,
@@ -790,10 +1424,29 @@ module OpenAI
           type stream_options = { ?include_obfuscation: bool }
 
           class StreamOptions < OpenAI::Internal::Type::BaseModel
+            # When true, stream obfuscation will be enabled. Stream obfuscation adds random
+            # characters to an `obfuscation` field on streaming delta events to normalize
+            # payload sizes as a mitigation to certain side-channel attacks. These obfuscation
+            # fields are included by default, but add a small amount of overhead to the data
+            # stream. You can set `include_obfuscation` to false to optimize for bandwidth if
+            # you trust the network links between your application and the OpenAI API.
             attr_reader include_obfuscation: bool?
 
+            # When true, stream obfuscation will be enabled. Stream obfuscation adds random
+            # characters to an `obfuscation` field on streaming delta events to normalize
+            # payload sizes as a mitigation to certain side-channel attacks. These obfuscation
+            # fields are included by default, but add a small amount of overhead to the data
+            # stream. You can set `include_obfuscation` to false to optimize for bandwidth if
+            # you trust the network links between your application and the OpenAI API.
             def include_obfuscation=: (bool) -> bool
 
+            # @param include_obfuscation
+            #   When true, stream obfuscation will be enabled. Stream obfuscation adds random
+            #   characters to an `obfuscation` field on streaming delta events to normalize
+            #   payload sizes as a mitigation to certain side-channel attacks. These obfuscation
+            #   fields are included by default, but add a small amount of overhead to the data
+            #   stream. You can set `include_obfuscation` to false to optimize for bandwidth if
+            #   you trust the network links between your application and the OpenAI API.
             def initialize: (?include_obfuscation: bool) -> void
 
             def to_hash: -> { ?include_obfuscation: bool }
@@ -817,8 +1470,11 @@ module OpenAI
               { ?type: :programmatic_tool_calling }
 
             class BetaSpecificProgrammaticToolCallingParam < OpenAI::Internal::Type::BaseModel
+              # The tool to call. Always `programmatic_tool_calling`.
               attr_accessor type: :programmatic_tool_calling
 
+              # @param type
+              #   The tool to call. Always `programmatic_tool_calling`.
               def initialize: (?type: :programmatic_tool_calling) -> void
 
               def to_hash: -> { ?type: :programmatic_tool_calling }