strongmind-platform-sdk 3.28.0 → 3.30.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 97b493cd879ebbc714026b5d819ddfe8366453b0fb3d4e037ccf653dd6bf852e
-  data.tar.gz: bf03370e3b62cdc6732dcb9d1a0966782afa45722ac6f2bf15e121978c0d1fce
+  metadata.gz: 47af8235ee05e3c5a4e31ac2f6ad5a4936dcfd004ce0a0eae2737cf19ca59440
+  data.tar.gz: e6814730ac3a3187e89554d7b7dd3d99b629f3833f41a72de4f332f59a769a72
 SHA512:
-  metadata.gz: 37074d6a5591e41ae57301530ffaed72b49bb21d07298ebd2c2434fcfe50cbd623f24b1fc6db4ee991b7b19c3eaa503014568a8e7b2548766265c8c90589dd0e
-  data.tar.gz: a539e7cad181064b9d617c020241a356dafb96102bfb2d1a63398476885c400b6736dfad46ab0b941e314654f6181960a46552bde1a3556ab0ea281b6a97e347
+  metadata.gz: e47283eb744412ddd608074dd12c38433db14273eb55ba3df3c5f60737b02e687b2ecce1ad70463d01709be5c6914178512c9d416f15c403444e6bf241d0e4e6
+  data.tar.gz: 24aeba0a4181cdf7cfda05ad764c54d0348016232029e0db2fe7b4c1a0362c43c75618c14eeb3bce79b47cda9977f8f296808d499681bf327f8e2ebb2c3909a8

data/CHANGELOG.md

@@ -1,5 +1,18 @@
 ## [Unreleased]
 
+## [3.30.0] - 2026-05-14
+
+- Add `PlatformSdk::Observability::Langfuse::OpenAIAdapter` — wraps direct `ruby-openai` chat calls and fires `llm_call.platform_sdk` notifications with model, input messages, output content, and token usage extracted from OpenAI's response shape. Apps that hit OpenAI's API outside of RubyLLM now get the same Langfuse generation observations.
+- Add `PlatformSdk::Observability::Langfuse::BedrockClaudeAdapter` — wraps direct AWS Bedrock `invoke_model` calls for Anthropic Claude (Messages API on Bedrock). Supports both non-streaming (`with_observability`) and event-streaming (`with_streaming_observability { |collector| ... }`) modes; the streaming collector accumulates `content_block_delta` text and pulls final token counts from `message_stop`'s `amazon-bedrock-invocationMetrics`.
+- Both adapters expose `with_observability` block helpers (success/failure fires + re-raises) and a bare `fire(...)` method for after-the-fact emission. Neither adapter requires its underlying gem (`ruby-openai`, `aws-sdk-bedrockruntime`) at load time — the SDK loads cleanly without them.
+
+## [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.30.0)
       asset_sync
       aws-sdk-cloudwatch
       aws-sdk-secretsmanager (~> 1.66)
@@ -177,12 +177,6 @@ GEM
     google-protobuf (4.33.6)
       bigdecimal
       rake (>= 13)
-    google-protobuf (4.33.6-x86_64-darwin)
-      bigdecimal
-      rake (>= 13)
-    google-protobuf (4.33.6-x86_64-linux-gnu)
-      bigdecimal
-      rake (>= 13)
     googleapis-common-protos-types (1.22.0)
       google-protobuf (~> 4.26)
     hashdiff (1.1.0)

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

