// 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.

syntax = "proto3";

package google.cloud.dialogflow.v2beta1;

import "google/api/field_behavior.proto";

option csharp_namespace = "Google.Cloud.Dialogflow.V2Beta1";
option go_package = "cloud.google.com/go/dialogflow/apiv2beta1/dialogflowpb;dialogflowpb";
option java_multiple_files = true;
option java_outer_classname = "GroundingProto";
option java_package = "com.google.cloud.dialogflow.v2beta1";
option objc_class_prefix = "DF";

// Grounding metadata contains sources, citations, and search entry points used
// to ground a generated answer or suggestion.
message GroundingMetadata {
  // Optional. The web search queries that were used to generate the content.
  repeated string web_search_queries = 1
      [(google.api.field_behavior) = OPTIONAL];

  // Optional. A web search entry point that can be used to display search
  // results.
  SearchEntryPoint search_entry_point = 2
      [(google.api.field_behavior) = OPTIONAL];

  // Optional. A list of supporting references retrieved from the grounding
  // source.
  repeated GroundingChunk grounding_chunks = 3
      [(google.api.field_behavior) = OPTIONAL];

  // Optional. A list of grounding supports that connect the generated
  // content to the grounding chunks.
  repeated GroundingSupport grounding_supports = 4
      [(google.api.field_behavior) = OPTIONAL];
}

// Google search entry point.
message SearchEntryPoint {
  // Optional. An HTML snippet that can be embedded in a web page or an
  // application's webview. This snippet displays a search result, including the
  // title, URL, and a brief description of the search result.
  string rendered_content = 1 [(google.api.field_behavior) = OPTIONAL];
}

// A piece of evidence that supports a claim made by the model.
//
// This is used to show a citation for a claim made by the model.
// It contains a reference to the source of the information.
message GroundingChunk {
  // A `Web` chunk is a piece of evidence that comes from a web page. It
  // contains the URI of the web page, the title of the page, and the domain of
  // the page. This is used to provide the user with a link to the source of
  // the information.
  message Web {
    // Output only. The URI of the web page that contains the evidence.
    string uri = 1 [(google.api.field_behavior) = OUTPUT_ONLY];

    // Output only. The title of the web page that contains the evidence.
    string title = 2 [(google.api.field_behavior) = OUTPUT_ONLY];

    // Output only. The domain of the web page that contains the evidence. This
    // can be used to filter out low-quality sources.
    string domain = 3 [(google.api.field_behavior) = OUTPUT_ONLY];
  }

  // Context retrieved from a data source to ground the model's response. This
  // is used when a retrieval tool fetches information from a user-provided
  // corpus or a public dataset.
  message RetrievedContext {
    // Output only. The URI of the retrieved data source.
    string uri = 1 [(google.api.field_behavior) = OUTPUT_ONLY];

    // Output only. The title of the retrieved data source.
    string title = 2 [(google.api.field_behavior) = OUTPUT_ONLY];

    // Output only. The content of the retrieved data source.
    string text = 3 [(google.api.field_behavior) = OUTPUT_ONLY];
  }

  // The source of the grounding chunk. Currently we only support web search.
  oneof chunk_type {
    // Optional. A grounding chunk from a web page, typically from web
    // search. See the `Web` message for details.
    Web web = 1 [(google.api.field_behavior) = OPTIONAL];

    // Optional. A grounding chunk from a data source retrieved by a
    // data store tool.
    RetrievedContext retrieved_context = 2
        [(google.api.field_behavior) = OPTIONAL];
  }
}

// A segment of the content.
message Segment {
  // Output only. The start index of the segment, measured in bytes. This marks
  // the beginning of the segment and is inclusive, meaning the byte at this
  // index is the first byte of the segment.
  int32 start_index = 1 [(google.api.field_behavior) = OUTPUT_ONLY];

  // Output only. The end index of the segment, measured in bytes. This marks
  // the end of the segment and is exclusive, meaning the segment includes
  // content up to, but not including, the byte at this index.
  int32 end_index = 2 [(google.api.field_behavior) = OUTPUT_ONLY];

  // Output only. The text of the segment.
  string text = 3 [(google.api.field_behavior) = OUTPUT_ONLY];
}

// A collection of supporting references for a segment or part of the
// model's response.
message GroundingSupport {
  // Optional. Segment of the content this support belongs to.
  Segment segment = 1 [(google.api.field_behavior) = OPTIONAL];

  // Optional. A list of indices into `grounding_chunks` field specifying the
  // citations associated with the claim. For instance [1, 3] means that
  // grounding_chunks[1] and grounding_chunks[3] are the retrieved contents
  // attributed to the claim.
  repeated int32 grounding_chunk_indices = 2
      [(google.api.field_behavior) = OPTIONAL];
}