google-cloud-discovery_engine-v1 2.3.1 → 2.5.0

data/proto_docs/google/cloud/discoveryengine/v1/search_service.rb

@@ -243,22 +243,16 @@ module Google
         #     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
@@ -280,6 +274,101 @@ module Google
         # @!attribute [rw] relevance_score_spec
         #   @return [::Google::Cloud::DiscoveryEngine::V1::SearchRequest::RelevanceScoreSpec]
         #     Optional. The specification for returning the relevance score.
+        # @!attribute [rw] ranking_expression
+        #   @return [::String]
+        #     The ranking expression controls the customized ranking on retrieval
+        #     documents. This overrides
+        #     {::Google::Cloud::DiscoveryEngine::V1::ServingConfig#ranking_expression ServingConfig.ranking_expression}.
+        #     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
+        #     {::Google::Cloud::DiscoveryEngine::V1::SearchRequest#ranking_expression_backend 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 };
+        #
+        #     Supported functions:
+        #
+        #       * double * relevance_score
+        #       * double * dotProduct(embedding_field_path)
+        #
+        #     Function variables:
+        #
+        #       * `relevance_score`: pre-defined keywords, used for measure relevance
+        #       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.
+        #
+        #      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
+        #     {::Google::Cloud::DiscoveryEngine::V1::SearchRequest#ranking_expression_backend 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
+        # @!attribute [rw] ranking_expression_backend
+        #   @return [::Google::Cloud::DiscoveryEngine::V1::SearchRequest::RankingExpressionBackend]
+        #     The backend to use for the ranking expression evaluation.
         class SearchRequest
           include ::Google::Protobuf::MessageExts
           extend ::Google::Protobuf::MessageExts::ClassMethods
@@ -1079,6 +1168,19 @@ module Google
             # High relevance threshold.
             HIGH = 4
           end
+
+          # The backend to use for the ranking expression evaluation.
+          module RankingExpressionBackend
+            # 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
+          end
         end
 
         # Response message for
@@ -1164,6 +1266,9 @@ module Google
           # @!attribute [r] model_scores
           #   @return [::Google::Protobuf::Map{::String => ::Google::Cloud::DiscoveryEngine::V1::DoubleList}]
           #     Output only. Google provided available scores.
+          # @!attribute [rw] rank_signals
+          #   @return [::Google::Cloud::DiscoveryEngine::V1::SearchResponse::SearchResult::RankSignals]
+          #     A set of ranking signals associated with the result.
           class SearchResult
             include ::Google::Protobuf::MessageExts
             extend ::Google::Protobuf::MessageExts::ClassMethods
@@ -1176,6 +1281,51 @@ module Google
               include ::Google::Protobuf::MessageExts
               extend ::Google::Protobuf::MessageExts::ClassMethods
             end
+
+            # A set of ranking signals.
+            # @!attribute [rw] keyword_similarity_score
+            #   @return [::Float]
+            #     Keyword matching adjustment.
+            # @!attribute [rw] relevance_score
+            #   @return [::Float]
+            #     Semantic relevance adjustment.
+            # @!attribute [rw] semantic_similarity_score
+            #   @return [::Float]
+            #     Semantic similarity adjustment.
+            # @!attribute [rw] pctr_rank
+            #   @return [::Float]
+            #     Predicted conversion rate adjustment as a rank.
+            # @!attribute [rw] topicality_rank
+            #   @return [::Float]
+            #     Topicality adjustment as a rank.
+            # @!attribute [rw] document_age
+            #   @return [::Float]
+            #     Age of the document in hours.
+            # @!attribute [rw] boosting_factor
+            #   @return [::Float]
+            #     Combined custom boosts for a doc.
+            # @!attribute [rw] default_rank
+            #   @return [::Float]
+            #     The default rank of the result.
+            # @!attribute [rw] custom_signals
+            #   @return [::Array<::Google::Cloud::DiscoveryEngine::V1::SearchResponse::SearchResult::RankSignals::CustomSignal>]
+            #     A list of custom clearbox signals.
+            class RankSignals
+              include ::Google::Protobuf::MessageExts
+              extend ::Google::Protobuf::MessageExts::ClassMethods
+
+              # Custom clearbox signal represented by name and value pair.
+              # @!attribute [rw] name
+              #   @return [::String]
+              #     Name of the signal.
+              # @!attribute [rw] value
+              #   @return [::Float]
+              #     Float value representing the ranking signal (e.g. 1.25 for BM25).
+              class CustomSignal
+                include ::Google::Protobuf::MessageExts
+                extend ::Google::Protobuf::MessageExts::ClassMethods
+              end
+            end
           end
 
           # A facet result.

