handle prompts, templating, etc.

.claude/settings.json

@@ -0,0 +1,48 @@
+{
+  "permissions": {
+    "allow": [
+      "Bash(git log:*)",
+      "Bash(git branch:*)",
+      "Bash(git remote:*)",
+      "Bash(git fetch:*)",
+      "Bash(git stash:*)",
+      "Bash(git diff:*)",
+      "Bash(git status:*)",
+      "Bash(git show:*)",
+      "Bash(gh repo view:*)",
+      "Bash(gh run list:*)",
+      "Bash(gh run view:*)",
+      "Bash(gh pr view:*)",
+      "Bash(gh pr diff:*)",
+      "Bash(gh pr list:*)",
+      "Bash(gh issue view:*)",
+      "Bash(gh release:*)",
+      "Bash(gh api:*)",
+      "Bash(rake -T:*)",
+      "Bash(bundle show:*)",
+      "Bash(bundle list:*)",
+      "Bash(bundle platform:*)",
+      "Bash(gem search:*)",
+      "Bash(gem list:*)",
+      "Bash(tree:*)",
+      "Bash(grep:*)",
+      "Bash(find:*)",
+      "Bash(echo:*)",
+      "Bash(sort:*)",
+      "Bash(cat:*)",
+      "Bash(head:*)",
+      "Bash(tail:*)",
+      "Bash(less:*)",
+      "Bash(wc:*)",
+      "Bash(ls:*)",
+      "Bash(pwd:*)",
+      "Bash(which:*)",
+      "Bash(type:*)",
+      "Bash(file:*)",
+      "Bash(VCR_MODE=new_episodes bundle exec ruby:*)",
+      "Bash(VCR_MODE=new_episodes bundle exec rake:*)",
+      "Bash(VCR_MODE=new_episodes rake test:*)"
+    ],
+    "deny": []
+  }
+}

Gemfile.lock

@@ -2,6 +2,7 @@ PATH
   remote: .
   specs:
     braintrust (0.0.12)
+      mustache (~> 1.0)
       openssl (~> 3.3.1)
       opentelemetry-exporter-otlp (~> 0.28)
       opentelemetry-sdk (~> 1.3)
@@ -49,6 +50,7 @@ GEM
       builder
       minitest (>= 5.0)
       ruby-progressbar
+    mustache (1.1.1)
     openssl (3.3.1)
     opentelemetry-api (1.7.0)
     opentelemetry-common (0.23.0)

braintrust.gemspec

@@ -31,6 +31,7 @@ Gem::Specification.new do |spec|
   # Runtime dependencies
   spec.add_runtime_dependency "opentelemetry-sdk", "~> 1.3"
   spec.add_runtime_dependency "opentelemetry-exporter-otlp", "~> 0.28"
+  spec.add_runtime_dependency "mustache", "~> 1.0"
 
   # OpenSSL 3.3.1+ fixes macOS CRL (Certificate Revocation List) verification issues
   # that occur with OpenSSL 3.6 + Ruby (certificate verify failed: unable to get certificate CRL).

examples/prompt.rb

