braintrust 0.1.1 → 0.1.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 40d5c41ef999d495f9eb7b3a4cd41f1bb9ee7ba831de2074195a7d9e18da2e3a
-  data.tar.gz: 8e48aee25cd02a4b936da1264a9964097c6e07744faf0564d81885daa72b87da
+  metadata.gz: 626876b443795d28b4ba5d12f8bf10381c3052d5d196adb01207d545303f3d1e
+  data.tar.gz: 347ca89ea9f485ca6521a38c067bdd15074db4e6a4757523901888a8d4cc3e9c
 SHA512:
-  metadata.gz: 9391f2dcec3c92e032d3e7009ec4bf1d26f6d2a606f0edad78acf78078f116393d95a4a3d70a08010b89df214f92498905c67cd02b3bd6327b5aa2cbf1dda872
-  data.tar.gz: 5665f9bcb49a8b5ca90f5d58d9c279120a053756c6ec03ba17557b6064c7a7142ac9674789fe4c89df70e2ac61d1d1ce9318a33b897b55da1d45b9bc9df1bf15
+  metadata.gz: 7b827a4f92e2bc4b39e41174e62dacdc431fdc0b6c8d13882bdcaaa369af9621174fc01bafa3d0d594b71464ea374c6904e9834631957951dad87d6583a58dc9
+  data.tar.gz: bb6f2d3807765ef4ad591849e0972379fc3f97ef8d90bda0785e1d4dab87ce5e91d954d9d3c8fc7eff6c9295d120d6cbe07acb5bb348873c842d791a3fbdce84

data/lib/braintrust/api/functions.rb

@@ -85,6 +85,17 @@ module Braintrust
         http_post_json("/v1/function/#{id}/invoke", payload)
       end
 
+      # Get a function by ID (includes full prompt_data)
+      # GET /v1/function/{id}
+      # @param id [String] Function UUID
+      # @param version [String, nil] Retrieve prompt at a specific version (transaction ID or version identifier)
+      # @return [Hash] Full function data including prompt_data
+      def get(id:, version: nil)
+        params = {}
+        params["version"] = version if version
+        http_get("/v1/function/#{id}", params)
+      end
+
       # Delete a function by ID
       # DELETE /v1/function/{id}
       # @param id [String] Function UUID

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/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

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

