nitro_intelligence 3.0.2 → 3.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: feb0fe8d0b4ae0d1da8564f048fa7130dc78318622a23a86163edc65d2f37dbf
-  data.tar.gz: 122277bfc6b70b0aeb67166624458f37f50b1ed2b1a77044ade87575ea101bb1
+  metadata.gz: 2151383fb66e0292ac5fbf73f16697e32b9c0f7d64263500babdb505275925cc
+  data.tar.gz: 91b5f4bbbb3e87f56e883b710f8af8a6c1900e3c1e733d3eba14258bbc8ebf05
 SHA512:
-  metadata.gz: bf69e4777017afa0be7457612c42aadf434921c083b3a199e13a0682959b6579494793069e2548c592dd022ac5a96d342155549cfa5d36fdf798bd0a05bd647f
-  data.tar.gz: 18854e89e04d994bddc0315296d5f21ad2551dd9b7d64d01efda6aadc25dbcd0858d1e8f24dacb2f2b261b2b65ab1bb3fe747956f5064ce6ef176b017e59b712
+  metadata.gz: d058b2fed129d9c85210558afe41b947a44090a5532aca084a6eff04fa2913f4e0d284f0848818ce98195673833e6d675141ee06464bafcf588cfdf29bfea9f8
+  data.tar.gz: 10b6c3213894be249388a5bdbc7cc5ef963b904581d00de2d02ac3175aeb9abc9348e959a2f54c8a27b20cb19b1ecdd4c09fdb974325d331367d25df98be73b7

data/Rakefile

@@ -1,6 +1,8 @@
 require "bundler/gem_tasks"
 require "rspec/core/rake_task"
+require "rubocop/rake_task"
 
 RSpec::Core::RakeTask.new(:spec)
+RuboCop::RakeTask.new
 
-task default: :spec
+task default: %i[spec rubocop]

data/docs/README.md