@@ -0,0 +1,100 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# Example: Loading and executing prompts from Braintrust
+#
+# This example demonstrates how to:
+# 1. Create a prompt (function) on the Braintrust server
+# 2. Load it using Prompt.load
+# 3. Build the prompt with Mustache variable substitution
+# 4. Execute the prompt with OpenAI and get a response
+#
+# Benefits of loading prompts:
+# - Centralized prompt management in Braintrust UI
+# - Version control and A/B testing for prompts
+# - No code deployment needed for prompt changes
+# - Works with any LLM client (OpenAI, Anthropic, etc.)
+# - Uses standard Mustache templating ({{variable}}, {{object.property}})
+
+require "bundler/setup"
+require "braintrust"
+require "openai"
+
+# Initialize Braintrust with tracing
+Braintrust.init
+
+# Wrap OpenAI client for tracing
+openai = Braintrust::Trace::OpenAI.wrap(OpenAI::Client.new)
+
+project_name = "ruby-sdk-examples"
+prompt_slug = "greeting-prompt-#{Time.now.to_i}"
+
+# First, create a prompt on the server
+# In practice, you would create prompts via the Braintrust UI
+puts "Creating prompt..."
+
+api = Braintrust::API.new
+api.functions.create(
+  project_name: project_name,
+  slug: prompt_slug,
+  function_data: {type: "prompt"},
+  prompt_data: {
+    prompt: {
+      type: "chat",
+      messages: [
+        {
+          role: "system",
+          content: "You are a friendly assistant. Respond in {{language}}. Keep responses brief (1-2 sentences)."
+        },
+        {
+          role: "user",
+          content: "Say hello to {{name}} and wish them a great {{time_of_day}}!"
+        }
+      ]
+    },
+    options: {
+      model: "gpt-4o-mini",
+      params: {temperature: 0.7, max_tokens: 100}
+    }
+  }
+)
+puts "Created prompt: #{prompt_slug}"
+
+# Load the prompt using Prompt.load
+puts "\nLoading prompt..."
+prompt = Braintrust::Prompt.load(project: project_name, slug: prompt_slug)
+
+puts "  ID: #{prompt.id}"
+puts "  Slug: #{prompt.slug}"
+puts "  Model: #{prompt.model}"
+
+# Build the prompt with Mustache variable substitution
+puts "\nBuilding prompt with variables..."
+params = prompt.build(
+  name: "Alice",
+  language: "Spanish",
+  time_of_day: "morning"
+)
+
+puts "  Model: #{params[:model]}"
+puts "  Temperature: #{params[:temperature]}"
+puts "  Messages:"
+params[:messages].each do |msg|
+  puts "    [#{msg[:role]}] #{msg[:content]}"
+end
+
+# Execute the prompt with OpenAI
+puts "\nExecuting prompt with OpenAI..."
+response = openai.chat.completions.create(**params)
+
+puts "\nResponse:"
+content = response.choices.first.message.content
+puts "  #{content}"
+
+# Clean up - delete the test prompt
+puts "\nCleaning up..."
+api.functions.delete(id: prompt.id)
+puts "Done!"
+
+# Flush traces
+OpenTelemetry.tracer_provider.shutdown

lib/braintrust.rb

@@ -5,6 +5,7 @@
 require_relative "braintrust/state"
 require_relative "braintrust/trace"
 require_relative "braintrust/api"
+require_relative "braintrust/prompt"
 require_relative "braintrust/internal/experiments"
 require_relative "braintrust/eval"
 

lib/braintrust/api/functions.rb

@@ -85,6 +85,14 @@ def invoke(id:, input:)
         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
+      # @return [Hash] Full function data including prompt_data
+      def get(id:)
+        http_get("/v1/function/#{id}")
+      end
+
       # Delete a function by ID
       # DELETE /v1/function/{id}
       # @param id [String] Function UUID

lib/braintrust/prompt.rb

@@ -0,0 +1,172 @@
+# frozen_string_literal: true
+
+require "mustache"
+
+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 state [State, nil] Braintrust state (default: global)
+    # @return [Prompt]
+    def self.load(project:, slug:, version: nil, defaults: {}, state: nil)
+      state ||= Braintrust.current_state
+      raise Error, "No state available - call Braintrust.init first" unless state
+
+      api = API.new(state: state)
+
+      # 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"])
+
+      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 = 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 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
+
+    # 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(stringify_keys(variables_hash)).merge(stringify_keys(kwargs))
+
+      # Render Mustache templates in messages
+      built_messages = messages.map do |msg|
+        {
+          role: msg["role"].to_sym,
+          content: render_template(msg["content"], vars, strict: strict)
+        }
+      end
+
+      # Build result with model and messages
+      result = {
+        model: model,
+        messages: built_messages
+      }
+
+      # 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
+
+    private
+
+    # Render Mustache template with variables
+    def render_template(text, variables, strict:)
+      return text unless text.is_a?(String)
+
+      if strict
+        # Check for missing variables before rendering
+        missing = find_missing_variables(text, variables)
+        if missing.any?
+          raise Error, "Missing required variables: #{missing.join(", ")}"
+        end
+      end
+
+      Mustache.render(text, variables)
+    end
+
+    # Find variables in template that are not provided
+    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 the variables hash
+    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 (handles both symbol and 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