braintrust 0.0.12 → 0.1.0

data/lib/braintrust/contrib/openai/patcher.rb

@@ -0,0 +1,130 @@
+# frozen_string_literal: true
+
+require_relative "../patcher"
+require_relative "instrumentation/chat"
+require_relative "instrumentation/responses"
+
+module Braintrust
+  module Contrib
+    module OpenAI
+      # Patcher for OpenAI integration - implements class-level patching.
+      # All new OpenAI::Client instances created after patch! will be automatically instrumented.
+      class ChatPatcher < Braintrust::Contrib::Patcher
+        class << self
+          def applicable?
+            defined?(::OpenAI::Client)
+          end
+
+          def patched?(**options)
+            # Use the target's singleton class if provided, otherwise check the base class.
+            target_class = get_singleton_class(options[:target]) || ::OpenAI::Resources::Chat::Completions
+
+            Instrumentation::Chat::Completions.applied?(target_class)
+          end
+
+          # Perform the actual patching.
+          # @param options [Hash] Configuration options passed from integration
+          # @option options [Object] :target Optional target instance to patch
+          # @option options [OpenTelemetry::SDK::Trace::TracerProvider] :tracer_provider Optional tracer provider
+          # @return [void]
+          def perform_patch(**options)
+            return unless applicable?
+
+            # Stream classes are shared across all clients, patch at class level.
+            # The instrumentation short-circuits when no context is present,
+            # so uninstrumented clients' streams pass through unaffected.
+            patch_stream_classes
+
+            if options[:target]
+              # Instance-level (for only this client)
+              raise ArgumentError, "target must be a kind of ::OpenAI::Client" unless options[:target].is_a?(::OpenAI::Client)
+
+              get_singleton_class(options[:target]).include(Instrumentation::Chat::Completions)
+            else
+              # Class-level (for all clients)
+              ::OpenAI::Resources::Chat::Completions.include(Instrumentation::Chat::Completions)
+            end
+          end
+
+          def patch_stream_classes
+            # Patch ChatCompletionStream for stream() method
+            if defined?(::OpenAI::Helpers::Streaming::ChatCompletionStream)
+              unless Instrumentation::Chat::ChatCompletionStream.applied?(::OpenAI::Helpers::Streaming::ChatCompletionStream)
+                ::OpenAI::Helpers::Streaming::ChatCompletionStream.include(Instrumentation::Chat::ChatCompletionStream)
+              end
+            end
+
+            # Patch Internal::Stream for stream_raw() method
+            if defined?(::OpenAI::Internal::Stream)
+              unless Instrumentation::Chat::InternalStream.applied?(::OpenAI::Internal::Stream)
+                ::OpenAI::Internal::Stream.include(Instrumentation::Chat::InternalStream)
+              end
+            end
+          end
+
+          private
+
+          def get_singleton_class(client)
+            client&.chat&.completions&.singleton_class
+          end
+        end
+      end
+
+      # Patcher for OpenAI integration - implements class-level patching.
+      # All new OpenAI::Client instances created after patch! will be automatically instrumented.
+      class ResponsesPatcher < Braintrust::Contrib::Patcher
+        class << self
+          def applicable?
+            defined?(::OpenAI::Client) && ::OpenAI::Client.instance_methods.include?(:responses)
+          end
+
+          def patched?(**options)
+            # Use the target's singleton class if provided, otherwise check the base class.
+            target_class = get_singleton_class(options[:target]) || ::OpenAI::Resources::Responses
+
+            Instrumentation::Responses.applied?(target_class)
+          end
+
+          # Perform the actual patching.
+          # @param options [Hash] Configuration options passed from integration
+          # @option options [Object] :target Optional target instance to patch
+          # @option options [OpenTelemetry::SDK::Trace::TracerProvider] :tracer_provider Optional tracer provider
+          # @return [void]
+          def perform_patch(**options)
+            return unless applicable?
+
+            # Stream class is shared across all clients, patch at class level.
+            # The instrumentation short-circuits when no context is present,
+            # so uninstrumented clients' streams pass through unaffected.
+            patch_response_stream
+
+            if options[:target]
+              # Instance-level (for only this client)
+              raise ArgumentError, "target must be a kind of ::OpenAI::Client" unless options[:target].is_a?(::OpenAI::Client)
+
+              get_singleton_class(options[:target]).include(Instrumentation::Responses)
+            else
+              # Class-level (for all clients)
+              ::OpenAI::Resources::Responses.include(Instrumentation::Responses)
+            end
+          end
+
+          def patch_response_stream
+            # Patch ResponseStream for stream() method
+            if defined?(::OpenAI::Helpers::Streaming::ResponseStream)
+              unless Instrumentation::ResponseStream.applied?(::OpenAI::Helpers::Streaming::ResponseStream)
+                ::OpenAI::Helpers::Streaming::ResponseStream.include(Instrumentation::ResponseStream)
+              end
+            end
+          end
+
+          private
+
+          def get_singleton_class(client)
+            client&.responses&.singleton_class
+          end
+        end
+      end
+    end
+  end
+end

