// Copyright 2026 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.v1beta;

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/common.proto";
import "google/cloud/discoveryengine/v1beta/document.proto";
import "google/cloud/discoveryengine/v1beta/import_config.proto";
import "google/cloud/discoveryengine/v1beta/purge_config.proto";
import "google/longrunning/operations.proto";
import "google/protobuf/timestamp.proto";

option csharp_namespace = "Google.Cloud.DiscoveryEngine.V1Beta";
option go_package = "cloud.google.com/go/discoveryengine/apiv1beta/discoveryenginepb;discoveryenginepb";
option java_multiple_files = true;
option java_outer_classname = "CompletionServiceProto";
option java_package = "com.google.cloud.discoveryengine.v1beta";
option objc_class_prefix = "DISCOVERYENGINE";
option php_namespace = "Google\\Cloud\\DiscoveryEngine\\V1beta";
option ruby_package = "Google::Cloud::DiscoveryEngine::V1beta";

// Service for Auto-Completion.
service CompletionService {
  option (google.api.default_host) = "discoveryengine.googleapis.com";
  option (google.api.oauth_scopes) =
      "https://www.googleapis.com/auth/cloud-platform,"
      "https://www.googleapis.com/auth/cloud_search.query,"
      "https://www.googleapis.com/auth/discoveryengine.assist.readwrite,"
      "https://www.googleapis.com/auth/discoveryengine.readwrite,"
      "https://www.googleapis.com/auth/discoveryengine.serving.readwrite";

  // Completes the specified user input with keyword suggestions.
  rpc CompleteQuery(CompleteQueryRequest) returns (CompleteQueryResponse) {
    option (google.api.http) = {
      get: "/v1beta/{data_store=projects/*/locations/*/dataStores/*}:completeQuery"
      additional_bindings {
        get: "/v1beta/{data_store=projects/*/locations/*/collections/*/dataStores/*}:completeQuery"
      }
    };
  }

  // Completes the user input with advanced keyword suggestions.
  rpc AdvancedCompleteQuery(AdvancedCompleteQueryRequest)
      returns (AdvancedCompleteQueryResponse) {
    option (google.api.http) = {
      post: "/v1beta/{completion_config=projects/*/locations/*/dataStores/*/completionConfig}:completeQuery"
      body: "*"
      additional_bindings {
        post: "/v1beta/{completion_config=projects/*/locations/*/collections/*/dataStores/*/completionConfig}:completeQuery"
        body: "*"
      }
      additional_bindings {
        post: "/v1beta/{completion_config=projects/*/locations/*/collections/*/engines/*/completionConfig}:completeQuery"
        body: "*"
      }
    };
  }

  // Imports all
  // [SuggestionDenyListEntry][google.cloud.discoveryengine.v1beta.SuggestionDenyListEntry]
  // for a DataStore.
  rpc ImportSuggestionDenyListEntries(ImportSuggestionDenyListEntriesRequest)
      returns (google.longrunning.Operation) {
    option (google.api.http) = {
      post: "/v1beta/{parent=projects/*/locations/*/collections/*/dataStores/*}/suggestionDenyListEntries:import"
      body: "*"
      additional_bindings {
        post: "/v1beta/{parent=projects/*/locations/*/dataStores/*}/suggestionDenyListEntries:import"
        body: "*"
      }
    };
    option (google.longrunning.operation_info) = {
      response_type: "google.cloud.discoveryengine.v1beta.ImportSuggestionDenyListEntriesResponse"
      metadata_type: "google.cloud.discoveryengine.v1beta.ImportSuggestionDenyListEntriesMetadata"
    };
  }

  // Permanently deletes all
  // [SuggestionDenyListEntry][google.cloud.discoveryengine.v1beta.SuggestionDenyListEntry]
  // for a DataStore.
  rpc PurgeSuggestionDenyListEntries(PurgeSuggestionDenyListEntriesRequest)
      returns (google.longrunning.Operation) {
    option (google.api.http) = {
      post: "/v1beta/{parent=projects/*/locations/*/collections/*/dataStores/*}/suggestionDenyListEntries:purge"
      body: "*"
      additional_bindings {
        post: "/v1beta/{parent=projects/*/locations/*/dataStores/**}/suggestionDenyListEntries:purge"
        body: "*"
      }
    };
    option (google.longrunning.operation_info) = {
      response_type: "google.cloud.discoveryengine.v1beta.PurgeSuggestionDenyListEntriesResponse"
      metadata_type: "google.cloud.discoveryengine.v1beta.PurgeSuggestionDenyListEntriesMetadata"
    };
  }

  // Imports
  // [CompletionSuggestion][google.cloud.discoveryengine.v1beta.CompletionSuggestion]s
  // for a DataStore.
  rpc ImportCompletionSuggestions(ImportCompletionSuggestionsRequest)
      returns (google.longrunning.Operation) {
    option (google.api.http) = {
      post: "/v1beta/{parent=projects/*/locations/*/collections/*/dataStores/*}/completionSuggestions:import"
      body: "*"
      additional_bindings {
        post: "/v1beta/{parent=projects/*/locations/*/dataStores/*}/completionSuggestions:import"
        body: "*"
      }
    };
    option (google.longrunning.operation_info) = {
      response_type: "google.cloud.discoveryengine.v1beta.ImportCompletionSuggestionsResponse"
      metadata_type: "google.cloud.discoveryengine.v1beta.ImportCompletionSuggestionsMetadata"
    };
  }

  // Permanently deletes all
  // [CompletionSuggestion][google.cloud.discoveryengine.v1beta.CompletionSuggestion]s
  // for a DataStore.
  rpc PurgeCompletionSuggestions(PurgeCompletionSuggestionsRequest)
      returns (google.longrunning.Operation) {
    option (google.api.http) = {
      post: "/v1beta/{parent=projects/*/locations/*/collections/*/dataStores/*}/completionSuggestions:purge"
      body: "*"
      additional_bindings {
        post: "/v1beta/{parent=projects/*/locations/*/dataStores/*}/completionSuggestions:purge"
        body: "*"
      }
    };
    option (google.longrunning.operation_info) = {
      response_type: "google.cloud.discoveryengine.v1beta.PurgeCompletionSuggestionsResponse"
      metadata_type: "google.cloud.discoveryengine.v1beta.PurgeCompletionSuggestionsMetadata"
    };
  }

  // Removes the search history suggestion in an engine for a user. This will
  // remove the suggestion from being returned in the
  // [AdvancedCompleteQueryResponse.recent_search_suggestions][google.cloud.discoveryengine.v1beta.AdvancedCompleteQueryResponse.recent_search_suggestions]
  // for this user. If the user searches the same suggestion again, the new
  // history will override and suggest this suggestion again.
  rpc RemoveSuggestion(RemoveSuggestionRequest)
      returns (RemoveSuggestionResponse) {
    option (google.api.http) = {
      post: "/v1beta/{completion_config=projects/*/locations/*/collections/*/engines/*/completionConfig}:removeSuggestion"
      body: "*"
    };
  }
}

