// Copyright 2021 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.dialogflow.cx.v3;

import "google/api/annotations.proto";
import "google/api/client.proto";
import "google/api/field_behavior.proto";
import "google/api/resource.proto";
import "google/protobuf/empty.proto";
import "google/protobuf/field_mask.proto";

option cc_enable_arenas = true;
option csharp_namespace = "Google.Cloud.Dialogflow.Cx.V3";
option go_package = "google.golang.org/genproto/googleapis/cloud/dialogflow/cx/v3;cx";
option java_multiple_files = true;
option java_outer_classname = "EntityTypeProto";
option java_package = "com.google.cloud.dialogflow.cx.v3";
option objc_class_prefix = "DF";

// Service for managing [EntityTypes][google.cloud.dialogflow.cx.v3.EntityType].
service EntityTypes {
  option (google.api.default_host) = "dialogflow.googleapis.com";
  option (google.api.oauth_scopes) =
      "https://www.googleapis.com/auth/cloud-platform,"
      "https://www.googleapis.com/auth/dialogflow";

  // Returns the list of all entity types in the specified agent.
  rpc ListEntityTypes(ListEntityTypesRequest) returns (ListEntityTypesResponse) {
    option (google.api.http) = {
      get: "/v3/{parent=projects/*/locations/*/agents/*}/entityTypes"
    };
    option (google.api.method_signature) = "parent";
  }

  // Retrieves the specified entity type.
  rpc GetEntityType(GetEntityTypeRequest) returns (EntityType) {
    option (google.api.http) = {
      get: "/v3/{name=projects/*/locations/*/agents/*/entityTypes/*}"
    };
    option (google.api.method_signature) = "name";
  }

  // Creates an entity type in the specified agent.
  //
  // Note: You should always train a flow prior to sending it queries. See the
  // [training
  // documentation](https://cloud.google.com/dialogflow/cx/docs/concept/training).
  rpc CreateEntityType(CreateEntityTypeRequest) returns (EntityType) {
    option (google.api.http) = {
      post: "/v3/{parent=projects/*/locations/*/agents/*}/entityTypes"
      body: "entity_type"
    };
    option (google.api.method_signature) = "parent,entity_type";
  }

  // Updates the specified entity type.
  //
  // Note: You should always train a flow prior to sending it queries. See the
  // [training
  // documentation](https://cloud.google.com/dialogflow/cx/docs/concept/training).
  rpc UpdateEntityType(UpdateEntityTypeRequest) returns (EntityType) {
    option (google.api.http) = {
      patch: "/v3/{entity_type.name=projects/*/locations/*/agents/*/entityTypes/*}"
      body: "entity_type"
    };
    option (google.api.method_signature) = "entity_type,update_mask";
  }

  // Deletes the specified entity type.
  //
  // Note: You should always train a flow prior to sending it queries. See the
  // [training
  // documentation](https://cloud.google.com/dialogflow/cx/docs/concept/training).
  rpc DeleteEntityType(DeleteEntityTypeRequest) returns (google.protobuf.Empty) {
    option (google.api.http) = {
      delete: "/v3/{name=projects/*/locations/*/agents/*/entityTypes/*}"
    };
    option (google.api.method_signature) = "name";
  }
}

