braintrust 0.1.0 → 0.1.2

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

@@ -3,6 +3,7 @@
 require_relative "../patcher"
 require_relative "instrumentation/chat"
 require_relative "instrumentation/responses"
+require_relative "instrumentation/moderations"
 
 module Braintrust
   module Contrib
@@ -80,6 +81,40 @@ module Braintrust
           end
         end
       end
+
+      # Patcher for ruby-openai moderations API.
+      # Instruments OpenAI::Client#moderations method.
+      class ModerationsPatcher < Braintrust::Contrib::Patcher
+        class << self
+          def applicable?
+            defined?(::OpenAI::Client) && ::OpenAI::Client.method_defined?(:moderations)
+          end
+
+          def patched?(**options)
+            target_class = options[:target]&.singleton_class || ::OpenAI::Client
+            Instrumentation::Moderations.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?
+
+            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)
+
+              options[:target].singleton_class.include(Instrumentation::Moderations)
+            else
+              # Class-level (for all clients)
+              ::OpenAI::Client.include(Instrumentation::Moderations)
+            end
+          end
+        end
+      end
     end
   end
 end

data/lib/braintrust/internal/env.rb

@@ -7,11 +7,17 @@ module Braintrust
       ENV_AUTO_INSTRUMENT = "BRAINTRUST_AUTO_INSTRUMENT"
       ENV_INSTRUMENT_EXCEPT = "BRAINTRUST_INSTRUMENT_EXCEPT"
       ENV_INSTRUMENT_ONLY = "BRAINTRUST_INSTRUMENT_ONLY"
+      ENV_FLUSH_ON_EXIT = "BRAINTRUST_FLUSH_ON_EXIT"
 
       def self.auto_instrument
         ENV[ENV_AUTO_INSTRUMENT] != "false"
       end
 
+      # Whether to automatically flush spans on program exit. Default: true
+      def self.flush_on_exit
+        ENV[ENV_FLUSH_ON_EXIT] != "false"
+      end
+
       def self.instrument_except
         parse_list(ENV_INSTRUMENT_EXCEPT)
       end

data/lib/braintrust/internal/template.rb

