strongmind-platform-sdk 3.28.0 → 3.29.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 97b493cd879ebbc714026b5d819ddfe8366453b0fb3d4e037ccf653dd6bf852e
-  data.tar.gz: bf03370e3b62cdc6732dcb9d1a0966782afa45722ac6f2bf15e121978c0d1fce
+  metadata.gz: 799fe97b77fb105775c8b846e6916380be6845209a5157633d832186ae81bd25
+  data.tar.gz: ee0bbab328e6e27bcf72a5e634535f9ed0ab91bb57976b94a9c1fd24fac268f1
 SHA512:
-  metadata.gz: 37074d6a5591e41ae57301530ffaed72b49bb21d07298ebd2c2434fcfe50cbd623f24b1fc6db4ee991b7b19c3eaa503014568a8e7b2548766265c8c90589dd0e
-  data.tar.gz: a539e7cad181064b9d617c020241a356dafb96102bfb2d1a63398476885c400b6736dfad46ab0b941e314654f6181960a46552bde1a3556ab0ea281b6a97e347
+  metadata.gz: 7080031758db9d9bd0894dcc2b8054df0377f1bc33a6da0ba987f7be9888c343cb0e2feb83d9d811c95114e1891ff4a62c1cde7d445333b35a5bcbf6a2b4007a
+  data.tar.gz: c8e8bb3e06b1b6808cbc02c50664921dd6850520050cf5e0191a4bc01b3e2e4357bb8d0fa4c4edd14a95db1134d351a5ca3fbd1105243eb0cfd317ac85955f80

data/CHANGELOG.md

@@ -1,5 +1,12 @@
 ## [Unreleased]
 
+## [3.29.0] - 2026-05-12
+
+- Add `PlatformSdk::Observability::Langfuse::NotificationSubscriber` — subscribes to the `llm_call.platform_sdk` `ActiveSupport::Notifications` event and forwards to `Recorder.record_generation`. Apps can instrument LLM calls without coupling to a host concern; adding a second observability backend later is one more `subscribe` call.
+- Auto-installed by `Langfuse.configure` (opt out with `autosubscribe: false`).
+- Payload contract: `name`, `model`, `input`, `output`, `usage: { input_tokens:, output_tokens: }`, `prompt: { name:, version: }`, `provider`, `error:` (optional Exception — when set, recorded as a failure observation).
+- Add `PlatformSdk::Observability::Langfuse::TraceSummarizable` mixin — template method for jobs to record a meaningful summary on the trace's Output column via `record_langfuse_trace_output` + `langfuse_trace_output_attributes`.
+
 ## [3.28.0] - 2026-05-05
 
 - Add `PlatformSdk::Observability::Langfuse` module providing OpenTelemetry-based tracing exported to Langfuse Cloud via OTLP.

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    strongmind-platform-sdk (3.28.0)
+    strongmind-platform-sdk (3.29.0)
       asset_sync
       aws-sdk-cloudwatch
       aws-sdk-secretsmanager (~> 1.66)
@@ -154,7 +154,7 @@ GEM
     ffi (1.17.0)
     ffi (1.17.0-x86_64-darwin)
     ffi (1.17.0-x86_64-linux-gnu)
-    fog-aws (3.33.1)
+    fog-aws (3.33.2)
       base64 (>= 0.2, < 0.4)
       fog-core (~> 2.6)
       fog-json (~> 1.1)
@@ -164,7 +164,7 @@ GEM
       excon (~> 1.0)
       formatador (>= 0.2, < 2.0)
       mime-types
-    fog-json (1.2.0)
+    fog-json (1.3.0)
       fog-core
       multi_json (~> 1.10)
     fog-xml (0.1.5)
@@ -213,7 +213,7 @@ GEM
     mime-types (3.7.0)
       logger
       mime-types-data (~> 3.2025, >= 3.2025.0507)
-    mime-types-data (3.2026.0317)
+    mime-types-data (3.2026.0414)
     mini_mime (1.1.5)
     mini_portile2 (2.8.7)
     minitest (5.24.1)