// Request message for
// [CompletionService.CompleteQuery][google.cloud.discoveryengine.v1beta.CompletionService.CompleteQuery]
// method.
message CompleteQueryRequest {
  // Required. The parent data store resource name for which the completion is
  // performed, such as
  // `projects/*/locations/global/collections/default_collection/dataStores/default_data_store`.
  string data_store = 1 [
    (google.api.field_behavior) = REQUIRED,
    (google.api.resource_reference) = {
      type: "discoveryengine.googleapis.com/DataStore"
    }
  ];

  // Required. The typeahead input used to fetch suggestions. Maximum length is
  // 128 characters.
  string query = 2 [(google.api.field_behavior) = REQUIRED];

  // Specifies the autocomplete data model. This overrides any model specified
  // in the Configuration > Autocomplete section of the Cloud console. Currently
  // supported values:
  //
  // * `document` - Using suggestions generated from user-imported documents.
  // * `search-history` - Using suggestions generated from the past history of
  // [SearchService.Search][google.cloud.discoveryengine.v1beta.SearchService.Search]
  // API calls. Do not use it when there is no traffic for Search API.
  // * `user-event` - Using suggestions generated from user-imported search
  // events.
  // * `document-completable` - Using suggestions taken directly from
  // user-imported document fields marked as completable.
  //
  // Default values:
  //
  // * `document` is the default model for regular dataStores.
  // * `search-history` is the default model for site search dataStores.
  string query_model = 3;

  // Optional. 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`.
  //
  // This should be the same identifier as
  // [UserEvent.user_pseudo_id][google.cloud.discoveryengine.v1beta.UserEvent.user_pseudo_id]
  // and
  // [SearchRequest.user_pseudo_id][google.cloud.discoveryengine.v1beta.SearchRequest.user_pseudo_id].
  //
  // 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 = 4 [(google.api.field_behavior) = OPTIONAL];

  // Indicates if tail suggestions should be returned if there are no
  // suggestions that match the full query. Even if set to true, if there are
  // suggestions that match the full query, those are returned and no
  // tail suggestions are returned.
  bool include_tail_suggestions = 5;
}