// Entities are extracted from user input and represent parameters that are
// meaningful to your application. For example, a date range, a proper name
// such as a geographic location or landmark, and so on. Entities represent
// actionable data for your application.
//
// When you define an entity, you can also include synonyms that all map to
// that entity. For example, "soft drink", "soda", "pop", and so on.
//
// There are three types of entities:
//
// *   **System** - entities that are defined by the Dialogflow API for common
//     data types such as date, time, currency, and so on. A system entity is
//     represented by the `EntityType` type.
//
// *   **Custom** - entities that are defined by you that represent
//     actionable data that is meaningful to your application. For example,
//     you could define a `pizza.sauce` entity for red or white pizza sauce,
//     a `pizza.cheese` entity for the different types of cheese on a pizza,
//     a `pizza.topping` entity for different toppings, and so on. A custom
//     entity is represented by the `EntityType` type.
//
// *   **User** - entities that are built for an individual user such as
//     favorites, preferences, playlists, and so on. A user entity is
//     represented by the [SessionEntityType][google.cloud.dialogflow.cx.v3.SessionEntityType] type.
//
// For more information about entity types, see the [Dialogflow
// documentation](https://cloud.google.com/dialogflow/docs/entities-overview).
message EntityType {
  option (google.api.resource) = {
    type: "dialogflow.googleapis.com/EntityType"
    pattern: "projects/{project}/locations/{location}/agents/{agent}/entityTypes/{entity_type}"
  };

  // An **entity entry** for an associated entity type.
  message Entity {
    // Required. The primary value associated with this entity entry.
    // For example, if the entity type is *vegetable*, the value could be
    // *scallions*.
    //
    // For `KIND_MAP` entity types:
    //
    // *   A canonical value to be used in place of synonyms.
    //
    // For `KIND_LIST` entity types:
    //
    // *   A string that can contain references to other entity types (with or
    //     without aliases).
    string value = 1 [(google.api.field_behavior) = REQUIRED];

    // Required. A collection of value synonyms. For example, if the entity type
    // is *vegetable*, and `value` is *scallions*, a synonym could be *green
    // onions*.
    //
    // For `KIND_LIST` entity types:
    //
    // *   This collection must contain exactly one synonym equal to `value`.
    repeated string synonyms = 2 [(google.api.field_behavior) = REQUIRED];
  }

  // An excluded entity phrase that should not be matched.
  message ExcludedPhrase {
    // Required. The word or phrase to be excluded.
    string value = 1 [(google.api.field_behavior) = REQUIRED];
  }

  // Represents kinds of entities.
  enum Kind {
    // Not specified. This value should be never used.
    KIND_UNSPECIFIED = 0;

    // Map entity types allow mapping of a group of synonyms to a canonical
    // value.
    KIND_MAP = 1;

    // List entity types contain a set of entries that do not map to canonical
    // values. However, list entity types can contain references to other entity
    // types (with or without aliases).
    KIND_LIST = 2;

    // Regexp entity types allow to specify regular expressions in entries
    // values.
    KIND_REGEXP = 3;
  }

  // Represents different entity type expansion modes. Automated expansion
  // allows an agent to recognize values that have not been explicitly listed in
  // the entity (for example, new kinds of shopping list items).
  enum AutoExpansionMode {
    // Auto expansion disabled for the entity.
    AUTO_EXPANSION_MODE_UNSPECIFIED = 0;

    // Allows an agent to recognize values that have not been explicitly
    // listed in the entity.
    AUTO_EXPANSION_MODE_DEFAULT = 1;
  }

  // The unique identifier of the entity type.
  // Required for [EntityTypes.UpdateEntityType][google.cloud.dialogflow.cx.v3.EntityTypes.UpdateEntityType].
  // Format: `projects/<Project ID>/locations/<Location ID>/agents/<Agent
  // ID>/entityTypes/<Entity Type ID>`.
  string name = 1;

  // Required. The human-readable name of the entity type, unique within the agent.
  string display_name = 2 [(google.api.field_behavior) = REQUIRED];

  // Required. Indicates the kind of entity type.
  Kind kind = 3 [(google.api.field_behavior) = REQUIRED];

  // Indicates whether the entity type can be automatically expanded.
  AutoExpansionMode auto_expansion_mode = 4;

  // The collection of entity entries associated with the entity type.
  repeated Entity entities = 5;

  // Collection of exceptional words and phrases that shouldn't be matched.
  // For example, if you have a size entity type with entry `giant`(an
  // adjective), you might consider adding `giants`(a noun) as an exclusion.
  // If the kind of entity type is `KIND_MAP`, then the phrases specified by
  // entities and excluded phrases should be mutually exclusive.
  repeated ExcludedPhrase excluded_phrases = 6;

  // Enables fuzzy entity extraction during classification.
  bool enable_fuzzy_extraction = 7;

  // Indicates whether parameters of the entity type should be redacted in log.
  // If redaction is enabled, page parameters and intent parameters referring to
  // the entity type will be replaced by parameter name when logging.
  bool redact = 9;
}

// The request message for [EntityTypes.ListEntityTypes][google.cloud.dialogflow.cx.v3.EntityTypes.ListEntityTypes].
message ListEntityTypesRequest {
  // Required. The agent to list all entity types for.
  // Format: `projects/<Project ID>/locations/<Location ID>/agents/<Agent ID>`.
  string parent = 1 [
    (google.api.field_behavior) = REQUIRED,
    (google.api.resource_reference) = {
      child_type: "dialogflow.googleapis.com/EntityType"
    }
  ];

  // The language to list entity types for. The following fields are language
  // dependent:
  //
  // *   `EntityType.entities.value`
  // *   `EntityType.entities.synonyms`
  // *   `EntityType.excluded_phrases.value`
  //
  // If not specified, the agent's default language is used.
  // [Many
  // languages](https://cloud.google.com/dialogflow/cx/docs/reference/language)
  // are supported.
  // Note: languages must be enabled in the agent before they can be used.
  string language_code = 2;

  // The maximum number of items to return in a single page. By default 100 and
  // at most 1000.
  int32 page_size = 3;

  // The next_page_token value returned from a previous list request.
  string page_token = 4;
}

