googleapis/google/cloud/discoveryengine/v1alpha/session.proto

// Copyright 2025 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.v1alpha;

import "google/api/field_behavior.proto";
import "google/api/resource.proto";
import "google/cloud/discoveryengine/v1alpha/answer.proto";
import "google/cloud/discoveryengine/v1alpha/common.proto";
import "google/protobuf/duration.proto";
import "google/protobuf/timestamp.proto";

option csharp_namespace = "Google.Cloud.DiscoveryEngine.V1Alpha";
option go_package = "cloud.google.com/go/discoveryengine/apiv1alpha/discoveryenginepb;discoveryenginepb";
option java_multiple_files = true;
option java_outer_classname = "SessionProto";
option java_package = "com.google.cloud.discoveryengine.v1alpha";
option objc_class_prefix = "DISCOVERYENGINE";
option php_namespace = "Google\\Cloud\\DiscoveryEngine\\V1alpha";
option ruby_package = "Google::Cloud::DiscoveryEngine::V1alpha";

// Original source of the file.
enum FileSource {
  // Default value. Unknown source.
  FILE_SOURCE_UNSPECIFIED = 0;

  // The data of the file was provided inline (e.g. pasted from the clipboard).
  FILE_SOURCE_INLINE = 1;

  // The file was uploaded from a local file.
  FILE_SOURCE_LOCAL = 2;

  // The file was uploaded from Cloud Storage.
  FILE_SOURCE_CLOUD_STORAGE = 3;

  // The file was uploaded from Drive.
  FILE_SOURCE_CLOUD_DRIVE = 4;

  // The file was retrieved from a URL (e.g. public web).
  FILE_SOURCE_URL = 5;
}

// External session proto definition.
message Session {
  option (google.api.resource) = {
    type: "discoveryengine.googleapis.com/Session"
    pattern: "projects/{project}/locations/{location}/dataStores/{data_store}/sessions/{session}"
    pattern: "projects/{project}/locations/{location}/collections/{collection}/dataStores/{data_store}/sessions/{session}"
    pattern: "projects/{project}/locations/{location}/collections/{collection}/engines/{engine}/sessions/{session}"
    plural: "sessions"
    singular: "session"
  };

  // Represents a turn, including a query from the user and a
  // answer from service.
  message Turn {
    // Optional. The user query. May not be set if this turn is merely
    // regenerating an answer to a different turn
    Query query = 1 [(google.api.field_behavior) = OPTIONAL];

    // Optional. The resource name of the answer to the user query.
    //
    // Only set if the answer generation (/answer API call) happened in this
    // turn.
    string answer = 2 [
      (google.api.field_behavior) = OPTIONAL,
      (google.api.resource_reference) = {
        type: "discoveryengine.googleapis.com/Answer"
      }
    ];

    // Output only. In
    // [ConversationalSearchService.GetSession][google.cloud.discoveryengine.v1alpha.ConversationalSearchService.GetSession]
    // API, if
    // [GetSessionRequest.include_answer_details][google.cloud.discoveryengine.v1alpha.GetSessionRequest.include_answer_details]
    // is set to true, this field will be populated when getting answer query
    // session.
    Answer detailed_answer = 7 [(google.api.field_behavior) = OUTPUT_ONLY];

    // Optional. Represents metadata related to the query config, for example
    // LLM model and version used, model parameters (temperature, grounding
    // parameters, etc.). The prefix "google." is reserved for Google-developed
    // functionality.
    map<string, string> query_config = 16
        [(google.api.field_behavior) = OPTIONAL];
  }

  // Enumeration of the state of the session.
  enum State {
    // State is unspecified.
    STATE_UNSPECIFIED = 0;

    // The session is currently open.
    IN_PROGRESS = 1;
  }

  // Immutable. Fully qualified name
  // `projects/{project}/locations/global/collections/{collection}/engines/{engine}/sessions/*`
  string name = 1 [(google.api.field_behavior) = IMMUTABLE];

  // Optional. The display name of the session.
  //
  // This field is used to identify the session in the UI.
  // By default, the display name is the first turn query text in the session.
  string display_name = 7 [(google.api.field_behavior) = OPTIONAL];

  // The state of the session.
  State state = 2;

  // A unique identifier for tracking users.
  string user_pseudo_id = 3;

  // Turns.
  repeated Turn turns = 4;

  // Output only. The time the session started.
  google.protobuf.Timestamp start_time = 5
      [(google.api.field_behavior) = OUTPUT_ONLY];

  // Output only. The time the session finished.
  google.protobuf.Timestamp end_time = 6
      [(google.api.field_behavior) = OUTPUT_ONLY];

  // Optional. Whether the session is pinned, pinned session will be displayed
  // on the top of the session list.
  bool is_pinned = 8 [(google.api.field_behavior) = OPTIONAL];
}