data/proto_docs/google/cloud/discoveryengine/v1/session.rb

@@ -59,10 +59,11 @@ module Google
           # answer from service.
           # @!attribute [rw] query
           #   @return [::Google::Cloud::DiscoveryEngine::V1::Query]
-          #     The user query.
+          #     Optional. The user query. May not be set if this turn is merely
+          #     regenerating an answer to a different turn
           # @!attribute [rw] answer
           #   @return [::String]
-          #     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.
@@ -74,9 +75,24 @@ module Google
           #     {::Google::Cloud::DiscoveryEngine::V1::GetSessionRequest#include_answer_details GetSessionRequest.include_answer_details}
           #     is set to true, this field will be populated when getting answer query
           #     session.
+          # @!attribute [rw] query_config
+          #   @return [::Google::Protobuf::Map{::String => ::String}]
+          #     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.
           class Turn
             include ::Google::Protobuf::MessageExts
             extend ::Google::Protobuf::MessageExts::ClassMethods
+
+            # @!attribute [rw] key
+            #   @return [::String]
+            # @!attribute [rw] value
+            #   @return [::String]
+            class QueryConfigEntry
+              include ::Google::Protobuf::MessageExts
+              extend ::Google::Protobuf::MessageExts::ClassMethods
+            end
           end
 
           # Enumeration of the state of the session.
@@ -93,9 +109,9 @@ module Google
         # @!attribute [rw] text
         #   @return [::String]
         #     Plain text.
-        # @!attribute [rw] query_id
+        # @!attribute [r] query_id
         #   @return [::String]
-        #     Unique Id for the query.
+        #     Output only. Unique Id for the query.
         class Query
           include ::Google::Protobuf::MessageExts
           extend ::Google::Protobuf::MessageExts::ClassMethods

data/proto_docs/google/cloud/discoveryengine/v1/user_event_service.rb

@@ -30,7 +30,7 @@ module Google
         #     is:
         #     `projects/{project}/locations/{location}/collections/{collection}/dataStores/{data_store}`.
         #     If the write user event action is applied in
-        #     `::Google::Cloud::Location::Location` level, for example, the event
+        #     [Location][google.cloud.location.Location] level, for example, the event
         #     with {::Google::Cloud::DiscoveryEngine::V1::Document Document} across multiple
         #     {::Google::Cloud::DiscoveryEngine::V1::DataStore DataStore}, the format is:
         #     `projects/{project}/locations/{location}`.
@@ -55,7 +55,7 @@ module Google
         #     is:
         #     `projects/{project}/locations/{location}/collections/{collection}/dataStores/{data_store}`.
         #     If the collect user event action is applied in
-        #     `::Google::Cloud::Location::Location` level, for example, the event
+        #     [Location][google.cloud.location.Location] level, for example, the event
         #     with {::Google::Cloud::DiscoveryEngine::V1::Document Document} across multiple
         #     {::Google::Cloud::DiscoveryEngine::V1::DataStore DataStore}, the format is:
         #     `projects/{project}/locations/{location}`.

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: google-cloud-discovery_engine-v1
 version: !ruby/object:Gem::Version
-  version: 2.3.1
+  version: 2.5.0
 platform: ruby
 authors:
 - Google LLC
@@ -15,14 +15,14 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '1.0'
+        version: '1.2'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '1.0'
+        version: '1.2'
 - !ruby/object:Gem::Dependency
   name: google-cloud-errors
   requirement: !ruby/object:Gem::Requirement
@@ -65,6 +65,13 @@ files:
 - README.md
 - lib/google-cloud-discovery_engine-v1.rb
 - lib/google/cloud/discovery_engine/v1.rb