@@ -221,7 +221,7 @@ GEM
     mutex_m (0.2.0)
     net-http (0.4.1)
       uri
-    net-imap (0.6.3)
+    net-imap (0.6.4)
       date
       net-protocol
     net-pop (0.1.2)

data/lib/platform_sdk/observability/langfuse/notification_subscriber.rb

@@ -0,0 +1,127 @@
+# frozen_string_literal: true
+
+require 'active_support/notifications'
+
+module PlatformSdk
+  module Observability
+    module Langfuse
+      # Subscribes to `llm_call.platform_sdk` ActiveSupport::Notifications events
+      # and forwards them to `Recorder.record_generation`.
+      #
+      # Apps instrument their LLM calls with the convention:
+      #
+      #   ActiveSupport::Notifications.instrument(
+      #     'llm_call.platform_sdk',
+      #     name: 'chat_response',
+      #     model: 'claude-3-5-sonnet',
+      #     input: prompt_messages,
+      #     output: response_text,
+      #     usage: { input_tokens: 120, output_tokens: 84 }
+      #   ) { call_the_llm }
+      #
+      # Inside the block, the payload Hash can be mutated to enrich it with
+      # values only known after the call completes. (`Instrumenter#instrument`
+      # passes the same Hash to the block and reads it again after `yield`;
+      # this isn't documented in the Rails Guide but is relied on across
+      # the ecosystem.)
+      #
+      # Two error-passing paths:
+      #
+      # 1. **Direct `instrument`-with-a-block callers** that let the block
+      #    raise: Rails populates `:exception_object` automatically and this
+      #    subscriber records a failure observation from it.
+      #
+      # 2. **Caller-rescues-and-rethrows** patterns (e.g. `RubyLLMAdapter.fire`,
+      #    course-builder's `LlmErrorHandling#with_llm_error_handling`): set
+      #    `payload[:error] = exception` before firing. Rails only auto-sets
+      #    `:exception_object` for the block form, so adapter-style callers
+      #    that `instrument` without a block need to populate `:error`.
+      #
+      # `format_output` prefers `:error` when both are set so the
+      # caller-provided value wins.
+      #
+      # Idempotent: `install!` is safe to call repeatedly — only the first
+      # call registers a subscriber.
+      module NotificationSubscriber
+        EVENT_NAME = LLM_CALL_EVENT
+        DEFAULT_NAME = 'llm_call'
+
+        @installed = false
+        @subscriber = nil
+        @mutex = Mutex.new
+
+        class << self
+          def install!
+            @mutex.synchronize do
+              return if @installed
+
+              @subscriber = ActiveSupport::Notifications.subscribe(EVENT_NAME) do |_name, _start, _finish, _id, payload|
+                handle_event(payload)
+              end
+              @installed = true
+            end
+          end
+
+          def reset!
+            @mutex.synchronize do
+              ActiveSupport::Notifications.unsubscribe(@subscriber) if @subscriber
+              @subscriber = nil
+              @installed = false
+            end
+          end
+
+          def installed?
+            @installed
+          end
+
+          private
+
+          def handle_event(payload)
+            payload ||= {}
+            Langfuse.record_generation(**build_kwargs(payload))
+          rescue StandardError => e
+            OpenTelemetry.handle_error(
+              message: "Langfuse notification subscriber failed: #{e.class}: #{e.message[0, 200]}"
+            )
+          end
+
+          def build_kwargs(payload)
+            warn_if_misshaped_prompt(payload[:prompt])
+            prompt = payload[:prompt].is_a?(Hash) ? payload[:prompt] : {}
+            {
+              name: payload[:name] || DEFAULT_NAME, model: payload[:model],
+              input: payload[:input], output: format_output(payload),
+              usage: payload[:usage],
+              prompt_name: prompt[:name], prompt_version: prompt[:version],
+              provider: payload[:provider]
+            }
+          end
+
+          # Surfaces a non-Hash `:prompt` value through OpenTelemetry so
+          # callers see the misconfiguration in development instead of
+          # silently losing prompt tracing. A plain string like
+          # `prompt: 'my_prompt_name'` (easy to confuse with `name:`) would
+          # otherwise fall back to `{}` with no feedback.
+          def warn_if_misshaped_prompt(raw_prompt)
+            return if raw_prompt.nil? || raw_prompt.is_a?(Hash)
+
+            OpenTelemetry.handle_error(
+              message: 'Langfuse NotificationSubscriber: :prompt must be a Hash with :name and :version ' \
+                       "(got #{raw_prompt.class}); prompt info will not be recorded"
+            )
+          end
+
+          # `:error` (caller-set) takes precedence over `:exception_object`
+          # (Rails-set when an instrument block raises) so a caller that
+          # rescues and re-fires has the final say. Cap the formatted
+          # message so a multi-MB upstream error body can't be forwarded
+          # verbatim to the telemetry sink.
+          def format_output(payload)
+            error = payload[:error] || payload[:exception_object]
+            error ? "[#{error.class}] #{error.message.to_s[0, 500]}" : payload[:output]
+          end
+        end
+      end
+    end
+  end
+end

