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

import "google/api/field_behavior.proto";
import "google/api/resource.proto";
import "google/cloud/ces/v1beta/common.proto";
import "google/cloud/ces/v1beta/example.proto";
import "google/protobuf/timestamp.proto";

option go_package = "cloud.google.com/go/ces/apiv1beta/cespb;cespb";
option java_multiple_files = true;
option java_outer_classname = "ConversationProto";
option java_package = "com.google.cloud.ces.v1beta";

// A conversation represents an interaction between an end user and the CES app.
message Conversation {
  option (google.api.resource) = {
    type: "ces.googleapis.com/Conversation"
    pattern: "projects/{project}/locations/{location}/apps/{app}/conversations/{conversation}"
    plural: "conversations"
    singular: "conversation"
  };

  // All information about a single turn in the conversation.
  message Turn {
    // Optional. List of messages in the conversation turn, including user
    // input, agent responses and intermediate events during the processing.
    repeated Message messages = 1 [(google.api.field_behavior) = OPTIONAL];

    // Optional. The root span of the action processing.
    Span root_span = 2 [(google.api.field_behavior) = OPTIONAL];
  }

  // The channel type of the conversation.
  enum ChannelType {
    // Unspecified channel type.
    CHANNEL_TYPE_UNSPECIFIED = 0;

    // The conversation only contains text messages between the end user and the
    // agent.
    TEXT = 1;

    // The conversation contains audio messages between the end user and the
    // agent.
    AUDIO = 2;

    // The conversation multi-modal messages (e.g. image) between the end user
    // and the agent.
    MULTIMODAL = 3;
  }

  // The source of the conversation.
  enum Source {
    // Unspecified source.
    SOURCE_UNSPECIFIED = 0;

    // The conversation is from the live end user.
    LIVE = 1;

    // The conversation is from the simulator.
    SIMULATOR = 2;

    // The conversation is from the evaluation.
    EVAL = 3;

    // The conversation is from an agent tool. Agent tool runs the agent in a
    // separate session, which is persisted for testing and debugging purposes.
    AGENT_TOOL = 4;
  }

  // Type of the input message.
  enum InputType {
    // Unspecified input type.
    INPUT_TYPE_UNSPECIFIED = 0;

    // The input message is text.
    INPUT_TYPE_TEXT = 1;

    // The input message is audio.
    INPUT_TYPE_AUDIO = 2;

    // The input message is image.
    INPUT_TYPE_IMAGE = 3;

    // The input message is blob file.
    INPUT_TYPE_BLOB = 4;

    // The input message is client function tool response.
    INPUT_TYPE_TOOL_RESPONSE = 5;

    // The input message are variables.
    INPUT_TYPE_VARIABLES = 6;
  }

  // Identifier. The unique identifier of the conversation.
  // Format:
  // `projects/{project}/locations/{location}/apps/{app}/conversations/{conversation}`
  string name = 1 [(google.api.field_behavior) = IDENTIFIER];

  // Output only. Timestamp when the conversation was created.
  google.protobuf.Timestamp start_time = 3
      [(google.api.field_behavior) = OUTPUT_ONLY];

  // Output only. Timestamp when the conversation was completed.
  google.protobuf.Timestamp end_time = 4
      [(google.api.field_behavior) = OUTPUT_ONLY];

  // Required. The turns in the conversation.
  repeated Turn turns = 6 [(google.api.field_behavior) = REQUIRED];

  // Output only. The number of turns in the conversation.
  int32 turn_count = 7 [(google.api.field_behavior) = OUTPUT_ONLY];

  // DEPRECATED. Please use
  // [input_types][google.cloud.ces.v1beta.Conversation.input_types] instead.
  ChannelType channel_type = 8 [deprecated = true];

  // Output only. Indicate the source of the conversation.
  Source source = 9 [(google.api.field_behavior) = OUTPUT_ONLY];

  // Output only. The input types of the conversation.
  repeated InputType input_types = 10
      [(google.api.field_behavior) = OUTPUT_ONLY];

  // Output only. The agent that initially handles the conversation. If not
  // specified, the conversation is handled by the root agent. Format:
  // `projects/{project}/locations/{location}/apps/{app}/agents/{agent}`
  string entry_agent = 11 [
    (google.api.field_behavior) = OUTPUT_ONLY,
    (google.api.resource_reference) = { type: "ces.googleapis.com/Agent" }
  ];

  // Output only. The deployment of the app used for processing the
  // conversation. Format:
  // `projects/{project}/locations/{location}/apps/{app}/deployments/{deployment}`
  string deployment = 12 [
    (google.api.field_behavior) = OUTPUT_ONLY,
    (google.api.resource_reference) = { type: "ces.googleapis.com/Deployment" }
  ];

  // Output only. The version of the app used for processing the conversation.
  // Format:
  // `projects/{project}/locations/{location}/apps/{app}/versions/{version}`
  string app_version = 13 [
    (google.api.field_behavior) = OUTPUT_ONLY,
    (google.api.resource_reference) = { type: "ces.googleapis.com/AppVersion" }
  ];

  // Output only. The language code of the conversation.
  string language_code = 14 [(google.api.field_behavior) = OUTPUT_ONLY];

  // Deprecated. Use turns instead.
  repeated Message messages = 2 [deprecated = true];
}