1// Copyright 2022 Google LLC
2//
3// Licensed under the Apache License, Version 2.0 (the "License");
4// you may not use this file except in compliance with the License.
5// You may obtain a copy of the License at
6//
7//     http://www.apache.org/licenses/LICENSE-2.0
8//
9// Unless required by applicable law or agreed to in writing, software
10// distributed under the License is distributed on an "AS IS" BASIS,
11// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12// See the License for the specific language governing permissions and
13// limitations under the License.
14
15syntax = "proto3";
16
17package google.cloud.discoveryengine.v1beta;
18
19import "google/api/annotations.proto";
20import "google/api/client.proto";
21import "google/api/field_behavior.proto";
22import "google/api/resource.proto";
23import "google/cloud/discoveryengine/v1beta/grounding.proto";
24
25option csharp_namespace = "Google.Cloud.DiscoveryEngine.V1Beta";
26option go_package = "cloud.google.com/go/discoveryengine/apiv1beta/discoveryenginepb;discoveryenginepb";
27option java_multiple_files = true;
28option java_outer_classname = "GroundedGenerationServiceProto";
29option java_package = "com.google.cloud.discoveryengine.v1beta";
30option objc_class_prefix = "DISCOVERYENGINE";
31option php_namespace = "Google\\Cloud\\DiscoveryEngine\\V1beta";
32option ruby_package = "Google::Cloud::DiscoveryEngine::V1beta";
33
34// Service for grounded generation.
35service GroundedGenerationService {
36  option (google.api.default_host) = "discoveryengine.googleapis.com";
37  option (google.api.oauth_scopes) =
38      "https://www.googleapis.com/auth/cloud-platform";
39
40  // Performs a grounding check.
41  rpc CheckGrounding(CheckGroundingRequest) returns (CheckGroundingResponse) {
42    option (google.api.http) = {
43      post: "/v1beta/{grounding_config=projects/*/locations/*/groundingConfigs/*}:check"
44      body: "*"
45    };
46  }
47}
48
49// Specification for the grounding check.
50message CheckGroundingSpec {
51  // The threshold (in [0,1]) used for determining whether a fact must be
52  // cited for a claim in the answer candidate. Choosing a higher threshold
53  // will lead to fewer but very strong citations, while choosing a lower
54  // threshold may lead to more but somewhat weaker citations. If unset, the
55  // threshold will default to 0.6.
56  optional double citation_threshold = 1;
57}
58
59// Request message for
60// [GroundedGenerationService.CheckGrounding][google.cloud.discoveryengine.v1beta.GroundedGenerationService.CheckGrounding]
61// method.
62message CheckGroundingRequest {
63  // Required. The resource name of the grounding config, such as
64  // `projects/*/locations/global/groundingConfigs/default_grounding_config`.
65  string grounding_config = 1 [
66    (google.api.field_behavior) = REQUIRED,
67    (google.api.resource_reference) = {
68      type: "discoveryengine.googleapis.com/GroundingConfig"
69    }
70  ];
71
72  // Answer candidate to check.
73  string answer_candidate = 2;
74
75  // List of facts for the grounding check.
76  // We support up to 200 facts.
77  repeated GroundingFact facts = 3;
78
79  // Configuration of the grounding check.
80  CheckGroundingSpec grounding_spec = 4;
81}
82
83// Response message for the
84// [GroundedGenerationService.CheckGrounding][google.cloud.discoveryengine.v1beta.GroundedGenerationService.CheckGrounding]
85// method.
86message CheckGroundingResponse {
87  // Text and citation info for a claim in the answer candidate.
88  message Claim {
89    // Position indicating the start of the claim in the answer candidate,
90    // measured in bytes.
91    optional int32 start_pos = 1;
92
93    // Position indicating the end of the claim in the answer candidate,
94    // exclusive.
95    optional int32 end_pos = 2;
96
97    // Text for the claim in the answer candidate. Always provided regardless of
98    // whether citations or anti-citations are found.
99    string claim_text = 3;
100
101    // A list of indices (into 'cited_chunks') specifying the citations
102    // associated with the claim. For instance [1,3,4] means that
103    // cited_chunks[1], cited_chunks[3], cited_chunks[4] are the facts cited
104    // supporting for the claim. A citation to a fact indicates that the claim
105    // is supported by the fact.
106    repeated int32 citation_indices = 4;
107  }
108
109  // The support score for the input answer candidate.
110  // Higher the score, higher is the fraction of claims that are supported by
111  // the provided facts. This is always set when a response is returned.
112  optional float support_score = 1;
113
114  // List of facts cited across all claims in the answer candidate.
115  // These are derived from the facts supplied in the request.
116  repeated FactChunk cited_chunks = 3;
117
118  // Claim texts and citation info across all claims in the answer candidate.
119  repeated Claim claims = 4;
120}
121