@@ -0,0 +1,244 @@
+# frozen_string_literal: true
+
+require 'active_support/notifications'
+require 'json'
+
+module PlatformSdk
+  module Observability
+    module Langfuse
+      # Fires `llm_call.platform_sdk` notifications for Anthropic Claude calls
+      # made directly through the AWS Bedrock SDK (rather than via RubyLLM).
+      # Two entry points cover the two Bedrock invocation modes:
+      #
+      #   # Non-streaming (`bedrock_client.invoke_model(payload)`)
+      #   PlatformSdk::Observability::Langfuse::BedrockClaudeAdapter.with_observability(
+      #     payload: { model_id: 'us.anthropic.claude-sonnet-4-6',
+      #                body: JSON.dump(anthropic_messages_payload) },
+      #     context: 'generate_outline'
+      #   ) { bedrock_client.invoke_model(payload) }
+      #
+      #   # Streaming (`bedrock_client.invoke_model_with_response_stream`)
+      #   PlatformSdk::Observability::Langfuse::BedrockClaudeAdapter.with_streaming_observability(
+      #     payload: { model_id: ..., body: JSON.dump(...) },
+      #     context: 'chat_stream'
+      #   ) do |collector|
+      #     bedrock_client.invoke_model_with_response_stream(
+      #       payload.merge(event_stream_handler: proc do |stream|
+      #         stream.on_chunk_event do |event|
+      #           collector.observe(event)
+      #           # ...the caller's own chunk handling
+      #         end
+      #       end)
+      #     )
+      #   end
+      #
+      # The streaming collector accumulates text from `content_block_delta`
+      # events and pulls the final `input_tokens`/`output_tokens` from the
+      # `message_stop` event's `amazon-bedrock-invocationMetrics`. The
+      # notification fires once after the block returns.
+      #
+      # No hard dependency on the AWS SDK — this adapter only reads the
+      # documented JSON shape of Anthropic's Messages API on Bedrock.
+      module BedrockClaudeAdapter
+        class << self
+          def with_observability(payload:, context:)
+            response = yield
+            fire(payload:, response:, context:)
+            response
+          rescue StandardError => e
+            fire(payload:, response: nil, context:, error: e)
+            raise
+          end
+
+          def with_streaming_observability(payload:, context:)
+            collector = StreamCollector.new
+            result = yield collector
+            fire_from_collector(payload:, collector:, context:)
+            result
+          rescue StandardError => e
+            fire_from_collector(payload:, collector:, context:, error: e)
+            raise
+          end
+
+          # After-the-fact emission for non-streaming calls. Caller can use
+          # this if they want to invoke Bedrock outside of the block helper
+          # and emit observability separately.
+          def fire(payload:, response:, context:, error: nil)
+            attrs = decode_response(response)
+            notify(payload:, output: attrs[:output], usage: attrs[:usage], context:, error:)
+          rescue StandardError => e
+            OpenTelemetry.handle_error(
+              message: "BedrockClaudeAdapter.fire failed: #{e.class}: #{e.message[0, 200]}"
+            )
+            nil
+          end
+
+          private
+
+          def fire_from_collector(payload:, collector:, context:, error: nil)
+            usage = collector.usage
+            notify(
+              payload:,
+              output: collector.text.empty? ? nil : collector.text,
+              usage: usage.values.any? ? usage : {},
+              context:,
+              error:
+            )
+          end
+
+          def notify(payload:, output:, usage:, context:, error:)
+            built = build_payload(payload:, output:, usage:, context:, error:)
+            return unless built
+
+            ActiveSupport::Notifications.instrument(LLM_CALL_EVENT, built)
+          rescue StandardError => e
+            OpenTelemetry.handle_error(
+              message: "BedrockClaudeAdapter.fire failed: #{e.class}: #{e.message[0, 200]}"
+            )
+            nil
+          end
+
+          def build_payload(payload:, output:, usage:, context:, error:)
+            return nil unless Langfuse.enabled?
+
+            # Tolerate non-Hash payloads (some callers pass `to_json`'d strings
+            # in tests) — extract only when the shape is what we expect.
+            payload = payload.is_a?(Hash) ? payload : {}
+            body = decode_body(payload[:body] || payload['body'])
+
+            {
+              name: context || 'llm_call',
+              model: payload[:model_id] || payload['model_id'] || body[:model] || body['model'],
+              input: body[:messages] || body['messages'],
+              output:,
+              usage: usage || {},
+              provider: 'aws.bedrock',
+              error:
+            }
+          end
+
+          def decode_body(body)
+            return body if body.is_a?(Hash)
+            return {} if body.nil?
+
+            JSON.parse(body.to_s)
+          rescue JSON::ParserError
+            {}
+          end
+
+          # Pulls `output` (concatenated text from content blocks) and `usage`
+          # (`input_tokens`/`output_tokens`) from a non-streaming Anthropic
+          # Messages-on-Bedrock response. Tolerant of both `response.body`
+          # (AWS SDK Seahorse) and plain Hash shapes for ease of testing.
+          def decode_response(response)
+            return { output: nil, usage: {} } if response.nil?
+
+            body = response.respond_to?(:body) ? response.body : response
+            # Rewind after read so the caller can re-read response.body
+            # downstream — Bedrock's Seahorse response wraps a StringIO that
+            # would otherwise be consumed by our instrumentation.
+            if body.respond_to?(:read)
+              raw = body.read
+              body.rewind if body.respond_to?(:rewind)
+              body = raw
+            end
+            parsed = body.is_a?(Hash) ? body : safe_parse_json(body.to_s)
+
+            { output: extract_text(parsed), usage: extract_usage(parsed) }
+          end
+
+          def safe_parse_json(str)
+            JSON.parse(str)
+          rescue JSON::ParserError
+            {}
+          end
+
+          def extract_text(parsed)
+            content = parsed['content'] || parsed[:content]
+            return nil unless content.is_a?(Array)
+
+            content.filter_map { |block| block['text'] || block[:text] }.join
+          end
+
+          def extract_usage(parsed)
+            usage = parsed['usage'] || parsed[:usage] || {}
+            {
+              input_tokens: usage['input_tokens'] || usage[:input_tokens],
+              output_tokens: usage['output_tokens'] || usage[:output_tokens]
+            }
+          end
+        end
+
+        # Accumulates streaming-response state so the adapter can emit a
+        # single observation after the stream ends.
+        #
+        # Bedrock's invoke_model_with_response_stream yields events whose
+        # `bytes` is JSON. For Anthropic on Bedrock the relevant event types
+        # are:
+        #
+        # * `content_block_delta` — incremental text in `delta.text`
+        # * `message_delta` — top-level `usage.output_tokens` (final count)
+        # * `message_stop` — Bedrock adds `amazon-bedrock-invocationMetrics`
+        #   here with `inputTokenCount` and `outputTokenCount`
+        #
+        # Both message_delta and message_stop are emitted on success; we
+        # prefer message_stop's metrics when both are present.
+        class StreamCollector
+          attr_reader :text
+
+          def initialize
+            @text = +''
+            @input_tokens = nil
+            @output_tokens = nil
+          end
+
+          def usage
+            { input_tokens: @input_tokens, output_tokens: @output_tokens }
+          end
+
+          def observe(event)
+            parsed = parse_event(event)
+            return if parsed.nil?
+
+            case parsed['type']
+            when 'message_start'
+              # Anthropic emits initial input_tokens here. Used as a
+              # fallback when Bedrock's message_stop invocationMetrics
+              # are absent (future models, guardrail truncations, etc.).
+              start_usage = parsed.dig('message', 'usage') || {}
+              @input_tokens ||= start_usage['input_tokens']
+            when 'content_block_delta'
+              delta_text = parsed.dig('delta', 'text')
+              @text << delta_text if delta_text
+            when 'message_delta'
+              # message_delta usage is cumulative across the (possibly many)
+              # message_delta events Anthropic emits, so the latest value
+              # wins. See https://docs.anthropic.com/en/api/messages-streaming
+              usage = parsed['usage'] || {}
+              @output_tokens = usage['output_tokens'] if usage['output_tokens']
+            when 'message_stop'
+              metrics = parsed['amazon-bedrock-invocationMetrics'] || {}
+              @input_tokens = metrics['inputTokenCount'] if metrics['inputTokenCount']
+              @output_tokens = metrics['outputTokenCount'] if metrics['outputTokenCount']
+            end
+          rescue StandardError => e
+            OpenTelemetry.handle_error(
+              message: "BedrockClaudeAdapter::StreamCollector#observe failed: #{e.class}: #{e.message[0, 200]}"
+            )
+          end
+
+          private
+
+          def parse_event(event)
+            bytes = event.respond_to?(:bytes) ? event.bytes : event
+            return nil if bytes.nil?
+
+            JSON.parse(bytes.to_s)
+          rescue JSON::ParserError
+            nil
+          end
+        end
+      end
+    end
+  end
+end

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/openai_adapter.rb

