google-cloud-discovery_engine-v1beta 0.20.1 → 0.22.0

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

@@ -223,8 +223,14 @@ module Google
         #     The ranking expression controls the customized ranking on retrieval
         #     documents. This overrides
         #     {::Google::Cloud::DiscoveryEngine::V1beta::ServingConfig#ranking_expression 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
+        #     {::Google::Cloud::DiscoveryEngine::V1beta::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 };
         #
@@ -239,13 +245,74 @@ module Google
         #       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
+        #     {::Google::Cloud::DiscoveryEngine::V1beta::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::V1beta::SearchRequest::RankingExpressionBackend]
+        #     The backend to use for the ranking expression evaluation.
         # @!attribute [rw] safe_search
         #   @return [::Boolean]
         #     Whether to turn on safe search. This is only supported for
@@ -286,22 +353,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
@@ -1159,6 +1220,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
@@ -1257,6 +1331,9 @@ module Google
           # @!attribute [rw] model_scores
           #   @return [::Google::Protobuf::Map{::String => ::Google::Cloud::DiscoveryEngine::V1beta::DoubleList}]
           #     Google provided available scores.
+          # @!attribute [rw] rank_signals
+          #   @return [::Google::Cloud::DiscoveryEngine::V1beta::SearchResponse::SearchResult::RankSignals]
+          #     A set of ranking signals associated with the result.
           class SearchResult
             include ::Google::Protobuf::MessageExts
             extend ::Google::Protobuf::MessageExts::ClassMethods
@@ -1269,6 +1346,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::V1beta::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/v1beta/session.rb

@@ -26,6 +26,12 @@ module Google
         #   @return [::String]
         #     Immutable. Fully qualified name
         #     `projects/{project}/locations/global/collections/{collection}/engines/{engine}/sessions/*`
+        # @!attribute [rw] display_name
+        #   @return [::String]
+        #     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.
         # @!attribute [rw] state
         #   @return [::Google::Cloud::DiscoveryEngine::V1beta::Session::State]
         #     The state of the session.
@@ -41,6 +47,10 @@ module Google
         # @!attribute [r] end_time
         #   @return [::Google::Protobuf::Timestamp]
         #     Output only. The time the session finished.
+        # @!attribute [rw] is_pinned
+        #   @return [::Boolean]
+        #     Optional. Whether the session is pinned, pinned session will be displayed
+        #     on the top of the session list.
         class Session
           include ::Google::Protobuf::MessageExts
           extend ::Google::Protobuf::MessageExts::ClassMethods
@@ -49,16 +59,40 @@ module Google
           # answer from service.
           # @!attribute [rw] query
           #   @return [::Google::Cloud::DiscoveryEngine::V1beta::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.
+          # @!attribute [r] detailed_answer
+          #   @return [::Google::Cloud::DiscoveryEngine::V1beta::Answer]
+          #     Output only. In
+          #     {::Google::Cloud::DiscoveryEngine::V1beta::ConversationalSearchService::Client#get_session ConversationalSearchService.GetSession}
+          #     API, if
+          #     {::Google::Cloud::DiscoveryEngine::V1beta::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.
@@ -75,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

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: google-cloud-discovery_engine-v1beta
 version: !ruby/object:Gem::Version
-  version: 0.20.1
+  version: 0.22.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
@@ -204,6 +204,13 @@ files:
 - lib/google/cloud/discovery_engine/v1beta/serving_config_service/rest.rb
 - lib/google/cloud/discovery_engine/v1beta/serving_config_service/rest/client.rb
 - lib/google/cloud/discovery_engine/v1beta/serving_config_service/rest/service_stub.rb
+- lib/google/cloud/discovery_engine/v1beta/session_service.rb
+- lib/google/cloud/discovery_engine/v1beta/session_service/client.rb
+- lib/google/cloud/discovery_engine/v1beta/session_service/credentials.rb
+- lib/google/cloud/discovery_engine/v1beta/session_service/paths.rb
+- lib/google/cloud/discovery_engine/v1beta/session_service/rest.rb
+- lib/google/cloud/discovery_engine/v1beta/session_service/rest/client.rb
+- lib/google/cloud/discovery_engine/v1beta/session_service/rest/service_stub.rb
 - lib/google/cloud/discovery_engine/v1beta/site_search_engine_service.rb
 - lib/google/cloud/discovery_engine/v1beta/site_search_engine_service/client.rb
 - lib/google/cloud/discovery_engine/v1beta/site_search_engine_service/credentials.rb
@@ -278,6 +285,8 @@ files:
 - lib/google/cloud/discoveryengine/v1beta/serving_config_service_pb.rb
 - lib/google/cloud/discoveryengine/v1beta/serving_config_service_services_pb.rb
 - lib/google/cloud/discoveryengine/v1beta/session_pb.rb
+- lib/google/cloud/discoveryengine/v1beta/session_service_pb.rb
+- lib/google/cloud/discoveryengine/v1beta/session_service_services_pb.rb
 - lib/google/cloud/discoveryengine/v1beta/site_search_engine_pb.rb
 - lib/google/cloud/discoveryengine/v1beta/site_search_engine_service_pb.rb
 - lib/google/cloud/discoveryengine/v1beta/site_search_engine_service_services_pb.rb