// Response message for
// [CompletionService.CompleteQuery][google.cloud.discoveryengine.v1beta.CompletionService.CompleteQuery]
// method.
message CompleteQueryResponse {
  // Suggestions as search queries.
  message QuerySuggestion {
    // The suggestion for the query.
    string suggestion = 1;

    // The unique document field paths that serve as the source of this
    // suggestion if it was generated from completable fields.
    //
    // This field is only populated for the document-completable model.
    repeated string completable_field_paths = 2;
  }

  // Results of the matched query suggestions. The result list is ordered and
  // the first result is a top suggestion.
  repeated QuerySuggestion query_suggestions = 1;

  // True if the returned suggestions are all tail suggestions.
  //
  // For tail matching to be triggered, include_tail_suggestions in the request
  // must be true and there must be no suggestions that match the full query.
  bool tail_match_triggered = 2;
}

// Request message for
// [CompletionService.AdvancedCompleteQuery][google.cloud.discoveryengine.v1beta.CompletionService.AdvancedCompleteQuery]
// method.
// .
message AdvancedCompleteQueryRequest {
  // Specification to boost suggestions based on the condition of the
  // suggestion.
  message BoostSpec {
    // Boost applies to suggestions which match a condition.
    message ConditionBoostSpec {
      // An expression which specifies a boost condition. The syntax is the same
      // as [filter expression
      // syntax](https://cloud.google.com/generative-ai-app-builder/docs/filter-search-metadata#filter-expression-syntax).
      // Currently, the only supported condition is a list of BCP-47 lang codes.
      //
      // Example:
      //
      // * To boost suggestions in languages `en` or `fr`:
      // `(lang_code: ANY("en", "fr"))`
      string condition = 1;

      // Strength of the boost, which should be in [-1, 1].
      // Negative boost means demotion. Default is 0.0.
      //
      // Setting to 1.0 gives the suggestions a big promotion. However, it does
      // not necessarily mean that the top result will be a boosted suggestion.
      //
      // Setting to -1.0 gives the suggestions a big demotion. However, other
      // suggestions that are relevant might still be shown.
      //
      // Setting to 0.0 means no boost applied. The boosting condition is
      // ignored.
      float boost = 2;
    }

    // Condition boost specifications. If a suggestion matches multiple
    // conditions in the specifications, boost values from these specifications
    // are all applied and combined in a non-linear way. Maximum number of
    // specifications is 20.
    //
    // Note: Currently only support language condition boost.
    repeated ConditionBoostSpec condition_boost_specs = 1;
  }

  // Specification of each suggestion type.
  message SuggestionTypeSpec {
    // Optional. Suggestion type.
    SuggestionType suggestion_type = 1 [(google.api.field_behavior) = OPTIONAL];

    // Optional. Maximum number of suggestions to return for each suggestion
    // type.
    int32 max_suggestions = 2 [(google.api.field_behavior) = OPTIONAL];
  }

  // Suggestion type to return.
  enum SuggestionType {
    // Default value.
    SUGGESTION_TYPE_UNSPECIFIED = 0;

    // Returns query suggestions.
    QUERY = 1;

    // Returns people suggestions.
    PEOPLE = 2;

    // Returns content suggestions.
    CONTENT = 3;

    // Returns recent search suggestions.
    RECENT_SEARCH = 4;

    // Returns Google Workspace suggestions.
    GOOGLE_WORKSPACE = 5;
  }

  // Required. The completion_config of the parent dataStore or engine resource
  // name for which the completion is performed, such as
  // `projects/*/locations/global/collections/default_collection/dataStores/*/completionConfig`
  // `projects/*/locations/global/collections/default_collection/engines/*/completionConfig`.
  string completion_config = 1 [
    (google.api.field_behavior) = REQUIRED,
    (google.api.resource_reference) = {
      type: "discoveryengine.googleapis.com/CompletionConfig"
    }
  ];

  // Required. The typeahead input used to fetch suggestions. Maximum length is
  // 128 characters.
  //
  // The query can not be empty for most of the suggestion types. If it is
  // empty, an `INVALID_ARGUMENT` error is returned. The exception is when the
  // suggestion_types contains only the type `RECENT_SEARCH`, the query can
  // be an empty string. The is called "zero prefix" feature, which returns
  // user's recently searched queries given the empty query.
  string query = 2 [(google.api.field_behavior) = REQUIRED];

  // Specifies the autocomplete query model, which only applies to the QUERY
  // SuggestionType. This overrides any model specified in the Configuration >
  // Autocomplete section of the Cloud console. Currently supported values:
  //
  // * `document` - Using suggestions generated from user-imported documents.
  // * `search-history` - Using suggestions generated from the past history of
  // [SearchService.Search][google.cloud.discoveryengine.v1beta.SearchService.Search]
  // API calls. Do not use it when there is no traffic for Search API.
  // * `user-event` - Using suggestions generated from user-imported search
  // events.
  // * `document-completable` - Using suggestions taken directly from
  // user-imported document fields marked as completable.
  //
  // Default values:
  //
  // * `document` is the default model for regular dataStores.
  // * `search-history` is the default model for site search dataStores.
  string query_model = 3;

  // Optional. 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`.
  //
  // This should be the same identifier as
  // [UserEvent.user_pseudo_id][google.cloud.discoveryengine.v1beta.UserEvent.user_pseudo_id]
  // and
  // [SearchRequest.user_pseudo_id][google.cloud.discoveryengine.v1beta.SearchRequest.user_pseudo_id].
  //
  // The field must be a UTF-8 encoded string with a length limit of 128
  string user_pseudo_id = 4 [(google.api.field_behavior) = OPTIONAL];

  // Optional. Information about the end user.
  //
  // This should be the same identifier information as
  // [UserEvent.user_info][google.cloud.discoveryengine.v1beta.UserEvent.user_info]
  // and
  // [SearchRequest.user_info][google.cloud.discoveryengine.v1beta.SearchRequest.user_info].
  UserInfo user_info = 9 [(google.api.field_behavior) = OPTIONAL];

  // Indicates if tail suggestions should be returned if there are no
  // suggestions that match the full query. Even if set to true, if there are
  // suggestions that match the full query, those are returned and no
  // tail suggestions are returned.
  bool include_tail_suggestions = 5;

  // Optional. Specification to boost suggestions matching the condition.
  BoostSpec boost_spec = 6 [(google.api.field_behavior) = OPTIONAL];

  // Optional. Suggestion types to return. If empty or unspecified, query
  // suggestions are returned. Only one suggestion type is supported at the
  // moment.
  repeated SuggestionType suggestion_types = 7
      [(google.api.field_behavior) = OPTIONAL];

  // Optional. Specification of each suggestion type.
  repeated SuggestionTypeSpec suggestion_type_specs = 10
      [(google.api.field_behavior) = OPTIONAL];

  // Optional. Experiment ids for this request.
  repeated string experiment_ids = 14 [(google.api.field_behavior) = OPTIONAL];
}