@@ -323,7 +323,7 @@ client.chat(
 
 ### Custom Trace IDs
 
-To generate a deterministic trace ID in the observability platform, you can pass `trace_seed` as a parameter. This is useful when you want a stable identifier that is derived from a specific domain value (e.g., document ID). The same `trace_seed` will produce the same trace ID, making it easier to correlate multiple events.
+To generate a deterministic trace ID in the observability platform, you can pass `trace_seed` as a parameter. This is useful when you want a stable identifier that is derived from a specific domain value (e.g., document ID). The same `trace_seed` will produce the same trace ID, making it easier to correlate multiple events. Each seeded call creates a root observation in that trace, including when another observation is active. With Langfuse v4 event reads, trace input and output come from the most recently ingested root observation. Calls without a seed keep their active parent observation.
 
 ```ruby
 document_id = "document-123"
@@ -424,6 +424,16 @@ trace_id = NitroIntelligence::Trace.create_id(seed: document_id)
 reporter.score(name: "precision", value: 0.5, trace_id:)
 ```
 
+#### Using different data types for scoring
+
+By default, scores submitted on a trace are numeric, but you can use the `data_type` keyword to change it to `:boolean` or `:categorical`. For example:
+
+```ruby
+reporter.score(name: "precision", value: "Partially Correct", trace_id:, data_type: :categorical)
+```
+
+Numeric data is helpful for scores that happen on a sliding scale, like success rate or percent similarity. Boolean data is helpful to convey something that either passes or fails. Categorical data is helpful for scores that have pre-defined categories, like "Correct", "Partially Correct", and "Incorrect".
+
 ### Prompts
 
 #### Message Shape

data/lib/nitro_intelligence/client/observers/langfuse_observer.rb

@@ -10,6 +10,10 @@ module NitroIntelligence
 
         MAX_STATUS_MESSAGE_LENGTH = 2000
 
+        # Attributes a handler may report off a response, each written only when it supplied
+        # one. See #record_result for why absence is left as absence.
+        RECORDED_ATTRIBUTES = %i[model model_parameters usage_details cost_details input output].freeze
+
         attr_reader :project_client
 
         def initialize(project_client:)
@@ -63,15 +67,30 @@ module NitroIntelligence
 
           handle_truncation(trace_attributes[:input], trace_attributes[:output], trace_attributes[:model])
 
-          generation.model = trace_attributes[:model] if trace_attributes[:model]
-          generation.usage_details = trace_attributes[:usage_details] if trace_attributes[:usage_details]
-          generation.cost_details = trace_attributes[:cost_details] if trace_attributes[:cost_details]
-          generation.input = trace_attributes[:input] if trace_attributes[:input]
-          generation.output = trace_attributes[:output] if trace_attributes[:output]
+          RECORDED_ATTRIBUTES.each do |name|
+            value = trace_attributes[name]
+            generation.public_send(:"#{name}=", value) if value
+          end
+
+          record_status(generation, trace_attributes)
 
           generation.update_trace(input: trace_attributes[:input], output: trace_attributes[:output])
         end
 
+        # A response the endpoint answered but did not finish -- a generation cut off at its
+        # token ceiling, say -- is neither a success worth nothing being said about nor a
+        # failure the request raised on. Recording it at WARNING leaves it findable without
+        # putting it among the errors.
+        def record_status(generation, trace_attributes)
+          status_message = trace_attributes[:status_message]
+          return if status_message.blank?
+
+          generation.update(
+            level: trace_attributes[:level] || "WARNING",
+            status_message: status_message.truncate(MAX_STATUS_MESSAGE_LENGTH)
+          )
+        end
+
         # Recorded before the request is made so that a request which raises still
         # shows what was sent. Handlers whose input is not safe to record twice
         # (image generation sends base64 payloads that are replaced with media

data/lib/nitro_intelligence/langfuse_extension.rb

@@ -4,6 +4,9 @@
 # The content of this file should eventually make its way upstream. Setting a custom trace ID is
 # already awaiting approval in https://github.com/simplepractice/langfuse-rb/pull/69.
 #
+# Explicit trace IDs create real roots here while the upstream fix awaits approval:
+# https://github.com/simplepractice/langfuse-rb/pull/128.
+#
 
 require "nitro_intelligence/langfuse_tracer_provider"
 
@@ -50,11 +53,15 @@ module NitroIntelligence
       Langfuse.send(:validate_observation_type!, as_type, type_str) unless skip_validation
 
       otel_tracer = @tracer_provider.tracer
-      otel_span = Langfuse.send(:create_otel_span,
-                                name:,
-                                start_time:,
-                                parent_span_context:,
-                                otel_tracer:)
+      otel_span = if trace_id
+                    @tracer_provider.start_root_span(name, trace_id: parent_span_context.trace_id, start_time:)
+                  else
+                    Langfuse.send(:create_otel_span,
+                                  name:,
+                                  start_time:,
+                                  parent_span_context:,
+                                  otel_tracer:)
+                  end
 
       # Serialize attributes
       # Only set attributes if span is still recording (should always be true here, but guard for safety)

data/lib/nitro_intelligence/langfuse_tracer_provider.rb

@@ -7,6 +7,7 @@
 module NitroIntelligence
   class LangfuseTracerProvider
     def initialize(config)
+      @trace_id_key = OpenTelemetry::Context.create_key("nitro-intelligence-trace-id")
       @tracer_provider = create_tracer_provider(config)
     end
 
@@ -18,6 +19,25 @@ module NitroIntelligence
       @tracer_provider.shutdown(timeout:)
     end
 
+    def start_root_span(name, trace_id:, start_time: nil)
+      # A seed identifies the trace, not a missing parent. Preserve propagated
+      # attributes while clearing the ambient span for this explicit root.
+      context = OpenTelemetry::Trace.context_with_span(OpenTelemetry::Trace::Span::INVALID)
+      context = context.set_value(@trace_id_key, trace_id)
+      # generate_trace_id has no context argument, so expose the seed through Context.current.
+      OpenTelemetry::Context.with_current(context) do
+        tracer.start_span(name, with_parent: context, start_timestamp: start_time)
+      end
+    end
+
+    def generate_trace_id
+      OpenTelemetry::Context.value(@trace_id_key) || OpenTelemetry::Trace.generate_trace_id
+    end
+
+    def generate_span_id
+      OpenTelemetry::Trace.generate_span_id
+    end
+
   private
 
     def create_tracer_provider(config)
@@ -36,7 +56,7 @@ module NitroIntelligence
         max_export_batch_size: config.batch_size
       )
 
-      tracer_provider = OpenTelemetry::SDK::Trace::TracerProvider.new
+      tracer_provider = OpenTelemetry::SDK::Trace::TracerProvider.new(id_generator: self)
       tracer_provider.add_span_processor(processor)
       span_processor = Langfuse::SpanProcessor.new(config:)
       tracer_provider.add_span_processor(span_processor)
@@ -53,6 +73,7 @@ module NitroIntelligence
       encoded = Base64.strict_encode64(credentials)
       {
         "Authorization" => "Basic #{encoded}",
+        "x-langfuse-ingestion-version" => "4",
       }
     end
   end

data/lib/nitro_intelligence/reporter.rb

@@ -35,12 +35,13 @@ module NitroIntelligence
       response
     end
 
-    def score(trace_id:, name:, value:, id: "#{trace_id}-#{name}")
+    def score(trace_id:, name:, value:, id: "#{trace_id}-#{name}", data_type: :numeric)
       @project_client.observability_client.create_score(
         id:,
         trace_id:,
         name:,
         value:,
+        data_type:,
         environment: NitroIntelligence.environment
       )
     end

data/lib/nitro_intelligence/version.rb

@@ -1,3 +1,3 @@
 module NitroIntelligence
-  VERSION = "3.0.2".freeze
+  VERSION = "3.1.0".freeze
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: nitro_intelligence
 version: !ruby/object:Gem::Version
-  version: 3.0.2
+  version: 3.1.0
 platform: ruby
 authors:
 - Igor Artemenko