openlayer 0.13.1 → 0.14.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f0ebd82d46fc27b599d3a133cdfd24180321ecdb473eb723f518988030fbeadd
-  data.tar.gz: 7eb9e3c362170b6d425fb4a3566920d8a6bc574c33865c834f39143d03dba3b0
+  metadata.gz: 697bde0fdcf61182dd6235f06ab2ab9439b245251284f66100a53c44a6bfc146
+  data.tar.gz: ea5d247e85a34a14143e82e2aa49e39e44c322d7329cbba01967afb15fb7fc5e
 SHA512:
-  metadata.gz: 164b9d01d9d76a03df6f7336010460fa6a0811c1e80f509becb9b7989891d82763726ea554327a34a754534442919dd2840a954b5c6a68d165c7b6a5dafc2117
-  data.tar.gz: 1409de06917f3f86d231d576941e1f2fb94a492fbc96eefd24e8b6b9e7c9bc2acc4c37426cab8dca5f54069df7e0b9ec95b2f75eb9938f56c0cf523b74ed79ad
+  metadata.gz: a22c1acd44798f116733781f5648b8cf74697811c09a8ed76ac73a217b803467dd3213a7efe19a1b57c13b3ff93dddd7ca0b4eb5496ea05228f559a29c830dc5
+  data.tar.gz: c2b731b11958e0adc38bd37b30045494a832225daf1d8c79a310fb78b8cb72e49a7765d45700c3fcf01e982a5a830faacc7bf8127b0e84806d4a79dccbfc4f8f

data/CHANGELOG.md

@@ -1,5 +1,27 @@
 # Changelog
 
