// 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/field_behavior.proto";
import "google/api/resource.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 = "AssistantProto";
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";

// Discovery Engine Assistant resource.
message Assistant {
  option (google.api.resource) = {
    type: "discoveryengine.googleapis.com/Assistant"
    pattern: "projects/{project}/locations/{location}/collections/{collection}/engines/{engine}/assistants/{assistant}"
  };

  // Configuration for the generation of the assistant response.
  message GenerationConfig {
    // System instruction, also known as the prompt preamble for LLM calls.
    message SystemInstruction {
      // Optional. Additional system instruction that will be added to the
      // default system instruction.
      string additional_system_instruction = 2
          [(google.api.field_behavior) = OPTIONAL];
    }

    // Optional. The default model to use for assistant.
    string default_model_id = 1 [(google.api.field_behavior) = OPTIONAL];

    // Optional. The list of models that are allowed to be used for assistant.
    repeated string allowed_model_ids = 2
        [(google.api.field_behavior) = OPTIONAL];

    // System instruction, also known as the prompt preamble for LLM calls.
    // See also
    // https://cloud.google.com/vertex-ai/generative-ai/docs/learn/prompts/system-instructions
    SystemInstruction system_instruction = 3;

    // The default language to use for the generation of the assistant
    // response.
    // Use an ISO 639-1 language code such as `en`.
    // If not specified, the language will be automatically detected.
    string default_language = 4;
  }

  // Information to identify a tool.
  message ToolInfo {
    // The name of the tool as defined by
    // DataConnectorService.QueryAvailableActions.
    // Note: it's using `action` in the DataConnectorService apis, but they are
    // the same as the `tool` here.
    string tool_name = 1;

    // The display name of the tool.
    string tool_display_name = 2;
  }

  // The enabled tools on a connector
  message ToolList {
    // The list of tools with corresponding tool information.
    repeated ToolInfo tool_info = 1;
  }

  // Customer-defined policy for the assistant.
  message CustomerPolicy {
    // Definition of a customer-defined banned phrase. A banned phrase is not
    // allowed to appear in the user query or the LLM response, or else the
    // answer will be refused.
    message BannedPhrase {
      // The matching method for the banned phrase.
      enum BannedPhraseMatchType {
        // Defaults to SIMPLE_STRING_MATCH.
        BANNED_PHRASE_MATCH_TYPE_UNSPECIFIED = 0;

        // The banned phrase matches if it is found anywhere in the text as an
        // exact substring.
        SIMPLE_STRING_MATCH = 1;

        // Banned phrase only matches if the pattern found in the text is
        // surrounded by word delimiters. The phrase itself may still contain
        // word delimiters.
        WORD_BOUNDARY_STRING_MATCH = 2;
      }

      // Required. The raw string content to be banned.
      string phrase = 1 [(google.api.field_behavior) = REQUIRED];

      // Optional. Match type for the banned phrase.
      BannedPhraseMatchType match_type = 2
          [(google.api.field_behavior) = OPTIONAL];

      // Optional. If true, diacritical marks (e.g., accents, umlauts) are
      // ignored when matching banned phrases. For example, "cafe" would match
      // "café".
      bool ignore_diacritics = 3 [(google.api.field_behavior) = OPTIONAL];
    }

    // Configuration for customer defined Model Armor templates to be used for
    // sanitizing user prompts and assistant responses.
    message ModelArmorConfig {
      // Determines the behavior when Model Armor fails to process a request.
      enum FailureMode {
        // Unspecified failure mode, default behavior is `FAIL_CLOSED`.
        FAILURE_MODE_UNSPECIFIED = 0;

        // In case of a Model Armor processing failure, the request is allowed
        // to proceed without any changes.
        FAIL_OPEN = 1;

        // In case of a Model Armor processing failure, the request is rejected.
        FAIL_CLOSED = 2;
      }

      // Optional. The resource name of the Model Armor template for sanitizing
      // user prompts. Format:
      // `projects/{project}/locations/{location}/templates/{template_id}`
      //
      // If not specified, no sanitization will be applied to the user prompt.
      string user_prompt_template = 1 [
        (google.api.field_behavior) = OPTIONAL,
        (google.api.resource_reference) = {
          type: "modelarmor.googleapis.com/Template"
        }
      ];

      // Optional. The resource name of the Model Armor template for sanitizing
      // assistant responses. Format:
      // `projects/{project}/locations/{location}/templates/{template_id}`
      //
      // If not specified, no sanitization will be applied to the assistant
      // response.
      string response_template = 2 [
        (google.api.field_behavior) = OPTIONAL,
        (google.api.resource_reference) = {
          type: "modelarmor.googleapis.com/Template"
        }
      ];

      // Optional. Defines the failure mode for Model Armor sanitization.
      FailureMode failure_mode = 3 [(google.api.field_behavior) = OPTIONAL];
    }

    // Optional. List of banned phrases.
    repeated BannedPhrase banned_phrases = 1
        [(google.api.field_behavior) = OPTIONAL];

    // Optional. Model Armor configuration to be used for sanitizing user
    // prompts and assistant responses.
    ModelArmorConfig model_armor_config = 2
        [(google.api.field_behavior) = OPTIONAL];
  }

  // The type of web grounding to use.
  enum WebGroundingType {
    // Default, unspecified setting. This is the same as disabled.
    WEB_GROUNDING_TYPE_UNSPECIFIED = 0;

    // Web grounding is disabled.
    WEB_GROUNDING_TYPE_DISABLED = 1;

    // Grounding with Google Search is enabled.
    WEB_GROUNDING_TYPE_GOOGLE_SEARCH = 2;

    // Grounding with Enterprise Web Search is enabled.
    WEB_GROUNDING_TYPE_ENTERPRISE_WEB_SEARCH = 3;
  }

  // Immutable. Resource name of the assistant.
  // Format:
  // `projects/{project}/locations/{location}/collections/{collection}/engines/{engine}/assistants/{assistant}`
  //
  // It must be a UTF-8 encoded string with a length limit of 1024 characters.
  string name = 1 [(google.api.field_behavior) = IMMUTABLE];

  // Required. The assistant display name.
  //
  // It must be a UTF-8 encoded string with a length limit of 128 characters.
  string display_name = 2 [(google.api.field_behavior) = REQUIRED];

  // Optional. Description for additional information. Expected to be shown on
  // the configuration UI, not to the users of the assistant.
  string description = 3 [(google.api.field_behavior) = OPTIONAL];

  // Optional. Configuration for the generation of the assistant response.
  GenerationConfig generation_config = 19
      [(google.api.field_behavior) = OPTIONAL];

  // Optional. The type of web grounding to use.
  WebGroundingType web_grounding_type = 4
      [(google.api.field_behavior) = OPTIONAL];

  // Optional. This field controls the default web grounding toggle for end
  // users if `web_grounding_type` is set to `WEB_GROUNDING_TYPE_GOOGLE_SEARCH`
  // or `WEB_GROUNDING_TYPE_ENTERPRISE_WEB_SEARCH`. By default, this field is
  // set to false. If `web_grounding_type` is `WEB_GROUNDING_TYPE_GOOGLE_SEARCH`
  // or `WEB_GROUNDING_TYPE_ENTERPRISE_WEB_SEARCH`, end users will have web
  // grounding enabled by default on UI. If true, grounding toggle will be
  // disabled by default on UI. End users can still enable web grounding in
  // the UI if web grounding is enabled.
  bool default_web_grounding_toggle_off = 22
      [(google.api.field_behavior) = OPTIONAL];

  // Optional. Note: not implemented yet. Use
  // [enabled_actions][google.cloud.discoveryengine.v1beta.Assistant.enabled_actions]
  // instead. The enabled tools on this assistant. The keys are connector name,
  // for example
  // "projects/{projectId}/locations/{locationId}/collections/{collectionId}/dataconnector
  // The values consist of admin enabled tools towards the connector
  // instance. Admin can selectively enable multiple tools on any of the
  // connector instances that they created in the project. For example
  // {"jira1ConnectorName": [(toolId1, "createTicket"), (toolId2,
  // "transferTicket")],
  //  "gmail1ConnectorName": [(toolId3, "sendEmail"),..] }
  map<string, ToolList> enabled_tools = 18
      [(google.api.field_behavior) = OPTIONAL];

  // Optional. Customer policy for the assistant.
  CustomerPolicy customer_policy = 12 [(google.api.field_behavior) = OPTIONAL];

  // Output only. Represents the time when this Assistant was created.
  google.protobuf.Timestamp create_time = 24
      [(google.api.field_behavior) = OUTPUT_ONLY];

  // Output only. Represents the time when this Assistant was most recently
  // updated.
  google.protobuf.Timestamp update_time = 25
      [(google.api.field_behavior) = OUTPUT_ONLY];
}