data/lib/platform_sdk/observability/langfuse/ruby_llm_adapter.rb

@@ -0,0 +1,118 @@
+# frozen_string_literal: true
+
+require 'active_support/notifications'
+
+module PlatformSdk
+  module Observability
+    module Langfuse
+      # Fires `llm_call.platform_sdk` ActiveSupport::Notifications events with
+      # a payload extracted from a RubyConversations / RubyLLM-shaped chat.
+      #
+      # Apps that use the RubyLLM (or RubyConversations) gem call this from
+      # any LLM call site to get cost, token, model, input, and output
+      # captured in Langfuse without having to know the OTel attribute keys:
+      #
+      #   PlatformSdk::Observability::Langfuse::RubyLLMAdapter.fire(
+      #     conversation: conversation_manager,
+      #     context: 'chat_response'
+      #   )
+      #
+      # The adapter is RubyLLM-aware but does not require the RubyLLM gem at
+      # load time — `RubyLLM::Content` references are guarded by `defined?`,
+      # so apps that don't use RubyLLM can load the SDK without paying for
+      # this code path.
+      #
+      # Dedup: nested or repeated calls that share the same `chat.messages.last`
+      # object are skipped, so a single LLM response can't double-fire when
+      # multiple layers of error-handling each wrap the same yield. The
+      # dedup state is registered via `Langfuse.track_thread_local`, so
+      # `Traceable`-wrapped Sidekiq jobs get it cleared in their ensure
+      # block. Callers outside `Traceable` (Rails controllers, long-lived
+      # Puma threads) should invoke
+      # `Langfuse.clear_tracked_thread_locals!` at their request/operation
+      # boundary to avoid dedup state leaking between unrelated calls.
+      module RubyLLMAdapter
+        MAX_PROMPT_MESSAGES = 30
+        THREAD_LOCAL_KEY = :platform_sdk_langfuse_last_message_id
+
+        class << self
+          # Fire an `llm_call.platform_sdk` notification for a single LLM call.
+          # Accepts either a RubyConversations conversation (preferred — the
+          # adapter reads `conversation.chat` and `conversation.model_identifier`)
+          # or a raw RubyLLM::Chat. Returns nil — never raises.
+          def fire(context:, conversation: nil, chat: nil, error: nil)
+            payload = build_payload(context:, conversation:, chat:, error:)
+            return unless payload
+
+            ActiveSupport::Notifications.instrument(LLM_CALL_EVENT, payload)
+          rescue StandardError => e
+            OpenTelemetry.handle_error(
+              message: "RubyLLMAdapter.fire failed: #{e.class}: #{e.message[0, 200]}"
+            )
+            nil
+          end
+
+          private
+
+          # Build the notification payload from a RubyLLM-shaped conversation
+          # or chat. Returns nil when there's nothing to record (e.g. empty
+          # chat, dup of the last recorded response, or Langfuse disabled).
+          # Internal — exercise via `fire` and span assertions; the Hash
+          # shape is not a stable public contract.
+          def build_payload(context:, conversation: nil, chat: nil, error: nil)
+            return nil unless Langfuse.enabled?
+
+            chat ||= conversation&.chat
+            last = chat&.messages&.last
+            return nil if last.nil? && error.nil?
+            return nil if duplicate_llm_response?(last)
+
+            track_llm_response(last) if last
+
+            {
+              name: context || 'llm_call',
+              model: last&.model_id || conversation&.model_identifier,
+              input: chat ? serialize_input(chat) : nil,
+              output: last&.content,
+              usage: { input_tokens: last&.input_tokens, output_tokens: last&.output_tokens },
+              error:
+            }
+          end
+
+          def duplicate_llm_response?(last)
+            return false if last.nil?
+
+            Thread.current[THREAD_LOCAL_KEY] == last.object_id
+          end
+
+          def track_llm_response(last)
+            Langfuse.track_thread_local(THREAD_LOCAL_KEY)
+            Thread.current[THREAD_LOCAL_KEY] = last.object_id
+          end
+
+          def serialize_input(chat)
+            messages = chat&.messages
+            return nil if messages.nil? || messages.empty?
+
+            # Strip the assistant's response (last message) so input represents what was sent TO the LLM.
+            # Cap to the most-recent N messages to bound allocation on long tool-heavy conversations.
+            # `last(n)` returns a fresh array, so we can pop in place — one allocation instead of two.
+            prompt_messages = messages.last(MAX_PROMPT_MESSAGES + 1).tap(&:pop)
+            prompt_messages.map { |m| { role: m.role, content: extract_message_content(m) } }
+          end
+
+          def extract_message_content(message)
+            content = message.content
+            return content.to_s unless ruby_llm_content?(content)
+
+            content.text.to_s
+          end
+
+          def ruby_llm_content?(content)
+            defined?(::RubyLLM::Content) && content.is_a?(::RubyLLM::Content)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/platform_sdk/observability/langfuse/spec_support.rb