+## 0.14.1 (2026-07-06)
+
+Full Changelog: [v0.14.0...v0.14.1](https://github.com/openlayer-ai/openlayer-ruby/compare/v0.14.0...v0.14.1)
+
+## 0.14.0 (2026-07-06)
+
+Full Changelog: [v0.13.1...v0.14.0](https://github.com/openlayer-ai/openlayer-ruby/compare/v0.13.1...v0.14.0)
+
+### Features
+
+* **closes OPEN-11569:** support additional columns in ConversationalSearchService tracer ([e5cd8df](https://github.com/openlayer-ai/openlayer-ruby/commit/e5cd8df9335795f7296b394ea007caea3b090475))
+
+
+### Bug Fixes
+
+* **client:** send content-type header for requests with an omitted optional body ([1778b7d](https://github.com/openlayer-ai/openlayer-ruby/commit/1778b7d71ddf2c244be71648141b84666f81addd))
+
+
+### Chores
+
+* **internal:** bound formatter parallelism to CPU count ([f8781d0](https://github.com/openlayer-ai/openlayer-ruby/commit/f8781d074e80fc95497513b400c601e246998729))
+
 ## 0.13.1 (2026-05-14)
 
 Full Changelog: [v0.13.0...v0.13.1](https://github.com/openlayer-ai/openlayer-ruby/compare/v0.13.0...v0.13.1)

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.13.1"
+gem "openlayer", "~> 0.14.1"
 ```
 
 <!-- x-release-please-end -->

data/lib/openlayer/integrations/google_conversational_search_tracer.rb

@@ -21,15 +21,25 @@ module Openlayer
     #   Openlayer::Integrations::GoogleConversationalSearchTracer.trace_client(
     #     google_client,
     #     openlayer_client: openlayer,
-    #     inference_pipeline_id: 'your-pipeline-id'
+    #     inference_pipeline_id: 'your-pipeline-id',
+    #     additional_columns: { environment: 'production' }
     #   )
     #
-    #   # Now all answer_query calls are automatically traced
+    #   # Now all answer_query calls are automatically traced! Pass
+    #   # additional_columns on an individual call to attach data (like your
+    #   # own trace ID) to just that row; it takes precedence over the
+    #   # static defaults above on a key conflict.
     #   response = google_client.answer_query(
     #     serving_config: "projects/.../servingConfigs/default",
-    #     query: { text: "What is the meaning of life?" }
+    #     query: { text: "What is the meaning of life?" },
+    #     additional_columns: { trace_id: "abc-123" }
     #   )
     class GoogleConversationalSearchTracer
+      # Row keys computed by this tracer. Any key in a caller-supplied
+      # additional_columns hash matching one of these is dropped, so custom
+      # data can never overwrite core trace fields.
+      RESERVED_ROW_KEYS = [:query, :answer, :latency_ms, :timestamp, :metadata, :steps, :context, :session_id, :user_id].freeze
+
       # Enable tracing on a Google ConversationalSearchService client
       #
       # @param client [Google::Cloud::DiscoveryEngine::V1::ConversationalSearchService::Client]
@@ -42,8 +52,12 @@ module Openlayer
       #   Optional session ID to use for all traces. Takes precedence over auto-extracted sessions.
       # @param user_id [String, nil]
       #   Optional user ID to use for all traces.
+      # @param additional_columns [Hash, nil]
+      #   Optional static column values merged into every trace sent through this client (e.g. `{ environment: 'production' }`).
+      #   A value passed to an individual answer_query call takes precedence over these on a key conflict. Keys colliding
+      #   with a reserved row column (query, answer, latency_ms, timestamp, metadata, steps, context, session_id, user_id) are dropped.
       # @return [void]
-      def self.trace_client(client, openlayer_client:, inference_pipeline_id:, session_id: nil, user_id: nil)
+      def self.trace_client(client, openlayer_client:, inference_pipeline_id:, session_id: nil, user_id: nil, additional_columns: {})
         # Store original method reference
         original_answer_query = client.method(:answer_query)
 
@@ -52,6 +66,10 @@ module Openlayer
           # Capture start time
           start_time = Time.now
 
+          # Extract per-call additional columns before forwarding to the
+          # real client; Google's client never sees this key
+          call_additional_columns = kwargs.delete(:additional_columns)
+
           # Execute the original method
           response = original_answer_query.call(*args, **kwargs, &block)
 
@@ -69,7 +87,9 @@ module Openlayer
               openlayer_client: openlayer_client,
               inference_pipeline_id: inference_pipeline_id,
               session_id: session_id,
-              user_id: user_id
+              user_id: user_id,
+              additional_columns: additional_columns,
+              call_additional_columns: call_additional_columns
             )
           rescue StandardError => e
             # Never break the user's application due to tracing errors
@@ -95,8 +115,10 @@ module Openlayer
       # @param inference_pipeline_id [String] Pipeline ID
       # @param session_id [String, nil] Optional session ID (takes precedence over auto-extracted)
       # @param user_id [String, nil] Optional user ID
+      # @param additional_columns [Hash, nil] Optional static column values (see {.trace_client})
+      # @param call_additional_columns [Hash, nil] Optional per-call column values; takes precedence over additional_columns
       # @return [void]
-      def self.send_trace(args:, kwargs:, response:, start_time:, end_time:, openlayer_client:, inference_pipeline_id:, session_id: nil, user_id: nil)
+      def self.send_trace(args:, kwargs:, response:, start_time:, end_time:, openlayer_client:, inference_pipeline_id:, session_id: nil, user_id: nil, additional_columns: {}, call_additional_columns: {})
         # Calculate latency
         latency_ms = ((end_time - start_time) * 1000).round(2)
 
@@ -199,6 +221,12 @@ module Openlayer
           trace_data[:config][:userIdColumnName] = "user_id"
         end
 
+        # Merge additional columns (per-call values take precedence over
+        # static defaults; keys colliding with reserved row columns are
+        # dropped so custom data can never corrupt core trace fields)
+        extra_columns = resolve_additional_columns(additional_columns, call_additional_columns)
+        trace_data[:rows][0].merge!(extra_columns) unless extra_columns.empty?
+
         # Send to Openlayer
         openlayer_client
           .inference_pipelines
@@ -317,6 +345,9 @@ module Openlayer
 
       # Extract references from answer
       #
+      # Each reference's `content` is a oneof: exactly one of chunk_info,
+      # structured_document_info, or unstructured_document_info is present.
+      #
       # @param answer [Object] Answer object from response
       # @return [Array<Hash>, nil] Array of reference hashes or nil
       def self.extract_references(answer)
@@ -326,25 +357,85 @@ module Openlayer
         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
+          extract_reference(reference, index)
         end.compact
       rescue StandardError => e
         warn_if_debug("[Openlayer] Failed to extract references: #{e.message}")
         nil
       end
 
+      # Extract a single reference hash from whichever `content` oneof
+      # variant is present on it
+      #
+      # @param reference [Object] Reference object
+      # @param index [Integer] Reference's index in the references array
+      # @return [Hash, nil] Reference hash, or nil if no known variant is set
+      def self.extract_reference(reference, index)
+        if (chunk_info = safe_extract(reference, :chunk_info))
+          extract_chunk_info_reference(chunk_info, index)
+        elsif (structured_document_info = safe_extract(reference, :structured_document_info))
+          extract_structured_document_info_reference(structured_document_info, index)
+        elsif (unstructured_document_info = safe_extract(reference, :unstructured_document_info))
+          extract_unstructured_document_info_reference(unstructured_document_info, index)
+        end
+      rescue StandardError => e
+        warn_if_debug("[Openlayer] Failed to extract reference: #{e.message}")
+        nil
+      end
+
+      # Build a reference hash from a ChunkInfo variant
+      #
+      # @param chunk_info [Object] ChunkInfo object
+      # @param index [Integer] Reference's index in the references array
+      # @return [Hash] Reference hash
+      def self.extract_chunk_info_reference(chunk_info, index)
+        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
+
+      # Build a reference hash from a StructuredDocumentInfo variant
+      #
+      # @param structured_document_info [Object] StructuredDocumentInfo object
+      # @param index [Integer] Reference's index in the references array
+      # @return [Hash] Reference hash
+      def self.extract_structured_document_info_reference(structured_document_info, index)
+        {
+          reference_id: index.to_s,
+          document_id: safe_extract(structured_document_info, :document),
+          uri: safe_extract(structured_document_info, :uri),
+          title: safe_extract(structured_document_info, :title),
+          struct_data: safe_extract(structured_document_info, :struct_data)
+        }.compact
+      end
+
+      # Build a reference hash from an UnstructuredDocumentInfo variant
+      #
+      # @param unstructured_document_info [Object] UnstructuredDocumentInfo object
+      # @param index [Integer] Reference's index in the references array
+      # @return [Hash] Reference hash
+      def self.extract_unstructured_document_info_reference(unstructured_document_info, index)
+        chunk_contents = safe_extract(unstructured_document_info, :chunk_contents)
+        content = if chunk_contents.respond_to?(:map)
+          chunk_contents.map { |chunk| safe_extract(chunk, :content) }.compact.join("\n")
+        end
+
+        {
+          reference_id: index.to_s,
+          content: (content unless content.nil? || content.empty?),
+          document_id: safe_extract(unstructured_document_info, :document),
+          uri: safe_extract(unstructured_document_info, :uri),
+          title: safe_extract(unstructured_document_info, :title)
+        }.compact
+      end
+
       # Extract related questions from answer
       #
       # @param answer [Object] Answer object from response
@@ -594,6 +685,45 @@ module Openlayer
         nil
       end
 
+      # Merge static and per-call additional columns into a single Hash of
+      # extra row columns. Call-level values take precedence over static
+      # ones on key conflict, and any key colliding with a reserved row
+      # column is dropped.
+      #
+      # @param static_columns [Object] Value passed to trace_client (expected Hash)
+      # @param call_columns [Object] Value passed to an individual answer_query call (expected Hash)
+      # @return [Hash] Extra columns safe to merge onto a trace row
+      def self.resolve_additional_columns(static_columns, call_columns)
+        merged = normalize_additional_columns(static_columns).merge(normalize_additional_columns(call_columns))
+
+        merged.each_with_object({}) do |(key, value), result|
+          if RESERVED_ROW_KEYS.include?(key)
+            warn_if_debug("[Openlayer] additional_columns key :#{key} collides with a reserved column and was ignored")
+          else
+            result[key] = value
+          end
+        end
+      end
+
+      # Normalize an additional_columns value into a Hash with Symbol keys.
+      # Non-Hash input (or a key that can't be a Symbol) is dropped rather
+      # than raising, so a caller mistake can never break tracing.
+      #
+      # @param columns [Object] Expected to be a Hash of column name => value
+      # @return [Hash]
+      def self.normalize_additional_columns(columns)
+        return {} unless columns.is_a?(Hash)
+
+        columns.each_with_object({}) do |(key, value), result|
+          next unless key.respond_to?(:to_sym)
+
+          result[key.to_sym] = value
+        end
+      rescue StandardError => e
+        warn_if_debug("[Openlayer] Failed to normalize additional columns: #{e.message}")
+        {}
+      end
+
       # Safely extract a field from an object
       #
       # @param obj [Object] Object to extract from
@@ -650,6 +780,10 @@ module Openlayer
                            :extract_citations,
                            :extract_citation_sources,
                            :extract_references,
+                           :extract_reference,
+                           :extract_chunk_info_reference,
+                           :extract_structured_document_info_reference,
+                           :extract_unstructured_document_info_reference,
                            :extract_related_questions,
                            :extract_steps,
                            :extract_step_data,
@@ -659,6 +793,8 @@ module Openlayer
                            :extract_session,
                            :extract_user_pseudo_id,
                            :extract_query_understanding_info,
+                           :resolve_additional_columns,
+                           :normalize_additional_columns,
                            :safe_extract,
                            :safe_count,
                            :extract_timestamp

data/lib/openlayer/internal/transport/base_client.rb

@@ -306,7 +306,10 @@ module Openlayer
               Openlayer::Internal::Util.deep_merge(*[req[:body], opts[:extra_body]].compact)
             end
 
-          headers.delete("content-type") if body.nil?
+          # Generated methods always pass `req[:body]` for operations that define a
+          # request body, so only elide the content-type header when the operation
+          # has no body at all, not when an optional body param was omitted.
+          headers.delete("content-type") if body.nil? && !req.key?(:body)
 
           url = Openlayer::Internal::Util.join_parsed_uri(
             @base_url_components,

data/lib/openlayer/version.rb

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

data/rbi/openlayer/integrations.rbi

@@ -10,7 +10,8 @@ module Openlayer
           openlayer_client: Openlayer::Client,
           inference_pipeline_id: String,
           session_id: T.nilable(String),
-          user_id: T.nilable(String)
+          user_id: T.nilable(String),
+          additional_columns: T::Hash[Symbol, T.untyped]
         ).void
       end
       def self.trace_client(
@@ -18,7 +19,8 @@ module Openlayer
         openlayer_client:,
         inference_pipeline_id:,
         session_id: nil,
-        user_id: nil
+        user_id: nil,
+        additional_columns: {}
       )
       end
     end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: openlayer
 version: !ruby/object:Gem::Version
-  version: 0.13.1
+  version: 0.14.1
 platform: ruby
 authors:
 - Openlayer
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-06-15 00:00:00.000000000 Z
+date: 2026-07-08 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: cgi