+- lib/google/cloud/discovery_engine/v1/assistant_service.rb
+- lib/google/cloud/discovery_engine/v1/assistant_service/client.rb
+- lib/google/cloud/discovery_engine/v1/assistant_service/credentials.rb
+- lib/google/cloud/discovery_engine/v1/assistant_service/paths.rb
+- lib/google/cloud/discovery_engine/v1/assistant_service/rest.rb
+- lib/google/cloud/discovery_engine/v1/assistant_service/rest/client.rb
+- lib/google/cloud/discovery_engine/v1/assistant_service/rest/service_stub.rb
 - lib/google/cloud/discovery_engine/v1/cmek_config_service.rb
 - lib/google/cloud/discovery_engine/v1/cmek_config_service/client.rb
 - lib/google/cloud/discovery_engine/v1/cmek_config_service/credentials.rb
@@ -196,6 +203,13 @@ files:
 - lib/google/cloud/discovery_engine/v1/serving_config_service/rest.rb
 - lib/google/cloud/discovery_engine/v1/serving_config_service/rest/client.rb
 - lib/google/cloud/discovery_engine/v1/serving_config_service/rest/service_stub.rb
+- lib/google/cloud/discovery_engine/v1/session_service.rb
+- lib/google/cloud/discovery_engine/v1/session_service/client.rb
+- lib/google/cloud/discovery_engine/v1/session_service/credentials.rb
+- lib/google/cloud/discovery_engine/v1/session_service/paths.rb
+- lib/google/cloud/discovery_engine/v1/session_service/rest.rb
+- lib/google/cloud/discovery_engine/v1/session_service/rest/client.rb
+- lib/google/cloud/discovery_engine/v1/session_service/rest/service_stub.rb
 - lib/google/cloud/discovery_engine/v1/site_search_engine_service.rb
 - lib/google/cloud/discovery_engine/v1/site_search_engine_service/client.rb
 - lib/google/cloud/discovery_engine/v1/site_search_engine_service/credentials.rb
@@ -225,6 +239,10 @@ files:
 - lib/google/cloud/discovery_engine/v1/user_license_service/rest/service_stub.rb
 - lib/google/cloud/discovery_engine/v1/version.rb
 - lib/google/cloud/discoveryengine/v1/answer_pb.rb
+- lib/google/cloud/discoveryengine/v1/assist_answer_pb.rb
+- lib/google/cloud/discoveryengine/v1/assistant_pb.rb
+- lib/google/cloud/discoveryengine/v1/assistant_service_pb.rb
+- lib/google/cloud/discoveryengine/v1/assistant_service_services_pb.rb
 - lib/google/cloud/discoveryengine/v1/chunk_pb.rb
 - lib/google/cloud/discoveryengine/v1/cmek_config_service_pb.rb
 - lib/google/cloud/discoveryengine/v1/cmek_config_service_services_pb.rb
@@ -276,6 +294,8 @@ files:
 - lib/google/cloud/discoveryengine/v1/serving_config_service_pb.rb
 - lib/google/cloud/discoveryengine/v1/serving_config_service_services_pb.rb
 - lib/google/cloud/discoveryengine/v1/session_pb.rb
+- lib/google/cloud/discoveryengine/v1/session_service_pb.rb
+- lib/google/cloud/discoveryengine/v1/session_service_services_pb.rb
 - lib/google/cloud/discoveryengine/v1/site_search_engine_pb.rb
 - lib/google/cloud/discoveryengine/v1/site_search_engine_service_pb.rb
 - lib/google/cloud/discoveryengine/v1/site_search_engine_service_services_pb.rb
@@ -292,6 +312,9 @@ files:
 - proto_docs/google/api/launch_stage.rb
 - proto_docs/google/api/resource.rb
 - proto_docs/google/cloud/discoveryengine/v1/answer.rb
+- proto_docs/google/cloud/discoveryengine/v1/assist_answer.rb
+- proto_docs/google/cloud/discoveryengine/v1/assistant.rb
+- proto_docs/google/cloud/discoveryengine/v1/assistant_service.rb
 - proto_docs/google/cloud/discoveryengine/v1/chunk.rb
 - proto_docs/google/cloud/discoveryengine/v1/cmek_config_service.rb
 - proto_docs/google/cloud/discoveryengine/v1/common.rb