openlayer 0.8.0 → 0.8.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d27be2afe4632dccf14077f8fecaf96b1e67d6cf81fb4bca4917d9a31a6bd66b
-  data.tar.gz: ba4f55cf2470fcad21b26531a3adfc0d59cdfae106cdd7ca65ad0d072093d618
+  metadata.gz: e2012084e7121e1610abd934759b02dea258adbf82bb08fed4975e793793b0bf
+  data.tar.gz: 2326a997d8b2a24a01e80007e002f5141a6b0ce5b06e769350172689f68197ef
 SHA512:
-  metadata.gz: 0313bd3321521fb207a7aa14844cb4e5f91131457baaff2b8451b5b0ec750f646e747694301c9b284d4ca86e49dc61bac63e63db0bcbe62a58abbf7e4d97e2d9
-  data.tar.gz: 1da5a6642fb3493d2484c67314f6ded8d619edab534b6d455a382caba85fdd6ec61839dabfabaff2c8be2c5ba38643680d4196fbc24316f685be460ba0430598
+  metadata.gz: 7d39d0ebbd0068ff855e3071021c6d8ab30d01c0c76c12ae61cdd3419eef0400b33f68249aeb682768e96b7f9c5a0bd72dfb6607cff34830d2c616c04ac83be5
+  data.tar.gz: 2a766e20dcbf8f279658818a25a2c5fcd6739ca208ef9a91313e90943434e4256326f00bb699adfa8e21269c36f363a6709bfac2bff79d7d5f7a8e10a5555c1e

data/CHANGELOG.md

@@ -1,5 +1,14 @@
 # Changelog
 