// The response message for [EntityTypes.ListEntityTypes][google.cloud.dialogflow.cx.v3.EntityTypes.ListEntityTypes].
message ListEntityTypesResponse {
  // The list of entity types. There will be a maximum number of items returned
  // based on the page_size field in the request.
  repeated EntityType entity_types = 1;

  // Token to retrieve the next page of results, or empty if there are no
  // more results in the list.
  string next_page_token = 2;
}

// The request message for [EntityTypes.GetEntityType][google.cloud.dialogflow.cx.v3.EntityTypes.GetEntityType].
message GetEntityTypeRequest {
  // Required. The name of the entity type.
  // Format: `projects/<Project ID>/locations/<Location ID>/agents/<Agent
  // ID>/entityTypes/<Entity Type ID>`.
  string name = 1 [
    (google.api.field_behavior) = REQUIRED,
    (google.api.resource_reference) = {
      type: "dialogflow.googleapis.com/EntityType"
    }
  ];

  // The language to retrieve the entity type for. The following fields are
  // language dependent:
  //
  // *   `EntityType.entities.value`
  // *   `EntityType.entities.synonyms`
  // *   `EntityType.excluded_phrases.value`
  //
  // If not specified, the agent's default language is used.
  // [Many
  // languages](https://cloud.google.com/dialogflow/cx/docs/reference/language)
  // are supported.
  // Note: languages must be enabled in the agent before they can be used.
  string language_code = 2;
}

// The request message for [EntityTypes.CreateEntityType][google.cloud.dialogflow.cx.v3.EntityTypes.CreateEntityType].
message CreateEntityTypeRequest {
  // Required. The agent to create a entity type for.
  // Format: `projects/<Project ID>/locations/<Location ID>/agents/<Agent ID>`.
  string parent = 1 [
    (google.api.field_behavior) = REQUIRED,
    (google.api.resource_reference) = {
      child_type: "dialogflow.googleapis.com/EntityType"
    }
  ];

  // Required. The entity type to create.
  EntityType entity_type = 2 [(google.api.field_behavior) = REQUIRED];

  // The language of the following fields in `entity_type`:
  //
  // *   `EntityType.entities.value`
  // *   `EntityType.entities.synonyms`
  // *   `EntityType.excluded_phrases.value`
  //
  // If not specified, the agent's default language is used.
  // [Many
  // languages](https://cloud.google.com/dialogflow/cx/docs/reference/language)
  // are supported.
  // Note: languages must be enabled in the agent before they can be used.
  string language_code = 3;
}

// The request message for [EntityTypes.UpdateEntityType][google.cloud.dialogflow.cx.v3.EntityTypes.UpdateEntityType].
message UpdateEntityTypeRequest {
  // Required. The entity type to update.
  EntityType entity_type = 1 [(google.api.field_behavior) = REQUIRED];

  // The language of the following fields in `entity_type`:
  //
  // *   `EntityType.entities.value`
  // *   `EntityType.entities.synonyms`
  // *   `EntityType.excluded_phrases.value`
  //
  // If not specified, the agent's default language is used.
  // [Many
  // languages](https://cloud.google.com/dialogflow/cx/docs/reference/language)
  // are supported.
  // Note: languages must be enabled in the agent before they can be used.
  string language_code = 2;

  // The mask to control which fields get updated.
  google.protobuf.FieldMask update_mask = 3;
}

// The request message for [EntityTypes.DeleteEntityType][google.cloud.dialogflow.cx.v3.EntityTypes.DeleteEntityType].
message DeleteEntityTypeRequest {
  // Required. The name of the entity type to delete.
  // Format: `projects/<Project ID>/locations/<Location ID>/agents/<Agent
  // ID>/entityTypes/<Entity Type ID>`.
  string name = 1 [
    (google.api.field_behavior) = REQUIRED,
    (google.api.resource_reference) = {
      type: "dialogflow.googleapis.com/EntityType"
    }
  ];

  // This field has no effect for entity type not being used.
  // For entity types that are used by intents or pages:
  //
  // *  If `force` is set to false, an error will be returned with message
  //    indicating the referencing resources.
  // *  If `force` is set to true, Dialogflow will remove the entity type, as
  //    well as any references to the entity type (i.e. Page
  //    [parameter][google.cloud.dialogflow.cx.v3.Form.Parameter] of the entity type will be changed to
  //    '@sys.any' and intent [parameter][google.cloud.dialogflow.cx.v3.Intent.Parameter] of the entity type
  //    will be removed).
  bool force = 2;
}
