@google-cloud/discoveryengine 1.6.0 → 1.7.0

package/build/protos/google/cloud/discoveryengine/v1/search_service.proto

@@ -69,6 +69,19 @@ message SearchRequest {
     }
   }
 
+  // A struct to define data stores to filter on in a search call.
+  message DataStoreSpec {
+    // Required. Full resource name of
+    // [DataStore][google.cloud.discoveryengine.v1.DataStore], such as
+    // `projects/{project}/locations/{location}/collections/{collection_id}/dataStores/{data_store_id}`.
+    string data_store = 1 [
+      (google.api.field_behavior) = REQUIRED,
+      (google.api.resource_reference) = {
+        type: "discoveryengine.googleapis.com/DataStore"
+      }
+    ];
+  }
+
   // A facet specification to perform faceted search.
   message FacetSpec {
     // Specifies how a facet is computed.
@@ -212,28 +225,29 @@ message SearchRequest {
       // Examples:
       //
       // * To boost documents with document ID "doc_1" or "doc_2", and
-      // color
-      //   "Red" or "Blue":
-      //     * (id: ANY("doc_1", "doc_2")) AND (color: ANY("Red","Blue"))
+      // color "Red" or "Blue":
+      // `(document_id: ANY("doc_1", "doc_2")) AND (color: ANY("Red", "Blue"))`
       string condition = 1;
 
       // Strength of the condition boost, which should be in [-1, 1]. Negative
       // boost means demotion. Default is 0.0.
       //
-      // Setting to 1.0 gives the document a big promotion. However, it does not
-      // necessarily mean that the boosted document will be the top result at
-      // all times, nor that other documents will be excluded. Results could
-      // still be shown even when none of them matches the condition. And
-      // results that are significantly more relevant to the search query can
-      // still trump your heavily favored but irrelevant documents.
+      // Setting to 1.0 gives the document a big promotion. However, it does
+      // not necessarily mean that the boosted document will be the top result
+      // at all times, nor that other documents will be excluded. Results
+      // could still be shown even when none of them matches the condition.
+      // And results that are significantly more relevant to the search query
+      // can still trump your heavily favored but irrelevant documents.
       //
       // Setting to -1.0 gives the document a big demotion. However, results
       // that are deeply relevant might still be shown. The document will have
-      // an upstream battle to get a fairly high ranking, but it is not blocked
-      // out completely.
+      // an upstream battle to get a fairly high ranking, but it is not
+      // blocked out completely.
       //
       // Setting to 0.0 means no boost applied. The boosting condition is
-      // ignored.
+      // ignored. Only one of the (condition, boost) combination or the
+      // boost_control_spec below are set. If both are set then the global boost
+      // is ignored and the more fine-grained boost_control_spec is applied.
       float boost = 2;
     }
 
@@ -335,11 +349,13 @@ message SearchRequest {
         // Supported values are:
         //
         // * `stable`: string. Default value when no value is specified. Uses a
-        //   generally available, fine-tuned version of the text-bison@001
-        //   model.
-        // * `preview`: string. (Public preview) Uses a fine-tuned version of
-        //   the text-bison@002 model. This model works only for summaries in
-        //   English.
+        //    generally available, fine-tuned model. For more information, see
+        //    [Answer generation model versions and
+        //    lifecycle](https://cloud.google.com/generative-ai-app-builder/docs/answer-generation-models).
+        // * `preview`: string. (Public preview) Uses a preview model. For more
+        //    information, see
+        //    [Answer generation model versions and
+        //    lifecycle](https://cloud.google.com/generative-ai-app-builder/docs/answer-generation-models).
         string version = 1;
       }
 
@@ -347,7 +363,10 @@ message SearchRequest {
       // of results returned is less than `summaryResultCount`, the summary is
       // generated from all of the results.
       //
-      // At most five results can be used to generate a summary.
+      // At most 10 results for documents mode, or 50 for chunks mode, can be
+      // used to generate a summary. The chunks mode is used when
+      // [SearchRequest.ContentSearchSpec.search_result_mode][] is set to
+      // [CHUNKS][SearchRequest.ContentSearchSpec.SearchResultMode.CHUNKS].
       int32 summary_result_count = 1;
 
       // Specifies whether to include citations in the summary. The default
@@ -406,6 +425,68 @@ message SearchRequest {
       // If specified, the spec will be used to modify the model specification
       // provided to the LLM.
       ModelSpec model_spec = 7;
+
+      // If true, answer will be generated from most relevant chunks from top
+      // search results. This feature will improve summary quality.
+      // Note that with this feature enabled, not all top search results
+      // will be referenced and included in the reference list, so the citation
+      // source index only points to the search results listed in the reference
+      // list.
+      bool use_semantic_chunks = 8;
+    }
+
+    // A specification for configuring the extractive content in a search
+    // response.
+    message ExtractiveContentSpec {
+      // The maximum number of extractive answers returned in each search
+      // result.
+      //
+      // An extractive answer is a verbatim answer extracted from the original
+      // document, which provides a precise and contextually relevant answer to
+      // the search query.
+      //
+      // If the number of matching answers is less than the
+      // `max_extractive_answer_count`, return all of the answers. Otherwise,
+      // return the `max_extractive_answer_count`.
+      //
+      // At most five answers are returned for each
+      // [SearchResult][google.cloud.discoveryengine.v1.SearchResponse.SearchResult].
+      int32 max_extractive_answer_count = 1;
+
+      // The max number of extractive segments returned in each search result.
+      // Only applied if the
+      // [DataStore][google.cloud.discoveryengine.v1.DataStore] is set to
+      // [DataStore.ContentConfig.CONTENT_REQUIRED][google.cloud.discoveryengine.v1.DataStore.ContentConfig.CONTENT_REQUIRED]
+      // or
+      // [DataStore.solution_types][google.cloud.discoveryengine.v1.DataStore.solution_types]
+      // is
+      // [SOLUTION_TYPE_CHAT][google.cloud.discoveryengine.v1.SolutionType.SOLUTION_TYPE_CHAT].
+      //
+      // An extractive segment is a text segment extracted from the original
+      // document that is relevant to the search query, and, in general, more
+      // verbose than an extractive answer. The segment could then be used as
+      // input for LLMs to generate summaries and answers.
+      //
+      // If the number of matching segments is less than
+      // `max_extractive_segment_count`, return all of the segments. Otherwise,
+      // return the `max_extractive_segment_count`.
+      int32 max_extractive_segment_count = 2;
+
+      // Specifies whether to return the confidence score from the extractive
+      // segments in each search result. This feature is available only for new
+      // or allowlisted data stores. To allowlist your data store,
+      // contact your Customer Engineer. The default value is `false`.
+      bool return_extractive_segment_score = 3;
+
+      // Specifies whether to also include the adjacent from each selected
+      // segments.
+      // Return at most `num_previous_segments` segments before each selected
+      // segments.
+      int32 num_previous_segments = 4;
+
+      // Return at most `num_next_segments` segments after each selected
+      // segments.
+      int32 num_next_segments = 5;
     }
 
     // If `snippetSpec` is not specified, snippets are not included in the
@@ -415,6 +496,10 @@ message SearchRequest {
     // If `summarySpec` is not specified, summaries are not included in the
     // search response.
     SummarySpec summary_spec = 2;
+
+    // If there is no extractive_content_spec provided, there will be no
+    // extractive answer in the search response.
+    ExtractiveContentSpec extractive_content_spec = 3;
   }
 
   // Required. The resource name of the Search serving config, such as
@@ -446,10 +531,14 @@ message SearchRequest {
   ImageQuery image_query = 19;
 
   // Maximum number of [Document][google.cloud.discoveryengine.v1.Document]s to
-  // return. If unspecified, defaults to a reasonable value. The maximum allowed
-  // value is 100. Values above 100 are coerced to 100.
+  // return. The maximum allowed value depends on the data type. Values above
+  // the maximum value are coerced to the maximum value.
   //
-  // If this field is negative, an  `INVALID_ARGUMENT`  is returned.
+  // * Websites with basic indexing: Default `10`, Maximum `25`.
+  // * Websites with advanced indexing: Default `25`, Maximum `50`.
+  // * Other: Default `50`, Maximum `100`.
+  //
+  // If this field is negative, an  `INVALID_ARGUMENT` is returned.
   int32 page_size = 4;
 
   // A page token received from a previous
@@ -472,6 +561,9 @@ message SearchRequest {
   // If this field is negative, an  `INVALID_ARGUMENT`  is returned.
   int32 offset = 6;
 
+  // A list of data store specs to apply on a search call.
+  repeated DataStoreSpec data_store_specs = 32;
+
   // The filter syntax consists of an expression language for constructing a
   // predicate from one or more fields of the documents being filtered. Filter
   // expression is case-sensitive.
@@ -685,6 +777,15 @@ message SearchResponse {
 
     // Document reference.
     message Reference {
+      // Chunk content.
+      message ChunkContent {
+        // Chunk textual content.
+        string content = 1;
+
+        // Page identifier.
+        string page_identifier = 2;
+      }
+
       // Title of the document.
       string title = 1;
 
@@ -701,6 +802,9 @@ message SearchResponse {
 
       // Cloud Storage or HTTP uri for the document.
       string uri = 3;
+
+      // List of cited chunk contents derived from document content.
+      repeated ChunkContent chunk_contents = 4;
     }
 
     // Summary with metadata information.

package/build/protos/google/cloud/discoveryengine/v1/user_event.proto

@@ -114,22 +114,26 @@ message UserEvent {
   // Token to attribute an API response to user action(s) to trigger the event.
   //
   // Highly recommended for user events that are the result of
-  // [RecommendationService.Recommend][]. This field enables accurate
-  // attribution of recommendation model performance.
+  // [RecommendationService.Recommend][google.cloud.discoveryengine.v1.RecommendationService.Recommend].
+  // This field enables accurate attribution of recommendation model
+  // performance.
   //
   // The value must be one of:
   //
-  // * [RecommendResponse.attribution_token][] for events that are the result of
-  // [RecommendationService.Recommend][].
+  // * [RecommendResponse.attribution_token][google.cloud.discoveryengine.v1.RecommendResponse.attribution_token] for events that are the result of
+  // [RecommendationService.Recommend][google.cloud.discoveryengine.v1.RecommendationService.Recommend].
   // * [SearchResponse.attribution_token][google.cloud.discoveryengine.v1.SearchResponse.attribution_token] for events that are the result of
   // [SearchService.Search][google.cloud.discoveryengine.v1.SearchService.Search].
   //
   // This token enables us to accurately attribute page view or conversion
   // completion back to the event and the particular predict response containing
   // this clicked/purchased product. If user clicks on product K in the
-  // recommendation results, pass [RecommendResponse.attribution_token][] as a
-  // URL parameter to product K's page. When recording events on product K's
-  // page, log the [RecommendResponse.attribution_token][] to this field.
+  // recommendation results, pass
+  // [RecommendResponse.attribution_token][google.cloud.discoveryengine.v1.RecommendResponse.attribution_token]
+  // as a URL parameter to product K's page. When recording events on product
+  // K's page, log the
+  // [RecommendResponse.attribution_token][google.cloud.discoveryengine.v1.RecommendResponse.attribution_token]
+  // to this field.
   string attribution_token = 8;
 
   // The filter syntax consists of an expression language for constructing a
@@ -142,9 +146,10 @@ message UserEvent {
   // conforming to https://google.aip.dev/160#filtering.
   //
   // Similarly, for `view-item-list` events that are generated from a
-  // [RecommendRequest][], this field may be populated directly from
-  // [RecommendRequest.filter][] conforming to
-  // https://google.aip.dev/160#filtering.
+  // [RecommendRequest][google.cloud.discoveryengine.v1.RecommendRequest], this
+  // field may be populated directly from
+  // [RecommendRequest.filter][google.cloud.discoveryengine.v1.RecommendRequest.filter]
+  // conforming to https://google.aip.dev/160#filtering.
   //
   // The value must be a UTF-8 encoded string with a length limit of 1,000
   // characters. Otherwise, an `INVALID_ARGUMENT` error is returned.
@@ -247,7 +252,7 @@ message PageInfo {
   // The most specific category associated with a category page.
   //
   // To represent full path of category, use '>' sign to separate different
-  // hierarchies. If '>' is part of the category name, please replace it with
+  // hierarchies. If '>' is part of the category name, replace it with
   // other character(s).
   //
   // Category pages include special pages such as sales or promotions. For

package/build/protos/google/cloud/discoveryengine/v1alpha/answer.proto

@@ -0,0 +1,328 @@
+// Copyright 2022 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.discoveryengine.v1alpha;
+
+import "google/api/field_behavior.proto";
+import "google/api/resource.proto";
+import "google/protobuf/timestamp.proto";
+
+option csharp_namespace = "Google.Cloud.DiscoveryEngine.V1Alpha";
+option go_package = "cloud.google.com/go/discoveryengine/apiv1alpha/discoveryenginepb;discoveryenginepb";
+option java_multiple_files = true;
+option java_outer_classname = "AnswerProto";
+option java_package = "com.google.cloud.discoveryengine.v1alpha";
+option objc_class_prefix = "DISCOVERYENGINE";
+option php_namespace = "Google\\Cloud\\DiscoveryEngine\\V1alpha";
+option ruby_package = "Google::Cloud::DiscoveryEngine::V1alpha";
+
+// Defines an answer.
+message Answer {
+  option (google.api.resource) = {
+    type: "discoveryengine.googleapis.com/Answer"
+    pattern: "projects/{project}/locations/{location}/dataStores/{data_store}/sessions/{session}/answers/{answer}"
+    pattern: "projects/{project}/locations/{location}/collections/{collection}/dataStores/{data_store}/sessions/{session}/answers/{answer}"
+    pattern: "projects/{project}/locations/{location}/collections/{collection}/engines/{engine}/sessions/{session}/answers/{answer}"
+  };
+
+  // Citation info for a segment.
+  message Citation {
+    // Index indicates the start of the segment, measured in bytes (UTF-8
+    // unicode).
+    int64 start_index = 1;
+
+    // End of the attributed segment, exclusive.
+    int64 end_index = 2;
+
+    // Citation sources for the attributed segment.
+    repeated CitationSource sources = 3;
+  }
+
+  // Citation source.
+  message CitationSource {
+    // ID of the citation source.
+    string reference_id = 1;
+  }
+
+  // Reference.
+  message Reference {
+    // Unstructured document information.
+    message UnstructuredDocumentInfo {
+      // Chunk content.
+      message ChunkContent {
+        // Chunk textual content.
+        string content = 1;
+
+        // Page identifier.
+        string page_identifier = 2;
+      }
+
+      // Document resource name.
+      string document = 1 [(google.api.resource_reference) = {
+        type: "discoveryengine.googleapis.com/Document"
+      }];
+
+      // URI for the document.
+      string uri = 2;
+
+      // Title.
+      string title = 3;
+
+      // List of cited chunk contents derived from document content.
+      repeated ChunkContent chunk_contents = 4;
+    }
+
+    // Chunk information.
+    message ChunkInfo {
+      // Document metadata.
+      message DocumentMetadata {
+        // Document resource name.
+        string document = 1 [(google.api.resource_reference) = {
+          type: "discoveryengine.googleapis.com/Document"
+        }];
+
+        // URI for the document.
+        string uri = 2;
+
+        // Title.
+        string title = 3;
+
+        // Page identifier.
+        string page_identifier = 4;
+      }
+
+      // Chunk resource name.
+      string chunk = 1 [(google.api.resource_reference) = {
+        type: "discoveryengine.googleapis.com/Chunk"
+      }];
+
+      // Chunk textual content.
+      string content = 2;
+
+      // Relevance score.
+      optional float relevance_score = 3;
+
+      // Document metadata.
+      DocumentMetadata document_metadata = 4;
+    }
+
+    // Search result content.
+    oneof content {
+      // Unstructured document information.
+      UnstructuredDocumentInfo unstructured_document_info = 1;
+
+      // Chunk information.
+      ChunkInfo chunk_info = 2;
+    }
+  }
+
+  // Step information.
+  message Step {
+    // Action.
+    message Action {
+      // Search action.
+      message SearchAction {
+        // The query to search.
+        string query = 1;
+      }
+
+      // Observation.
+      message Observation {
+        message SearchResult {
+          // Snippet information.
+          message SnippetInfo {
+            // Snippet content.
+            string snippet = 1;
+
+            // Status of the snippet defined by the search team.
+            string snippet_status = 2;
+          }
+
+          // Chunk information.
+          message ChunkInfo {
+            // Chunk resource name.
+            string chunk = 1;
+
+            // Chunk textual content.
+            string content = 2;
+
+            // Relevance score.
+            optional float relevance_score = 3;
+          }
+
+          // Document resource name.
+          string document = 1;
+
+          // URI for the document.
+          string uri = 2;
+
+          // Title.
+          string title = 3;
+
+          // If citation_type is DOCUMENT_LEVEL_CITATION, populate document
+          // level snippets.
+          repeated SnippetInfo snippet_info = 4;
+
+          // If citation_type is CHUNK_LEVEL_CITATION and chunk mode is on,
+          // populate chunk info.
+          repeated ChunkInfo chunk_info = 5;
+        }
+
+        // Search results observed by the search action, it can be snippets info
+        // or chunk info, depending on the citation type set by the user.
+        repeated SearchResult search_results = 2;
+      }
+
+      // The action.
+      oneof action {
+        // Search action.
+        SearchAction search_action = 2;
+      }
+
+      // Observation.
+      Observation observation = 3;
+    }
+
+    // Enumeration of the state of the step.
+    enum State {
+      // Unknown.
+      STATE_UNSPECIFIED = 0;
+
+      // Step is currently in progress.
+      IN_PROGRESS = 1;
+
+      // Step currently failed.
+      FAILED = 2;
+
+      // Step has succeeded.
+      SUCCEEDED = 3;
+    }
+
+    // The state of the step.
+    State state = 1;
+
+    // The description of the step.
+    string description = 2;
+
+    // The thought of the step.
+    string thought = 3;
+
+    // Actions.
+    repeated Action actions = 4;
+  }
+
+  // Query understanding information.
+  message QueryUnderstandingInfo {
+    // Query classification information.
+    message QueryClassificationInfo {
+      // Query classification types.
+      enum Type {
+        // Unspecified query classification type.
+        TYPE_UNSPECIFIED = 0;
+
+        // Adversarial query classification type.
+        ADVERSARIAL_QUERY = 1;
+
+        // Non-answer-seeking query classification type.
+        NON_ANSWER_SEEKING_QUERY = 2;
+      }
+
+      // Query classification type.
+      Type type = 1;
+
+      // Classification output.
+      bool positive = 2;
+    }
+
+    // Query classification information.
+    repeated QueryClassificationInfo query_classification_info = 1;
+  }
+
+  // Enumeration of the state of the answer generation.
+  enum State {
+    // Unknown.
+    STATE_UNSPECIFIED = 0;
+
+    // Answer generation is currently in progress.
+    IN_PROGRESS = 1;
+
+    // Answer generation currently failed.
+    FAILED = 2;
+
+    // Answer generation has succeeded.
+    SUCCEEDED = 3;
+  }
+
+  // An enum for answer skipped reasons.
+  enum AnswerSkippedReason {
+    // Default value. The answer skipped reason is not specified.
+    ANSWER_SKIPPED_REASON_UNSPECIFIED = 0;
+
+    // The adversarial query ignored case.
+    ADVERSARIAL_QUERY_IGNORED = 1;
+
+    // The non-answer seeking query ignored case.
+    NON_ANSWER_SEEKING_QUERY_IGNORED = 2;
+
+    // The out-of-domain query ignored case.
+    //
+    // Google skips the answer if there are no high-relevance search results.
+    OUT_OF_DOMAIN_QUERY_IGNORED = 3;
+
+    // The potential policy violation case.
+    //
+    // Google skips the answer if there is a potential policy violation
+    // detected. This includes content that may be violent or toxic.
+    POTENTIAL_POLICY_VIOLATION = 4;
+  }
+
+  // Immutable. Fully qualified name
+  // `projects/{project}/locations/global/collections/{collection}/engines/{engine}/sessions/*/answers/*`
+  string name = 1 [(google.api.field_behavior) = IMMUTABLE];
+
+  // The state of the answer generation.
+  State state = 2;
+
+  // The textual answer.
+  string answer_text = 3;
+
+  // Citations.
+  repeated Citation citations = 4;
+
+  // References.
+  repeated Reference references = 5;
+
+  // Suggested related questions.
+  repeated string related_questions = 6;
+
+  // Answer generation steps.
+  repeated Step steps = 7;
+
+  // Query understanding information.
+  QueryUnderstandingInfo query_understanding_info = 10;
+
+  // Additional answer-skipped reasons. This provides the reason for ignored
+  // cases. If nothing is skipped, this field is not set.
+  repeated AnswerSkippedReason answer_skipped_reasons = 11;
+
+  // Output only. Answer creation timestamp.
+  google.protobuf.Timestamp create_time = 8
+      [(google.api.field_behavior) = OUTPUT_ONLY];
+
+  // Output only. Answer completed timestamp.
+  google.protobuf.Timestamp complete_time = 9
+      [(google.api.field_behavior) = OUTPUT_ONLY];
+}

package/build/protos/google/cloud/discoveryengine/v1alpha/chunk.proto

@@ -46,6 +46,40 @@ message Chunk {
 
     // Title of the document.
     string title = 2;
+
+    // Data representation.
+    // The structured JSON data for the document. It should conform to the
+    // registered [Schema][google.cloud.discoveryengine.v1alpha.Schema] or an
+    // `INVALID_ARGUMENT` error is thrown.
+    google.protobuf.Struct struct_data = 3;
+  }
+
+  // Page span of the chunk.
+  message PageSpan {
+    // The start page of the chunk.
+    int32 page_start = 1;
+
+    // The end page of the chunk.
+    int32 page_end = 2;
+  }
+
+  // Metadata of the current chunk. This field is only populated on
+  // [SearchService.Search][google.cloud.discoveryengine.v1alpha.SearchService.Search]
+  // API.
+  message ChunkMetadata {
+    // The previous chunks of the current chunk. The number is controlled by
+    // [SearchRequest.ContentSearchSpec.ChunkSpec.num_previous_chunks][google.cloud.discoveryengine.v1alpha.SearchRequest.ContentSearchSpec.ChunkSpec.num_previous_chunks].
+    // This field is only populated on
+    // [SearchService.Search][google.cloud.discoveryengine.v1alpha.SearchService.Search]
+    // API.
+    repeated Chunk previous_chunks = 1;
+
+    // The next chunks of the current chunk. The number is controlled by
+    // [SearchRequest.ContentSearchSpec.ChunkSpec.num_next_chunks][google.cloud.discoveryengine.v1alpha.SearchRequest.ContentSearchSpec.ChunkSpec.num_next_chunks].
+    // This field is only populated on
+    // [SearchService.Search][google.cloud.discoveryengine.v1alpha.SearchService.Search]
+    // API.
+    repeated Chunk next_chunks = 2;
   }
 
   // The full resource name of the chunk.
@@ -56,7 +90,7 @@ message Chunk {
   // characters.
   string name = 1;
 
-  // Unique chunk id of the current chunk.
+  // Unique chunk ID of the current chunk.
   string id = 2;
 
   // Content is a string from a document (parsed content).
@@ -69,4 +103,10 @@ message Chunk {
   // It contains derived data that are not in the original input document.
   google.protobuf.Struct derived_struct_data = 4
       [(google.api.field_behavior) = OUTPUT_ONLY];
+
+  // Page span of the chunk.
+  PageSpan page_span = 6;
+
+  // Output only. Metadata of the current chunk.
+  ChunkMetadata chunk_metadata = 7 [(google.api.field_behavior) = OUTPUT_ONLY];
 }