data/lib/braintrust/contrib/patcher.rb

@@ -0,0 +1,76 @@
+# frozen_string_literal: true
+
+module Braintrust
+  module Contrib
+    # Base class for all patchers.
+    # Provides thread-safe, idempotent patching with error handling.
+    class Patcher
+      # For thread-safety, a mutex is used to wrap patching.
+      # Each instance of Patcher should have its own copy of the mutex.,
+      # allowing each Patcher to work in parallel while protecting the
+      # critical patch section.
+      @patch_mutex = Mutex.new
+
+      def self.inherited(subclass)
+        subclass.instance_variable_set(:@patch_mutex, Mutex.new)
+      end
+
+      class << self
+        # Has this patcher already been applied?
+        # @return [Boolean]
+        def patched?(**options)
+          @patched == true
+        end
+
+        # Override in subclasses to check if patcher should apply.
+        # Called after patcher loads but before perform_patch.
+        # @return [Boolean] true if this patcher should be applied
+        def applicable?
+          true # Default: always applicable
+        end
+
+        # Apply the patch (thread-safe and idempotent).
+        # @param options [Hash] Configuration options passed from integration
+        # @option options [Object] :target Optional target instance to patch
+        # @option options [OpenTelemetry::SDK::Trace::TracerProvider] :tracer_provider Optional tracer provider
+        # @return [Boolean] true if patching succeeded or was already done
+        def patch!(**options)
+          return false unless applicable?
+          return true if patched?(**options) # Fast path
+
+          @patch_mutex.synchronize do
+            unless applicable?
+              Braintrust::Log.debug("Skipping #{name} - not applicable")
+              return false
+            end
+            return true if patched?(**options) # Double-check under lock
+
+            perform_patch(**options)
+            @patched = true
+          end
+          Braintrust::Log.debug("Patched #{name}")
+          true
+        rescue => e
+          Braintrust::Log.error("Failed to patch #{name}: #{e.message}")
+          false
+        end
+
+        # Subclasses implement this to perform the actual patching.
+        # This method is called under lock after applicable? returns true.
+        #
+        # @param options [Hash] Configuration options passed from integration
+        # @option options [Object] :target Optional target instance to patch
+        # @option options [OpenTelemetry::SDK::Trace::TracerProvider] :tracer_provider Optional tracer provider
+        # @return [void]
+        def perform_patch(**options)
+          raise NotImplementedError, "#{self} must implement perform_patch"
+        end
+
+        # Reset patched state (primarily for testing).
+        def reset!
+          @patched = false
+        end
+      end
+    end
+  end
+end

data/lib/braintrust/contrib/rails/railtie.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+module Braintrust
+  module Contrib
+    module Rails
+      class Railtie < ::Rails::Railtie
+        config.after_initialize do
+          Braintrust.auto_instrument!(
+            only: Braintrust::Internal::Env.instrument_only,
+            except: Braintrust::Internal::Env.instrument_except
+          )
+        end
+      end
+    end
+  end
+end

data/lib/braintrust/contrib/registry.rb

