@google-cloud/discoveryengine 2.3.0 → 2.5.0

package/build/protos/google/cloud/discoveryengine/v1alpha/search_service.proto

@@ -966,8 +966,14 @@ message SearchRequest {
   // The ranking expression controls the customized ranking on retrieval
   // documents. This overrides
   // [ServingConfig.ranking_expression][google.cloud.discoveryengine.v1alpha.ServingConfig.ranking_expression].
-  // The ranking expression is a single function or multiple functions that are
-  // joined by "+".
+  // The syntax and supported features depend on the
+  // `ranking_expression_backend` value. If `ranking_expression_backend` is not
+  // provided, it defaults to `RANK_BY_EMBEDDING`.
+  //
+  // If
+  // [ranking_expression_backend][google.cloud.discoveryengine.v1alpha.SearchRequest.ranking_expression_backend]
+  // is not provided or set to `RANK_BY_EMBEDDING`, it should be a single
+  // function or multiple functions that are joined by "+".
   //
   //   * ranking_expression = function, { " + ", function };
   //
@@ -982,15 +988,90 @@ message SearchRequest {
   //   between query and document.
   //   * `embedding_field_path`: the document embedding field
   //   used with query embedding vector.
-  //   * `dotProduct`: embedding function between embedding_field_path and query
-  //   embedding vector.
+  //   * `dotProduct`: embedding function between `embedding_field_path` and
+  //   query embedding vector.
   //
   //  Example ranking expression:
   //
   //    If document has an embedding field doc_embedding, the ranking expression
   //    could be `0.5 * relevance_score + 0.3 * dotProduct(doc_embedding)`.
+  //
+  // If
+  // [ranking_expression_backend][google.cloud.discoveryengine.v1alpha.SearchRequest.ranking_expression_backend]
+  // is set to `RANK_BY_FORMULA`, the following expression types (and
+  // combinations of those chained using + or
+  // * operators) are supported:
+  //
+  //   * `double`
+  //   * `signal`
+  //   * `log(signal)`
+  //   * `exp(signal)`
+  //   * `rr(signal, double > 0)`  -- reciprocal rank transformation with second
+  //   argument being a denominator constant.
+  //   * `is_nan(signal)` -- returns 0 if signal is NaN, 1 otherwise.
+  //   * `fill_nan(signal1, signal2 | double)` -- if signal1 is NaN, returns
+  //   signal2 | double, else returns signal1.
+  //
+  //   Here are a few examples of ranking formulas that use the supported
+  //   ranking expression types:
+  //
+  //   - `0.2 * semantic_similarity_score + 0.8 * log(keyword_similarity_score)`
+  //   -- mostly rank by the logarithm of `keyword_similarity_score` with slight
+  //   `semantic_smilarity_score` adjustment.
+  //   - `0.2 * exp(fill_nan(semantic_similarity_score, 0)) + 0.3 *
+  //   is_nan(keyword_similarity_score)` -- rank by the exponent of
+  //   `semantic_similarity_score` filling the value with 0 if it's NaN, also
+  //   add constant 0.3 adjustment to the final score if
+  //   `semantic_similarity_score` is NaN.
+  //   - `0.2 * rr(semantic_similarity_score, 16) + 0.8 *
+  //   rr(keyword_similarity_score, 16)` -- mostly rank by the reciprocal rank
+  //   of `keyword_similarity_score` with slight adjustment of reciprocal rank
+  //   of `semantic_smilarity_score`.
+  //
+  // The following signals are supported:
+  //
+  //   * `semantic_similarity_score`: semantic similarity adjustment that is
+  //   calculated using the embeddings generated by a proprietary Google model.
+  //   This score determines how semantically similar a search query is to a
+  //   document.
+  //   * `keyword_similarity_score`: keyword match adjustment uses the Best
+  //   Match 25 (BM25) ranking function. This score is calculated using a
+  //   probabilistic model to estimate the probability that a document is
+  //   relevant to a given query.
+  //   * `relevance_score`: semantic relevance adjustment that uses a
+  //   proprietary Google model to determine the meaning and intent behind a
+  //   user's query in context with the content in the documents.
+  //   * `pctr_rank`: predicted conversion rate adjustment as a rank use
+  //   predicted Click-through rate (pCTR) to gauge the relevance and
+  //   attractiveness of a search result from a user's perspective. A higher
+  //   pCTR suggests that the result is more likely to satisfy the user's query
+  //   and intent, making it a valuable signal for ranking.
+  //   * `freshness_rank`: freshness adjustment as a rank
+  //   * `document_age`: The time in hours elapsed since the document was last
+  //   updated, a floating-point number (e.g., 0.25 means 15 minutes).
+  //   * `topicality_rank`: topicality adjustment as a rank. Uses proprietary
+  //   Google model to determine the keyword-based overlap between the query and
+  //   the document.
+  //   * `base_rank`: the default rank of the result
   string ranking_expression = 26;
 
+  // The backend to use for the ranking expression evaluation.
+  enum RankingExpressionBackend {
+    reserved 1, 2;
+
+    // Default option for unspecified/unknown values.
+    RANKING_EXPRESSION_BACKEND_UNSPECIFIED = 0;
+    // Ranking by custom embedding model, the default way to evaluate the
+    // ranking expression.
+    RANK_BY_EMBEDDING = 3;
+    // Ranking by custom formula.
+    RANK_BY_FORMULA = 4;
+  }
+
+  // The backend to use for the ranking expression evaluation.
+  RankingExpressionBackend ranking_expression_backend = 53
+      [(google.api.field_behavior) = OPTIONAL];
+
   // Whether to turn on safe search. This is only supported for
   // website search.
   bool safe_search = 20;
@@ -1035,22 +1116,16 @@ message SearchRequest {
   // between /search API calls and /answer API calls.
   //
   // Example #1 (multi-turn /search API calls):
-  //   1. Call /search API with the auto-session mode (see below).
-  //   2. Call /search API with the session ID generated in the first call.
-  //      Here, the previous search query gets considered in query
-  //      standing. I.e., if the first query is "How did Alphabet do in 2022?"
-  //      and the current query is "How about 2023?", the current query will
-  //      be interpreted as "How did Alphabet do in 2023?".
+  //   Call /search API with the session ID generated in the first call.
+  //   Here, the previous search query gets considered in query
+  //   standing. I.e., if the first query is "How did Alphabet do in 2022?"
+  //   and the current query is "How about 2023?", the current query will
+  //   be interpreted as "How did Alphabet do in 2023?".
   //
   // Example #2 (coordination between /search API calls and /answer API calls):
-  //   1. Call /search API with the auto-session mode (see below).
-  //   2. Call /answer API with the session ID generated in the first call.
-  //      Here, the answer generation happens in the context of the search
-  //      results from the first search call.
-  //
-  // Auto-session mode: when `projects/.../sessions/-` is used, a new session
-  // gets automatically created. Otherwise, users can use the create-session API
-  // to create a session manually.
+  //   Call /answer API with the session ID generated in the first call.
+  //   Here, the answer generation happens in the context of the search
+  //   results from the first search call.
   //
   // Multi-turn Search feature is currently at private GA stage. Please use
   // v1alpha or v1beta version instead before we launch this feature to public
@@ -1094,6 +1169,49 @@ message SearchResponse {
 
     // Google provided available scores.
     map<string, DoubleList> model_scores = 4;
+
+    // A set of ranking signals.
+    message RankSignals {
+      reserved 5;
+
+      // Keyword matching adjustment.
+      optional float keyword_similarity_score = 1
+          [(google.api.field_behavior) = OPTIONAL];
+      // Semantic relevance adjustment.
+      optional float relevance_score = 2
+          [(google.api.field_behavior) = OPTIONAL];
+      // Semantic similarity adjustment.
+      optional float semantic_similarity_score = 3
+          [(google.api.field_behavior) = OPTIONAL];
+      // Predicted conversion rate adjustment as a rank.
+      optional float pctr_rank = 4 [(google.api.field_behavior) = OPTIONAL];
+      // Topicality adjustment as a rank.
+      optional float topicality_rank = 6
+          [(google.api.field_behavior) = OPTIONAL];
+      // Age of the document in hours.
+      optional float document_age = 7 [(google.api.field_behavior) = OPTIONAL];
+      // Combined custom boosts for a doc.
+      optional float boosting_factor = 8
+          [(google.api.field_behavior) = OPTIONAL];
+
+      // The default rank of the result.
+      float default_rank = 32 [(google.api.field_behavior) = OPTIONAL];
+
+      // Custom clearbox signal represented by name and value pair.
+      message CustomSignal {
+        // Name of the signal.
+        string name = 1 [(google.api.field_behavior) = OPTIONAL];
+        // Float value representing the ranking signal (e.g. 1.25 for BM25).
+        float value = 2 [(google.api.field_behavior) = OPTIONAL];
+      }
+
+      // A list of custom clearbox signals.
+      repeated CustomSignal custom_signals = 33
+          [(google.api.field_behavior) = OPTIONAL];
+    }
+
+    // A set of ranking signals associated with the result.
+    RankSignals rank_signals = 7 [(google.api.field_behavior) = OPTIONAL];
   }
 
   // A facet result.

package/build/protos/google/cloud/discoveryengine/v1alpha/session.proto

@@ -18,6 +18,9 @@ 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";
@@ -29,6 +32,27 @@ 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) = {
@@ -36,21 +60,42 @@ message 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 {
-    // The user query.
-    Query query = 1;
+    // 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];
 
-    // The resource name of the answer to the user query.
+    // 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.resource_reference) = {
-      type: "discoveryengine.googleapis.com/Answer"
-    }];
+    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.
@@ -66,6 +111,12 @@ message Session {
   // `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;
 
@@ -82,6 +133,10 @@ message Session {
   // 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.
@@ -92,6 +147,181 @@ message Query {
     string text = 2;
   }
 
-  // Unique Id for the query.
-  string query_id = 1;
+  // 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];
 }