feat: [retail] add conversational search

packages/google-cloud-retail/protos/google/cloud/retail/v2/common.proto

@@ -337,7 +337,7 @@ message Rule {
     }
 
     // Each instance corresponds to a force return attribute for the given
-    // condition. There can't be more 3 instances here.
+    // condition. There can't be more 15 instances here.
     repeated FacetPositionAdjustment facet_position_adjustments = 1;
   }
 

packages/google-cloud-retail/protos/google/cloud/retail/v2/completion_service.proto

@@ -151,9 +151,9 @@ message CompleteQueryRequest {
   // capped by 20.
   int32 max_suggestions = 5;
 
-  // If true, attribute suggestions are enabled and provided in response.
+  // If true, attribute suggestions are enabled and provided in the response.
   //
-  // This field is only available for "cloud-retail" dataset.
+  // This field is only available for the "cloud-retail" dataset.
   bool enable_attribute_suggestions = 9;
 
   // The entity for customers who run multiple entities, domains, sites, or
@@ -192,6 +192,12 @@ message CompleteQueryResponse {
     string recent_search = 1;
   }
 
+  // Resource that represents attribute results.
+  // The list of suggestions for the attribute.
+  message AttributeResult {
+    repeated string suggestions = 1;
+  }
+
   // Results of the matching suggestions. The result list is ordered and the
   // first result is top suggestion.
   repeated CompletionResult completion_results = 1;
@@ -224,4 +230,14 @@ message CompleteQueryResponse {
   // Recent searches are deduplicated. More recent searches will be reserved
   // when duplication happens.
   repeated RecentSearchResult recent_search_results = 3 [deprecated = true];
+
+  // A map of matched attribute suggestions. This field is only available for
+  // "cloud-retail" dataset.
+  //
+  // Current supported keys:
+  //
+  // * `brands`
+  //
+  // * `categories`
+  map<string, AttributeResult> attribute_results = 4;
 }

packages/google-cloud-retail/protos/google/cloud/retail/v2/generative_question.proto

@@ -0,0 +1,72 @@
+// Copyright 2024 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.retail.v2;
+
+import "google/api/field_behavior.proto";
+
+option csharp_namespace = "Google.Cloud.Retail.V2";
+option go_package = "cloud.google.com/go/retail/apiv2/retailpb;retailpb";
+option java_multiple_files = true;
+option java_outer_classname = "GenerativeQuestionProto";
+option java_package = "com.google.cloud.retail.v2";
+option objc_class_prefix = "RETAIL";
+option php_namespace = "Google\\Cloud\\Retail\\V2";
+option ruby_package = "Google::Cloud::Retail::V2";
+
+// Configuration for overall generative question feature state.
+message GenerativeQuestionsFeatureConfig {
+  // Required. Resource name of the affected catalog.
+  // Format: projects/{project}/locations/{location}/catalogs/{catalog}
+  string catalog = 1 [(google.api.field_behavior) = REQUIRED];
+
+  // Optional. Determines whether questions will be used at serving time.
+  // Note: This feature cannot be enabled until initial data requirements are
+  // satisfied.
+  bool feature_enabled = 2 [(google.api.field_behavior) = OPTIONAL];
+
+  // Optional. Minimum number of products in the response to trigger follow-up
+  // questions. Value must be 0 or positive.
+  int32 minimum_products = 3 [(google.api.field_behavior) = OPTIONAL];
+}
+
+// Configuration for a single generated question.
+message GenerativeQuestionConfig {
+  // Required. Resource name of the catalog.
+  // Format: projects/{project}/locations/{location}/catalogs/{catalog}
+  string catalog = 1 [(google.api.field_behavior) = REQUIRED];
+
+  // Required. The facet to which the question is associated.
+  string facet = 2 [(google.api.field_behavior) = REQUIRED];
+
+  // Output only. The LLM generated question.
+  string generated_question = 3 [(google.api.field_behavior) = OUTPUT_ONLY];
+
+  // Optional. The question that will be used at serving time.
+  // Question can have a max length of 300 bytes.
+  // When not populated, generated_question should be used.
+  string final_question = 4 [(google.api.field_behavior) = OPTIONAL];
+
+  // Output only. Values that can be used to answer the question.
+  repeated string example_values = 5
+      [(google.api.field_behavior) = OUTPUT_ONLY];
+
+  // Output only. The ratio of how often a question was asked.
+  float frequency = 6 [(google.api.field_behavior) = OUTPUT_ONLY];
+
+  // Optional. Whether the question is asked at serving time.
+  bool allowed_in_conversation = 7 [(google.api.field_behavior) = OPTIONAL];
+}

packages/google-cloud-retail/protos/google/cloud/retail/v2/generative_question_service.proto

@@ -0,0 +1,172 @@
+// Copyright 2024 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.retail.v2;
+
+import "google/api/annotations.proto";
+import "google/api/client.proto";
+import "google/api/field_behavior.proto";
+import "google/api/resource.proto";
+import "google/cloud/retail/v2/generative_question.proto";
+import "google/protobuf/field_mask.proto";
+
+option csharp_namespace = "Google.Cloud.Retail.V2";
+option go_package = "cloud.google.com/go/retail/apiv2/retailpb;retailpb";
+option java_multiple_files = true;
+option java_outer_classname = "GenerativeQuestionServiceProto";
+option java_package = "com.google.cloud.retail.v2";
+option objc_class_prefix = "RETAIL";
+option php_namespace = "Google\\Cloud\\Retail\\V2";
+option ruby_package = "Google::Cloud::Retail::V2";
+
+// Service for managing LLM generated questions in search serving.
+service GenerativeQuestionService {
+  option (google.api.default_host) = "retail.googleapis.com";
+  option (google.api.oauth_scopes) =
+      "https://www.googleapis.com/auth/cloud-platform";
+
+  // Manages overal generative question feature state -- enables toggling
+  // feature on and off.
+  rpc UpdateGenerativeQuestionsFeatureConfig(
+      UpdateGenerativeQuestionsFeatureConfigRequest)
+      returns (GenerativeQuestionsFeatureConfig) {
+    option (google.api.http) = {
+      patch: "/v2/{generative_questions_feature_config.catalog=projects/*/locations/*/catalogs/*}/generativeQuestionFeature"
+      body: "generative_questions_feature_config"
+    };
+    option (google.api.method_signature) =
+        "generative_questions_feature_config,update_mask";
+  }
+
+  // Manages overal generative question feature state -- enables toggling
+  // feature on and off.
+  rpc GetGenerativeQuestionsFeatureConfig(
+      GetGenerativeQuestionsFeatureConfigRequest)
+      returns (GenerativeQuestionsFeatureConfig) {
+    option (google.api.http) = {
+      get: "/v2/{catalog=projects/*/locations/*/catalogs/*}/generativeQuestionFeature"
+    };
+    option (google.api.method_signature) = "catalog";
+  }
+
+  // Returns all questions for a given catalog.
+  rpc ListGenerativeQuestionConfigs(ListGenerativeQuestionConfigsRequest)
+      returns (ListGenerativeQuestionConfigsResponse) {
+    option (google.api.http) = {
+      get: "/v2/{parent=projects/*/locations/*/catalogs/*}/generativeQuestions"
+    };
+    option (google.api.method_signature) = "parent";
+  }
+
+  // Allows management of individual questions.
+  rpc UpdateGenerativeQuestionConfig(UpdateGenerativeQuestionConfigRequest)
+      returns (GenerativeQuestionConfig) {
+    option (google.api.http) = {
+      patch: "/v2/{generative_question_config.catalog=projects/*/locations/*/catalogs/*}/generativeQuestion"
+      body: "generative_question_config"
+    };
+    option (google.api.method_signature) =
+        "generative_question_config,update_mask";
+  }
+
+  // Allows management of multiple questions.
+  rpc BatchUpdateGenerativeQuestionConfigs(
+      BatchUpdateGenerativeQuestionConfigsRequest)
+      returns (BatchUpdateGenerativeQuestionConfigsResponse) {
+    option (google.api.http) = {
+      post: "/v2/{parent=projects/*/locations/*/catalogs/*}/generativeQuestion:batchUpdate"
+      body: "*"
+    };
+    option (google.api.method_signature) = "parent,requests";
+  }
+}
+
+// Request for UpdateGenerativeQuestionsFeatureConfig method.
+message UpdateGenerativeQuestionsFeatureConfigRequest {
+  // Required. The configuration managing the feature state.
+  GenerativeQuestionsFeatureConfig generative_questions_feature_config = 2
+      [(google.api.field_behavior) = REQUIRED];
+
+  // Optional. Indicates which fields in the provided
+  // [GenerativeQuestionsFeatureConfig][google.cloud.retail.v2.GenerativeQuestionsFeatureConfig]
+  // to update. If not set or empty, all supported fields are updated.
+  google.protobuf.FieldMask update_mask = 4
+      [(google.api.field_behavior) = OPTIONAL];
+}
+
+// Request for GetGenerativeQuestionsFeatureConfig method.
+message GetGenerativeQuestionsFeatureConfigRequest {
+  // Required. Resource name of the parent catalog.
+  // Format: projects/{project}/locations/{location}/catalogs/{catalog}
+  string catalog = 1 [
+    (google.api.field_behavior) = REQUIRED,
+    (google.api.resource_reference) = { type: "retail.googleapis.com/Catalog" }
+  ];
+}
+
+// Request for ListQuestions method.
+message ListGenerativeQuestionConfigsRequest {
+  // Required. Resource name of the parent catalog.
+  // Format: projects/{project}/locations/{location}/catalogs/{catalog}
+  string parent = 1 [
+    (google.api.field_behavior) = REQUIRED,
+    (google.api.resource_reference) = { type: "retail.googleapis.com/Catalog" }
+  ];
+}
+
+// Response for ListQuestions method.
+message ListGenerativeQuestionConfigsResponse {
+  // All the questions for a given catalog.
+  repeated GenerativeQuestionConfig generative_question_configs = 1;
+}
+
+// Request for UpdateGenerativeQuestionConfig method.
+message UpdateGenerativeQuestionConfigRequest {
+  // Required. The question to update.
+  GenerativeQuestionConfig generative_question_config = 3
+      [(google.api.field_behavior) = REQUIRED];
+
+  // Optional. Indicates which fields in the provided
+  // [GenerativeQuestionConfig][google.cloud.retail.v2.GenerativeQuestionConfig]
+  // to update. The following are NOT supported:
+  //
+  // * [GenerativeQuestionConfig.frequency][google.cloud.retail.v2.GenerativeQuestionConfig.frequency]
+  //
+  // If not set or empty, all supported fields are updated.
+  google.protobuf.FieldMask update_mask = 4
+      [(google.api.field_behavior) = OPTIONAL];
+}
+
+// Request for BatchUpdateGenerativeQuestionConfig method.
+message BatchUpdateGenerativeQuestionConfigsRequest {
+  // Optional. Resource name of the parent catalog.
+  // Format: projects/{project}/locations/{location}/catalogs/{catalog}
+  string parent = 1 [
+    (google.api.field_behavior) = OPTIONAL,
+    (google.api.resource_reference) = { type: "retail.googleapis.com/Catalog" }
+  ];
+
+  // Required. The updates question configs.
+  repeated UpdateGenerativeQuestionConfigRequest requests = 2
+      [(google.api.field_behavior) = REQUIRED];
+}
+
+// Aggregated response for UpdateGenerativeQuestionConfig method.
+message BatchUpdateGenerativeQuestionConfigsResponse {
+  // Optional. The updates question configs.
+  repeated GenerativeQuestionConfig generative_question_configs = 1
+      [(google.api.field_behavior) = OPTIONAL];
+}

packages/google-cloud-retail/protos/google/cloud/retail/v2/product.proto

@@ -380,6 +380,15 @@ message Product {
   // Default to
   // [Availability.IN_STOCK][google.cloud.retail.v2.Product.Availability.IN_STOCK].
   //
+  // For primary products with variants set the availability of the primary as
+  // [Availability.OUT_OF_STOCK][google.cloud.retail.v2.Product.Availability.OUT_OF_STOCK]
+  // and set the true availability at the variant level. This way the primary
+  // product will be considered "in stock" as long as it has at least one
+  // variant in stock.
+  //
+  // For primary products with no variants set the true availability at the
+  // primary level.
+  //
   // Corresponding properties: Google Merchant Center property
   // [availability](https://support.google.com/merchants/answer/6324448).
   // Schema.org property [Offer.availability](https://schema.org/availability).
@@ -553,8 +562,6 @@ message Product {
   // * [name][google.cloud.retail.v2.Product.name]
   // * [color_info][google.cloud.retail.v2.Product.color_info]
   //
-  // The maximum number of paths is 30. Otherwise, an INVALID_ARGUMENT error is
-  // returned.
   //
   // Note: Returning more fields in
   // [SearchResponse][google.cloud.retail.v2.SearchResponse] can increase