@google-cloud/discoveryengine 1.5.0 → 1.7.0

package/build/protos/google/cloud/discoveryengine/v1beta/conversational_search_service.proto

@@ -20,8 +20,10 @@ import "google/api/annotations.proto";
 import "google/api/client.proto";
 import "google/api/field_behavior.proto";
 import "google/api/resource.proto";
+import "google/cloud/discoveryengine/v1beta/answer.proto";
 import "google/cloud/discoveryengine/v1beta/conversation.proto";
 import "google/cloud/discoveryengine/v1beta/search_service.proto";
+import "google/cloud/discoveryengine/v1beta/session.proto";
 import "google/protobuf/empty.proto";
 import "google/protobuf/field_mask.proto";
 
@@ -147,6 +149,123 @@ service ConversationalSearchService {
     };
     option (google.api.method_signature) = "parent";
   }
+
+  // Answer query method.
+  rpc AnswerQuery(AnswerQueryRequest) returns (AnswerQueryResponse) {
+    option (google.api.http) = {
+      post: "/v1beta/{serving_config=projects/*/locations/*/dataStores/*/servingConfigs/*}:answer"
+      body: "*"
+      additional_bindings {
+        post: "/v1beta/{serving_config=projects/*/locations/*/collections/*/dataStores/*/servingConfigs/*}:answer"
+        body: "*"
+      }
+      additional_bindings {
+        post: "/v1beta/{serving_config=projects/*/locations/*/collections/*/engines/*/servingConfigs/*}:answer"
+        body: "*"
+      }
+    };
+  }
+
+  // Gets a Answer.
+  rpc GetAnswer(GetAnswerRequest) returns (Answer) {
+    option (google.api.http) = {
+      get: "/v1beta/{name=projects/*/locations/*/dataStores/*/sessions/*/answers/*}"
+      additional_bindings {
+        get: "/v1beta/{name=projects/*/locations/*/collections/*/dataStores/*/sessions/*/answers/*}"
+      }
+      additional_bindings {
+        get: "/v1beta/{name=projects/*/locations/*/collections/*/engines/*/sessions/*/answers/*}"
+      }
+    };
+    option (google.api.method_signature) = "name";
+  }
+
+  // Creates a Session.
+  //
+  // If the [Session][google.cloud.discoveryengine.v1beta.Session] to create
+  // already exists, an ALREADY_EXISTS error is returned.
+  rpc CreateSession(CreateSessionRequest) returns (Session) {
+    option (google.api.http) = {
+      post: "/v1beta/{parent=projects/*/locations/*/dataStores/*}/sessions"
+      body: "session"
+      additional_bindings {
+        post: "/v1beta/{parent=projects/*/locations/*/collections/*/dataStores/*}/sessions"
+        body: "session"
+      }
+      additional_bindings {
+        post: "/v1beta/{parent=projects/*/locations/*/collections/*/engines/*}/sessions"
+        body: "session"
+      }
+    };
+    option (google.api.method_signature) = "parent,session";
+  }
+
+  // Deletes a Session.
+  //
+  // If the [Session][google.cloud.discoveryengine.v1beta.Session] to delete
+  // does not exist, a NOT_FOUND error is returned.
+  rpc DeleteSession(DeleteSessionRequest) returns (google.protobuf.Empty) {
+    option (google.api.http) = {
+      delete: "/v1beta/{name=projects/*/locations/*/dataStores/*/sessions/*}"
+      additional_bindings {
+        delete: "/v1beta/{name=projects/*/locations/*/collections/*/dataStores/*/sessions/*}"
+      }
+      additional_bindings {
+        delete: "/v1beta/{name=projects/*/locations/*/collections/*/engines/*/sessions/*}"
+      }
+    };
+    option (google.api.method_signature) = "name";
+  }
+
+  // Updates a Session.
+  //
+  // [Session][google.cloud.discoveryengine.v1beta.Session] action type cannot
+  // be changed. If the [Session][google.cloud.discoveryengine.v1beta.Session]
+  // to update does not exist, a NOT_FOUND error is returned.
+  rpc UpdateSession(UpdateSessionRequest) returns (Session) {
+    option (google.api.http) = {
+      patch: "/v1beta/{session.name=projects/*/locations/*/dataStores/*/sessions/*}"
+      body: "session"
+      additional_bindings {
+        patch: "/v1beta/{session.name=projects/*/locations/*/collections/*/dataStores/*/sessions/*}"
+        body: "session"
+      }
+      additional_bindings {
+        patch: "/v1beta/{session.name=projects/*/locations/*/collections/*/engines/*/sessions/*}"
+        body: "session"
+      }
+    };
+    option (google.api.method_signature) = "session,update_mask";
+  }
+
+  // Gets a Session.
+  rpc GetSession(GetSessionRequest) returns (Session) {
+    option (google.api.http) = {
+      get: "/v1beta/{name=projects/*/locations/*/dataStores/*/sessions/*}"
+      additional_bindings {
+        get: "/v1beta/{name=projects/*/locations/*/collections/*/dataStores/*/sessions/*}"
+      }
+      additional_bindings {
+        get: "/v1beta/{name=projects/*/locations/*/collections/*/engines/*/sessions/*}"
+      }
+    };
+    option (google.api.method_signature) = "name";
+  }
+
+  // Lists all Sessions by their parent
+  // [DataStore][google.cloud.discoveryengine.v1beta.DataStore].
+  rpc ListSessions(ListSessionsRequest) returns (ListSessionsResponse) {
+    option (google.api.http) = {
+      get: "/v1beta/{parent=projects/*/locations/*/dataStores/*}/sessions"
+      additional_bindings {
+        get: "/v1beta/{parent=projects/*/locations/*/collections/*/dataStores/*}/sessions"
+      }
+      additional_bindings {
+        get: "/v1beta/{parent=projects/*/locations/*/collections/*/engines/*}/sessions"
+      }
+    };
+    option (google.api.method_signature) = "parent";
+  }
 }
 
 // Request message for