+## 0.8.1 (2026-01-06)
+
+Full Changelog: [v0.8.0...v0.8.1](https://github.com/openlayer-ai/openlayer-ruby/compare/v0.8.0...v0.8.1)
+
+### Chores
+
+* **closes OPEN-8602:** parse document chunks from ConversationalSearchService response ([afb7d2e](https://github.com/openlayer-ai/openlayer-ruby/commit/afb7d2e7ea00f809c27e382bc410bc4ea1571c7f))
+* **closes OPEN-8603:** represent nested steps for ConversationalSearchService traces ([e5026c7](https://github.com/openlayer-ai/openlayer-ruby/commit/e5026c72738e77610da528eff1fa826a67ffa5fe))
+
 ## 0.8.0 (2026-01-05)
 
 Full Changelog: [v0.7.1...v0.8.0](https://github.com/openlayer-ai/openlayer-ruby/compare/v0.7.1...v0.8.0)

data/README.md

@@ -17,7 +17,7 @@ To use this gem, install via Bundler by adding the following to your application
 <!-- x-release-please-start-version -->
 
 ```ruby
-gem "openlayer", "~> 0.8.0"
+gem "openlayer", "~> 0.8.1"
 ```
 
 <!-- x-release-please-end -->

data/lib/openlayer/integrations/google_conversational_search_tracer.rb

@@ -113,6 +113,51 @@ module Openlayer
         prompt_tokens = (query_text.length / 4.0).ceil
         completion_tokens = (answer_data[:answer_text].length / 4.0).ceil
 
+        # Extract grounding information from metadata for step root level
+        citations = metadata.delete(:citations)
+        references = metadata.delete(:references)
+        related_questions = metadata.delete(:relatedQuestions)
+
+        # Extract context from references (array of content strings)
+        context = if references && references.is_a?(Array)
+          references.map { |ref| ref[:content] }.compact
+        else
+          nil
+        end
+
+        # Extract nested steps (Google's execution steps)
+        answer = response.respond_to?(:answer) ? response.answer : nil
+        nested_steps = answer ? extract_steps(answer, query_text) : nil
+
+        # Build step object
+        step = {
+          name: "Conversational Search answer_query",
+          type: "chat_completion",
+          provider: "Google",
+          startTime: start_time.to_i,
+          endTime: end_time.to_i,
+          latency: latency_ms,
+          metadata: metadata,
+          inputs: {
+            prompt: [
+              {role: "user", content: query_text}
+            ]
+          },
+          output: answer_data[:answer_text],
+          promptTokens: prompt_tokens,
+          completionTokens: completion_tokens,
+          tokens: prompt_tokens + completion_tokens,
+          model: "google-discovery-engine"
+        }
+
+        # Add grounding information at step root level
+        step[:citations] = citations if citations
+        step[:references] = references if references
+        step[:relatedQuestions] = related_questions if related_questions
+
+        # Add nested steps (Google's execution steps as RetrieverSteps)
+        step[:steps] = nested_steps if nested_steps && !nested_steps.empty?
+
         # Build trace data in Openlayer format
         trace_data = {
           config: {
@@ -128,31 +173,17 @@ module Openlayer
               latency_ms: latency_ms,
               timestamp: start_time.to_i,
               metadata: metadata,
-              steps: [
-                {
-                  name: "Conversational Search answer_query",
-                  type: "chat_completion",
-                  provider: "Google",
-                  startTime: start_time.to_i,
-                  endTime: end_time.to_i,
-                  latency: latency_ms,
-                  metadata: metadata,
-                  inputs: {
-                    prompt: [
-                      {role: "user", content: query_text}
-                    ]
-                  },
-                  output: answer_data[:answer_text],
-                  promptTokens: prompt_tokens,
-                  completionTokens: completion_tokens,
-                  tokens: prompt_tokens + completion_tokens,
-                  model: "google-discovery-engine"
-                }
-              ]
+              steps: [step]
             }
           ]
         }
 
+        # Add context column if available
+        if context && !context.empty?
+          trace_data[:rows][0][:context] = context
+          trace_data[:config][:contextColumnName] = "context"
+        end
+
         # Determine which session to use (kwarg takes precedence over auto-extracted)
         final_session = session_id || metadata[:session]
         if final_session
@@ -160,9 +191,11 @@ module Openlayer
           trace_data[:config][:sessionIdColumnName] = "session_id"
         end
 
-        # Add user_id if provided
-        if user_id
-          trace_data[:rows][0][:user_id] = user_id
+        # Determine which user_id to use (kwarg takes precedence over auto-extracted)
+        user_pseudo_id = extract_user_pseudo_id(response)
+        final_user_id = user_id || user_pseudo_id
+        if final_user_id
+          trace_data[:rows][0][:user_id] = final_user_id
           trace_data[:config][:userIdColumnName] = "user_id"
         end
 
@@ -223,20 +256,208 @@ module Openlayer
         answer = response.answer
         return {answer_text: nil} if answer.nil?
 
+        # Extract answer_skipped_reasons if present
+        answer_skipped_reasons = safe_extract(answer, :answer_skipped_reasons)
+        answer_skipped_reasons = if answer_skipped_reasons && answer_skipped_reasons.respond_to?(:to_a)
+          answer_skipped_reasons.to_a.map(&:to_s).compact
+        end
+
         {
           answer_text: safe_extract(answer, :answer_text),
+          answer_name: safe_extract(answer, :name),
           state: safe_extract(answer, :state)&.to_s,
           grounding_score: safe_extract(answer, :grounding_score),
           create_time: extract_timestamp(answer, :create_time),
           complete_time: extract_timestamp(answer, :complete_time),
           citations_count: safe_count(answer, :citations),
-          references_count: safe_count(answer, :references)
+          references_count: safe_count(answer, :references),
+          answer_skipped_reasons: answer_skipped_reasons
         }
       rescue StandardError => e
         warn_if_debug("[Openlayer] Failed to extract answer data: #{e.message}")
         {answer_text: nil}
       end
 
+      # Extract citations from answer
+      #
+      # @param answer [Object] Answer object from response
+      # @return [Array<Hash>, nil] Array of citation hashes or nil
+      def self.extract_citations(answer)
+        return nil unless answer && answer.respond_to?(:citations)
+
+        citations = safe_extract(answer, :citations)
+        return nil if citations.nil? || !citations.respond_to?(:map)
+
+        citations.map do |citation|
+          {
+            start_index: safe_extract(citation, :start_index)&.to_i,
+            end_index: safe_extract(citation, :end_index)&.to_i,
+            sources: extract_citation_sources(citation)
+          }.compact
+        end
+      rescue StandardError => e
+        warn_if_debug("[Openlayer] Failed to extract citations: #{e.message}")
+        nil
+      end
+
+      # Extract sources from a citation
+      #
+      # @param citation [Object] Citation object
+      # @return [Array<Hash>, nil] Array of source hashes or nil
+      def self.extract_citation_sources(citation)
+        sources = safe_extract(citation, :sources)
+        return nil if sources.nil? || !sources.respond_to?(:map)
+
+        sources.map do |source|
+          {reference_id: safe_extract(source, :reference_id)}.compact
+        end
+      rescue StandardError
+        nil
+      end
+
+      # Extract references from answer
+      #
+      # @param answer [Object] Answer object from response
+      # @return [Array<Hash>, nil] Array of reference hashes or nil
+      def self.extract_references(answer)
+        return nil unless answer && answer.respond_to?(:references)
+
+        references = safe_extract(answer, :references)
+        return nil if references.nil? || !references.respond_to?(:each_with_index)
+
+        references.each_with_index.map do |reference, index|
+          chunk_info = safe_extract(reference, :chunk_info)
+          next nil if chunk_info.nil?
+
+          doc_metadata = safe_extract(chunk_info, :document_metadata)
+
+          {
+            reference_id: index.to_s,
+            content: safe_extract(chunk_info, :content),
+            relevance_score: safe_extract(chunk_info, :relevance_score)&.to_f,
+            document_id: doc_metadata ? safe_extract(doc_metadata, :document) : nil,
+            uri: doc_metadata ? safe_extract(doc_metadata, :uri) : nil,
+            title: doc_metadata ? safe_extract(doc_metadata, :title) : nil
+          }.compact
+        end.compact
+      rescue StandardError => e
+        warn_if_debug("[Openlayer] Failed to extract references: #{e.message}")
+        nil
+      end
+
+      # Extract related questions from answer
+      #
+      # @param answer [Object] Answer object from response
+      # @return [Array<String>, nil] Array of related questions or nil
+      def self.extract_related_questions(answer)
+        return nil unless answer && answer.respond_to?(:related_questions)
+
+        questions = safe_extract(answer, :related_questions)
+        return nil if questions.nil? || !questions.respond_to?(:to_a)
+
+        questions.to_a.map(&:to_s).compact
+      rescue StandardError => e
+        warn_if_debug("[Openlayer] Failed to extract related questions: #{e.message}")
+        nil
+      end
+
+      # Extract execution steps from answer
+      #
+      # @param answer [Object] Answer object from response
+      # @param original_query [String, nil] Original user query for comparison
+      # @return [Array<Hash>, nil] Array of step hashes or nil
+      def self.extract_steps(answer, original_query = nil)
+        return nil unless answer && answer.respond_to?(:steps)
+
+        steps = safe_extract(answer, :steps)
+        return nil if steps.nil? || !steps.respond_to?(:map)
+
+        steps.map do |step|
+          extract_step_data(step, original_query)
+        end.compact
+      rescue StandardError => e
+        warn_if_debug("[Openlayer] Failed to extract steps: #{e.message}")
+        nil
+      end
+
+      # Extract data from a single step
+      #
+      # @param step [Object] Step object
+      # @param original_query [String, nil] Original user query for comparison
+      # @return [Hash, nil] Step hash or nil
+      def self.extract_step_data(step, original_query = nil)
+        return nil if step.nil?
+
+        # Extract basic step info
+        description = safe_extract(step, :description)
+        state = safe_extract(step, :state)&.to_s
+        actions = safe_extract(step, :actions)
+
+        # Extract search action and results from first action
+        search_query = nil
+        search_results = nil
+
+        if actions && actions.respond_to?(:first)
+          first_action = actions.first
+          if first_action
+            search_action = safe_extract(first_action, :search_action)
+            observation = safe_extract(first_action, :observation)
+
+            search_query = safe_extract(search_action, :query) if search_action
+            search_results = safe_extract(observation, :search_results) if observation
+          end
+        end
+
+        # Build inputs showing both original and rephrased queries
+        inputs = if search_query
+          result = {rephrased_query: search_query}
+          result[:original_query] = original_query if original_query && original_query != search_query
+          result
+        end
+
+        # Map to OpenLayer RetrieverStep format
+        {
+          name: (description ? description.gsub(/\.\z/, "") : "Search and retrieve documents"),
+          type: "retriever",
+          inputs: inputs,
+          output: search_results ? {num_results: search_results.length} : nil,
+          documents: extract_search_results(search_results),
+          metadata: {
+            state: state,
+            action_type: "searchAction"
+          }.compact
+        }.compact
+      rescue StandardError => e
+        warn_if_debug("[Openlayer] Failed to extract step data: #{e.message}")
+        nil
+      end
+
+      # Extract search results as documents
+      #
+      # @param search_results [Array] Array of search result objects
+      # @return [Array<Hash>, nil] Array of document hashes or nil
+      def self.extract_search_results(search_results)
+        return nil if search_results.nil? || !search_results.respond_to?(:map)
+
+        search_results.map do |result|
+          snippet_info = safe_extract(result, :snippet_info)
+          snippet = if snippet_info && snippet_info.respond_to?(:first)
+            first_snippet = snippet_info.first
+            safe_extract(first_snippet, :snippet) if first_snippet
+          end
+
+          {
+            id: safe_extract(result, :document),
+            uri: safe_extract(result, :uri),
+            title: safe_extract(result, :title),
+            snippet: snippet
+          }.compact
+        end.compact
+      rescue StandardError => e
+        warn_if_debug("[Openlayer] Failed to extract search results: #{e.message}")
+        nil
+      end
+
       # Extract metadata from request and response
       #
       # @param args [Array] Positional arguments
@@ -246,6 +467,7 @@ module Openlayer
       # @return [Hash] Metadata hash
       def self.extract_metadata(args, kwargs, response, latency_ms)
         answer_data = extract_answer_data(response)
+        answer = response.respond_to?(:answer) ? response.answer : nil
 
         metadata = {
           provider: "google",
@@ -254,15 +476,36 @@ module Openlayer
         }
 
         # Add answer metadata
+        metadata[:answer_name] = answer_data[:answer_name] if answer_data[:answer_name]
         metadata[:grounding_score] = answer_data[:grounding_score] if answer_data[:grounding_score]
         metadata[:state] = answer_data[:state] if answer_data[:state]
         metadata[:citations_count] = answer_data[:citations_count] if answer_data[:citations_count]
         metadata[:references_count] = answer_data[:references_count] if answer_data[:references_count]
+        metadata[:answer_skipped_reasons] = answer_data[:answer_skipped_reasons] if answer_data[:answer_skipped_reasons] && !answer_data[:answer_skipped_reasons].empty?
+
+        # Add grounding information (citations, references, related questions)
+        if answer
+          citations = extract_citations(answer)
+          references = extract_references(answer)
+          related_questions = extract_related_questions(answer)
+
+          metadata[:citations] = citations if citations && !citations.empty?
+          metadata[:references] = references if references && !references.empty?
+          metadata[:relatedQuestions] = related_questions if related_questions && !related_questions.empty?
+
+          # Add query understanding info
+          query_understanding_info = extract_query_understanding_info(answer)
+          metadata[:query_understanding_info] = query_understanding_info if query_understanding_info
+        end
 
         # Add request metadata
         metadata[:serving_config] = extract_serving_config(args, kwargs)
         metadata[:session] = extract_session(args, kwargs)
 
+        # Add answer query token
+        answer_query_token = safe_extract(response, :answer_query_token)
+        metadata[:answer_query_token] = answer_query_token if answer_query_token
+
         # Add timing metadata
         if answer_data[:create_time] && answer_data[:complete_time]
           generation_time_ms = ((answer_data[:complete_time] - answer_data[:create_time]) * 1000).round(2)
@@ -309,6 +552,48 @@ module Openlayer
         nil
       end
 
+      # Extract user pseudo ID from response session
+      #
+      # @param response [Object] Response object
+      # @return [String, nil] User pseudo ID or nil
+      def self.extract_user_pseudo_id(response)
+        return nil unless response && response.respond_to?(:session)
+
+        session = safe_extract(response, :session)
+        return nil unless session
+
+        safe_extract(session, :user_pseudo_id)
+      rescue StandardError
+        nil
+      end
+
+      # Extract query understanding info from answer
+      #
+      # @param answer [Object] Answer object
+      # @return [Hash, nil] Query understanding info or nil
+      def self.extract_query_understanding_info(answer)
+        return nil unless answer && answer.respond_to?(:query_understanding_info)
+
+        query_understanding_info = safe_extract(answer, :query_understanding_info)
+        return nil unless query_understanding_info
+
+        result = {}
+
+        # Extract query classification info
+        classification_info = safe_extract(query_understanding_info, :query_classification_info)
+        if classification_info && classification_info.respond_to?(:map)
+          result[:query_classification_info] = classification_info.map do |info|
+            type = safe_extract(info, :type)
+            type ? {type: type.to_s} : nil
+          end.compact
+        end
+
+        result.empty? ? nil : result
+      rescue StandardError => e
+        warn_if_debug("[Openlayer] Failed to extract query understanding info: #{e.message}")
+        nil
+      end
+
       # Safely extract a field from an object
       #
       # @param obj [Object] Object to extract from
@@ -362,9 +647,18 @@ module Openlayer
       # from the singleton method context
       private_class_method :extract_query,
                            :extract_answer_data,
+                           :extract_citations,
+                           :extract_citation_sources,
+                           :extract_references,
+                           :extract_related_questions,
+                           :extract_steps,
+                           :extract_step_data,
+                           :extract_search_results,
                            :extract_metadata,
                            :extract_serving_config,
                            :extract_session,
+                           :extract_user_pseudo_id,
+                           :extract_query_understanding_info,
                            :safe_extract,
                            :safe_count,
                            :extract_timestamp

data/lib/openlayer/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Openlayer
-  VERSION = "0.8.0"
+  VERSION = "0.8.1"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: openlayer
 version: !ruby/object:Gem::Version
-  version: 0.8.0
+  version: 0.8.1
 platform: ruby
 authors:
 - Openlayer
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-01-05 00:00:00.000000000 Z
+date: 2026-01-06 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: connection_pool