@@ -0,0 +1,91 @@
+# frozen_string_literal: true
+
+require_relative "../vendor/mustache"
+
+module Braintrust
+  module Internal
+    # Template rendering utilities for Mustache templates
+    module Template
+      module_function
+
+      # Render a template string with variable substitution
+      #
+      # @param text [String] Template text to render
+      # @param variables [Hash] Variables to substitute
+      # @param format [String] Template format: "mustache", "none", or "nunjucks"
+      # @param strict [Boolean] Raise error on missing variables (default: false)
+      # @return [String] Rendered text
+      def render(text, variables, format:, strict: false)
+        return text unless text.is_a?(String)
+
+        case format
+        when "none"
+          # No templating - return text unchanged
+          text
+        when "nunjucks"
+          # Nunjucks is a UI-only feature in Braintrust
+          raise Error, "Nunjucks templates are not supported in the Ruby SDK. " \
+                       "Nunjucks only works in Braintrust playgrounds. " \
+                       "Please use 'mustache' or 'none' template format, or invoke the prompt via the API proxy."
+        when "mustache", "", nil
+          # Default: Mustache templating
+          if strict
+            missing = find_missing_variables(text, variables)
+            if missing.any?
+              raise Error, "Missing required variables: #{missing.join(", ")}"
+            end
+          end
+
+          Vendor::Mustache.render(text, variables)
+        else
+          raise Error, "Unknown template format: #{format.inspect}. " \
+                       "Supported formats are 'mustache' and 'none'."
+        end
+      end
+
+      # Find Mustache variables in template that are not provided
+      #
+      # @param text [String] Template text
+      # @param variables [Hash] Available variables
+      # @return [Array<String>] List of missing variable names
+      def find_missing_variables(text, variables)
+        # Extract {{variable}} and {{variable.path}} patterns
+        # Mustache uses {{name}} syntax
+        text.scan(/\{\{([^}#^\/!>]+)\}\}/).flatten.map(&:strip).uniq.reject do |var|
+          resolve_variable(var, variables)
+        end
+      end
+
+      # Check if a variable path exists in a hash
+      #
+      # @param path [String] Dot-separated variable path (e.g., "user.name")
+      # @param variables [Hash] Variables to search
+      # @return [Object, nil] The value if found, nil otherwise
+      def resolve_variable(path, variables)
+        parts = path.split(".")
+        value = variables
+
+        parts.each do |part|
+          return nil unless value.is_a?(Hash)
+          # Try both string and symbol keys
+          value = value[part] || value[part.to_sym]
+          return nil if value.nil?
+        end
+
+        value
+      end
+
+      # Convert hash keys to strings recursively
+      #
+      # @param hash [Hash] Hash with symbol or string keys
+      # @return [Hash] Hash with all string keys
+      def stringify_keys(hash)
+        return {} unless hash.is_a?(Hash)
+
+        hash.transform_keys(&:to_s).transform_values do |v|
+          v.is_a?(Hash) ? stringify_keys(v) : v
+        end
+      end
+    end
+  end
+end

data/lib/braintrust/prompt.rb

@@ -0,0 +1,143 @@
+# frozen_string_literal: true
+
+require "json"
+require_relative "internal/template"
+
+module Braintrust
+  # Prompt class for loading and building prompts from Braintrust
+  #
+  # @example Load and use a prompt
+  #   prompt = Braintrust::Prompt.load(project: "my-project", slug: "summarizer")
+  #   params = prompt.build(text: "Article to summarize...")
+  #   client.messages.create(**params)
+  class Prompt
+    attr_reader :id, :name, :slug, :project_id
+
+    # Load a prompt from Braintrust
+    #
+    # @param project [String] Project name
+    # @param slug [String] Prompt slug
+    # @param version [String, nil] Specific version (default: latest)
+    # @param defaults [Hash] Default variable values for build()
+    # @param api [API, nil] Braintrust API client (default: creates one using global state)
+    # @return [Prompt]
+    def self.load(project:, slug:, version: nil, defaults: {}, api: nil)
+      api ||= API.new
+
+      # Find the function by project + slug
+      result = api.functions.list(project_name: project, slug: slug)
+      function = result.dig("objects")&.first
+      raise Error, "Prompt '#{slug}' not found in project '#{project}'" unless function
+
+      # Fetch full function data including prompt_data
+      full_data = api.functions.get(id: function["id"], version: version)
+
+      new(full_data, defaults: defaults)
+    end
+
+    # Initialize a Prompt from function data
+    #
+    # @param data [Hash] Function data from API
+    # @param defaults [Hash] Default variable values for build()
+    def initialize(data, defaults: {})
+      @data = data
+      @defaults = Internal::Template.stringify_keys(defaults)
+
+      @id = data["id"]
+      @name = data["name"]
+      @slug = data["slug"]
+      @project_id = data["project_id"]
+    end
+
+    # Get the raw prompt definition
+    # @return [Hash, nil]
+    def prompt
+      @data.dig("prompt_data", "prompt")
+    end
+
+    # Get the prompt messages
+    # @return [Array<Hash>]
+    def messages
+      prompt&.dig("messages") || []
+    end
+
+    # Get the tools definition (parsed from JSON string)
+    # @return [Array<Hash>, nil]
+    def tools
+      tools_json = prompt&.dig("tools")
+      return nil unless tools_json.is_a?(String) && !tools_json.empty?
+
+      JSON.parse(tools_json)
+    rescue JSON::ParserError
+      nil
+    end
+
+    # Get the model name
+    # @return [String, nil]
+    def model
+      @data.dig("prompt_data", "options", "model")
+    end
+
+    # Get model options
+    # @return [Hash]
+    def options
+      @data.dig("prompt_data", "options") || {}
+    end
+
+    # Get the template format
+    # @return [String] "mustache" (default), "nunjucks", or "none"
+    def template_format
+      @data.dig("prompt_data", "template_format") || "mustache"
+    end
+
+    # Build the prompt with variable substitution
+    #
+    # Returns a hash ready to pass to an LLM client:
+    #   {model: "...", messages: [...], temperature: ..., ...}
+    #
+    # @param variables [Hash] Variables to substitute (e.g., {name: "Alice"})
+    # @param strict [Boolean] Raise error on missing variables (default: false)
+    # @return [Hash] Built prompt ready for LLM client
+    #
+    # @example With keyword arguments
+    #   prompt.build(name: "Alice", task: "coding")
+    #
+    # @example With explicit hash
+    #   prompt.build({name: "Alice"}, strict: true)
+    def build(variables = nil, strict: false, **kwargs)
+      # Support both explicit hash and keyword arguments
+      variables_hash = variables.is_a?(Hash) ? variables : {}
+      vars = @defaults
+        .merge(Internal::Template.stringify_keys(variables_hash))
+        .merge(Internal::Template.stringify_keys(kwargs))
+
+      # Render Mustache templates in messages
+      built_messages = messages.map do |msg|
+        {
+          role: msg["role"].to_sym,
+          content: Internal::Template.render(msg["content"], vars, format: template_format, strict: strict)
+        }
+      end
+
+      # Build result with model and messages
+      result = {
+        model: model,
+        messages: built_messages
+      }
+
+      # Add tools if defined
+      parsed_tools = tools
+      result[:tools] = parsed_tools if parsed_tools
+
+      # Add params (temperature, max_tokens, etc.) to top level
+      params = options.dig("params")
+      if params.is_a?(Hash)
+        params.each do |key, value|
+          result[key.to_sym] = value
+        end
+      end
+
+      result
+    end
+  end
+end

data/lib/braintrust/state.rb

@@ -73,7 +73,7 @@ module Braintrust
       @org_id = org_id
       @default_project = default_project
       @app_url = app_url || "https://www.braintrust.dev"
-      @api_url = api_url
+      @api_url = api_url || "https://api.braintrust.dev"
       @proxy_url = proxy_url
       @config = config
 

data/lib/braintrust/trace.rb

@@ -4,10 +4,18 @@ require "opentelemetry/sdk"
 require "opentelemetry/exporter/otlp"
 require_relative "trace/span_processor"
 require_relative "trace/span_filter"
+require_relative "internal/env"
 require_relative "logger"
 
 module Braintrust
   module Trace
+    # Track whether the at_exit hook has been registered
+    @exit_hook_registered = false
+
+    class << self
+      attr_accessor :exit_hook_registered
+    end
+
     # Set up OpenTelemetry tracing with Braintrust
     # @param state [State] Braintrust state
     # @param tracer_provider [TracerProvider, nil] Optional tracer provider
@@ -32,6 +40,9 @@ module Braintrust
           OpenTelemetry.tracer_provider = tracer_provider
           Log.debug("Created OpenTelemetry tracer provider")
         end
+
+        # Register at_exit hook for global provider (only once)
+        register_exit_hook
       end
 
       # Enable Braintrust tracing (adds span processor)
@@ -39,6 +50,36 @@ module Braintrust
       enable(tracer_provider, state: state, config: config, exporter: exporter)
     end
 
+    # Register an at_exit hook to flush spans before program exit.
+    # This ensures buffered spans in BatchSpanProcessor are exported.
+    # Only registers once, and only for the global tracer provider.
+    # Controlled by BRAINTRUST_FLUSH_ON_EXIT env var (default: true).
+    def self.register_exit_hook
+      return if @exit_hook_registered
+      return unless Internal::Env.flush_on_exit
+
+      @exit_hook_registered = true
+      at_exit { flush_spans }
+      Log.debug("Registered at_exit hook for span flushing")
+    end
+
+    # Flush buffered spans from the global tracer provider.
+    # Forces immediate export of any spans buffered by BatchSpanProcessor.
+    # @return [Boolean] true if flush succeeded, false otherwise
+    def self.flush_spans
+      provider = OpenTelemetry.tracer_provider
+      return false unless provider.respond_to?(:force_flush)
+
+      Log.debug("Flushing spans")
+      begin
+        provider.force_flush
+        true
+      rescue => e
+        Log.debug("Failed to flush spans: #{e.message}")
+        false
+      end
+    end
+
     def self.enable(tracer_provider, state: nil, exporter: nil, config: nil)
       state ||= Braintrust.current_state
       raise Error, "No state available" unless state

data/lib/braintrust/vendor/mustache/context.rb

@@ -0,0 +1,180 @@
+# frozen_string_literal: true
+
+# Vendored from mustache gem v1.1.1
+# https://github.com/mustache/mustache
+# License: MIT
+# Modifications: Namespaced under Braintrust::Vendor
+
+require_relative "context_miss"
+
+module Braintrust
+  module Vendor
+    class Mustache
+      # A Context represents the context which a Mustache template is
+      # executed within. All Mustache tags reference keys in the Context.
+      class Context
+        # Initializes a Mustache::Context.
+        #
+        # @param [Mustache] mustache A Mustache instance.
+        #
+        def initialize(mustache)
+          @stack = [mustache]
+          @partial_template_cache = {}
+        end
+
+        # A {{>partial}} tag translates into a call to the context's
+        # `partial` method, which would be this sucker right here.
+        #
+        # If the Mustache view handling the rendering (e.g. the view
+        # representing your profile page or some other template) responds
+        # to `partial`, we call it and render the result.
+        #
+        def partial(name, indentation = "")
+          # Look for the first Mustache in the stack.
+          mustache = mustache_in_stack
+
+          # Indent the partial template by the given indentation.
+          part = mustache.partial(name).to_s.gsub(/^/, indentation)
+
+          # Get a template object for the partial and render the result.
+          template_for_partial(part).render(self)
+        end
+
+        def template_for_partial(partial)
+          @partial_template_cache[partial] ||= Template.new(partial)
+        end
+
+        # Find the first Mustache in the stack.
+        #
+        # If we're being rendered inside a Mustache object as a context,
+        # we'll use that one.
+        #
+        # @return [Mustache] First Mustache in the stack.
+        #
+        def mustache_in_stack
+          @mustache_in_stack ||= @stack.find { |frame| frame.is_a?(Mustache) }
+        end
+
+        # Allows customization of how Mustache escapes things.
+        #
+        # @param [Object] value Value to escape.
+        #
+        # @return [String] Escaped string.
+        #
+        def escape(value)
+          mustache_in_stack.escape(value)
+        end
+
+        # Adds a new object to the context's internal stack.
+        #
+        # @param [Object] new_obj Object to be added to the internal stack.
+        #
+        # @return [Context] Returns the Context.
+        #
+        def push(new_obj)
+          @stack.unshift(new_obj)
+          @mustache_in_stack = nil
+          self
+        end
+
+        # Removes the most recently added object from the context's
+        # internal stack.
+        #
+        # @return [Context] Returns the Context.
+        #
+        def pop
+          @stack.shift
+          @mustache_in_stack = nil
+          self
+        end
+
+        # Can be used to add a value to the context in a hash-like way.
+        #
+        # context[:name] = "Chris"
+        def []=(name, value)
+          push(name => value)
+        end
+
+        # Alias for `fetch`.
+        def [](name)
+          fetch(name, nil)
+        end
+
+        # Do we know about a particular key? In other words, will calling
+        # `context[key]` give us a result that was set. Basically.
+        def has_key?(key)
+          fetch(key, false)
+        rescue ContextMiss
+          false
+        end
+
+        # Similar to Hash#fetch, finds a value by `name` in the context's
+        # stack. You may specify the default return value by passing a
+        # second parameter.
+        #
+        # If no second parameter is passed (or raise_on_context_miss is
+        # set to true), will raise a ContextMiss exception on miss.
+        def fetch(name, default = :__raise)
+          @stack.each do |frame|
+            # Prevent infinite recursion.
+            next if frame == self
+
+            value = find(frame, name, :__missing)
+            return value if :__missing != value
+          end
+
+          if default == :__raise || mustache_in_stack.raise_on_context_miss?
+            raise ContextMiss.new("Can't find #{name} in #{@stack.inspect}")
+          else
+            default
+          end
+        end
+
+        # Finds a key in an object, using whatever method is most
+        # appropriate. If the object is a hash, does a simple hash lookup.
+        # If it's an object that responds to the key as a method call,
+        # invokes that method. You get the idea.
+        #
+        # @param [Object] obj The object to perform the lookup on.
+        # @param [String,Symbol] key The key whose value you want
+        # @param [Object] default An optional default value, to return if the key is not found.
+        #
+        # @return [Object] The value of key in object if it is found, and default otherwise.
+        #
+        def find(obj, key, default = nil)
+          return find_in_hash(obj.to_hash, key, default) if obj.respond_to?(:to_hash)
+
+          unless obj.respond_to?(key)
+            # no match for the key, but it may include a hyphen, so try again replacing hyphens with underscores.
+            key = key.to_s.tr("-", "_")
+            return default unless obj.respond_to?(key)
+          end
+
+          meth = obj.method(key) rescue proc { obj.send(key) }
+          meth.arity == 1 ? meth.to_proc : meth.call
+        end
+
+        def current
+          @stack.first
+        end
+
+        private
+
+        # Fetches a hash key if it exists, or returns the given default.
+        def find_in_hash(obj, key, default)
+          return obj[key] if obj.has_key?(key)
+          return obj[key.to_s] if obj.has_key?(key.to_s)
+          return obj[key] if obj.respond_to?(:default_proc) && obj.default_proc && obj[key]
+
+          # If default is :__missing then we are from #fetch which is hunting through the stack
+          # If default is nil then we are reducing dot notation
+          if :__missing != default && mustache_in_stack.raise_on_context_miss?
+            raise ContextMiss.new("Can't find #{key} in #{obj}")
+          else
+            obj.fetch(key, default)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/braintrust/vendor/mustache/context_miss.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+# Vendored from mustache gem v1.1.1
+# https://github.com/mustache/mustache
+# License: MIT
+# Modifications: Namespaced under Braintrust::Vendor
+
+module Braintrust
+  module Vendor
+    class Mustache
+      # A ContextMiss is raised whenever a tag's target can not be found
+      # in the current context if `Mustache#raise_on_context_miss?` is
+      # set to true.
+      #
+      # For example, if your View class does not respond to `music` but
+      # your template contains a `{{music}}` tag this exception will be raised.
+      #
+      # By default it is not raised. See Mustache.raise_on_context_miss.
+      class ContextMiss < RuntimeError; end
+    end
+  end
+end

data/lib/braintrust/vendor/mustache/enumerable.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+# Vendored from mustache gem v1.1.1
+# https://github.com/mustache/mustache
+# License: MIT
+# Modifications: Namespaced under Braintrust::Vendor
+
+module Braintrust
+  module Vendor
+    class Mustache
+      Enumerable = Module.new
+    end
+  end
+end