@@ -0,0 +1,87 @@
+# 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 `ruby-openai` chat call. Apps that hit
+      # OpenAI's chat completions API directly (rather than via RubyLLM) call
+      # `with_observability` to get cost, tokens, model, input, and output
+      # captured in Langfuse:
+      #
+      #   PlatformSdk::Observability::Langfuse::OpenAIAdapter.with_observability(
+      #     parameters: { model: 'gpt-4o', messages: [...], ... },
+      #     context: 'amend_json'
+      #   ) do
+      #     OpenAI::Client.new.chat(parameters: parameters)
+      #   end
+      #
+      # The block runs the actual LLM call and its return value is forwarded
+      # back to the caller. On success a generation observation is recorded
+      # with model/usage from the response. On raise a failure observation
+      # is recorded and the exception is re-raised unchanged.
+      #
+      # No hard dependency on the `ruby-openai` gem — this adapter only
+      # touches the plain-Hash response shape OpenAI's API returns.
+      module OpenAIAdapter
+        class << self
+          # Wrap an `OpenAI::Client#chat` call. Forwards the block's return
+          # value. On success: fires success notification with model/input/
+          # output/usage extracted from `parameters` and the returned response.
+          # On raise: fires failure notification with `error:` set, re-raises.
+          def with_observability(parameters:, context:)
+            response = yield
+            fire(parameters:, response:, context:)
+            response
+          rescue StandardError => e
+            fire(parameters:, response: nil, context:, error: e)
+            raise
+          end
+
+          # Fire a single `llm_call.platform_sdk` notification. Useful when
+          # the caller has already invoked OpenAI and just wants to record
+          # the observation after the fact.
+          def fire(parameters:, response:, context:, error: nil)
+            payload = build_payload(parameters:, response:, context:, error:)
+            return unless payload
+
+            ActiveSupport::Notifications.instrument(LLM_CALL_EVENT, payload)
+          rescue StandardError => e
+            OpenTelemetry.handle_error(
+              message: "OpenAIAdapter.fire failed: #{e.class}: #{e.message[0, 200]}"
+            )
+            nil
+          end
+
+          private
+
+          def build_payload(parameters:, response:, context:, error:)
+            return nil unless Langfuse.enabled?
+
+            parameters ||= {}
+            choice = response.is_a?(Hash) ? response.dig('choices', 0, 'message') : nil
+            usage = response.is_a?(Hash) ? response['usage'] : nil
+
+            {
+              name: context || 'llm_call',
+              model: parameters[:model] || parameters['model'],
+              input: parameters[:messages] || parameters['messages'],
+              output: choice && choice['content'],
+              # ruby-openai responses use prompt_tokens / completion_tokens; the
+              # input_tokens / output_tokens fallbacks cover OpenAI-compatible
+              # proxies and any future rename of those fields.
+              usage: {
+                input_tokens: usage && (usage['prompt_tokens'] || usage['input_tokens']),
+                output_tokens: usage && (usage['completion_tokens'] || usage['output_tokens'])
+              },
+              provider: 'openai',
+              error:
+            }
+          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,31 @@
 # 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'
+require 'platform_sdk/observability/langfuse/openai_adapter'
+require 'platform_sdk/observability/langfuse/bedrock_claude_adapter'
 
 module PlatformSdk
   module Observability
@@ -13,20 +33,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 +102,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 = 30
   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.30.0
 platform: ruby
 authors:
 - Platform Team
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2026-05-11 00:00:00.000000000 Z
+date: 2026-05-15 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: faraday
@@ -316,12 +316,17 @@ files:
 - lib/platform_sdk/logging/pii_formatter.rb
 - lib/platform_sdk/observability.rb
 - lib/platform_sdk/observability/langfuse.rb
+- lib/platform_sdk/observability/langfuse/bedrock_claude_adapter.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/openai_adapter.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