Candidate.cs

/*
 * Copyright 2025 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.
 */

using System.Collections.Generic;
using Firebase.AI.Internal;

namespace Firebase.AI
{
  /// <summary>
  /// Represents the reason why the model stopped generating content.
  /// </summary>
  public enum FinishReason
  {
    /// <summary>
    /// A new and not yet supported value.
    /// </summary>
    Unknown = 0,
    /// <summary>
    /// Natural stop point of the model or provided stop sequence.
    /// </summary>
    Stop,
    /// <summary>
    /// The maximum number of tokens as specified in the request was reached.
    /// </summary>
    MaxTokens,
    /// <summary>
    /// The token generation was stopped because the response was flagged for safety reasons.
    /// </summary>
    Safety,
    /// <summary>
    /// The token generation was stopped because the response was flagged for unauthorized citations.
    /// </summary>
    Recitation,
    /// <summary>
    /// All other reasons that stopped token generation.
    /// </summary>
    Other,
    /// <summary>
    /// Token generation was stopped because the response contained forbidden terms.
    /// </summary>
    Blocklist,
    /// <summary>
    /// Token generation was stopped because the response contained potentially prohibited content.
    /// </summary>
    ProhibitedContent,
    /// <summary>
    /// Token generation was stopped because of Sensitive Personally Identifiable Information (SPII).
    /// </summary>
    SPII,
    /// <summary>
    /// Token generation was stopped because the function call generated by the model was invalid.
    /// </summary>
    MalformedFunctionCall,
    /// <summary>
    /// Token generation stopped because generated images contain safety violations.
    /// </summary>
    ImageSafety,
    /// <summary>
    /// Image generation stopped because generated images have other prohibited content.
    /// </summary>
    ImageProhibitedContent,
    /// <summary>
    /// Image generation stopped because of other miscellaneous issue.
    /// </summary>
    ImageOther,
    /// <summary>
    /// The model was expected to generate an image, but none was generated.
    /// </summary>
    NoImage,
    /// <summary>
    /// Image generation stopped due to recitation.
    /// </summary>
    ImageRecitation,
    /// <summary>
    /// The response candidate content was flagged for using an unsupported language.
    /// </summary>
    Language,
    /// <summary>
    /// Model generated a tool call but no tools were enabled in the request.
    /// </summary>
    UnexpectedToolCall,
    /// <summary>
    /// Model called too many tools consecutively, thus the system exited execution.
    /// </summary>
    TooManyToolCalls,
    /// <summary>
    /// Request has at least one thought signature missing.
    /// </summary>
    MissingThoughtSignature,
    /// <summary>
    /// Finished due to malformed response.
    /// </summary>
    MalformedResponse,
  }

  /// <summary>
  /// A struct representing a possible reply to a content generation prompt.
  /// Each content generation prompt may produce multiple candidate responses.
  /// </summary>
  public readonly struct Candidate
  {
    private readonly IReadOnlyList<SafetyRating> _safetyRatings;

    /// <summary>
    /// The response’s content.
    /// </summary>
    public ModelContent Content { get; }

    /// <summary>
    /// The safety rating of the response content.
    /// </summary>
    public IReadOnlyList<SafetyRating> SafetyRatings
    {
      get
      {
        return _safetyRatings ?? new List<SafetyRating>();
      }
    }

    /// <summary>
    /// The reason the model stopped generating content, if it exists;
    /// for example, if the model generated a predefined stop sequence.
    /// </summary>
    public FinishReason? FinishReason { get; }

    /// <summary>
    /// Cited works in the model’s response content, if it exists.
    /// </summary>
    public CitationMetadata? CitationMetadata { get; }

    /// <summary>
    /// Grounding metadata for the response, if any.
    /// </summary>
    public GroundingMetadata? GroundingMetadata { get; }

    /// <summary>
    /// Metadata related to the `URLContext` tool.
    /// </summary>
    public UrlContextMetadata? UrlContextMetadata { get; }

    // Hidden constructor, users don't need to make this.
    private Candidate(ModelContent content, List<SafetyRating> safetyRatings,
        FinishReason? finishReason, CitationMetadata? citationMetadata,
        GroundingMetadata? groundingMetadata, UrlContextMetadata? urlContextMetadata)
    {
      Content = content;
      _safetyRatings = safetyRatings ?? new List<SafetyRating>();
      FinishReason = finishReason;
      CitationMetadata = citationMetadata;
      GroundingMetadata = groundingMetadata;
      UrlContextMetadata = urlContextMetadata;
    }

    private static FinishReason ParseFinishReason(string str)
    {
      return str switch
      {
        "STOP" => Firebase.AI.FinishReason.Stop,
        "MAX_TOKENS" => Firebase.AI.FinishReason.MaxTokens,
        "SAFETY" => Firebase.AI.FinishReason.Safety,
        "RECITATION" => Firebase.AI.FinishReason.Recitation,
        "OTHER" => Firebase.AI.FinishReason.Other,
        "BLOCKLIST" => Firebase.AI.FinishReason.Blocklist,
        "PROHIBITED_CONTENT" => Firebase.AI.FinishReason.ProhibitedContent,
        "SPII" => Firebase.AI.FinishReason.SPII,
        "MALFORMED_FUNCTION_CALL" => Firebase.AI.FinishReason.MalformedFunctionCall,
        "IMAGE_SAFETY" => Firebase.AI.FinishReason.ImageSafety,
        "IMAGE_PROHIBITED_CONTENT" => Firebase.AI.FinishReason.ImageProhibitedContent,
        "IMAGE_OTHER" => Firebase.AI.FinishReason.ImageOther,
        "NO_IMAGE" => Firebase.AI.FinishReason.NoImage,
        "IMAGE_RECITATION" => Firebase.AI.FinishReason.ImageRecitation,
        "LANGUAGE" => Firebase.AI.FinishReason.Language,
        "UNEXPECTED_TOOL_CALL" => Firebase.AI.FinishReason.UnexpectedToolCall,
        "TOO_MANY_TOOL_CALLS" => Firebase.AI.FinishReason.TooManyToolCalls,
        "MISSING_THOUGHT_SIGNATURE" => Firebase.AI.FinishReason.MissingThoughtSignature,
        "MALFORMED_RESPONSE" => Firebase.AI.FinishReason.MalformedResponse,
        _ => Firebase.AI.FinishReason.Unknown,
      };
    }

    /// <summary>
    /// Intended for internal use only.
    /// This method is used for deserializing JSON responses and should not be called directly.
    /// </summary>
    internal static Candidate FromJson(Dictionary<string, object> jsonDict,
        FirebaseAI.Backend.InternalProvider backend)
    {
      return new Candidate(
        jsonDict.ParseObject("content", ModelContent.FromJson, defaultValue: new ModelContent("model")),
        jsonDict.ParseObjectList("safetyRatings", SafetyRating.FromJson),
        jsonDict.ParseNullableEnum("finishReason", ParseFinishReason),
        jsonDict.ParseNullableObject("citationMetadata",
            (d) => Firebase.AI.CitationMetadata.FromJson(d, backend)),
        jsonDict.ParseNullableObject("groundingMetadata",
            Firebase.AI.GroundingMetadata.FromJson),
        jsonDict.ParseNullableObject("urlContextMetadata",
            Firebase.AI.UrlContextMetadata.FromJson));
    }
  }

}