@@ -348,3 +467,443 @@ message ListConversationsResponse {
   // Pagination token, if not returned indicates the last page.
   string next_page_token = 2;
 }
+
+// Request message for
+// [ConversationalSearchService.AnswerQuery][google.cloud.discoveryengine.v1beta.ConversationalSearchService.AnswerQuery]
+// method.
+message AnswerQueryRequest {
+  // Safety specification.
+  message SafetySpec {
+    // Enable the safety filtering on the answer response. It is false by
+    // default.
+    bool enable = 1;
+  }
+
+  // Related questions specification.
+  message RelatedQuestionsSpec {
+    // Enable related questions feature if true.
+    bool enable = 1;
+  }
+
+  // Answer generation specification.
+  message AnswerGenerationSpec {
+    // Answer Generation Model specification.
+    message ModelSpec {
+      // Model version. If not set, it will use the default stable model.
+      // Allowed values are: stable, preview.
+      string model_version = 1;
+    }
+
+    // Answer generation prompt specification.
+    message PromptSpec {
+      // Customized preamble.
+      string preamble = 1;
+    }
+
+    // Answer generation model specification.
+    ModelSpec model_spec = 1;
+
+    // Answer generation prompt specification.
+    PromptSpec prompt_spec = 2;
+
+    // Specifies whether to include citation metadata in the answer. The default
+    // value is `false`.
+    bool include_citations = 3;
+
+    // Language code for Answer. Use language tags defined by
+    // [BCP47](https://www.rfc-editor.org/rfc/bcp/bcp47.txt).
+    // Note: This is an experimental feature.
+    string answer_language_code = 4;
+
+    // Specifies whether to filter out adversarial queries. The default value
+    // is `false`.
+    //
+    // Google employs search-query classification to detect adversarial
+    // queries. No answer is returned if the search query is classified as an
+    // adversarial query. For example, a user might ask a question regarding
+    // negative comments about the company or submit a query designed to
+    // generate unsafe, policy-violating output. If this field is set to
+    // `true`, we skip generating answers for adversarial queries and return
+    // fallback messages instead.
+    bool ignore_adversarial_query = 5;
+
+    // Specifies whether to filter out queries that are not answer-seeking.
+    // The default value is `false`.
+    //
+    // Google employs search-query classification to detect answer-seeking
+    // queries. No answer is returned if the search query is classified as a
+    // non-answer seeking query. If this field is set to `true`, we skip
+    // generating answers for non-answer seeking queries and return
+    // fallback messages instead.
+    bool ignore_non_answer_seeking_query = 6;
+  }
+
+  // Search specification.
+  message SearchSpec {
+    // Search parameters.
+    message SearchParams {
+      // Number of search results to return.
+      // The default value is 10.
+      int32 max_return_results = 1;
+
+      // 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. This will be used to filter
+      // search results which may affect the Answer response.
+      //
+      // If this field is unrecognizable, an  `INVALID_ARGUMENT`  is returned.
+      //
+      // Filtering in Vertex AI Search is done by mapping the LHS filter key
+      // to a key property defined in the Vertex AI Search backend -- this
+      // mapping is defined by the customer in their schema. For example a
+      // media customers might have a field 'name' in their schema. In this
+      // case the filter would look like this: filter --> name:'ANY("king
+      // kong")'
+      //
+      // For more information about filtering including syntax and filter
+      // operators, see
+      // [Filter](https://cloud.google.com/generative-ai-app-builder/docs/filter-search-metadata)
+      string filter = 2;
+
+      // Boost specification to boost certain documents in search results which
+      // may affect the answer query response. For more information on boosting,
+      // see [Boosting](https://cloud.google.com/retail/docs/boosting#boost)
+      SearchRequest.BoostSpec boost_spec = 3;
+
+      // The order in which documents are returned. Documents can be ordered
+      // by a field in an
+      // [Document][google.cloud.discoveryengine.v1beta.Document] object. Leave
+      // it unset if ordered by relevance. `order_by` expression is
+      // case-sensitive. For more information on ordering, see
+      // [Ordering](https://cloud.google.com/retail/docs/filter-and-order#order)
+      //
+      // If this field is unrecognizable, an `INVALID_ARGUMENT` is returned.
+      string order_by = 4;
+    }
+
+    // Search result list.
+    message SearchResultList {
+      // Search result.
+      message SearchResult {
+        // Unstructured document information.
+        message UnstructuredDocumentInfo {
+          // Document context.
+          message DocumentContext {
+            // Page identifier.
+            string page_identifier = 1;
+
+            // Document content.
+            string content = 2;
+          }
+
+          // Extractive segment.
+          // [Guide](https://cloud.google.com/generative-ai-app-builder/docs/snippets#extractive-segments)
+          message ExtractiveSegment {
+            // Page identifier.
+            string page_identifier = 1;
+
+            // Extractive segment content.
+            string content = 2;
+          }
+
+          // Extractive answer.
+          // [Guide](https://cloud.google.com/generative-ai-app-builder/docs/snippets#get-answers)
+          message ExtractiveAnswer {
+            // Page identifier.
+            string page_identifier = 1;
+
+            // Extractive answer content.
+            string content = 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 document contexts.
+          repeated DocumentContext document_contexts = 4;
+
+          // List of extractive segments.
+          repeated ExtractiveSegment extractive_segments = 5;
+
+          // List of extractive answers.
+          repeated ExtractiveAnswer extractive_answers = 6;
+        }
+
+        // Chunk information.
+        message ChunkInfo {
+          // Chunk resource name.
+          string chunk = 1 [(google.api.resource_reference) = {
+            type: "discoveryengine.googleapis.com/Chunk"
+          }];
+
+          // Chunk textual content.
+          string content = 2;
+        }
+
+        // Search result content.
+        oneof content {
+          // Unstructured document information.
+          UnstructuredDocumentInfo unstructured_document_info = 1;
+
+          // Chunk information.
+          ChunkInfo chunk_info = 2;
+        }
+      }
+
+      // Search results.
+      repeated SearchResult search_results = 1;
+    }
+
+    // Search parameters to control the search behavior.
+    // Or provide search result list to generate answer.
+    oneof input {
+      // Search parameters.
+      SearchParams search_params = 1;
+
+      // Search result list.
+      SearchResultList search_result_list = 2;
+    }
+  }
+
+  // Query understanding specification.
+  message QueryUnderstandingSpec {
+    // Query classification specification.
+    message QueryClassificationSpec {
+      // 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;
+      }
+
+      // Enabled query classification types.
+      repeated Type types = 1;
+    }
+
+    // Query rephraser specification.
+    message QueryRephraserSpec {
+      // Disable query rephraser.
+      bool disable = 1;
+
+      // Max rephrase steps.
+      // The max number is 10 steps.
+      // If not set or set to < 1, it will be set to 1 by default.
+      int32 max_rephrase_steps = 2;
+    }
+
+    // Query classification specification.
+    QueryClassificationSpec query_classification_spec = 1;
+
+    // Query rephraser specification.
+    QueryRephraserSpec query_rephraser_spec = 2;
+  }
+
+  // Required. The resource name of the Search serving config, such as
+  // `projects/*/locations/global/collections/default_collection/engines/*/servingConfigs/default_serving_config`,
+  // or
+  // `projects/*/locations/global/collections/default_collection/dataStores/*/servingConfigs/default_serving_config`.
+  // This field is used to identify the serving configuration name, set
+  // of models used to make the search.
+  string serving_config = 1 [
+    (google.api.field_behavior) = REQUIRED,
+    (google.api.resource_reference) = {
+      type: "discoveryengine.googleapis.com/ServingConfig"
+    }
+  ];
+
+  // Required. Current user query.
+  Query query = 2 [(google.api.field_behavior) = REQUIRED];
+
+  // The session resource name. Not required.
+  //
+  // When session field is not set, the API is in sessionless mode.
+  //
+  // We support auto session mode: users can use the wildcard symbol “-” as
+  // session id.  A new id will be automatically generated and assigned.
+  string session = 3 [(google.api.resource_reference) = {
+    type: "discoveryengine.googleapis.com/Session"
+  }];
+
+  // Model specification.
+  SafetySpec safety_spec = 4;
+
+  // Related questions specification.
+  RelatedQuestionsSpec related_questions_spec = 5;
+
+  // Answer generation specification.
+  AnswerGenerationSpec answer_generation_spec = 7;
+
+  // Search specification.
+  SearchSpec search_spec = 8;
+
+  // Query understanding specification.
+  QueryUnderstandingSpec query_understanding_spec = 9;
+
+  // Asynchronous mode control.
+  //
+  // If enabled, the response will be returned with answer/session resource
+  // name without final answer. The API users need to do the polling to get
+  // the latest status of answer/session by calling
+  // [ConversationalSearchService.GetAnswer][google.cloud.discoveryengine.v1beta.ConversationalSearchService.GetAnswer]
+  // or
+  // [ConversationalSearchService.GetSession][google.cloud.discoveryengine.v1beta.ConversationalSearchService.GetSession]
+  // method.
+  bool asynchronous_mode = 10;
+
+  // A unique identifier for tracking visitors. For example, this could be
+  // implemented with an HTTP cookie, which should be able to uniquely identify
+  // a visitor on a single device. This unique identifier should not change if
+  // the visitor logs in or out of the website.
+  //
+  // This field should NOT have a fixed value such as `unknown_visitor`.
+  //
+  // The field must be a UTF-8 encoded string with a length limit of 128
+  // characters. Otherwise, an  `INVALID_ARGUMENT`  error is returned.
+  string user_pseudo_id = 12;
+}
+
+// Response message for
+// [ConversationalSearchService.AnswerQuery][google.cloud.discoveryengine.v1beta.ConversationalSearchService.AnswerQuery]
+// method.
+message AnswerQueryResponse {
+  // Answer resource object.
+  // If [AnswerQueryRequest.StepSpec.max_step_count][] is greater than 1,
+  // use [Answer.name][google.cloud.discoveryengine.v1beta.Answer.name] to fetch
+  // answer information using
+  // [ConversationalSearchService.GetAnswer][google.cloud.discoveryengine.v1beta.ConversationalSearchService.GetAnswer]
+  // API.
+  Answer answer = 1;
+
+  // Session resource object.
+  // It will be only available when session field is set and valid in the
+  // [AnswerQueryRequest][google.cloud.discoveryengine.v1beta.AnswerQueryRequest]
+  // request.
+  Session session = 2;
+}
+
+// Request for GetAnswer method.
+message GetAnswerRequest {
+  // Required. The resource name of the Answer to get. Format:
+  // `projects/{project_number}/locations/{location_id}/collections/{collection}/engines/{engine_id}/sessions/{session_id}/answers/{answer_id}`
+  string name = 1 [
+    (google.api.field_behavior) = REQUIRED,
+    (google.api.resource_reference) = {
+      type: "discoveryengine.googleapis.com/Answer"
+    }
+  ];
+}
+
+// Request for CreateSession method.
+message CreateSessionRequest {
+  // Required. Full resource name of parent data store. Format:
+  // `projects/{project_number}/locations/{location_id}/collections/{collection}/dataStores/{data_store_id}`
+  string parent = 1 [
+    (google.api.field_behavior) = REQUIRED,
+    (google.api.resource_reference) = {
+      type: "discoveryengine.googleapis.com/DataStore"
+    }
+  ];
+
+  // Required. The session to create.
+  Session session = 2 [(google.api.field_behavior) = REQUIRED];
+}
+
+// Request for UpdateSession method.
+message UpdateSessionRequest {
+  // Required. The Session to update.
+  Session session = 1 [(google.api.field_behavior) = REQUIRED];
+
+  // Indicates which fields in the provided
+  // [Session][google.cloud.discoveryengine.v1beta.Session] to update. The
+  // following are NOT supported:
+  //
+  // * [Session.name][google.cloud.discoveryengine.v1beta.Session.name]
+  //
+  // If not set or empty, all supported fields are updated.
+  google.protobuf.FieldMask update_mask = 2;
+}
+
+// Request for DeleteSession method.
+message DeleteSessionRequest {
+  // Required. The resource name of the Session to delete. Format:
+  // `projects/{project_number}/locations/{location_id}/collections/{collection}/dataStores/{data_store_id}/sessions/{session_id}`
+  string name = 1 [
+    (google.api.field_behavior) = REQUIRED,
+    (google.api.resource_reference) = {
+      type: "discoveryengine.googleapis.com/Session"
+    }
+  ];
+}
+
+// Request for GetSession method.
+message GetSessionRequest {
+  // Required. The resource name of the Session to get. Format:
+  // `projects/{project_number}/locations/{location_id}/collections/{collection}/dataStores/{data_store_id}/sessions/{session_id}`
+  string name = 1 [
+    (google.api.field_behavior) = REQUIRED,
+    (google.api.resource_reference) = {
+      type: "discoveryengine.googleapis.com/Session"
+    }
+  ];
+}
+
+// Request for ListSessions method.
+message ListSessionsRequest {
+  // Required. The data store resource name. Format:
+  // `projects/{project_number}/locations/{location_id}/collections/{collection}/dataStores/{data_store_id}`
+  string parent = 1 [
+    (google.api.field_behavior) = REQUIRED,
+    (google.api.resource_reference) = {
+      type: "discoveryengine.googleapis.com/DataStore"
+    }
+  ];
+
+  // Maximum number of results to return. If unspecified, defaults
+  // to 50. Max allowed value is 1000.
+  int32 page_size = 2;
+
+  // A page token, received from a previous `ListSessions` call.
+  // Provide this to retrieve the subsequent page.
+  string page_token = 3;
+
+  // A filter to apply on the list results. The supported features are:
+  // user_pseudo_id, state.
+  //
+  // Example:
+  // "user_pseudo_id = some_id"
+  string filter = 4;
+
+  // A comma-separated list of fields to order by, sorted in ascending order.
+  // Use "desc" after a field name for descending.
+  // Supported fields:
+  //   * `update_time`
+  //   * `create_time`
+  //   * `session_name`
+  //
+  // Example:
+  // "update_time desc"
+  // "create_time"
+  string order_by = 5;
+}
+
+// Response for ListSessions method.
+message ListSessionsResponse {
+  // All the Sessions for a given data store.
+  repeated Session sessions = 1;
+
+  // Pagination token, if not returned indicates the last page.
+  string next_page_token = 2;
+}