@@ -37,7 +37,13 @@ module PlatformSdk
               )
             end
             config.before(:each) do
+              # Drain the BatchSpanProcessor before clearing — otherwise spans
+              # emitted by the previous example sit in the processor's queue
+              # and flush into the next example's view, producing
+              # order-dependent assertion failures.
+              PlatformSdk::Observability::Langfuse.configuration&.tracer_provider&.force_flush(timeout: 5)
               PlatformSdk::Observability::Langfuse::SpecSupport.exporter&.clear
+              PlatformSdk::Observability::Langfuse.clear_tracked_thread_locals!
             end
             config.include TestHelpers
           end

data/lib/platform_sdk/observability/langfuse/trace_summarizable.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+module PlatformSdk
+  module Observability
+    module Langfuse
+      # Mix into Sidekiq jobs (or anything running under a `Traceable` span)
+      # to record a meaningful summary of the work in the trace's Output
+      # column in Langfuse.
+      #
+      # Including classes implement `#langfuse_trace_output_attributes`
+      # returning a Hash; call `record_langfuse_trace_output` once the
+      # relevant instance state is settled (typically at the end of perform).
+      #
+      #   class GenerateThingJob
+      #     include Sidekiq::Job
+      #     include PlatformSdk::Observability::Langfuse::Traceable
+      #     include PlatformSdk::Observability::Langfuse::TraceSummarizable
+      #
+      #     def perform(args)
+      #       @thing = build_thing(args)
+      #       record_langfuse_trace_output
+      #     end
+      #
+      #     private
+      #
+      #     def langfuse_trace_output_attributes
+      #       { thing_id: @thing&.id, status: @thing&.status }
+      #     end
+      #   end
+      module TraceSummarizable
+        private
+
+        def record_langfuse_trace_output
+          PlatformSdk::Observability::Langfuse.set_trace_output(langfuse_trace_output_attributes)
+        end
+
+        def langfuse_trace_output_attributes
+          raise NotImplementedError, "#{self.class} must implement #langfuse_trace_output_attributes"
+        end
+      end
+    end
+  end
+end

data/lib/platform_sdk/observability/langfuse.rb

@@ -1,11 +1,29 @@
 # frozen_string_literal: true
 