@@ -0,0 +1,107 @@
+# frozen_string_literal: true
+
+require "singleton"
+
+module Braintrust
+  module Contrib
+    # Thread-safe singleton registry for integrations.
+    # Provides registration, lookup, and require-path mapping for auto-instrumentation.
+    class Registry
+      include Singleton
+
+      def initialize
+        @integrations = {}
+        @require_path_map = nil # Lazy cache
+        @mutex = Mutex.new
+      end
+
+      # Register an integration class with the registry.
+      # @param integration_class [Class] The integration class to register
+      def register(integration_class)
+        @mutex.synchronize do
+          @integrations[integration_class.integration_name] = integration_class
+          @require_path_map = nil # Invalidate cache
+        end
+      end
+
+      # Look up an integration by name.
+      # @param name [Symbol, String] The integration name
+      # @return [Class, nil] The integration class, or nil if not found
+      def [](name)
+        @integrations[name.to_sym]
+      end
+
+      # Get all registered integrations.
+      # @return [Array<Class>] All registered integration classes
+      def all
+        @integrations.values
+      end
+
+      # Get all available integrations (target library is loaded).
+      # @return [Array<Class>] Available integration classes
+      def available
+        @integrations.values.select(&:available?)
+      end
+
+      # Iterate over all registered integrations.
+      # @yield [Class] Each registered integration class
+      def each(&block)
+        @integrations.values.each(&block)
+      end
+
+      # Returns integrations associated with a require path.
+      # Thread-safe with double-checked locking for performance.
+      # @param path [String] The require path (e.g., "openai", "anthropic")
+      # @return [Array<Class>] Integrations matching the require path
+      def integrations_for_require_path(path)
+        map = @require_path_map
+        if map.nil?
+          map = @mutex.synchronize do
+            @require_path_map ||= build_require_path_map
+          end
+        end
+
+        path_str = path.to_s
+        basename = File.basename(path_str, ".rb")
+
+        # Quick check: is this basename even in our map?
+        return EMPTY_ARRAY unless map.key?(basename)
+
+        # Only match top-level requires or gem entry points.
+        # Avoid matching internal subpaths (e.g., ruby_llm/providers/anthropic).
+        return EMPTY_ARRAY unless gem_entry_point?(path_str, basename)
+
+        map.fetch(basename, EMPTY_ARRAY)
+      end
+
+      private
+
+      EMPTY_ARRAY = [].freeze
+
+      # Check if this is a gem entry point require.
+      # @param path [String] Full require path
+      # @param basename [String] File basename without extension
+      # @return [Boolean]
+      def gem_entry_point?(path, basename)
+        # Direct require like `require 'anthropic'` - no directory separators
+        return true unless path.include?("/")
+
+        # Full path to gem entry point: /gems/anthropic-1.0.0/lib/anthropic.rb
+        # The basename appears in both the gem directory name AND as the final file
+        path.match?(%r{/#{Regexp.escape(basename)}[^/]*/lib/#{Regexp.escape(basename)}(\.rb)?$})
+      end
+
+      def build_require_path_map
+        map = {}
+        @integrations.each_value do |integration|
+          integration.require_paths.each do |req|
+            map[req] ||= []
+            map[req] << integration
+          end
+        end
+        map.each_value(&:freeze)
+        map.freeze
+      end
+    end
+  end
+end

data/lib/braintrust/contrib/ruby_llm/deprecated.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+# Backward compatibility shim for the old ruby_llm integration API.
+# This file now just delegates to the new API.
+
+module Braintrust
+  module Trace
+    module Contrib
+      module Github
+        module Crmne
+          module RubyLLM
+            # Wrap RubyLLM to automatically create spans for chat requests.
+            # This is the legacy API - delegates to the new contrib framework.
+            #
+            # @param chat [RubyLLM::Chat, nil] the chat instance to wrap (if nil, wraps the class)
+            # @param tracer_provider [OpenTelemetry::SDK::Trace::TracerProvider] the tracer provider
+            # @return [RubyLLM::Chat, nil] the wrapped chat instance
+            def self.wrap(chat = nil, tracer_provider: nil)
+              Log.warn("Braintrust::Trace::Contrib::Github::Crmne::RubyLLM.wrap() is deprecated and will be removed in a future version: use Braintrust.instrument!() instead.")
+              Braintrust.instrument!(:ruby_llm, target: chat, tracer_provider: tracer_provider)
+              chat
+            end
+
+            # Unwrap RubyLLM to disable Braintrust tracing.
+            # This is the legacy API - uses the Context pattern to disable tracing.
+            #
+            # Note: Prepended modules cannot be truly removed in Ruby.
+            # This method sets `enabled: false` in the Context, which the
+            # instrumentation checks before creating spans.
+            #
+            # @param chat [RubyLLM::Chat, nil] the chat instance to unwrap (if nil, unwraps the class)
+            # @return [RubyLLM::Chat, nil] the chat instance
+            def self.unwrap(chat = nil)
+              Log.warn("Braintrust::Trace::Contrib::Github::Crmne::RubyLLM.unwrap() is deprecated and will be removed in a future version.")
+
+              target = chat || ::RubyLLM::Chat
+              Braintrust::Contrib::Context.set!(target, enabled: false)
+              chat
+            end
+          end
+        end
+      end
+    end
+  end
+end