firebase-ios-sdk/GeminiLanguageModel/Sources/GeminiAPIDataModels/GenerateContent/GenerationConfig.swift

// Copyright 2026 Google LLC
//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
//
//      http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.

import Foundation

/// An internal data model for `GenerationConfig`.
///
/// ### Gemini Developer API
///
/// Type: `GoogleAiGenerativelanguageV1betaGenerationConfig`
///
/// Configuration options for model generation and outputs. Not all parameters
/// are configurable for every model.
///
/// ### Gemini Enterprise API
///
/// Type: `GoogleCloudAiplatformV1beta1GenerationConfig`
///
/// Configuration for content generation.
///
/// This message contains all the parameters that control how the model generates
/// content. It allows you to influence the randomness, length, and structure of
/// the output.
package struct GenerationConfig: Codable, Sendable, Equatable, Hashable {
  /// Optional. Number of generated responses to return. If unset, this will default
  ///
  /// ### Gemini Developer API
  ///
  /// Optional. Number of generated responses to return. If unset, this will default
  /// to 1. Please note that this doesn't work for previous generation
  /// models (Gemini 1.0 family)
  ///
  /// ### Gemini Enterprise API
  ///
  /// Optional. The number of candidate responses to generate.
  ///
  /// A higher `candidate_count` can provide more options to choose from, but it
  /// also consumes more resources. This can be useful for generating a variety
  /// of responses and selecting the best one.
  package let candidateCount: Int?

  /// Optional. The set of character sequences (up to 5) that will stop output generation.
  ///
  /// ### Gemini Developer API
  ///
  /// Optional. The set of character sequences (up to 5) that will stop output generation.
  /// If specified, the API will stop at the first appearance of a
  /// `stop_sequence`. The stop sequence will not be included as part of the
  /// response.
  ///
  /// ### Gemini Enterprise API
  ///
  /// Optional. A list of character sequences that will stop the model from
  /// generating further tokens. If a stop sequence is generated, the output
  /// will end at that point. This is useful for controlling the length and
  /// structure of the output. For example, you can use ["\n", "###"] to stop
  /// generation at a new line or a specific marker.
  package let stopSequences: [String]?

  /// Optional. The maximum number of tokens to include in a response candidate.
  ///
  /// ### Gemini Developer API
  ///
  /// Optional. The maximum number of tokens to include in a response candidate.
  ///
  /// Note: The default value varies by model, see the `Model.output_token_limit`
  /// attribute of the `Model` returned from the `getModel` function.
  ///
  /// ### Gemini Enterprise API
  ///
  /// Optional. The maximum number of tokens to generate in the response.
  ///
  /// A token is approximately four characters. The default value varies by
  /// model. This parameter can be used to control the length of the generated
  /// text and prevent overly long responses.
  package let maxOutputTokens: Int?

  /// Optional. Controls the randomness of the output.
  ///
  /// ### Gemini Developer API
  ///
  /// Optional. Controls the randomness of the output.
  ///
  /// Note: The default value varies by model, see the `Model.temperature`
  /// attribute of the `Model` returned from the `getModel` function.
  ///
  /// Values can range from [0.0, 2.0].
  ///
  /// ### Gemini Enterprise API
  ///
  /// Optional. Controls the randomness of the output. A higher temperature
  /// results in more creative and diverse responses, while a lower temperature
  /// makes the output more predictable and focused. The valid range is (0.0,
  /// 2.0].
  package let temperature: Double?

  /// Optional. The maximum cumulative probability of tokens to consider when sampling.
  ///
  /// ### Gemini Developer API
  ///
  /// Optional. The maximum cumulative probability of tokens to consider when sampling.
  ///
  /// The model uses combined Top-k and Top-p (nucleus) sampling.
  ///
  /// Tokens are sorted based on their assigned probabilities so that only the
  /// most likely tokens are considered. Top-k sampling directly limits the
  /// maximum number of tokens to consider, while Nucleus sampling limits the
  /// number of tokens based on the cumulative probability.
  ///
  /// Note: The default value varies by `Model` and is specified by
  /// the`Model.top_p` attribute returned from the `getModel` function. An empty
  /// `top_k` attribute indicates that the model doesn't apply top-k sampling
  /// and doesn't allow setting `top_k` on requests.
  ///
  /// ### Gemini Enterprise API
  ///
  /// Optional. Specifies the nucleus sampling threshold. The model considers
  /// only the smallest set of tokens whose cumulative probability is at least
  /// `top_p`. This helps generate more diverse and less repetitive responses.
  /// For example, a `top_p` of 0.9 means the model considers tokens until the
  /// cumulative probability of the tokens to select from reaches 0.9. It's
  /// recommended to adjust either temperature or `top_p`, but not both.
  package let topP: Double?

  /// Optional. The maximum number of tokens to consider when sampling.
  ///
  /// ### Gemini Developer API
  ///
  /// Optional. The maximum number of tokens to consider when sampling.
  ///
  /// Gemini models use Top-p (nucleus) sampling or a combination of Top-k and
  /// nucleus sampling. Top-k sampling considers the set of `top_k` most probable
  /// tokens. Models running with nucleus sampling don't allow top_k setting.
  ///
  /// Note: The default value varies by `Model` and is specified by
  /// the`Model.top_p` attribute returned from the `getModel` function. An empty
  /// `top_k` attribute indicates that the model doesn't apply top-k sampling
  /// and doesn't allow setting `top_k` on requests.
  ///
  /// ### Gemini Enterprise API
  ///
  /// Optional. Specifies the top-k sampling threshold. The model considers only
  /// the top k most probable tokens for the next token. This can be useful for
  /// generating more coherent and less random text. For example, a `top_k` of 40
  /// means the model will choose the next word from the 40 most likely words.
  package let topK: Int?

  /// Optional. Seed used in decoding. If not set, the request uses a randomly generated
  ///
  /// ### Gemini Developer API
  ///
  /// Optional. Seed used in decoding. If not set, the request uses a randomly generated
  /// seed.
  ///
  /// ### Gemini Enterprise API
  ///
  /// Optional. A seed for the random number generator.
  ///
  /// By setting a seed, you can make the model's output mostly deterministic.
  /// For a given prompt and parameters (like temperature, top_p, etc.), the
  /// model will produce the same response every time. However, it's not a
  /// guaranteed absolute deterministic behavior. This is different from
  /// parameters like `temperature`, which control the *level* of randomness.
  /// `seed` ensures that the "random" choices the model makes are the same on
  /// every run, making it essential for testing and ensuring reproducible
  /// results.
  package let seed: Int?

  /// Optional. MIME type of the generated candidate text.
  ///
  /// ### Gemini Developer API
  ///
  /// Optional. MIME type of the generated candidate text.
  /// Supported MIME types are:
  /// `text/plain`: (default) Text output.
  /// `application/json`: JSON response in the response candidates.
  /// `text/x.enum`: ENUM as a string response in the response candidates.
  /// Refer to the
  /// [docs](https://ai.google.dev/gemini-api/docs/prompting_with_media#plain_text_formats)
  /// for a list of all supported text MIME types.
  ///
  /// ### Gemini Enterprise API
  ///
  /// Optional. The IANA standard MIME type of the response. The model will
  /// generate output that conforms to this MIME type. Supported values include
  /// 'text/plain' (default) and 'application/json'. The model needs to be
  /// prompted to output the appropriate response type, otherwise the behavior is
  /// undefined.
  /// Deprecated: Use `response_format` instead.
  package let responseMimeType: String?

  /// Optional. Output schema of the generated candidate text. Schemas must be a
  ///
  /// ### Gemini Developer API
  ///
  /// Optional. Output schema of the generated candidate text. Schemas must be a
  /// subset of the [OpenAPI schema](https://spec.openapis.org/oas/v3.0.3#schema)
  /// and can be objects, primitives or arrays.
  ///
  /// If set, a compatible `response_mime_type` must also be set.
  /// Compatible MIME types:
  /// `application/json`: Schema for JSON response.
  /// Refer to the [JSON text generation
  /// guide](https://ai.google.dev/gemini-api/docs/json-mode) for more details.
  ///
  /// ### Gemini Enterprise API
  ///
  /// Optional. Lets you to specify a schema for the model's response, ensuring
  /// that the output conforms to a particular structure. This is useful for
  /// generating structured data such as JSON. The schema is a subset of the
  /// [OpenAPI 3.0 schema object](https://spec.openapis.org/oas/v3.0.3#schema)
  /// object.
  ///
  /// When this field is set, you must also set the `response_mime_type` to
  /// `application/json`.
  /// Deprecated: Use `response_format` instead.
  package let responseSchema: Schema?

  /// Optional. Output schema of the generated response.
  ///
  /// ### Gemini Developer API
  ///
  /// Optional. Output schema of the generated response. This is an alternative to
  /// `response_schema` that accepts [JSON Schema](https://json-schema.org/).
  ///
  /// If set, `response_schema` must be omitted, but `response_mime_type` is
  /// required.
  ///
  /// While the full JSON Schema may be sent, not all features are supported.
  /// Specifically, only the following properties are supported:
  ///
  /// - `$id`
  /// - `$defs`
  /// - `$ref`
  /// - `$anchor`
  /// - `type`
  /// - `format`
  /// - `title`
  /// - `description`
  /// - `enum` (for strings and numbers)
  /// - `items`
  /// - `prefixItems`
  /// - `minItems`
  /// - `maxItems`
  /// - `minimum`
  /// - `maximum`
  /// - `anyOf`
  /// - `oneOf` (interpreted the same as `anyOf`)
  /// - `properties`
  /// - `additionalProperties`
  /// - `required`
  ///
  /// The non-standard `propertyOrdering` property may also be set.
  ///
  /// Cyclic references are unrolled to a limited degree and, as such, may only
  /// be used within non-required properties. (Nullable properties are not
  /// sufficient.) If `$ref` is set on a sub-schema, no other properties, except
  /// for than those starting as a `$`, may be set.
  ///
  /// ### Gemini Enterprise API
  ///
  /// Optional. When this field is set, `response_schema` must be omitted and `response_mime_type`
  /// must be set to `application/json`.
  /// Deprecated: Use `response_format` instead.
  package let responseJsonSchema: JSONValue?

  /// Optional. Presence penalty applied to the next token's logprobs if the token has
  ///
  /// ### Gemini Developer API
  ///
  /// Optional. Presence penalty applied to the next token's logprobs if the token has
  /// already been seen in the response.
  ///
  /// This penalty is binary on/off and not dependant on the number of times the
  /// token is used (after the first). Use
  /// frequency_penalty
  /// for a penalty that increases with each use.
  ///
  /// A positive penalty will discourage the use of tokens that have already
  /// been used in the response, increasing the vocabulary.
  ///
  /// A negative penalty will encourage the use of tokens that have already been
  /// used in the response, decreasing the vocabulary.
  ///
  /// ### Gemini Enterprise API
  ///
  /// Optional. Penalizes tokens that have already appeared in the generated
  /// text. A positive value encourages the model to generate more diverse and
  /// less repetitive text. Valid values can range from [-2.0, 2.0].
  package let presencePenalty: Double?

  /// Optional. Frequency penalty applied to the next token's logprobs, multiplied by the
  ///
  /// ### Gemini Developer API
  ///
  /// Optional. Frequency penalty applied to the next token's logprobs, multiplied by the
  /// number of times each token has been seen in the respponse so far.
  ///
  /// A positive penalty will discourage the use of tokens that have already
  /// been used, proportional to the number of times the token has been used:
  /// The more a token is used, the more difficult it is for the model to use
  /// that token again increasing the vocabulary of responses.
  ///
  /// Caution: A _negative_ penalty will encourage the model to reuse tokens
  /// proportional to the number of times the token has been used. Small
  /// negative values will reduce the vocabulary of a response. Larger negative
  /// values will cause the model to start repeating a common token  until it
  /// hits the max_output_tokens
  /// limit.
  ///
  /// ### Gemini Enterprise API
  ///
  /// Optional. Penalizes tokens based on their frequency in the generated text.
  /// A positive value helps to reduce the repetition of words and phrases.
  /// Valid values can range from [-2.0, 2.0].
  package let frequencyPenalty: Double?

  /// Optional. If true, export the logprobs results in response.
  ///
  /// ### Gemini Developer API
  ///
  /// Optional. If true, export the logprobs results in response.
  ///
  /// ### Gemini Enterprise API
  ///
  /// Optional. If set to true, the log probabilities of the output tokens are
  /// returned.
  ///
  /// Log probabilities are the logarithm of the probability of a token appearing
  /// in the output. A higher log probability means the token is more likely to
  /// be generated. This can be useful for analyzing the model's confidence in
  /// its own output and for debugging.
  package let responseLogprobs: Bool?

  /// Optional. Only valid if response_logprobs=True.
  ///
  /// ### Gemini Developer API
  ///
  /// Optional. Only valid if response_logprobs=True.
  /// This sets the number of top logprobs, including the chosen candidate, to
  /// return at each decoding step in the Candidate.logprobs_result. The
  /// number must be in the range of [0, 20].
  ///
  /// ### Gemini Enterprise API
  ///
  /// Optional. The number of top log probabilities to return for each token.
  ///
  /// This can be used to see which other tokens were considered likely
  /// candidates for a given position. A higher value will return more options,
  /// but it will also increase the size of the response.
  package let logprobs: Int?

  /// Optional. Enables enhanced civic answers. It may not be available for all models.
  ///
  /// ### Gemini Developer API
  ///
  /// Optional. Enables enhanced civic answers. It may not be available for all models.
  ///
  /// ### Gemini Enterprise API
  ///
  /// > Important: This property is not supported in the Gemini Enterprise API.
  package let enableEnhancedCivicAnswers: Bool?

  /// Optional. The requested modalities of the response. Represents the set of modalities
  ///
  /// ### Gemini Developer API
  ///
  /// Optional. The requested modalities of the response. Represents the set of modalities
  /// that the model can return, and should be expected in the response. This is
  /// an exact match to the modalities of the response.
  ///
  /// A model may have multiple combinations of supported modalities. If the
  /// requested modalities do not match any of the supported combinations, an
  /// error will be returned.
  ///
  /// An empty list is equivalent to requesting only text.
  ///
  /// ### Gemini Enterprise API
  ///
  /// Optional. The modalities of the response. The model will generate a
  /// response that includes all the specified modalities. For example, if this
  /// is set to `[TEXT, IMAGE]`, the response will include both text and an
  /// image.
  package let responseModalities: [String]?

  /// Optional. The speech generation config.
  package let speechConfig: SpeechConfig?

  /// Optional. Config for thinking features.
  ///
  /// ### Gemini Developer API
  ///
  /// Optional. Config for thinking features.
  /// An error will be returned if this field is set for models that don't
  /// support thinking.
  ///
  /// ### Gemini Enterprise API
  ///
  /// Optional. Configuration for thinking features.
  /// An error will be returned if this field is set for models that don't
  /// support thinking.
  package let thinkingConfig: ThinkingConfig?

  /// Optional. Config for image generation.
  ///
  /// ### Gemini Developer API
  ///
  /// Optional. Config for image generation.
  /// An error will be returned if this field is set for models that don't
  /// support these config options.
  ///
  /// ### Gemini Enterprise API
  ///
  /// Optional. Config for image generation features.
  /// Deprecated: Use `response_format.image` instead.
  package let imageConfig: ImageConfig?

  /// Optional. If specified, the media resolution specified will be used.
  ///
  /// ### Gemini Developer API
  ///
  /// Optional. If specified, the media resolution specified will be used.
  ///
  /// ### Gemini Enterprise API
  ///
  /// Optional. The token resolution at which input media content is sampled. This is
  /// used to control the trade-off between the quality of the response and the
  /// number of tokens used to represent the media. A higher resolution allows
  /// the model to perceive more detail, which can lead to a more nuanced
  /// response, but it will also use more tokens. This does not affect the
  /// image dimensions sent to the model.
  package let mediaResolution: MediaResolution?

  /// Optional. If enabled, the model will detect emotions and adapt its responses
  ///
  /// ### Gemini Developer API
  ///
  /// Optional. If enabled, the model will detect emotions and adapt its responses
  /// accordingly.
  ///
  /// ### Gemini Enterprise API
  ///
  /// Optional. If enabled, the model will detect emotions and adapt its
  /// responses accordingly. For example, if the model detects that the user is
  /// frustrated, it may provide a more empathetic response.
  package let enableAffectiveDialog: Bool?

  /// Optional. Configuration for the response output format. Allows specifying output
  ///
  /// ### Gemini Developer API
  ///
  /// Optional. Configuration for the response output format. Allows specifying output
  /// configuration per modality (text, audio, image) in a flat structure.
  ///
  /// ### Gemini Enterprise API
  ///
  /// Optional. New response format field for the model to configure output formatting and
  /// delivery.
  package let responseFormat: ResponseFormatConfig?

  /// Optional. If enabled, audio timestamps will be included in the request to
  ///
  /// ### Gemini Developer API
  ///
  /// > Important: This property is not supported in the Gemini Developer API.
  ///
  /// ### Gemini Enterprise API
  ///
  /// Optional. If enabled, audio timestamps will be included in the request to
  /// the model. This can be useful for synchronizing audio with other modalities
  /// in the response.
  package let audioTimestamp: Bool?

  /// Creates a new `GenerationConfig`.
  ///
  /// - Parameters:
  ///   - candidateCount: Optional. Number of generated responses to return. If unset, this will default (behavior varies by backend). For more details, see ``candidateCount``.
  ///   - stopSequences: Optional. The set of character sequences (up to 5) that will stop output generation. (behavior varies by backend). For more details, see ``stopSequences``.
  ///   - maxOutputTokens: Optional. The maximum number of tokens to include in a response candidate. (behavior varies by backend). For more details, see ``maxOutputTokens``.
  ///   - temperature: Optional. Controls the randomness of the output. (behavior varies by backend). For more details, see ``temperature``.
  ///   - topP: Optional. The maximum cumulative probability of tokens to consider when sampling. (behavior varies by backend). For more details, see ``topP``.
  ///   - topK: Optional. The maximum number of tokens to consider when sampling. (behavior varies by backend). For more details, see ``topK``.
  ///   - seed: Optional. Seed used in decoding. If not set, the request uses a randomly generated (behavior varies by backend). For more details, see ``seed``.
  ///   - responseMimeType: Optional. MIME type of the generated candidate text. (behavior varies by backend). For more details, see ``responseMimeType``.
  ///   - responseSchema: Optional. Output schema of the generated candidate text. Schemas must be a (behavior varies by backend). For more details, see ``responseSchema``.
  ///   - responseJsonSchema: Optional. Output schema of the generated response. (behavior varies by backend). For more details, see ``responseJsonSchema``.
  ///   - presencePenalty: Optional. Presence penalty applied to the next token's logprobs if the token has (behavior varies by backend). For more details, see ``presencePenalty``.
  ///   - frequencyPenalty: Optional. Frequency penalty applied to the next token's logprobs, multiplied by the (behavior varies by backend). For more details, see ``frequencyPenalty``.
  ///   - responseLogprobs: Optional. If true, export the logprobs results in response. (behavior varies by backend). For more details, see ``responseLogprobs``.
  ///   - logprobs: Optional. Only valid if response_logprobs=True. (behavior varies by backend). For more details, see ``logprobs``.
  ///   - enableEnhancedCivicAnswers: Optional. Enables enhanced civic answers. It may not be available for all models. (Gemini Developer API only). For more details, see ``enableEnhancedCivicAnswers``.
  ///   - responseModalities: Optional. The requested modalities of the response. Represents the set of modalities (behavior varies by backend). For more details, see ``responseModalities``.
  ///   - speechConfig: Optional. The speech generation config.
  ///   - thinkingConfig: Optional. Config for thinking features. (behavior varies by backend). For more details, see ``thinkingConfig``.
  ///   - imageConfig: Optional. Config for image generation. (behavior varies by backend). For more details, see ``imageConfig``.
  ///   - mediaResolution: Optional. If specified, the media resolution specified will be used. (behavior varies by backend). For more details, see ``mediaResolution``.
  ///   - enableAffectiveDialog: Optional. If enabled, the model will detect emotions and adapt its responses (behavior varies by backend). For more details, see ``enableAffectiveDialog``.
  ///   - responseFormat: Optional. Configuration for the response output format. Allows specifying output (behavior varies by backend). For more details, see ``responseFormat``.
  ///   - audioTimestamp: Optional. If enabled, audio timestamps will be included in the request to (Gemini Enterprise API only). For more details, see ``audioTimestamp``.
  package init(
    candidateCount: Int? = nil,
    stopSequences: [String]? = nil,
    maxOutputTokens: Int? = nil,
    temperature: Double? = nil,
    topP: Double? = nil,
    topK: Int? = nil,
    seed: Int? = nil,
    responseMimeType: String? = nil,
    responseSchema: Schema? = nil,
    responseJsonSchema: JSONValue? = nil,
    presencePenalty: Double? = nil,
    frequencyPenalty: Double? = nil,
    responseLogprobs: Bool? = nil,
    logprobs: Int? = nil,
    enableEnhancedCivicAnswers: Bool? = nil,
    responseModalities: [String]? = nil,
    speechConfig: SpeechConfig? = nil,
    thinkingConfig: ThinkingConfig? = nil,
    imageConfig: ImageConfig? = nil,
    mediaResolution: MediaResolution? = nil,
    enableAffectiveDialog: Bool? = nil,
    responseFormat: ResponseFormatConfig? = nil,
    audioTimestamp: Bool? = nil
  ) {
    self.candidateCount = candidateCount
    self.stopSequences = stopSequences
    self.maxOutputTokens = maxOutputTokens
    self.temperature = temperature
    self.topP = topP
    self.topK = topK
    self.seed = seed
    self.responseMimeType = responseMimeType
    self.responseSchema = responseSchema
    self.responseJsonSchema = responseJsonSchema
    self.presencePenalty = presencePenalty
    self.frequencyPenalty = frequencyPenalty
    self.responseLogprobs = responseLogprobs
    self.logprobs = logprobs
    self.enableEnhancedCivicAnswers = enableEnhancedCivicAnswers
    self.responseModalities = responseModalities
    self.speechConfig = speechConfig
    self.thinkingConfig = thinkingConfig
    self.imageConfig = imageConfig
    self.mediaResolution = mediaResolution
    self.enableAffectiveDialog = enableAffectiveDialog
    self.responseFormat = responseFormat
    self.audioTimestamp = audioTimestamp
  }
  enum CodingKeys: String, CodingKey {
    case candidateCount = "candidateCount"
    case stopSequences = "stopSequences"
    case maxOutputTokens = "maxOutputTokens"
    case temperature = "temperature"
    case topP = "topP"
    case topK = "topK"
    case seed = "seed"
    case responseMimeType = "responseMimeType"
    case responseSchema = "responseSchema"
    case responseJsonSchema = "responseJsonSchema"
    case presencePenalty = "presencePenalty"
    case frequencyPenalty = "frequencyPenalty"
    case responseLogprobs = "responseLogprobs"
    case logprobs = "logprobs"
    case enableEnhancedCivicAnswers = "enableEnhancedCivicAnswers"
    case responseModalities = "responseModalities"
    case speechConfig = "speechConfig"
    case thinkingConfig = "thinkingConfig"
    case imageConfig = "imageConfig"
    case mediaResolution = "mediaResolution"
    case enableAffectiveDialog = "enableAffectiveDialog"
    case responseFormat = "responseFormat"
    case audioTimestamp = "audioTimestamp"
  }
}