// Response message for
// [CompletionService.AdvancedCompleteQuery][google.cloud.discoveryengine.v1beta.CompletionService.AdvancedCompleteQuery]
// method.
message AdvancedCompleteQueryResponse {
  // Suggestions as search queries.
  message QuerySuggestion {
    // The suggestion for the query.
    string suggestion = 1;

    // The unique document field paths that serve as the source of this
    // suggestion if it was generated from completable fields.
    //
    // This field is only populated for the document-completable model.
    repeated string completable_field_paths = 2;

    // The name of the dataStore that this suggestion belongs to.
    repeated string data_store = 3;

    // The score of each suggestion. The score is in the range of [0, 1].
    double score = 4;
  }

  // Suggestions as people.
  message PersonSuggestion {
    // The type of the person based on the source.
    enum PersonType {
      // Default value.
      PERSON_TYPE_UNSPECIFIED = 0;

      // The suggestion is from a GOOGLE_IDENTITY source.
      CLOUD_IDENTITY = 1;

      // The suggestion is from a THIRD_PARTY_IDENTITY source.
      THIRD_PARTY_IDENTITY = 2;
    }

    // The suggestion for the query.
    string suggestion = 1;

    // The type of the person.
    PersonType person_type = 2;

    // The document data snippet in the suggestion. Only a subset of fields is
    // populated.
    Document document = 4;

    // The name of the dataStore that this suggestion belongs to.
    string data_store = 5 [(google.api.resource_reference) = {
      type: "discoveryengine.googleapis.com/DataStore"
    }];

    // The score of each suggestion. The score is in the range of [0, 1].
    double score = 6;

    // The photo uri of the person suggestion.
    string display_photo_uri = 7;

    // The destination uri of the person suggestion.
    string destination_uri = 8;
  }

  // Suggestions as content.
  message ContentSuggestion {
    // The type of the content returned for content suggestions.
    enum ContentType {
      // Default value.
      CONTENT_TYPE_UNSPECIFIED = 0;

      // The suggestion is from a Google Workspace source.
      GOOGLE_WORKSPACE = 1;

      // The suggestion is from a third party source.
      THIRD_PARTY = 2;
    }

    // The suggestion for the query.
    string suggestion = 1;

    // The type of the content suggestion.
    ContentType content_type = 2;

    // The document data snippet in the suggestion. Only a subset of fields will
    // be populated.
    Document document = 4;

    // The name of the dataStore that this suggestion belongs to.
    string data_store = 5 [(google.api.resource_reference) = {
      type: "discoveryengine.googleapis.com/DataStore"
    }];

    // The score of each suggestion. The score is in the range of [0, 1].
    double score = 6;

    // The icon uri of the content suggestion.
    string icon_uri = 7;

    // The destination uri of the content suggestion.
    string destination_uri = 8;
  }

  // Suggestions from recent search history.
  message RecentSearchSuggestion {
    // The suggestion for the query.
    string suggestion = 1;

    // The time when this recent rearch happened.
    google.protobuf.Timestamp recent_search_time = 2;

    // The score of each suggestion. The score is in the range of [0, 1].
    double score = 3;
  }

  // Results of the matched query suggestions. The result list is ordered and
  // the first result is a top suggestion.
  repeated QuerySuggestion query_suggestions = 1;

  // True if the returned suggestions are all tail suggestions.
  //
  // For tail matching to be triggered, include_tail_suggestions in the request
  // must be true and there must be no suggestions that match the full query.
  bool tail_match_triggered = 2;

  // Results of the matched people suggestions. The result list is ordered and
  // the first result is the top suggestion.
  repeated PersonSuggestion people_suggestions = 3;

  // Results of the matched content suggestions. The result list is ordered and
  // the first result is the top suggestion.
  repeated ContentSuggestion content_suggestions = 4;

  // Results of the matched "recent search" suggestions. The result list is
  // ordered and the first result is the top suggestion.
  repeated RecentSearchSuggestion recent_search_suggestions = 5;
}