package/build/protos/google/cloud/discoveryengine/v1beta/document_processing_config.proto

@@ -48,12 +48,9 @@ message DocumentProcessingConfig {
 
     // The OCR parsing configurations for documents.
     message OcrParsingConfig {
-      // Apply additional enhanced OCR processing to a list of document
-      // elements.
-      //
-      // Supported values:
-      // * `table`: advanced table parsing model.
-      repeated string enhanced_document_elements = 1;
+      // [DEPRECATED] This field is deprecated. To use the additional enhanced
+      // document elements processing, please switch to `layout_parsing_config`.
+      repeated string enhanced_document_elements = 1 [deprecated = true];
 
       // If true, will use native text instead of OCR text on pages containing
       // native text.

package/build/protos/google/cloud/discoveryengine/v1beta/document_service.proto

@@ -25,6 +25,7 @@ import "google/cloud/discoveryengine/v1beta/import_config.proto";
 import "google/cloud/discoveryengine/v1beta/purge_config.proto";
 import "google/longrunning/operations.proto";
 import "google/protobuf/empty.proto";
+import "google/protobuf/field_mask.proto";
 
 option csharp_namespace = "Google.Cloud.DiscoveryEngine.V1Beta";
 option go_package = "cloud.google.com/go/discoveryengine/apiv1beta/discoveryenginepb;discoveryenginepb";
@@ -88,6 +89,7 @@ service DocumentService {
         body: "document"
       }
     };
+    option (google.api.method_signature) = "document,update_mask";
   }
 
   // Deletes a [Document][google.cloud.discoveryengine.v1beta.Document].
