openai 0.91.0 → 0.93.0

data/sig/openai/models/responses/response_create_params.rbs

@@ -40,92 +40,548 @@ module OpenAI
         extend OpenAI::Internal::Type::RequestParameters::Converter
         include OpenAI::Internal::Type::RequestParameters
 
+        # 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::Responses::ResponseCreateParams::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::Responses::ResponseCreateParams::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::Responses::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::Responses::ResponseCreateParams::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::Responses::ResponseCreateParams::input
         ) -> OpenAI::Models::Responses::ResponseCreateParams::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: OpenAI::Models::metadata?
 
+        # 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::responses_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::responses_model
         ) -> OpenAI::Models::responses_model
 
+        # Configuration for running moderation on the input and output of this response.
         attr_accessor moderation: OpenAI::Responses::ResponseCreateParams::Moderation?
 
+        # 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::Responses::ResponsePrompt?
 
+        # 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::Responses::ResponseCreateParams::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::Responses::ResponseCreateParams::PromptCacheOptions
         ) -> OpenAI::Responses::ResponseCreateParams::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::Responses::ResponseCreateParams::prompt_cache_retention?
 
+        # Configuration options for
+        # [reasoning models](https://developers.openai.com/api/docs/guides/reasoning).
         attr_accessor reasoning: OpenAI::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::Responses::ResponseCreateParams::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?
 
+        # Options for streaming responses. Only set this when you set `stream: true`.
         attr_accessor stream_options: OpenAI::Responses::ResponseCreateParams::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::Responses::ResponseTextConfig?
 
+        # 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::Responses::ResponseTextConfig
         ) -> OpenAI::Responses::ResponseTextConfig
 
+        # 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::Responses::ResponseCreateParams::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::Responses::ResponseCreateParams::tool_choice
         ) -> OpenAI::Models::Responses::ResponseCreateParams::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::Responses::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::Responses::tool]
         ) -> ::Array[OpenAI::Models::Responses::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::Responses::ResponseCreateParams::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 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_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).
         def initialize: (
           ?background: bool?,
           ?context_management: ::Array[OpenAI::Responses::ResponseCreateParams::ContextManagement]?,
@@ -197,10 +653,16 @@ module OpenAI
         type context_management = { 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? }
@@ -230,10 +692,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::Responses::ResponseCreateParams::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::Responses::ResponseCreateParams::Moderation::Policy?
@@ -251,10 +721,16 @@ module OpenAI
             }
 
           class Policy < OpenAI::Internal::Type::BaseModel
+            # The moderation policy for the response input.
             attr_accessor input: OpenAI::Responses::ResponseCreateParams::Moderation::Policy::Input?
 
+            # The moderation policy for the response output.
             attr_accessor output: OpenAI::Responses::ResponseCreateParams::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::Responses::ResponseCreateParams::Moderation::Policy::Input?,
               ?output: OpenAI::Responses::ResponseCreateParams::Moderation::Policy::Output?
@@ -332,24 +808,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::Responses::ResponseCreateParams::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::Responses::ResponseCreateParams::PromptCacheOptions::mode
           ) -> OpenAI::Models::Responses::ResponseCreateParams::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::Responses::ResponseCreateParams::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::Responses::ResponseCreateParams::PromptCacheOptions::ttl
           ) -> OpenAI::Models::Responses::ResponseCreateParams::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::Responses::ResponseCreateParams::PromptCacheOptions::mode,
@@ -417,10 +934,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 }
@@ -444,8 +980,11 @@ module OpenAI
             { ?type: :programmatic_tool_calling }
 
           class SpecificProgrammaticToolCallingParam < 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 }