+# Constants declared up-front so the files we require below can reference
+# them at load time without a circular dependency.
+module PlatformSdk
+  module Observability
+    module Langfuse
+      # ActiveSupport::Notifications event name for LLM calls. Owned by the
+      # `Langfuse` namespace (rather than `NotificationSubscriber`) so the
+      # adapter can emit without requiring the subscriber to be loaded.
+      LLM_CALL_EVENT = 'llm_call.platform_sdk'
+
+      OWNED_THREAD_LOCALS_KEY = :platform_sdk_langfuse_owned_thread_locals
+    end
+  end
+end
+
 require 'platform_sdk/observability/langfuse/coercions'
 require 'platform_sdk/observability/langfuse/configuration'
 require 'platform_sdk/observability/langfuse/null_span_exporter'
 require 'platform_sdk/observability/langfuse/recorder'
+require 'platform_sdk/observability/langfuse/trace_summarizable'
 require 'platform_sdk/observability/langfuse/traceable'
 require 'platform_sdk/observability/langfuse/sidekiq_lifecycle'
+require 'platform_sdk/observability/langfuse/notification_subscriber'
+require 'platform_sdk/observability/langfuse/ruby_llm_adapter'
 
 module PlatformSdk
   module Observability
@@ -13,20 +31,16 @@ module PlatformSdk
       class Error < StandardError; end
       class ConfigurationError < Error; end
 
-      OWNED_THREAD_LOCALS_KEY = :platform_sdk_langfuse_owned_thread_locals
-
       class << self
         attr_reader :configuration
 
-        def configure(app_name:, environment: nil, prompt_label: nil, exporter: nil)
+        def configure(app_name:, environment: nil, prompt_label: nil, exporter: nil, autosubscribe: true)
           @configuration&.force_flush_and_shutdown
-          @configuration = Configuration.new(
-            app_name: app_name,
-            environment: environment,
-            prompt_label: prompt_label,
-            exporter: exporter
-          )
-          SidekiqLifecycle.install! if @configuration.enabled?
+          @configuration = Configuration.new(app_name:, environment:, prompt_label:, exporter:)
+          if @configuration.enabled?
+            SidekiqLifecycle.install!
+            NotificationSubscriber.install! if autosubscribe
+          end
           @configuration
         end
 
@@ -86,6 +100,7 @@ module PlatformSdk
           @configuration&.force_flush_and_shutdown
           @configuration = nil
           SidekiqLifecycle.reset!
+          NotificationSubscriber.reset!
         end
 
         # Register thread-local keys that should be cleared at the next

data/lib/platform_sdk/version.rb

@@ -2,7 +2,7 @@
 
 module PlatformSdk
   MAJOR = 3
-  MINOR = 28
+  MINOR = 29
   PATCH = 0
 
   VERSION = "#{PlatformSdk::MAJOR}.#{PlatformSdk::MINOR}.#{PlatformSdk::PATCH}"

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: strongmind-platform-sdk
 version: !ruby/object:Gem::Version
-  version: 3.28.0
+  version: 3.29.0
 platform: ruby
 authors:
 - Platform Team
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2026-05-11 00:00:00.000000000 Z
+date: 2026-05-13 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: faraday
@@ -318,10 +318,13 @@ files:
 - lib/platform_sdk/observability/langfuse.rb
 - lib/platform_sdk/observability/langfuse/coercions.rb
 - lib/platform_sdk/observability/langfuse/configuration.rb
+- lib/platform_sdk/observability/langfuse/notification_subscriber.rb
 - lib/platform_sdk/observability/langfuse/null_span_exporter.rb
 - lib/platform_sdk/observability/langfuse/recorder.rb
+- lib/platform_sdk/observability/langfuse/ruby_llm_adapter.rb
 - lib/platform_sdk/observability/langfuse/sidekiq_lifecycle.rb
 - lib/platform_sdk/observability/langfuse/spec_support.rb
+- lib/platform_sdk/observability/langfuse/trace_summarizable.rb
 - lib/platform_sdk/observability/langfuse/traceable.rb
 - lib/platform_sdk/one_roster.rb
 - lib/platform_sdk/one_roster/client.rb