# frozen_string_literal: true

module OpenAI
  module Models
    module Chat
      # @see OpenAI::Resources::Chat::Completions#create
      #
      # @see OpenAI::Resources::Chat::Completions#stream_raw
      class CompletionCreateParams < OpenAI::Internal::Type::BaseModel
        extend OpenAI::Internal::Type::RequestParameters::Converter
        include OpenAI::Internal::Type::RequestParameters

        # @!attribute messages
        #   A list of messages comprising the conversation so far. Depending on the
        #   [model](https://platform.openai.com/docs/models) you use, different message
        #   types (modalities) are supported, like
        #   [text](https://platform.openai.com/docs/guides/text-generation),
        #   [images](https://platform.openai.com/docs/guides/vision), and
        #   [audio](https://platform.openai.com/docs/guides/audio).
        #
        #   @return [Array<OpenAI::Models::Chat::ChatCompletionDeveloperMessageParam, OpenAI::Models::Chat::ChatCompletionSystemMessageParam, OpenAI::Models::Chat::ChatCompletionUserMessageParam, OpenAI::Models::Chat::ChatCompletionAssistantMessageParam, OpenAI::Models::Chat::ChatCompletionToolMessageParam, OpenAI::Models::Chat::ChatCompletionFunctionMessageParam>]
        required :messages,
                 -> { OpenAI::Internal::Type::ArrayOf[union: OpenAI::Chat::ChatCompletionMessageParam] }

        # @!attribute model
        #   Model ID used to generate the response, like `gpt-4o` or `o3`. OpenAI offers a
        #   wide range of models with different capabilities, performance characteristics,
        #   and price points. Refer to the
        #   [model guide](https://platform.openai.com/docs/models) to browse and compare
        #   available models.
        #
        #   @return [String, Symbol, OpenAI::Models::ChatModel]
        required :model, union: -> { OpenAI::Chat::CompletionCreateParams::Model }

        # @!attribute audio
        #   Parameters for audio output. Required when audio output is requested with
        #   `modalities: ["audio"]`.
        #   [Learn more](https://platform.openai.com/docs/guides/audio).
        #
        #   @return [OpenAI::Models::Chat::ChatCompletionAudioParam, nil]
        optional :audio, -> { OpenAI::Chat::ChatCompletionAudioParam }, nil?: true

        # @!attribute frequency_penalty
        #   Number between -2.0 and 2.0. Positive values penalize new tokens based on their
        #   existing frequency in the text so far, decreasing the model's likelihood to
        #   repeat the same line verbatim.
        #
        #   @return [Float, nil]
        optional :frequency_penalty, Float, nil?: true

        # @!attribute function_call
        #   @deprecated
        #
        #   Deprecated in favor of `tool_choice`.
        #
        #   Controls which (if any) function is called by the model.
        #
        #   `none` means the model will not call a function and instead generates a message.
        #
        #   `auto` means the model can pick between generating a message or calling a
        #   function.
        #
        #   Specifying a particular function via `{"name": "my_function"}` forces the model
        #   to call that function.
        #
        #   `none` is the default when no functions are present. `auto` is the default if
        #   functions are present.
        #
        #   @return [Symbol, OpenAI::Models::Chat::CompletionCreateParams::FunctionCall::FunctionCallMode, OpenAI::Models::Chat::ChatCompletionFunctionCallOption, nil]
        optional :function_call, union: -> { OpenAI::Chat::CompletionCreateParams::FunctionCall }

        # @!attribute functions
        #   @deprecated
        #
        #   Deprecated in favor of `tools`.
        #
        #   A list of functions the model may generate JSON inputs for.
        #
        #   @return [Array<OpenAI::Models::Chat::CompletionCreateParams::Function>, nil]
        optional :functions,
                 -> { OpenAI::Internal::Type::ArrayOf[OpenAI::Chat::CompletionCreateParams::Function] }

        # @!attribute logit_bias
        #   Modify the likelihood of specified tokens appearing in the completion.
        #
        #   Accepts a JSON object that maps tokens (specified by their token ID in the
        #   tokenizer) to an associated bias value from -100 to 100. Mathematically, the
        #   bias is added to the logits generated by the model prior to sampling. The exact
        #   effect will vary per model, but values between -1 and 1 should decrease or
        #   increase likelihood of selection; values like -100 or 100 should result in a ban
        #   or exclusive selection of the relevant token.
        #
        #   @return [Hash{Symbol=>Integer}, nil]
        optional :logit_bias, OpenAI::Internal::Type::HashOf[Integer], nil?: true

        # @!attribute logprobs
        #   Whether to return log probabilities of the output tokens or not. If true,
        #   returns the log probabilities of each output token returned in the `content` of
        #   `message`.
        #
        #   @return [Boolean, nil]
        optional :logprobs, OpenAI::Internal::Type::Boolean, nil?: true

        # @!attribute max_completion_tokens
        #   An upper bound for the number of tokens that can be generated for a completion,
        #   including visible output tokens and
        #   [reasoning tokens](https://platform.openai.com/docs/guides/reasoning).
        #
        #   @return [Integer, nil]
        optional :max_completion_tokens, Integer, nil?: true

        # @!attribute max_tokens
        #   @deprecated
        #
        #   The maximum number of [tokens](/tokenizer) that can be generated in the chat
        #   completion. This value can be used to control
        #   [costs](https://openai.com/api/pricing/) for text generated via API.
        #
        #   This value is now deprecated in favor of `max_completion_tokens`, and is not
        #   compatible with
        #   [o-series models](https://platform.openai.com/docs/guides/reasoning).
        #
        #   @return [Integer, nil]
        optional :max_tokens, Integer, nil?: true

        # @!attribute 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.
        #
        #   @return [Hash{Symbol=>String}, nil]
        optional :metadata, OpenAI::Internal::Type::HashOf[String], nil?: true

        # @!attribute modalities
        #   Output types that you would like the model to generate. Most models are capable
        #   of generating text, which is the default:
        #
        #   `["text"]`
        #
        #   The `gpt-4o-audio-preview` model can also be used to
        #   [generate audio](https://platform.openai.com/docs/guides/audio). To request that
        #   this model generate both text and audio responses, you can use:
        #
        #   `["text", "audio"]`
        #
        #   @return [Array<Symbol, OpenAI::Models::Chat::CompletionCreateParams::Modality>, nil]
        optional :modalities,
                 -> { OpenAI::Internal::Type::ArrayOf[enum: OpenAI::Chat::CompletionCreateParams::Modality] },
                 nil?: true

        # @!attribute n
        #   How many chat completion choices to generate for each input message. Note that
        #   you will be charged based on the number of generated tokens across all of the
        #   choices. Keep `n` as `1` to minimize costs.
        #
        #   @return [Integer, nil]
        optional :n, Integer, nil?: true

        # @!attribute parallel_tool_calls
        #   Whether to enable
        #   [parallel function calling](https://platform.openai.com/docs/guides/function-calling#configuring-parallel-function-calling)
        #   during tool use.
        #
        #   @return [Boolean, nil]
        optional :parallel_tool_calls, OpenAI::Internal::Type::Boolean

        # @!attribute prediction
        #   Static predicted output content, such as the content of a text file that is
        #   being regenerated.
        #
        #   @return [OpenAI::Models::Chat::ChatCompletionPredictionContent, nil]
        optional :prediction, -> { OpenAI::Chat::ChatCompletionPredictionContent }, nil?: true

        # @!attribute presence_penalty
        #   Number between -2.0 and 2.0. Positive values penalize new tokens based on
        #   whether they appear in the text so far, increasing the model's likelihood to
        #   talk about new topics.
        #
        #   @return [Float, nil]
        optional :presence_penalty, Float, nil?: true

        # @!attribute 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://platform.openai.com/docs/guides/prompt-caching).
        #
        #   @return [String, nil]
        optional :prompt_cache_key, String

        # @!attribute reasoning_effort
        #   Constrains effort on reasoning for
        #   [reasoning models](https://platform.openai.com/docs/guides/reasoning). Currently
        #   supported values are `minimal`, `low`, `medium`, and `high`. Reducing reasoning
        #   effort can result in faster responses and fewer tokens used on reasoning in a
        #   response.
        #
        #   Note: The `gpt-5-pro` model defaults to (and only supports) `high` reasoning
        #   effort.
        #
        #   @return [Symbol, OpenAI::Models::ReasoningEffort, nil]
        optional :reasoning_effort, enum: -> { OpenAI::ReasoningEffort }, nil?: true

        # @!attribute response_format
        #   An object specifying the format that the model must output.
        #
        #   Setting to `{ "type": "json_schema", "json_schema": {...} }` enables Structured
        #   Outputs which ensures the model will match your supplied JSON schema. Learn more
        #   in the
        #   [Structured Outputs guide](https://platform.openai.com/docs/guides/structured-outputs).
        #
        #   Setting to `{ "type": "json_object" }` enables the older JSON mode, which
        #   ensures the message the model generates is valid JSON. Using `json_schema` is
        #   preferred for models that support it.
        #
        #   @return [OpenAI::Models::ResponseFormatText, OpenAI::Models::ResponseFormatJSONSchema, OpenAI::StructuredOutput::JsonSchemaConverter, OpenAI::Models::ResponseFormatJSONObject, nil]
        optional :response_format, union: -> { OpenAI::Chat::CompletionCreateParams::ResponseFormat }

        # @!attribute 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. We recommend hashing their username or email address, in
        #   order to avoid sending us any identifying information.
        #   [Learn more](https://platform.openai.com/docs/guides/safety-best-practices#safety-identifiers).
        #
        #   @return [String, nil]
        optional :safety_identifier, String

        # @!attribute seed
        #   @deprecated
        #
        #   This feature is in Beta. If specified, our system will make a best effort to
        #   sample deterministically, such that repeated requests with the same `seed` and
        #   parameters should return the same result. Determinism is not guaranteed, and you
        #   should refer to the `system_fingerprint` response parameter to monitor changes
        #   in the backend.
        #
        #   @return [Integer, nil]
        optional :seed, Integer, nil?: true

        # @!attribute 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://platform.openai.com/docs/guides/flex-processing)' or
        #     '[priority](https://openai.com/api-priority-processing/)', then the request
        #     will be processed with the corresponding service tier.
        #   - 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.
        #
        #   @return [Symbol, OpenAI::Models::Chat::CompletionCreateParams::ServiceTier, nil]
        optional :service_tier, enum: -> { OpenAI::Chat::CompletionCreateParams::ServiceTier }, nil?: true

        # @!attribute stop
        #   Not supported with latest reasoning models `o3` and `o4-mini`.
        #
        #   Up to 4 sequences where the API will stop generating further tokens. The
        #   returned text will not contain the stop sequence.
        #
        #   @return [String, Array<String>, nil]
        optional :stop, union: -> { OpenAI::Chat::CompletionCreateParams::Stop }, nil?: true

        # @!attribute store
        #   Whether or not to store the output of this chat completion request for use in
        #   our [model distillation](https://platform.openai.com/docs/guides/distillation)
        #   or [evals](https://platform.openai.com/docs/guides/evals) products.
        #
        #   Supports text and image inputs. Note: image inputs over 8MB will be dropped.
        #
        #   @return [Boolean, nil]
        optional :store, OpenAI::Internal::Type::Boolean, nil?: true

        # @!attribute stream_options
        #   Options for streaming response. Only set this when you set `stream: true`.
        #
        #   @return [OpenAI::Models::Chat::ChatCompletionStreamOptions, nil]
        optional :stream_options, -> { OpenAI::Chat::ChatCompletionStreamOptions }, nil?: true

        # @!attribute 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.
        #
        #   @return [Float, nil]
        optional :temperature, Float, nil?: true

        # @!attribute tool_choice
        #   Controls which (if any) tool is called by the model. `none` means the model will
        #   not call any tool and instead generates a message. `auto` means the model can
        #   pick between generating a message or calling one or more tools. `required` means
        #   the model must call one or more tools. Specifying a particular tool via
        #   `{"type": "function", "function": {"name": "my_function"}}` forces the model to
        #   call that tool.
        #
        #   `none` is the default when no tools are present. `auto` is the default if tools
        #   are present.
        #
        #   @return [Symbol, OpenAI::Models::Chat::ChatCompletionToolChoiceOption::Auto, OpenAI::Models::Chat::ChatCompletionAllowedToolChoice, OpenAI::Models::Chat::ChatCompletionNamedToolChoice, OpenAI::Models::Chat::ChatCompletionNamedToolChoiceCustom, nil]
        optional :tool_choice, union: -> { OpenAI::Chat::ChatCompletionToolChoiceOption }

        # @!attribute tools
        #   A list of tools the model may call. You can provide either
        #   [custom tools](https://platform.openai.com/docs/guides/function-calling#custom-tools)
        #   or [function tools](https://platform.openai.com/docs/guides/function-calling).
        #
        #   @return [Array<OpenAI::Models::Chat::ChatCompletionTool, OpenAI::StructuredOutput::JsonSchemaConverter>, nil]
        optional :tools,
                 -> {
                   OpenAI::Internal::Type::ArrayOf[union: OpenAI::UnionOf[
                     OpenAI::Chat::ChatCompletionTool, OpenAI::StructuredOutput::JsonSchemaConverter
                   ]]
                 }

        # @!attribute top_logprobs
        #   An integer between 0 and 20 specifying the number of most likely tokens to
        #   return at each token position, each with an associated log probability.
        #   `logprobs` must be set to `true` if this parameter is used.
        #
        #   @return [Integer, nil]
        optional :top_logprobs, Integer, nil?: true

        # @!attribute 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.
        #
        #   @return [Float, nil]
        optional :top_p, Float, nil?: true

        # @!attribute user
        #   @deprecated
        #
        #   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://platform.openai.com/docs/guides/safety-best-practices#safety-identifiers).
        #
        #   @return [String, nil]
        optional :user, String

        # @!attribute verbosity
        #   Constrains the verbosity of the model's response. Lower values will result in
        #   more concise responses, while higher values will result in more verbose
        #   responses. Currently supported values are `low`, `medium`, and `high`.
        #
        #   @return [Symbol, OpenAI::Models::Chat::CompletionCreateParams::Verbosity, nil]
        optional :verbosity, enum: -> { OpenAI::Chat::CompletionCreateParams::Verbosity }, nil?: true

        # @!attribute web_search_options
        #   This tool searches the web for relevant results to use in a response. Learn more
        #   about the
        #   [web search tool](https://platform.openai.com/docs/guides/tools-web-search?api-mode=chat).
        #
        #   @return [OpenAI::Models::Chat::CompletionCreateParams::WebSearchOptions, nil]
        optional :web_search_options, -> { OpenAI::Chat::CompletionCreateParams::WebSearchOptions }

        # @!method initialize(messages:, model:, audio: nil, frequency_penalty: nil, function_call: nil, functions: nil, logit_bias: nil, logprobs: nil, max_completion_tokens: nil, max_tokens: nil, metadata: nil, modalities: nil, n: nil, parallel_tool_calls: nil, prediction: nil, presence_penalty: nil, prompt_cache_key: nil, reasoning_effort: nil, response_format: nil, safety_identifier: nil, seed: nil, service_tier: nil, stop: nil, store: nil, stream_options: nil, temperature: nil, tool_choice: nil, tools: nil, top_logprobs: nil, top_p: nil, user: nil, verbosity: nil, web_search_options: nil, request_options: {})
        #   Some parameter documentations has been truncated, see
        #   {OpenAI::Models::Chat::CompletionCreateParams} for more details.
        #
        #   @param messages [Array<OpenAI::Models::Chat::ChatCompletionDeveloperMessageParam, OpenAI::Models::Chat::ChatCompletionSystemMessageParam, OpenAI::Models::Chat::ChatCompletionUserMessageParam, OpenAI::Models::Chat::ChatCompletionAssistantMessageParam, OpenAI::Models::Chat::ChatCompletionToolMessageParam, OpenAI::Models::Chat::ChatCompletionFunctionMessageParam>] A list of messages comprising the conversation so far. Depending on the
        #
        #   @param model [String, Symbol, OpenAI::Models::ChatModel] Model ID used to generate the response, like `gpt-4o` or `o3`. OpenAI
        #
        #   @param audio [OpenAI::Models::Chat::ChatCompletionAudioParam, nil] Parameters for audio output. Required when audio output is requested with
        #
        #   @param frequency_penalty [Float, nil] Number between -2.0 and 2.0. Positive values penalize new tokens based on
        #
        #   @param function_call [Symbol, OpenAI::Models::Chat::CompletionCreateParams::FunctionCall::FunctionCallMode, OpenAI::Models::Chat::ChatCompletionFunctionCallOption] Deprecated in favor of `tool_choice`.
        #
        #   @param functions [Array<OpenAI::Models::Chat::CompletionCreateParams::Function>] Deprecated in favor of `tools`.
        #
        #   @param logit_bias [Hash{Symbol=>Integer}, nil] Modify the likelihood of specified tokens appearing in the completion.
        #
        #   @param logprobs [Boolean, nil] Whether to return log probabilities of the output tokens or not. If true,
        #
        #   @param max_completion_tokens [Integer, nil] An upper bound for the number of tokens that can be generated for a completion,
        #
        #   @param max_tokens [Integer, nil] The maximum number of [tokens](/tokenizer) that can be generated in the
        #
        #   @param metadata [Hash{Symbol=>String}, nil] Set of 16 key-value pairs that can be attached to an object. This can be
        #
        #   @param modalities [Array<Symbol, OpenAI::Models::Chat::CompletionCreateParams::Modality>, nil] Output types that you would like the model to generate.
        #
        #   @param n [Integer, nil] How many chat completion choices to generate for each input message. Note that y
        #
        #   @param parallel_tool_calls [Boolean] Whether to enable [parallel function calling](https://platform.openai.com/docs/g
        #
        #   @param prediction [OpenAI::Models::Chat::ChatCompletionPredictionContent, nil] Static predicted output content, such as the content of a text file that is
        #
        #   @param presence_penalty [Float, nil] Number between -2.0 and 2.0. Positive values penalize new tokens based on
        #
        #   @param prompt_cache_key [String] Used by OpenAI to cache responses for similar requests to optimize your cache hi
        #
        #   @param reasoning_effort [Symbol, OpenAI::Models::ReasoningEffort, nil] Constrains effort on reasoning for
        #
        #   @param response_format [OpenAI::Models::ResponseFormatText, OpenAI::Models::ResponseFormatJSONSchema, OpenAI::StructuredOutput::JsonSchemaConverter, OpenAI::Models::ResponseFormatJSONObject] An object specifying the format that the model must output.
        #
        #   @param safety_identifier [String] A stable identifier used to help detect users of your application that may be vi
        #
        #   @param seed [Integer, nil] This feature is in Beta.
        #
        #   @param service_tier [Symbol, OpenAI::Models::Chat::CompletionCreateParams::ServiceTier, nil] Specifies the processing type used for serving the request.
        #
        #   @param stop [String, Array<String>, nil] Not supported with latest reasoning models `o3` and `o4-mini`.
        #
        #   @param store [Boolean, nil] Whether or not to store the output of this chat completion request for
        #
        #   @param stream_options [OpenAI::Models::Chat::ChatCompletionStreamOptions, nil] Options for streaming response. Only set this when you set `stream: true`.
        #
        #   @param temperature [Float, nil] What sampling temperature to use, between 0 and 2. Higher values like 0.8 will m
        #
        #   @param tool_choice [Symbol, OpenAI::Models::Chat::ChatCompletionToolChoiceOption::Auto, OpenAI::Models::Chat::ChatCompletionAllowedToolChoice, OpenAI::Models::Chat::ChatCompletionNamedToolChoice, OpenAI::Models::Chat::ChatCompletionNamedToolChoiceCustom] Controls which (if any) tool is called by the model.
        #
        #   @param tools [Array<OpenAI::StructuredOutput::JsonSchemaConverter, OpenAI::Models::Chat::ChatCompletionFunctionTool, OpenAI::Models::Chat::ChatCompletionCustomTool>] A list of tools the model may call. You can provide either
        #
        #   @param top_logprobs [Integer, nil] An integer between 0 and 20 specifying the number of most likely tokens to
        #
        #   @param top_p [Float, nil] An alternative to sampling with temperature, called nucleus sampling,
        #
        #   @param user [String] This field is being replaced by `safety_identifier` and `prompt_cache_key`. Use
        #
        #   @param verbosity [Symbol, OpenAI::Models::Chat::CompletionCreateParams::Verbosity, nil] Constrains the verbosity of the model's response. Lower values will result in
        #
        #   @param web_search_options [OpenAI::Models::Chat::CompletionCreateParams::WebSearchOptions] This tool searches the web for relevant results to use in a response.
        #
        #   @param request_options [OpenAI::RequestOptions, Hash{Symbol=>Object}]

        # Model ID used to generate the response, like `gpt-4o` or `o3`. OpenAI offers a
        # wide range of models with different capabilities, performance characteristics,
        # and price points. Refer to the
        # [model guide](https://platform.openai.com/docs/models) to browse and compare
        # available models.
        module Model
          extend OpenAI::Internal::Type::Union

          variant String

          # Model ID used to generate the response, like `gpt-4o` or `o3`. OpenAI
          # offers a wide range of models with different capabilities, performance
          # characteristics, and price points. Refer to the [model guide](https://platform.openai.com/docs/models)
          # to browse and compare available models.
          variant enum: -> { OpenAI::ChatModel }

          # @!method self.variants
          #   @return [Array(String, Symbol, OpenAI::Models::ChatModel)]
        end

        # @deprecated
        #
        # Deprecated in favor of `tool_choice`.
        #
        # Controls which (if any) function is called by the model.
        #
        # `none` means the model will not call a function and instead generates a message.
        #
        # `auto` means the model can pick between generating a message or calling a
        # function.
        #
        # Specifying a particular function via `{"name": "my_function"}` forces the model
        # to call that function.
        #
        # `none` is the default when no functions are present. `auto` is the default if
        # functions are present.
        module FunctionCall
          extend OpenAI::Internal::Type::Union

          # `none` means the model will not call a function and instead generates a message. `auto` means the model can pick between generating a message or calling a function.
          variant enum: -> { OpenAI::Chat::CompletionCreateParams::FunctionCall::FunctionCallMode }

          # Specifying a particular function via `{"name": "my_function"}` forces the model to call that function.
          variant -> { OpenAI::Chat::ChatCompletionFunctionCallOption }

          # `none` means the model will not call a function and instead generates a message.
          # `auto` means the model can pick between generating a message or calling a
          # function.
          module FunctionCallMode
            extend OpenAI::Internal::Type::Enum

            NONE = :none
            AUTO = :auto

            # @!method self.values
            #   @return [Array<Symbol>]
          end

          # @!method self.variants
          #   @return [Array(Symbol, OpenAI::Models::Chat::CompletionCreateParams::FunctionCall::FunctionCallMode, OpenAI::Models::Chat::ChatCompletionFunctionCallOption)]
        end

        # @deprecated
        class Function < OpenAI::Internal::Type::BaseModel
          # @!attribute name
          #   The name of the function to be called. Must be a-z, A-Z, 0-9, or contain
          #   underscores and dashes, with a maximum length of 64.
          #
          #   @return [String]
          required :name, String

          # @!attribute description
          #   A description of what the function does, used by the model to choose when and
          #   how to call the function.
          #
          #   @return [String, nil]
          optional :description, String

          # @!attribute parameters
          #   The parameters the functions accepts, described as a JSON Schema object. See the
          #   [guide](https://platform.openai.com/docs/guides/function-calling) for examples,
          #   and the
          #   [JSON Schema reference](https://json-schema.org/understanding-json-schema/) for
          #   documentation about the format.
          #
          #   Omitting `parameters` defines a function with an empty parameter list.
          #
          #   @return [Hash{Symbol=>Object}, nil]
          optional :parameters, OpenAI::Internal::Type::HashOf[OpenAI::Internal::Type::Unknown]

          # @!method initialize(name:, description: nil, parameters: nil)
          #   Some parameter documentations has been truncated, see
          #   {OpenAI::Models::Chat::CompletionCreateParams::Function} for more details.
          #
          #   @param name [String] The name of the function to be called. Must be a-z, A-Z, 0-9, or contain undersc
          #
          #   @param description [String] A description of what the function does, used by the model to choose when and ho
          #
          #   @param parameters [Hash{Symbol=>Object}] The parameters the functions accepts, described as a JSON Schema object. See the
        end

        module Modality
          extend OpenAI::Internal::Type::Enum

          TEXT = :text
          AUDIO = :audio

          # @!method self.values
          #   @return [Array<Symbol>]
        end

        # An object specifying the format that the model must output.
        #
        # Setting to `{ "type": "json_schema", "json_schema": {...} }` enables Structured
        # Outputs which ensures the model will match your supplied JSON schema. Learn more
        # in the
        # [Structured Outputs guide](https://platform.openai.com/docs/guides/structured-outputs).
        #
        # Setting to `{ "type": "json_object" }` enables the older JSON mode, which
        # ensures the message the model generates is valid JSON. Using `json_schema` is
        # preferred for models that support it.
        module ResponseFormat
          extend OpenAI::Internal::Type::Union

          # Default response format. Used to generate text responses.
          variant -> { OpenAI::ResponseFormatText }

          # JSON Schema response format. Used to generate structured JSON responses.
          # Learn more about [Structured Outputs](https://platform.openai.com/docs/guides/structured-outputs).
          variant -> { OpenAI::ResponseFormatJSONSchema }

          # An {OpenAI::BaseModel} can be provided and implicitly converted into {OpenAI::Models::ResponseFormatJSONSchema}.
          # See examples for more details.
          #
          # Learn more about [Structured Outputs](https://platform.openai.com/docs/guides/structured-outputs).
          variant -> { OpenAI::StructuredOutput::JsonSchemaConverter }

          # JSON object response format. An older method of generating JSON responses.
          # Using `json_schema` is recommended for models that support it. Note that the
          # model will not generate JSON without a system or user message instructing it
          # to do so.
          variant -> { OpenAI::ResponseFormatJSONObject }

          # @!method self.variants
          #   @return [Array(OpenAI::Models::ResponseFormatText, OpenAI::Models::ResponseFormatJSONSchema, OpenAI::Models::ResponseFormatJSONObject)]
        end

        # 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://platform.openai.com/docs/guides/flex-processing)' or
        #   '[priority](https://openai.com/api-priority-processing/)', then the request
        #   will be processed with the corresponding service tier.
        # - 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.
        module ServiceTier
          extend OpenAI::Internal::Type::Enum

          AUTO = :auto
          DEFAULT = :default
          FLEX = :flex
          SCALE = :scale
          PRIORITY = :priority

          # @!method self.values
          #   @return [Array<Symbol>]
        end

        # Not supported with latest reasoning models `o3` and `o4-mini`.
        #
        # Up to 4 sequences where the API will stop generating further tokens. The
        # returned text will not contain the stop sequence.
        module Stop
          extend OpenAI::Internal::Type::Union

          variant String

          variant -> { OpenAI::Models::Chat::CompletionCreateParams::Stop::StringArray }

          # @!method self.variants
          #   @return [Array(String, Array<String>)]

          # @type [OpenAI::Internal::Type::Converter]
          StringArray = OpenAI::Internal::Type::ArrayOf[String]
        end

        # Constrains the verbosity of the model's response. Lower values will result in
        # more concise responses, while higher values will result in more verbose
        # responses. Currently supported values are `low`, `medium`, and `high`.
        module Verbosity
          extend OpenAI::Internal::Type::Enum

          LOW = :low
          MEDIUM = :medium
          HIGH = :high

          # @!method self.values
          #   @return [Array<Symbol>]
        end

        class WebSearchOptions < OpenAI::Internal::Type::BaseModel
          # @!attribute search_context_size
          #   High level guidance for the amount of context window space to use for the
          #   search. One of `low`, `medium`, or `high`. `medium` is the default.
          #
          #   @return [Symbol, OpenAI::Models::Chat::CompletionCreateParams::WebSearchOptions::SearchContextSize, nil]
          optional :search_context_size,
                   enum: -> { OpenAI::Chat::CompletionCreateParams::WebSearchOptions::SearchContextSize }

          # @!attribute user_location
          #   Approximate location parameters for the search.
          #
          #   @return [OpenAI::Models::Chat::CompletionCreateParams::WebSearchOptions::UserLocation, nil]
          optional :user_location,
                   -> { OpenAI::Chat::CompletionCreateParams::WebSearchOptions::UserLocation },
                   nil?: true

          # @!method initialize(search_context_size: nil, user_location: nil)
          #   Some parameter documentations has been truncated, see
          #   {OpenAI::Models::Chat::CompletionCreateParams::WebSearchOptions} for more
          #   details.
          #
          #   This tool searches the web for relevant results to use in a response. Learn more
          #   about the
          #   [web search tool](https://platform.openai.com/docs/guides/tools-web-search?api-mode=chat).
          #
          #   @param search_context_size [Symbol, OpenAI::Models::Chat::CompletionCreateParams::WebSearchOptions::SearchContextSize] High level guidance for the amount of context window space to use for the
          #
          #   @param user_location [OpenAI::Models::Chat::CompletionCreateParams::WebSearchOptions::UserLocation, nil] Approximate location parameters for the search.

          # High level guidance for the amount of context window space to use for the
          # search. One of `low`, `medium`, or `high`. `medium` is the default.
          #
          # @see OpenAI::Models::Chat::CompletionCreateParams::WebSearchOptions#search_context_size
          module SearchContextSize
            extend OpenAI::Internal::Type::Enum

            LOW = :low
            MEDIUM = :medium
            HIGH = :high

            # @!method self.values
            #   @return [Array<Symbol>]
          end

          # @see OpenAI::Models::Chat::CompletionCreateParams::WebSearchOptions#user_location
          class UserLocation < OpenAI::Internal::Type::BaseModel
            # @!attribute approximate
            #   Approximate location parameters for the search.
            #
            #   @return [OpenAI::Models::Chat::CompletionCreateParams::WebSearchOptions::UserLocation::Approximate]
            required :approximate,
                     -> { OpenAI::Chat::CompletionCreateParams::WebSearchOptions::UserLocation::Approximate }

            # @!attribute type
            #   The type of location approximation. Always `approximate`.
            #
            #   @return [Symbol, :approximate]
            required :type, const: :approximate

            # @!method initialize(approximate:, type: :approximate)
            #   Some parameter documentations has been truncated, see
            #   {OpenAI::Models::Chat::CompletionCreateParams::WebSearchOptions::UserLocation}
            #   for more details.
            #
            #   Approximate location parameters for the search.
            #
            #   @param approximate [OpenAI::Models::Chat::CompletionCreateParams::WebSearchOptions::UserLocation::Approximate] Approximate location parameters for the search.
            #
            #   @param type [Symbol, :approximate] The type of location approximation. Always `approximate`.

            # @see OpenAI::Models::Chat::CompletionCreateParams::WebSearchOptions::UserLocation#approximate
            class Approximate < OpenAI::Internal::Type::BaseModel
              # @!attribute city
              #   Free text input for the city of the user, e.g. `San Francisco`.
              #
              #   @return [String, nil]
              optional :city, String

              # @!attribute country
              #   The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of
              #   the user, e.g. `US`.
              #
              #   @return [String, nil]
              optional :country, String

              # @!attribute region
              #   Free text input for the region of the user, e.g. `California`.
              #
              #   @return [String, nil]
              optional :region, String

              # @!attribute timezone
              #   The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the
              #   user, e.g. `America/Los_Angeles`.
              #
              #   @return [String, nil]
              optional :timezone, String

              # @!method initialize(city: nil, country: nil, region: nil, timezone: nil)
              #   Some parameter documentations has been truncated, see
              #   {OpenAI::Models::Chat::CompletionCreateParams::WebSearchOptions::UserLocation::Approximate}
              #   for more details.
              #
              #   Approximate location parameters for the search.
              #
              #   @param city [String] Free text input for the city of the user, e.g. `San Francisco`.
              #
              #   @param country [String] The two-letter
              #
              #   @param region [String] Free text input for the region of the user, e.g. `California`.
              #
              #   @param timezone [String] The [IANA timezone](https://timeapi.io/documentation/iana-timezones)
            end
          end
        end
      end
    end
  end
end