@@ -0,0 +1,188 @@
+# 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
+      # The Generator is in charge of taking an array of Mustache tokens,
+      # usually assembled by the Parser, and generating an interpolatable
+      # Ruby string. This string is considered the "compiled" template
+      # because at that point we're relying on Ruby to do the parsing and
+      # run our code.
+      #
+      # For example, let's take this template:
+      #
+      #   Hi {{thing}}!
+      #
+      # If we run this through the Parser we'll get these tokens:
+      #
+      #   [:multi,
+      #     [:static, "Hi "],
+      #     [:mustache, :etag, "thing"],
+      #     [:static, "!\n"]]
+      #
+      # Now let's hand that to the Generator:
+      #
+      # >> puts Braintrust::Vendor::Mustache::Generator.new.compile(tokens)
+      # "Hi #{ctx.escape(ctx[:thing])}!\n"
+      class Generator
+        # Options can be used to manipulate the resulting ruby code string behavior.
+        def initialize(options = {})
+          @options = options
+          @option_static_lambdas = options[:static_lambdas] == true
+        end
+
+        # Given an array of tokens, returns an interpolatable Ruby string.
+        def compile(exp)
+          "\"#{compile!(exp)}\""
+        end
+
+        private
+
+        # Given an array of tokens, converts them into Ruby code. In
+        # particular there are three types of expressions we are concerned
+        # with:
+        #
+        #   :multi
+        #     Mixed bag of :static, :mustache, and whatever.
+        #
+        #   :static
+        #     Normal HTML, the stuff outside of {{mustaches}}.
+        #
+        #   :mustache
+        #     Any Mustache tag, from sections to partials.
+        def compile!(exp)
+          case exp.first
+          when :multi
+            exp[1..-1].reduce(+"") { |sum, e| sum << compile!(e) }
+          when :static
+            str(exp[1])
+          when :mustache
+            send(:"on_#{exp[1]}", *exp[2..-1])
+          else
+            raise "Unhandled exp: #{exp.first}"
+          end
+        end
+
+        # Callback fired when the compiler finds a section token. We're
+        # passed the section name and the array of tokens.
+        def on_section(name, offset, content, raw, delims)
+          # Convert the tokenized content of this section into a Ruby
+          # string we can use.
+          code = compile(content)
+
+          # Lambda handling - default handling is to dynamically interpret
+          # the returned lambda result as mustache source
+          proc_handling = if @option_static_lambdas
+            <<-compiled
+              v.call(lambda {|v| #{code}}.call(v)).to_s
+            compiled
+          else
+            <<-compiled
+              t = Braintrust::Vendor::Mustache::Template.new(v.call(#{raw.inspect}).to_s)
+              def t.tokens(src=@source)
+                p = Braintrust::Vendor::Mustache::Parser.new
+                p.otag, p.ctag = #{delims.inspect}
+                p.compile(src)
+              end
+              t.render(ctx.dup)
+            compiled
+          end
+
+          # Compile the Ruby for this section now that we know what's
+          # inside the section.
+          ev(<<-compiled)
+          case v = #{compile!(name)}
+          when NilClass, FalseClass
+          when TrueClass
+            #{code}
+          when Proc
+            #{proc_handling}
+          when Array, Enumerator, Braintrust::Vendor::Mustache::Enumerable
+            v.map { |_| ctx.push(_); r = #{code}; ctx.pop; r }.join
+          else
+            ctx.push(v); r = #{code}; ctx.pop; r
+          end
+          compiled
+        end
+
+        # Fired when we find an inverted section. Just like `on_section`,
+        # we're passed the inverted section name and the array of tokens.
+        def on_inverted_section(name, offset, content, raw, delims)
+          # Convert the tokenized content of this section into a Ruby
+          # string we can use.
+          code = compile(content)
+
+          # Compile the Ruby for this inverted section now that we know
+          # what's inside.
+          ev(<<-compiled)
+          v = #{compile!(name)}
+          if v.nil? || v == false || v.respond_to?(:empty?) && v.empty?
+            #{code}
+          end
+          compiled
+        end
+
+        # Fired when the compiler finds a partial. We want to return code
+        # which calls a partial at runtime instead of expanding and
+        # including the partial's body to allow for recursive partials.
+        def on_partial(name, offset, indentation)
+          ev("ctx.partial(#{name.to_sym.inspect}, #{indentation.inspect})")
+        end
+
+        # An unescaped tag.
+        def on_utag(name, offset)
+          ev(<<-compiled)
+            v = #{compile!(name)}
+            if v.is_a?(Proc)
+              v = #{@option_static_lambdas ? "v.call" : "Braintrust::Vendor::Mustache::Template.new(v.call.to_s).render(ctx.dup)"}
+            end
+            v.to_s
+          compiled
+        end
+
+        # An escaped tag.
+        def on_etag(name, offset)
+          ev(<<-compiled)
+            v = #{compile!(name)}
+            if v.is_a?(Proc)
+              v = #{@option_static_lambdas ? "v.call" : "Braintrust::Vendor::Mustache::Template.new(v.call.to_s).render(ctx.dup)"}
+            end
+            ctx.escape(v)
+          compiled
+        end
+
+        def on_fetch(names)
+          return "ctx.current" if names.empty?
+
+          names = names.map { |n| n.to_sym }
+
+          initial, *rest = names
+          if rest.any?
+            <<-compiled
+              #{rest.inspect}.reduce(ctx[#{initial.inspect}]) { |value, key| value && ctx.find(value, key) }
+            compiled
+          else
+            <<-compiled
+              ctx[#{initial.inspect}]
+            compiled
+          end
+        end
+
+        # An interpolation-friendly version of a string, for use within a
+        # Ruby string.
+        def ev(s)
+          "#\{#{s}}"
+        end
+
+        def str(s)
+          s.inspect[1..-2]
+        end
+      end
+    end
+  end
+end