Thanks to visit codestin.com
Credit goes to github.com

Skip to content

Commit 1f0e127

Browse files
Google APIscopybara-github
Google APIs
authored and
copybara-github
committed
feat: release the conversational search public SDK
PiperOrigin-RevId: 803583303
1 parent 8f0f886 commit 1f0e127

File tree

4 files changed

+461
-0
lines changed

4 files changed

+461
-0
lines changed

‎google/cloud/retail/v2/BUILD.bazel‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -31,6 +31,7 @@ proto_library(
3131
"completion_service.proto",
3232
"control.proto",
3333
"control_service.proto",
34+
"conversational_search_service.proto",
3435
"export_config.proto",
3536
"generative_question.proto",
3637
"generative_question_service.proto",
@@ -42,6 +43,7 @@ proto_library(
4243
"product_service.proto",
4344
"promotion.proto",
4445
"purge_config.proto",
46+
"safety.proto",
4547
"search_service.proto",
4648
"serving_config.proto",
4749
"serving_config_service.proto",

‎google/cloud/retail/v2/conversational_search_service.proto‎

Lines changed: 359 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,359 @@
1+
// Copyright 2025 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+
15+
syntax = "proto3";
16+
17+
package google.cloud.retail.v2;
18+
19+
import "google/api/annotations.proto";
20+
import "google/api/client.proto";
21+
import "google/api/field_behavior.proto";
22+
import "google/api/resource.proto";
23+
import "google/cloud/retail/v2/common.proto";
24+
import "google/cloud/retail/v2/safety.proto";
25+
import "google/cloud/retail/v2/search_service.proto";
26+
27+
option csharp_namespace = "Google.Cloud.Retail.V2";
28+
option go_package = "cloud.google.com/go/retail/apiv2/retailpb;retailpb";
29+
option java_multiple_files = true;
30+
option java_outer_classname = "ConversationalSearchServiceProto";
31+
option java_package = "com.google.cloud.retail.v2";
32+
option objc_class_prefix = "RETAIL";
33+
option php_namespace = "Google\\Cloud\\Retail\\V2";
34+
option ruby_package = "Google::Cloud::Retail::V2";
35+
36+
// Service for retail conversational search.
37+
//
38+
// This feature is only available for users who have Retail Conversational
39+
// Search enabled. Enable Retail Conversational Search on Cloud Console
40+
// before using this feature.
41+
service ConversationalSearchService {
42+
option (google.api.default_host) = "retail.googleapis.com";
43+
option (google.api.oauth_scopes) =
44+
"https://www.googleapis.com/auth/cloud-platform";
45+
46+
// Performs a conversational search.
47+
//
48+
// This feature is only available for users who have Conversational Search
49+
// enabled.
50+
rpc ConversationalSearch(ConversationalSearchRequest)
51+
returns (stream ConversationalSearchResponse) {
52+
option (google.api.http) = {
53+
post: "/v2/{placement=projects/*/locations/*/catalogs/*/placements/*}:conversationalSearch"
54+
body: "*"
55+
additional_bindings {
56+
post: "/v2/{placement=projects/*/locations/*/catalogs/*/servingConfigs/*}:conversationalSearch"
57+
body: "*"
58+
}
59+
};
60+
}
61+
}
62+
63+
// Request message for
64+
// [ConversationalSearchService.ConversationalSearch][google.cloud.retail.v2.ConversationalSearchService.ConversationalSearch]
65+
// method.
66+
message ConversationalSearchRequest {
67+
// Search parameters.
68+
message SearchParams {
69+
// Optional. The filter string to restrict search results.
70+
//
71+
// The syntax of the filter string is the same as
72+
// [SearchRequest.filter][google.cloud.retail.v2.SearchRequest.filter].
73+
string filter = 1 [(google.api.field_behavior) = OPTIONAL];
74+
75+
// Optional. The canonical filter string to restrict search results.
76+
//
77+
// The syntax of the canonical filter string is the same as
78+
// [SearchRequest.canonical_filter][google.cloud.retail.v2.SearchRequest.canonical_filter].
79+
string canonical_filter = 2 [(google.api.field_behavior) = OPTIONAL];
80+
81+
// Optional. The sort string to specify the sorting of search results.
82+
//
83+
// The syntax of the sort string is the same as
84+
// [SearchRequest.sort][].
85+
string sort_by = 3 [(google.api.field_behavior) = OPTIONAL];
86+
87+
// Optional. The boost spec to specify the boosting of search results.
88+
//
89+
// The syntax of the boost spec is the same as
90+
// [SearchRequest.boost_spec][google.cloud.retail.v2.SearchRequest.boost_spec].
91+
SearchRequest.BoostSpec boost_spec = 4
92+
[(google.api.field_behavior) = OPTIONAL];
93+
}
94+
95+
// This field specifies the current user answer during the conversational
96+
// filtering search. This can be either user selected from suggested answers
97+
// or user input plain text.
98+
message UserAnswer {
99+
// This field specifies the selected answers during the conversational
100+
// search.
101+
message SelectedAnswer {
102+
// Optional. This field specifies the selected answer which is a attribute
103+
// key-value.
104+
ProductAttributeValue product_attribute_value = 1
105+
[(google.api.field_behavior) = OPTIONAL];
106+
}
107+
108+
// This field specifies the type of user answer.
109+
oneof type {
110+
// This field specifies the incremental input text from the user during
111+
// the conversational search.
112+
string text_answer = 1;
113+
114+
// Optional. This field specifies the selected answer during the
115+
// conversational search. This should be a subset of
116+
// [ConversationalSearchResponse.followup_question.suggested_answers][].
117+
SelectedAnswer selected_answer = 2
118+
[(google.api.field_behavior) = OPTIONAL];
119+
}
120+
}
121+
122+
// This field specifies all conversational filtering related parameters
123+
// addition to conversational retail search.
124+
message ConversationalFilteringSpec {
125+
// Enum to control Conversational Filtering mode.
126+
// A single conversation session including multiple turns supports modes for
127+
// Conversational Search OR Conversational Filtering without
128+
// Conversational Search, but not both.
129+
enum Mode {
130+
// Default value.
131+
MODE_UNSPECIFIED = 0;
132+
133+
// Disables Conversational Filtering when using Conversational Search.
134+
DISABLED = 1;
135+
136+
// Enables Conversational Filtering when using Conversational Search.
137+
ENABLED = 2;
138+
139+
// Enables Conversational Filtering without Conversational Search.
140+
CONVERSATIONAL_FILTER_ONLY = 3;
141+
}
142+
143+
// Optional. This field is deprecated. Please use
144+
// [ConversationalFilteringSpec.conversational_filtering_mode][google.cloud.retail.v2.ConversationalSearchRequest.ConversationalFilteringSpec.conversational_filtering_mode]
145+
// instead.
146+
bool enable_conversational_filtering = 1
147+
[deprecated = true, (google.api.field_behavior) = OPTIONAL];
148+
149+
// Optional. This field specifies the current user answer during the
150+
// conversational filtering search. It can be either user selected from
151+
// suggested answers or user input plain text.
152+
UserAnswer user_answer = 2 [(google.api.field_behavior) = OPTIONAL];
153+
154+
// Optional. Mode to control Conversational Filtering.
155+
// Defaults to
156+
// [Mode.DISABLED][google.cloud.retail.v2.ConversationalSearchRequest.ConversationalFilteringSpec.Mode.DISABLED]
157+
// if it's unset.
158+
Mode conversational_filtering_mode = 4
159+
[(google.api.field_behavior) = OPTIONAL];
160+
}
161+
162+
// Required. The resource name of the search engine placement, such as
163+
// `projects/*/locations/global/catalogs/default_catalog/placements/default_search`
164+
// or
165+
// `projects/*/locations/global/catalogs/default_catalog/servingConfigs/default_serving_config`
166+
// This field is used to identify the serving config name and the set
167+
// of models that will be used to make the search.
168+
string placement = 1 [(google.api.field_behavior) = REQUIRED];
169+
170+
// Required. The branch resource name, such as
171+
// `projects/*/locations/global/catalogs/default_catalog/branches/0`.
172+
//
173+
// Use "default_branch" as the branch ID or leave this field empty, to search
174+
// products under the default branch.
175+
string branch = 2 [
176+
(google.api.field_behavior) = REQUIRED,
177+
(google.api.resource_reference) = { type: "retail.googleapis.com/Branch" }
178+
];
179+
180+
// Optional. Raw search query to be searched for.
181+
//
182+
// If this field is empty, the request is considered a category browsing
183+
// request.
184+
string query = 3 [(google.api.field_behavior) = OPTIONAL];
185+
186+
// Optional. The categories associated with a category page. Must be set for
187+
// category navigation queries to achieve good search quality. The format
188+
// should be the same as
189+
// [UserEvent.page_categories][google.cloud.retail.v2.UserEvent.page_categories];
190+
//
191+
// To represent full path of category, use '>' sign to separate different
192+
// hierarchies. If '>' is part of the category name, replace it with
193+
// other character(s).
194+
//
195+
// Category pages include special pages such as sales or promotions. For
196+
// instance, a special sale page may have the category hierarchy:
197+
// "pageCategories" : ["Sales > 2017 Black Friday Deals"].
198+
repeated string page_categories = 4 [(google.api.field_behavior) = OPTIONAL];
199+
200+
// Optional. This field specifies the conversation id, which maintains the
201+
// state of the conversation between client side and server side. Use the
202+
// value from the previous
203+
// [ConversationalSearchResponse.conversation_id][google.cloud.retail.v2.ConversationalSearchResponse.conversation_id].
204+
// For the initial request, this should be empty.
205+
string conversation_id = 5 [(google.api.field_behavior) = OPTIONAL];
206+
207+
// Optional. Search parameters.
208+
SearchParams search_params = 6 [(google.api.field_behavior) = OPTIONAL];
209+
210+
// Required. A unique identifier for tracking visitors. For example, this
211+
// could be implemented with an HTTP cookie, which should be able to uniquely
212+
// identify a visitor on a single device. This unique identifier should not
213+
// change if the visitor logs in or out of the website.
214+
//
215+
// This should be the same identifier as
216+
// [UserEvent.visitor_id][google.cloud.retail.v2.UserEvent.visitor_id].
217+
//
218+
// The field must be a UTF-8 encoded string with a length limit of 128
219+
// characters. Otherwise, an INVALID_ARGUMENT error is returned.
220+
string visitor_id = 9 [(google.api.field_behavior) = REQUIRED];
221+
222+
// Optional. User information.
223+
UserInfo user_info = 7 [(google.api.field_behavior) = OPTIONAL];
224+
225+
// Optional. This field specifies all conversational filtering related
226+
// parameters.
227+
ConversationalFilteringSpec conversational_filtering_spec = 8
228+
[(google.api.field_behavior) = OPTIONAL];
229+
230+
// Optional. The user labels applied to a resource must meet the following
231+
// requirements:
232+
//
233+
// * Each resource can have multiple labels, up to a maximum of 64.
234+
// * Each label must be a key-value pair.
235+
// * Keys have a minimum length of 1 character and a maximum length of 63
236+
// characters and cannot be empty. Values can be empty and have a maximum
237+
// length of 63 characters.
238+
// * Keys and values can contain only lowercase letters, numeric characters,
239+
// underscores, and dashes. All characters must use UTF-8 encoding, and
240+
// international characters are allowed.
241+
// * The key portion of a label must be unique. However, you can use the same
242+
// key with multiple resources.
243+
// * Keys must start with a lowercase letter or international character.
244+
//
245+
// See [Google Cloud
246+
// Document](https://cloud.google.com/resource-manager/docs/creating-managing-labels#requirements)
247+
// for more details.
248+
map<string, string> user_labels = 12 [(google.api.field_behavior) = OPTIONAL];
249+
250+
// Optional. The safety settings to be applied to the generated content.
251+
repeated SafetySetting safety_settings = 14
252+
[(google.api.field_behavior) = OPTIONAL];
253+
}
254+
255+
// Response message for
256+
// [ConversationalSearchService.ConversationalSearch][google.cloud.retail.v2.ConversationalSearchService.ConversationalSearch]
257+
// method.
258+
message ConversationalSearchResponse {
259+
// The conversational followup question generated for Intent refinement.
260+
message FollowupQuestion {
261+
// Suggested answers to the follow-up question.
262+
// If it's numerical attribute, only ProductAttributeInterval will be set.
263+
// If it's textual attribute, only productAttributeValue will be set.
264+
message SuggestedAnswer {
265+
// Product attribute value, including an attribute key and an
266+
// attribute value. Other types can be added here in the future.
267+
ProductAttributeValue product_attribute_value = 1;
268+
}
269+
270+
// The conversational followup question generated for Intent refinement.
271+
string followup_question = 1;
272+
273+
// The answer options provided to client for the follow-up question.
274+
repeated SuggestedAnswer suggested_answers = 2;
275+
}
276+
277+
// The proposed refined search for intent-refinement/bundled shopping
278+
// conversation. When using CONVERSATIONAL_FILTER_ONLY mode, the
279+
// refined_query from search response will be populated here.
280+
message RefinedSearch {
281+
// The query to be used for search.
282+
string query = 1;
283+
}
284+
285+
// This field specifies all related information that is needed on client
286+
// side for UI rendering of conversational filtering search.
287+
message ConversationalFilteringResult {
288+
// Additional filter that client side need to apply.
289+
message AdditionalFilter {
290+
// Product attribute value, including an attribute key and an
291+
// attribute value. Other types can be added here in the future.
292+
ProductAttributeValue product_attribute_value = 1;
293+
}
294+
295+
// The conversational filtering question.
296+
FollowupQuestion followup_question = 1;
297+
298+
// This is the incremental additional filters implied from the current
299+
// user answer. User should add the suggested addition filters to the
300+
// previous [ConversationalSearchRequest.search_params.filter][] and
301+
// [SearchRequest.filter][google.cloud.retail.v2.SearchRequest.filter], and
302+
// use the merged filter in the follow up requests.
303+
AdditionalFilter additional_filter = 2;
304+
}
305+
306+
// The state of the response generation.
307+
enum State {
308+
// Unknown.
309+
STATE_UNSPECIFIED = 0;
310+
311+
// Response generation is being streamed.
312+
STREAMING = 1;
313+
314+
// Response generation has succeeded.
315+
SUCCEEDED = 2;
316+
}
317+
318+
// The types Retail classifies the search query as.
319+
//
320+
// Supported values are:
321+
//
322+
// - "ORDER_SUPPORT"
323+
// - "SIMPLE_PRODUCT_SEARCH"
324+
// - "INTENT_REFINEMENT"
325+
// - "PRODUCT_DETAILS"
326+
// - "PRODUCT_COMPARISON"
327+
// - "DEALS_AND_COUPONS"
328+
// - "STORE_RELEVANT"
329+
// - "BLOCKLISTED"
330+
// - "BEST_PRODUCT"
331+
// - "RETAIL_SUPPORT"
332+
// - "DISABLED"
333+
repeated string user_query_types = 10;
334+
335+
// The conversational answer-based text response generated by the Server.
336+
string conversational_text_response = 2;
337+
338+
// The conversational followup question generated for Intent refinement.
339+
FollowupQuestion followup_question = 3;
340+
341+
// Conversation UUID. This field will be stored in client side storage to
342+
// maintain the conversation session with server and will be used for next
343+
// search request's
344+
// [ConversationalSearchRequest.conversation_id][google.cloud.retail.v2.ConversationalSearchRequest.conversation_id]
345+
// to restore conversation state in server.
346+
string conversation_id = 4;
347+
348+
// The proposed refined search queries. They can be used to fetch the relevant
349+
// search results. When using CONVERSATIONAL_FILTER_ONLY mode, the
350+
// refined_query from search response will be populated here.
351+
repeated RefinedSearch refined_search = 6;
352+
353+
// This field specifies all related information that is needed on client
354+
// side for UI rendering of conversational filtering search.
355+
ConversationalFilteringResult conversational_filtering_result = 7;
356+
357+
// Output only. The state of the response generation.
358+
State state = 9 [(google.api.field_behavior) = OUTPUT_ONLY];
359+
}

‎google/cloud/retail/v2/retail_v2.yaml‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -9,6 +9,7 @@ apis:
99
- name: google.cloud.retail.v2.CatalogService
1010
- name: google.cloud.retail.v2.CompletionService
1111
- name: google.cloud.retail.v2.ControlService
12+
- name: google.cloud.retail.v2.ConversationalSearchService
1213
- name: google.cloud.retail.v2.GenerativeQuestionService
1314
- name: google.cloud.retail.v2.ModelService
1415
- name: google.cloud.retail.v2.PredictionService
@@ -91,6 +92,10 @@ authentication:
9192
oauth:
9293
canonical_scopes: |-
9394
https://www.googleapis.com/auth/cloud-platform
95+
- selector: google.cloud.retail.v2.ConversationalSearchService.ConversationalSearch
96+
oauth:
97+
canonical_scopes: |-
98+
https://www.googleapis.com/auth/cloud-platform
9499
- selector: 'google.cloud.retail.v2.GenerativeQuestionService.*'
95100
oauth:
96101
canonical_scopes: |-

0 commit comments

Comments
 (0)