// Request message for
// [CompletionService.RemoveSuggestion][google.cloud.discoveryengine.v1beta.CompletionService.RemoveSuggestion]
// method.
message RemoveSuggestionRequest {
  // The suggestion to be removed.
  oneof suggestion {
    // The search history suggestion to be removed.
    string search_history_suggestion = 2;

    // Remove all search history suggestions for the user.
    bool remove_all_search_history_suggestions = 6;
  }

  // Required. The completion_config of the parent engine resource name for
  // which the search history suggestion is to be removed, such as
  // `projects/*/locations/global/collections/default_collection/engines/*/completionConfig`.
  string completion_config = 1 [
    (google.api.field_behavior) = REQUIRED,
    (google.api.resource_reference) = {
      type: "discoveryengine.googleapis.com/CompletionConfig"
    }
  ];

  // Required. 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`.
  //
  // This should be the same identifier as
  // [UserEvent.user_pseudo_id][google.cloud.discoveryengine.v1beta.UserEvent.user_pseudo_id]
  // and
  // [SearchRequest.user_pseudo_id][google.cloud.discoveryengine.v1beta.SearchRequest.user_pseudo_id].
  //
  // The field must be a UTF-8 encoded string with a length limit of 128.
  string user_pseudo_id = 3 [(google.api.field_behavior) = REQUIRED];

  // Optional. Information about the end user.
  //
  // This should be the same identifier information as
  // [UserEvent.user_info][google.cloud.discoveryengine.v1beta.UserEvent.user_info]
  // and
  // [SearchRequest.user_info][google.cloud.discoveryengine.v1beta.SearchRequest.user_info].
  UserInfo user_info = 4 [(google.api.field_behavior) = OPTIONAL];

  // Required. Time at which the suggestion was removed. If not set, the current
  // time will be used.
  google.protobuf.Timestamp remove_time = 5
      [(google.api.field_behavior) = REQUIRED];
}

// Response message for
// [CompletionService.RemoveSuggestion][google.cloud.discoveryengine.v1beta.CompletionService.RemoveSuggestion]
// method.
message RemoveSuggestionResponse {}