// 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.ces.v1;

import "google/api/field_behavior.proto";
import "google/cloud/ces/v1/python_function.proto";
import "google/cloud/ces/v1/schema.proto";
import "google/protobuf/struct.proto";

option go_package = "cloud.google.com/go/ces/apiv1/cespb;cespb";
option java_multiple_files = true;
option java_outer_classname = "WidgetToolProto";
option java_package = "com.google.cloud.ces.v1";

// Represents a widget tool that the agent can invoke. When the tool is chosen
// by the agent, agent will return the widget to the client. The client is
// responsible for processing the widget and generating the next user query to
// continue the interaction with the agent.
message WidgetTool {
  // Configuration for mapping data from a source tool to the widget's input
  // parameters.
  message DataMapping {
    // The strategy used to map data from the source tool to the widget.
    enum Mode {
      // Unspecified mode.
      MODE_UNSPECIFIED = 0;

      // Use the `field_mappings` map for data transformation.
      FIELD_MAPPING = 1;

      // Use the `python_script` for data transformation.
      PYTHON_SCRIPT = 2;
    }

    // Optional. The resource name of the tool that provides the data for the
    // widget (e.g., a search tool or a custom function). Format:
    // `projects/{project}/locations/{location}/agents/{agent}/tools/{tool}`
    string source_tool_name = 1 [(google.api.field_behavior) = OPTIONAL];

    // Optional. A map of widget input parameter fields to the corresponding
    // output fields of the source tool.
    map<string, string> field_mappings = 2
        [(google.api.field_behavior) = OPTIONAL];

    // Optional. Configuration for a Python function used to transform the
    // source tool's output into the widget's input format.
    PythonFunction python_function = 5 [(google.api.field_behavior) = OPTIONAL];

    // Optional. The mode of the data mapping.
    Mode mode = 4 [(google.api.field_behavior) = OPTIONAL];

    // Deprecated: Use `python_function` instead.
    string python_script = 3 [deprecated = true];
  }

  // All available widget types.
  // New values may be added to this enum in the future.
  enum WidgetType {
    // Unspecified widget type.
    WIDGET_TYPE_UNSPECIFIED = 0;

    // Custom widget type.
    CUSTOM = 1;

    // Product carousel widget.
    PRODUCT_CAROUSEL = 2;

    // Product details widget.
    PRODUCT_DETAILS = 3;

    // Quick actions widget.
    QUICK_ACTIONS = 4;

    // Product comparison widget.
    PRODUCT_COMPARISON = 5;

    // Advanced product details widget.
    ADVANCED_PRODUCT_DETAILS = 6;

    // Short form widget.
    SHORT_FORM = 7;

    // Overall satisfaction widget.
    OVERALL_SATISFACTION = 8;

    // Order summary widget.
    ORDER_SUMMARY = 9;

    // Appointment details widget.
    APPOINTMENT_DETAILS = 10;

    // Appointment scheduler widget.
    APPOINTMENT_SCHEDULER = 11;

    // Contact form widget.
    CONTACT_FORM = 12;
  }

  // The input of the widget tool.
  oneof input {
    // Optional. The input parameters of the widget tool.
    Schema parameters = 4 [(google.api.field_behavior) = OPTIONAL];
  }

  // Required. The display name of the widget tool.
  string name = 1 [(google.api.field_behavior) = REQUIRED];

  // Optional. The description of the widget tool.
  string description = 2 [(google.api.field_behavior) = OPTIONAL];

  // Optional. The type of the widget tool. If not specified, the default type
  // will be CUSTOMIZED.
  WidgetType widget_type = 3 [(google.api.field_behavior) = OPTIONAL];

  // Optional. Configuration for rendering the widget.
  google.protobuf.Struct ui_config = 5 [(google.api.field_behavior) = OPTIONAL];

  // Optional. The mapping that defines how data from a source tool is mapped to
  // the widget's input parameters.
  DataMapping data_mapping = 6 [(google.api.field_behavior) = OPTIONAL];
}