@@ -292,6 +294,10 @@ message UpdateDocumentRequest {
   // new [Document][google.cloud.discoveryengine.v1beta.Document] will be
   // created.
   bool allow_missing = 2;
+
+  // Indicates which fields in the provided imported 'document' to update. If
+  // not set, will by default update all fields.
+  google.protobuf.FieldMask update_mask = 3;
 }
 
 // Request message for

package/build/protos/google/cloud/discoveryengine/v1beta/engine.proto

@@ -43,7 +43,7 @@ message Engine {
     // The search feature tier of this engine.
     //
     // Different tiers might have different
-    // pricing. To learn more, please check the pricing documentation.
+    // pricing. To learn more, check the pricing documentation.
     //
     // Defaults to
     // [SearchTier.SEARCH_TIER_STANDARD][google.cloud.discoveryengine.v1beta.SearchTier.SEARCH_TIER_STANDARD]
@@ -110,7 +110,7 @@ message Engine {
     // [EngineService.GetEngine][google.cloud.discoveryengine.v1beta.EngineService.GetEngine]
     // or
     // [EngineService.ListEngines][google.cloud.discoveryengine.v1beta.EngineService.ListEngines]
-    // API after engine creation. Please use
+    // API after engine creation. Use
     // [ChatEngineMetadata.dialogflow_agent][google.cloud.discoveryengine.v1beta.Engine.ChatEngineMetadata.dialogflow_agent]
     // for actual agent association after Engine is created.
     string dialogflow_agent_to_link = 2;