// Defines a user inputed query.
message Query {
  // Query content.
  oneof content {
    // Plain text.
    string text = 2;
  }

  // Output only. Unique Id for the query.
  string query_id = 1 [(google.api.field_behavior) = OUTPUT_ONLY];
}

// Standard characteristics of an image media view.
message ImageCharacteristics {
  // Possible color spaces of an image (e.g., "RGB", "CMYK", "Grayscale").
  enum ColorSpace {
    // Default value. Unknown color space.
    COLOR_SPACE_UNSPECIFIED = 0;

    // Red, green, blue colorspace.
    RGB = 1;

    // Cyan, magenta, yellow, and black colorspace.
    CMYK = 2;

    // Grayscale colorspace.
    GRAYSCALE = 3;

    // YUV colorspace.
    YUV = 4;

    // Other colorspace.
    OTHER_COLOR_SPACE = 5;
  }

  // Output only. Image width in pixels.
  int32 width = 1 [(google.api.field_behavior) = OUTPUT_ONLY];

  // Output only. Image height in pixels.
  int32 height = 2 [(google.api.field_behavior) = OUTPUT_ONLY];

  // Output only. Color space of the image (e.g., "RGB", "CMYK", "Grayscale").
  ColorSpace color_space = 3 [(google.api.field_behavior) = OUTPUT_ONLY];

  // Output only. Bit depth of the image (e.g., 8-bit, 16-bit).
  int32 bit_depth = 4 [(google.api.field_behavior) = OUTPUT_ONLY];
}

// Standard characteristics of a video media view.
message VideoCharacteristics {
  // Output only. Video width in pixels.
  int32 width = 1 [(google.api.field_behavior) = OUTPUT_ONLY];

  // Output only. Video height in pixels.
  int32 height = 2 [(google.api.field_behavior) = OUTPUT_ONLY];

  // Output only. Video duration.
  google.protobuf.Duration duration = 3
      [(google.api.field_behavior) = OUTPUT_ONLY];

  // Output only. Frame rate (frames per second).
  double frame_rate = 4 [(google.api.field_behavior) = OUTPUT_ONLY];

  // Output only. Audio codecs used in the video.
  repeated string audio_codecs = 5 [(google.api.field_behavior) = OUTPUT_ONLY];

  // Output only. Video codecs used in the video.
  repeated string video_codecs = 6 [(google.api.field_behavior) = OUTPUT_ONLY];

  // Output only. Bitrate of the video in kbps.
  int32 video_bitrate_kbps = 7 [(google.api.field_behavior) = OUTPUT_ONLY];

  // Output only. Bitrate of the audio in kbps.
  int32 audio_bitrate_kbps = 8 [(google.api.field_behavior) = OUTPUT_ONLY];
}

// Caracteristics of other file types.
message FileCharacteristics {
  // Output only. Generic map of characteristics.
  map<string, string> characteristics = 6
      [(google.api.field_behavior) = OUTPUT_ONLY];
}

// Represents a specific alternate version or "view" of a file object,
// such as a summary, a thumbnail, a translated version, etc.
message FileView {
  // Characteristics of the media view, allowing for flexible extensions.
  // Metadata is always internally generated by the process creating
  // the view.
  oneof characteristics {
    // Output only. Characteristics of an image media view.
    ImageCharacteristics image_characteristics = 6
        [(google.api.field_behavior) = OUTPUT_ONLY];

    // Output only. Characteristics of a video media view.
    VideoCharacteristics video_characteristics = 7
        [(google.api.field_behavior) = OUTPUT_ONLY];

    // Output only. Characteristics of other file types.
    FileCharacteristics file_characteristics = 8
        [(google.api.field_behavior) = OUTPUT_ONLY];
  }

  // Output only. Globally Unique id for this specific view.
  string view_id = 1 [(google.api.field_behavior) = OUTPUT_ONLY];

  // Output only. The URI to access this media view.
  string uri = 2 [(google.api.field_behavior) = OUTPUT_ONLY];

  // Output only. MIME type (e.g., "image/jpeg", "image/png", "text/plain",
  // "video/mp4")
  string mime_type = 3 [(google.api.field_behavior) = OUTPUT_ONLY];

  // Output only. The size of the view in bytes.
  int64 byte_size = 4 [(google.api.field_behavior) = OUTPUT_ONLY];

  // Output only. The time the view was created.
  google.protobuf.Timestamp create_time = 5
      [(google.api.field_behavior) = OUTPUT_ONLY];
}

// Represents a file attached to a session (context file)
message FileMetadata {
  // Output only. The ID of the file.
  string file_id = 1 [(google.api.field_behavior) = OUTPUT_ONLY];

  // Output only. The name of the file uploaded.
  string name = 2 [(google.api.field_behavior) = OUTPUT_ONLY];

  // The content type of the file, see
  // https://www.iana.org/assignments/media-types/media-types.xhtml.
  string mime_type = 3;

  // Output only. The size of the context file in bytes.
  int64 byte_size = 4 [(google.api.field_behavior) = OUTPUT_ONLY];

  // Optional. The original location of the file. It may be a local file path,
  // or any other URI that allows accessing the file in an external system.
  // There are two scenarios in which this url may be empty:
  // 1. If the file was sent as inline data (e.g. pasted from the clipboard).
  // 2. If the original location is not available.
  //
  // Note that there's no guarantee that the URI will be pointing to a valid
  // or actually existing file. For example, a file might have been uploaded
  // to the session, and then deleted from the original source.
  string original_uri = 9 [(google.api.field_behavior) = OPTIONAL];

  // Optional. The type of the original source of the file.
  FileSource original_source_type = 10 [(google.api.field_behavior) = OPTIONAL];

  // Output only. The time the file was uploaded (If this is a file
  // generated by an internal process and then made available to the session,
  // this indicates the moment it happened).
  google.protobuf.Timestamp upload_time = 12
      [(google.api.field_behavior) = OUTPUT_ONLY];

  // Output only. The time the file was added to the session. Note that if a
  // file was added, then modified externally, then added again, the add time
  // will be updated.
  google.protobuf.Timestamp last_add_time = 13
      [(google.api.field_behavior) = OUTPUT_ONLY];

  // Optional. Represents metadata related to the file that can suit particular
  // use cases. The prefix "google." is reserved for the key for use by
  // Google, but other prefixes can be freely used.
  map<string, string> metadata = 18 [(google.api.field_behavior) = OPTIONAL];

  // Output only. The
  // [AssistantService.DownloadSessionFile][google.cloud.discoveryengine.v1alpha.AssistantService.DownloadSessionFile]
  // URL to download the file. This URL will need the same credentials as
  // [AssistantService.ListSessionFileMetadata][google.cloud.discoveryengine.v1alpha.AssistantService.ListSessionFileMetadata]
  // method and will provide the resource.
  string download_uri = 20 [(google.api.field_behavior) = OUTPUT_ONLY];

  // Optional. The origin of the file.
  FileOriginType file_origin_type = 21 [(google.api.field_behavior) = OPTIONAL];

  // Output only. Alternate views of this file object. Each file view is
  // attached to a specific role. Possible example keys:
  //   - "thumbnail"
  //   - "mobile_thumbnail"
  //   - "clip"
  //   - "summary"
  //   - "translation"
  map<string, FileView> views = 22 [(google.api.field_behavior) = OUTPUT_ONLY];
}