braintrust 0.0.2 → 0.0.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 3330f067e867f2d0d81ea12db80bb2dbf83d9ca447ef819e2bff7c97138e7f9e
-  data.tar.gz: f2e4f8e34bfe2292d5b3883923d4b638de89b6c930144c02a4c7941b831ca7e6
+  metadata.gz: 39d85e02bd85a931ee7f16de103d48d1184048e3ad8d791eda37bc323a653716
+  data.tar.gz: a0b1d5493e8ad3004007e78d608154077a33c92a436bce23eb36cfbe94c3bdd4
 SHA512:
-  metadata.gz: feb0969a48253f3729b9f38d243abcb6f0367176b9cddf9df112be9e415f8b5dadf90ca50588bd2e09be84a4efb406f40aa13b4ccab88310bba1a73e993205e6
-  data.tar.gz: 67e9c6163c4b20944953e7063286f98b2e079e424fd80991376110864971f251cb1ca6a663a99d923d9cd92d74be17030dba90a9ba5619f610d307d4075aa38f
+  metadata.gz: a5dcbd1b2bf2c0ab2355ff36c9cfce4fe10e175c0aa8df80ea3176be4002271744ca3a9fd7ef52cec888e0b326772518554921f7d657a79ba347b26c4c93b80c
+  data.tar.gz: 78677bd57e6ed1778f74b87e050dd5bbfdc8390e73f919aa57ea680cd2cd4338086e5df4982274c3fd62e690d34ec81078d7c76e75a467ab2f5b0667e6d530d6

data/README.md

@@ -1,7 +1,7 @@
 # Braintrust Ruby SDK
 
-[![Gem Version](https://badge.fury.io/rb/braintrust.svg)](https://badge.fury.io/rb/braintrust)
-[![Documentation](https://img.shields.io/badge/docs-rubydoc.info-blue.svg)](https://rubydoc.info/gems/braintrust)
+[![Gem Version](https://img.shields.io/gem/v/braintrust.svg)](https://rubygems.org/gems/braintrust)
+[![Documentation](https://img.shields.io/badge/docs-gemdocs.org-blue.svg)](https://gemdocs.org/gems/braintrust/)
 ![Beta](https://img.shields.io/badge/status-beta-yellow)
 
 ## Overview
@@ -136,10 +136,95 @@ puts "View trace at: #{Braintrust::Trace.permalink(root_span)}"
 OpenTelemetry.tracer_provider.shutdown
 ```
 
+### Anthropic Tracing
+
+```ruby
+require "braintrust"
+require "anthropic"
+
+Braintrust.init
+
+client = Anthropic::Client.new(api_key: ENV["ANTHROPIC_API_KEY"])
+
+Braintrust::Trace::Anthropic.wrap(client)
+
+tracer = OpenTelemetry.tracer_provider.tracer("anthropic-app")
+root_span = nil
+
+message = tracer.in_span("chat-message") do |span|
+  root_span = span
+
+  client.messages.create(
+    model: "claude-3-5-sonnet-20241022",
+    max_tokens: 100,
+    system: "You are a helpful assistant.",
+    messages: [
+      {role: "user", content: "Say hello!"}
+    ]
+  )
+end
+
+puts "Response: #{message.content[0].text}"
+
+puts "View trace at: #{Braintrust::Trace.permalink(root_span)}"
+
+OpenTelemetry.tracer_provider.shutdown
+```
+
+### Attachments
+
+Attachments allow you to log binary data (images, PDFs, audio, etc.) as part of your traces. This is particularly useful for multimodal AI applications like vision models.
+
+```ruby
+require "braintrust"
+require "braintrust/trace/attachment"
+
+Braintrust.init
+
+tracer = OpenTelemetry.tracer_provider.tracer("vision-app")
+
+tracer.in_span("analyze-image") do |span|
+  # Create attachment from file
+  att = Braintrust::Trace::Attachment.from_file(
+    Braintrust::Trace::Attachment::IMAGE_PNG,
+    "./photo.png"
+  )
+
+  # Build message with attachment (OpenAI/Anthropic format)
+  messages = [
+    {
+      role: "user",
+      content: [
+        {type: "text", text: "What's in this image?"},
+        att.to_h  # Converts to {"type" => "base64_attachment", "content" => "data:..."}
+      ]
+    }
+  ]
+
+  # Log to trace
+  span.set_attribute("braintrust.input_json", JSON.generate(messages))
+end
+
+OpenTelemetry.tracer_provider.shutdown
+```
+
+You can create attachments from bytes, files, or URLs:
+
+```ruby
+# From bytes
+att = Braintrust::Trace::Attachment.from_bytes("image/jpeg", image_data)
+
+# From file
+att = Braintrust::Trace::Attachment.from_file("application/pdf", "./doc.pdf")
+
+# From URL
+att = Braintrust::Trace::Attachment.from_url("https://example.com/image.png")
+```
+
 ## Features
 
 - **Evaluations**: Run systematic evaluations of your AI systems with custom scoring functions
-- **Tracing**: Automatic instrumentation for OpenAI API calls with OpenTelemetry
+- **Tracing**: Automatic instrumentation for OpenAI and Anthropic API calls with OpenTelemetry
 - **Datasets**: Manage and version your evaluation datasets
 - **Experiments**: Track different versions and configurations of your AI systems
 - **Observability**: Monitor your AI applications in production
@@ -151,13 +236,15 @@ Check out the [`examples/`](./examples/) directory for complete working examples
 - [eval.rb](./examples/eval.rb) - Create and run evaluations with custom test cases and scoring functions
 - [trace.rb](./examples/trace.rb) - Manual span creation and tracing
 - [openai.rb](./examples/openai.rb) - Automatically trace OpenAI API calls
+- [anthropic.rb](./examples/anthropic.rb) - Automatically trace Anthropic API calls
+- [trace/trace_attachments.rb](./examples/trace/trace_attachments.rb) - Log attachments (images, PDFs) in traces
 - [eval/dataset.rb](./examples/eval/dataset.rb) - Run evaluations using datasets stored in Braintrust
 - [eval/remote_functions.rb](./examples/eval/remote_functions.rb) - Use remote scoring functions
 
 ## Documentation
 
 - [Braintrust Documentation](https://www.braintrust.dev/docs)
-- [API Documentation](https://rubydoc.info/gems/braintrust)
+- [API Documentation](https://gemdocs.org/gems/braintrust/)
 
 ## Contributing
 

data/lib/braintrust/config.rb

@@ -4,14 +4,18 @@ module Braintrust
   # Configuration object that reads from environment variables
   # and allows overriding with explicit options
   class Config
-    attr_reader :api_key, :org_name, :default_project, :app_url, :api_url
+    attr_reader :api_key, :org_name, :default_project, :app_url, :api_url,
+      :filter_ai_spans, :span_filter_funcs
 
-    def initialize(api_key: nil, org_name: nil, default_project: nil, app_url: nil, api_url: nil)
+    def initialize(api_key: nil, org_name: nil, default_project: nil, app_url: nil, api_url: nil,
+      filter_ai_spans: nil, span_filter_funcs: nil)
       @api_key = api_key
       @org_name = org_name
       @default_project = default_project
       @app_url = app_url
       @api_url = api_url
+      @filter_ai_spans = filter_ai_spans
+      @span_filter_funcs = span_filter_funcs || []
     end
 
     # Create a Config from environment variables, with option overrides
@@ -21,14 +25,27 @@ module Braintrust
     # @param default_project [String, nil] Default project (overrides BRAINTRUST_DEFAULT_PROJECT env var)
     # @param app_url [String, nil] App URL (overrides BRAINTRUST_APP_URL env var)
     # @param api_url [String, nil] API URL (overrides BRAINTRUST_API_URL env var)
+    # @param filter_ai_spans [Boolean, nil] Enable AI span filtering (overrides BRAINTRUST_OTEL_FILTER_AI_SPANS env var)
+    # @param span_filter_funcs [Array<Proc>, nil] Custom span filter functions
     # @return [Config] the created config
-    def self.from_env(api_key: nil, org_name: nil, default_project: nil, app_url: nil, api_url: nil)
+    def self.from_env(api_key: nil, org_name: nil, default_project: nil, app_url: nil, api_url: nil,
+      filter_ai_spans: nil, span_filter_funcs: nil)
+      # Parse filter_ai_spans from ENV if not explicitly provided
+      env_filter_ai_spans = ENV["BRAINTRUST_OTEL_FILTER_AI_SPANS"]
+      filter_ai_spans_value = if filter_ai_spans.nil?
+        env_filter_ai_spans&.downcase == "true"
+      else
+        filter_ai_spans
+      end
+
       new(
         api_key: api_key || ENV["BRAINTRUST_API_KEY"],
         org_name: org_name || ENV["BRAINTRUST_ORG_NAME"],
         default_project: default_project || ENV["BRAINTRUST_DEFAULT_PROJECT"],
         app_url: app_url || ENV["BRAINTRUST_APP_URL"] || "https://www.braintrust.dev",
-        api_url: api_url || ENV["BRAINTRUST_API_URL"] || "https://api.braintrust.dev"
+        api_url: api_url || ENV["BRAINTRUST_API_URL"] || "https://api.braintrust.dev",
+        filter_ai_spans: filter_ai_spans_value,
+        span_filter_funcs: span_filter_funcs
       )
     end
   end

data/lib/braintrust/eval.rb

@@ -9,6 +9,170 @@ require "opentelemetry/sdk"
 require "json"
 
 module Braintrust
+  # Evaluation framework for testing AI systems with custom test cases and scoring functions.
+  #
+  # The Eval module provides tools for running systematic evaluations of your AI systems. An
+  # evaluation consists of:
+  # - **Cases**: Test inputs with optional expected outputs
+  # - **Task**: The code/model being evaluated
+  # - **Scorers**: Functions that judge the quality of outputs
+  #
+  # @example Basic evaluation with inline cases
+  #   require "braintrust"
+  #
+  #   Braintrust.init
+  #
+  #   # Define a simple task (the code being evaluated)
+  #   task = ->(input) { input.include?("a") ? "fruit" : "vegetable" }
+  #
+  #   # Run evaluation with inline cases
+  #   Braintrust::Eval.run(
+  #     project: "my-project",
+  #     experiment: "food-classifier",
+  #     cases: [
+  #       {input: "apple", expected: "fruit"},
+  #       {input: "carrot", expected: "vegetable"},
+  #       {input: "banana", expected: "fruit"}
+  #     ],
+  #     task: task,
+  #     scorers: [
+  #       # Named scorer with Eval.scorer
+  #       Braintrust::Eval.scorer("exact_match") do |input, expected, output|
+  #         output == expected ? 1.0 : 0.0
+  #       end
+  #     ]
+  #   )
+  #
+  # @example Different ways to define scorers (recommended patterns)
+  #   # Method reference (auto-uses method name as scorer name)
+  #   def exact_match(input, expected, output)
+  #     output == expected ? 1.0 : 0.0
+  #   end
+  #
+  #   # Named scorer with Eval.scorer
+  #   case_insensitive = Braintrust::Eval.scorer("case_insensitive") do |input, expected, output|
+  #     output.downcase == expected.downcase ? 1.0 : 0.0
+  #   end
+  #
+  #   # Callable class with name method
+  #   class FuzzyMatch
+  #     def name
+  #       "fuzzy_match"
+  #     end
+  #
+  #     def call(input, expected, output, metadata = {})
+  #       threshold = metadata[:threshold] || 0.8
+  #       # scoring logic here
+  #       1.0
+  #     end
+  #   end
+  #
+  #   # Anonymous lambda that returns named score object
+  #   multi_score = ->(input, expected, output) {
+  #     [
+  #       {name: "exact_match", score: output == expected ? 1.0 : 0.0},
+  #       {name: "length_match", score: output.length == expected.length ? 1.0 : 0.0}
+  #     ]
+  #   }
+  #
+  #   # All can be used together
+  #   Braintrust::Eval.run(
+  #     project: "my-project",
+  #     experiment: "scorer-examples",
+  #     cases: [{input: "test", expected: "test"}],
+  #     task: ->(input) { input },
+  #     scorers: [method(:exact_match), case_insensitive, FuzzyMatch.new, multi_score]
+  #   )
+  #
+  # @example Different ways to define tasks
+  #   # Lambda
+  #   task_lambda = ->(input) { "result" }
+  #
+  #   # Proc
+  #   task_proc = proc { |input| "result" }
+  #
+  #   # Method reference
+  #   def my_task(input)
+  #     "result"
+  #   end
+  #   task_method = method(:my_task)
+  #
+  #   # Callable class
+  #   class MyTask
+  #     def call(input)
+  #       "result"
+  #     end
+  #   end
+  #   task_class = MyTask.new
+  #
+  #   # All of these can be used as the task parameter
+  #   Braintrust::Eval.run(
+  #     project: "my-project",
+  #     experiment: "task-examples",
+  #     cases: [{input: "test"}],
+  #     task: task_lambda, # or task_proc, task_method, task_class
+  #     scorers: [
+  #       Braintrust::Eval.scorer("my_scorer") { |input, expected, output| 1.0 }
+  #     ]
+  #   )
+  #
+  # @example Using datasets instead of inline cases
+  #   # Fetch cases from a dataset stored in Braintrust
+  #   Braintrust::Eval.run(
+  #     project: "my-project",
+  #     experiment: "with-dataset",
+  #     dataset: "my-dataset-name", # fetches from same project
+  #     task: ->(input) { "result" },
+  #     scorers: [
+  #       Braintrust::Eval.scorer("my_scorer") { |input, expected, output| 1.0 }
+  #     ]
+  #   )
+  #
+  #   # Or with more options
+  #   Braintrust::Eval.run(
+  #     project: "my-project",
+  #     experiment: "with-dataset-options",
+  #     dataset: {
+  #       name: "my-dataset",
+  #       project: "other-project",
+  #       version: "1.0",
+  #       limit: 100
+  #     },
+  #     task: ->(input) { "result" },
+  #     scorers: [
+  #       Braintrust::Eval.scorer("my_scorer") { |input, expected, output| 1.0 }
+  #     ]
+  #   )
+  #
+  # @example Using metadata and tags
+  #   Braintrust::Eval.run(
+  #     project: "my-project",
+  #     experiment: "with-metadata",
+  #     cases: [
+  #       {
+  #         input: "apple",
+  #         expected: "fruit",
+  #         tags: ["tropical", "sweet"],
+  #         metadata: {threshold: 0.9, category: "produce"}
+  #       }
+  #     ],
+  #     task: ->(input) { "fruit" },
+  #     scorers: [
+  #       # Scorer can access case metadata
+  #       Braintrust::Eval.scorer("threshold_match") do |input, expected, output, metadata|
+  #         threshold = metadata[:threshold] || 0.5
+  #         # scoring logic using threshold
+  #         1.0
+  #       end
+  #     ],
+  #     # Experiment-level tags and metadata
+  #     tags: ["v1", "production"],
+  #     metadata: {
+  #       model: "gpt-4",
+  #       temperature: 0.7,
+  #       version: "1.0.0"
+  #     }
+  #   )
   module Eval
     class << self
       # Create a scorer with a name and callable

data/lib/braintrust/state.rb

@@ -6,7 +6,7 @@ module Braintrust
   # State object that holds Braintrust configuration
   # Thread-safe global state management
   class State
-    attr_reader :api_key, :org_name, :org_id, :default_project, :app_url, :api_url, :proxy_url, :logged_in
+    attr_reader :api_key, :org_name, :org_id, :default_project, :app_url, :api_url, :proxy_url, :logged_in, :config
 
     @mutex = Mutex.new
     @global_state = nil
@@ -20,15 +20,20 @@ module Braintrust
     # @param blocking_login [Boolean] whether to block and login synchronously (default: false)
     # @param enable_tracing [Boolean] whether to enable OpenTelemetry tracing (default: true)
     # @param tracer_provider [TracerProvider, nil] Optional tracer provider to use
+    # @param filter_ai_spans [Boolean, nil] Enable AI span filtering
+    # @param span_filter_funcs [Array<Proc>, nil] Custom span filter functions
+    # @param exporter [Exporter, nil] Optional exporter override (for testing)
     # @return [State] the created state
-    def self.from_env(api_key: nil, org_name: nil, default_project: nil, app_url: nil, api_url: nil, blocking_login: false, enable_tracing: true, tracer_provider: nil)
+    def self.from_env(api_key: nil, org_name: nil, default_project: nil, app_url: nil, api_url: nil, blocking_login: false, enable_tracing: true, tracer_provider: nil, filter_ai_spans: nil, span_filter_funcs: nil, exporter: nil)
       require_relative "config"
       config = Config.from_env(
         api_key: api_key,
         org_name: org_name,
         default_project: default_project,
         app_url: app_url,
-        api_url: api_url
+        api_url: api_url,
+        filter_ai_spans: filter_ai_spans,
+        span_filter_funcs: span_filter_funcs
       )
       new(
         api_key: config.api_key,
@@ -38,11 +43,13 @@ module Braintrust
         api_url: config.api_url,
         blocking_login: blocking_login,
         enable_tracing: enable_tracing,
-        tracer_provider: tracer_provider
+        tracer_provider: tracer_provider,
+        config: config,
+        exporter: exporter
       )
     end
 
-    def initialize(api_key: nil, org_name: nil, org_id: nil, default_project: nil, app_url: nil, api_url: nil, proxy_url: nil, blocking_login: false, enable_tracing: true, tracer_provider: nil)
+    def initialize(api_key: nil, org_name: nil, org_id: nil, default_project: nil, app_url: nil, api_url: nil, proxy_url: nil, blocking_login: false, enable_tracing: true, tracer_provider: nil, config: nil, exporter: nil)
       # Instance-level mutex for thread-safe login
       @login_mutex = Mutex.new
       raise ArgumentError, "api_key is required" if api_key.nil? || api_key.empty?
@@ -55,6 +62,7 @@ module Braintrust
       @api_url = api_url
       @proxy_url = proxy_url
       @logged_in = false
+      @config = config
 
       # Perform login after state setup
       if blocking_login
@@ -66,7 +74,7 @@ module Braintrust
       # Setup tracing if requested
       if enable_tracing
         require_relative "trace"
-        Trace.setup(self, tracer_provider)
+        Trace.setup(self, tracer_provider, exporter: exporter)
       end
     end
 

data/lib/braintrust/trace/attachment.rb

@@ -0,0 +1,138 @@
+# frozen_string_literal: true
+
+require "base64"
+require "net/http"
+require "uri"
+
+module Braintrust
+  module Trace
+    # Attachment represents binary data (images, audio, PDFs, etc.) that can be logged
+    # as part of traces in Braintrust. Attachments are stored securely and can be viewed
+    # in the Braintrust UI.
+    #
+    # Attachments are particularly useful for multimodal AI applications, such as vision
+    # models that process images.
+    #
+    # @example Create attachment from file
+    #   att = Braintrust::Trace::Attachment.from_file("image/png", "./photo.png")
+    #   data_url = att.to_data_url
+    #   # => "data:image/png;base64,iVBORw0KGgo..."
+    #
+    # @example Create attachment from bytes
+    #   att = Braintrust::Trace::Attachment.from_bytes("image/jpeg", image_bytes)
+    #   message = att.to_message
+    #   # => {"type" => "base64_attachment", "content" => "data:image/jpeg;base64,..."}
+    #
+    # @example Use in a trace span
+    #   att = Braintrust::Trace::Attachment.from_file("image/png", "./photo.png")
+    #   messages = [
+    #     {
+    #       role: "user",
+    #       content: [
+    #         {type: "text", text: "What's in this image?"},
+    #         att.to_h  # Converts to {"type" => "base64_attachment", "content" => "..."}
+    #       ]
+    #     }
+    #   ]
+    #   span.set_attribute("braintrust.input_json", JSON.generate(messages))
+    class Attachment
+      # Common MIME type constants for convenience
+      IMAGE_PNG = "image/png"
+      IMAGE_JPEG = "image/jpeg"
+      IMAGE_JPG = "image/jpg"
+      IMAGE_GIF = "image/gif"
+      IMAGE_WEBP = "image/webp"
+      TEXT_PLAIN = "text/plain"
+      APPLICATION_PDF = "application/pdf"
+
+      # @!visibility private
+      def initialize(content_type, data)
+        @content_type = content_type
+        @data = data
+      end
+
+      # Creates an attachment from raw bytes.
+      #
+      # @param content_type [String] MIME type of the data (e.g., "image/png")
+      # @param data [String] Binary data as a string
+      # @return [Attachment] New attachment instance
+      #
+      # @example
+      #   image_data = File.binread("photo.png")
+      #   att = Braintrust::Trace::Attachment.from_bytes("image/png", image_data)
+      def self.from_bytes(content_type, data)
+        new(content_type, data)
+      end
+
+      # Creates an attachment by reading from a file.
+      #
+      # @param content_type [String] MIME type of the file (e.g., "image/png")
+      # @param path [String] Path to the file to read
+      # @return [Attachment] New attachment instance
+      # @raise [Errno::ENOENT] If the file does not exist
+      #
+      # @example
+      #   att = Braintrust::Trace::Attachment.from_file("image/png", "./photo.png")
+      def self.from_file(content_type, path)
+        data = File.binread(path)
+        new(content_type, data)
+      end
+
+      # Creates an attachment by fetching data from a URL.
+      #
+      # The content type is inferred from the Content-Type header in the HTTP response.
+      # If the header is not present, it falls back to "application/octet-stream".
+      #
+      # @param url [String] URL to fetch
+      # @return [Attachment] New attachment instance
+      # @raise [StandardError] If the HTTP request fails
+      #
+      # @example
+      #   att = Braintrust::Trace::Attachment.from_url("https://example.com/image.png")
+      def self.from_url(url)
+        uri = URI.parse(url)
+        response = Net::HTTP.get_response(uri)
+
+        unless response.is_a?(Net::HTTPSuccess)
+          raise StandardError, "Failed to fetch URL: #{response.code} #{response.message}"
+        end
+
+        content_type = response.content_type || "application/octet-stream"
+        new(content_type, response.body)
+      end
+
+      # Converts the attachment to a data URL format.
+      #
+      # @return [String] Data URL in the format "data:<content-type>;base64,<encoded-data>"
+      #
+      # @example
+      #   att = Braintrust::Trace::Attachment.from_bytes("image/png", image_data)
+      #   att.to_data_url
+      #   # => "data:image/png;base64,iVBORw0KGgo..."
+      def to_data_url
+        encoded = Base64.strict_encode64(@data)
+        "data:#{@content_type};base64,#{encoded}"
+      end
+
+      # Converts the attachment to a message format suitable for LLM APIs.
+      #
+      # @return [Hash] Message hash with "type" and "content" keys
+      #
+      # @example
+      #   att = Braintrust::Trace::Attachment.from_bytes("image/png", image_data)
+      #   att.to_message
+      #   # => {"type" => "base64_attachment", "content" => "data:image/png;base64,..."}
+      def to_message
+        {
+          "type" => "base64_attachment",
+          "content" => to_data_url
+        }
+      end
+
+      # Alias for {#to_message}. Converts the attachment to a hash representation.
+      #
+      # @return [Hash] Same as {#to_message}
+      alias_method :to_h, :to_message
+    end
+  end
+end

data/lib/braintrust/trace/contrib/anthropic.rb

@@ -0,0 +1,439 @@
+# frozen_string_literal: true
+
+require "opentelemetry/sdk"
+require "json"
+
+module Braintrust
+  module Trace
+    module Anthropic
+      # Helper to safely set a JSON attribute on a span
+      # Only sets the attribute if obj is present
+      # @param span [OpenTelemetry::Trace::Span] the span to set attribute on
+      # @param attr_name [String] the attribute name (e.g., "braintrust.output_json")
+      # @param obj [Object] the object to serialize to JSON
+      # @return [void]
+      def self.set_json_attr(span, attr_name, obj)
+        return unless obj
+        span.set_attribute(attr_name, JSON.generate(obj))
+      end
+
+      # Parse usage tokens from Anthropic API response, handling cache tokens
+      # Maps Anthropic field names to Braintrust standard names:
+      # - input_tokens → contributes to prompt_tokens
+      # - cache_creation_input_tokens → prompt_cache_creation_tokens (and adds to prompt_tokens)
+      # - cache_read_input_tokens → prompt_cached_tokens (and adds to prompt_tokens)
+      # - output_tokens → completion_tokens
+      # - total_tokens → tokens (or calculated if missing)
+      #
+      # @param usage [Hash, Object] usage object from Anthropic response
+      # @return [Hash<String, Integer>] metrics hash with normalized names
+      def self.parse_usage_tokens(usage)
+        metrics = {}
+        return metrics unless usage
+
+        # Convert to hash if it's an object
+        usage_hash = usage.respond_to?(:to_h) ? usage.to_h : usage
+
+        # Extract base values for calculation
+        input_tokens = 0
+        cache_creation_tokens = 0
+        cache_read_tokens = 0
+
+        usage_hash.each do |key, value|
+          next unless value.is_a?(Numeric)
+          key_str = key.to_s
+
+          case key_str
+          when "input_tokens"
+            input_tokens = value.to_i
+          when "cache_creation_input_tokens"
+            cache_creation_tokens = value.to_i
+            metrics["prompt_cache_creation_tokens"] = value.to_i
+          when "cache_read_input_tokens"
+            cache_read_tokens = value.to_i
+            metrics["prompt_cached_tokens"] = value.to_i
+          when "output_tokens"
+            metrics["completion_tokens"] = value.to_i
+          when "total_tokens"
+            metrics["tokens"] = value.to_i
+          else
+            # Keep other numeric fields as-is (future-proofing)
+            metrics[key_str] = value.to_i
+          end
+        end
+
+        # Calculate total prompt tokens (input + cache creation + cache read)
+        total_prompt_tokens = input_tokens + cache_creation_tokens + cache_read_tokens
+        metrics["prompt_tokens"] = total_prompt_tokens
+
+        # Calculate total tokens if not provided by Anthropic
+        if !metrics.key?("tokens") && metrics.key?("completion_tokens")
+          metrics["tokens"] = total_prompt_tokens + metrics["completion_tokens"]
+        end
+
+        metrics
+      end
+
+      # Wrap an Anthropic::Client to automatically create spans for messages and responses
+      # Supports both synchronous and streaming requests
+      # @param client [Anthropic::Client] the Anthropic client to wrap
+      # @param tracer_provider [OpenTelemetry::SDK::Trace::TracerProvider] the tracer provider (defaults to global)
+      def self.wrap(client, tracer_provider: nil)
+        tracer_provider ||= ::OpenTelemetry.tracer_provider
+
+        # Wrap messages.create
+        wrap_messages_create(client, tracer_provider)
+
+        # Wrap messages.stream (Anthropic SDK always has this method)
+        wrap_messages_stream(client, tracer_provider)
+
+        client
+      end
+
+      # Wrap messages.create API
+      # @param client [Anthropic::Client] the Anthropic client
+      # @param tracer_provider [OpenTelemetry::SDK::Trace::TracerProvider] the tracer provider
+      def self.wrap_messages_create(client, tracer_provider)
+        # Create a wrapper module that intercepts messages.create
+        wrapper = Module.new do
+          define_method(:create) do |**params|
+            tracer = tracer_provider.tracer("braintrust")
+
+            tracer.in_span("anthropic.messages.create") do |span|
+              # Initialize metadata hash
+              metadata = {
+                "provider" => "anthropic",
+                "endpoint" => "/v1/messages"
+              }
+
+              # Capture request metadata fields
+              metadata_fields = %i[
+                model max_tokens temperature top_p top_k stop_sequences
+                stream tools tool_choice thinking metadata service_tier
+              ]
+
+              metadata_fields.each do |field|
+                metadata[field.to_s] = params[field] if params.key?(field)
+              end
+
+              # Build input messages array, prepending system prompt if present
+              input_messages = []
+
+              # Prepend system prompt as a message if present
+              if params[:system]
+                # System can be a string or array of text blocks
+                system_content = params[:system]
+                if system_content.is_a?(Array)
+                  # Extract text from array of text blocks
+                  system_text = system_content.map { |block|
+                    block.is_a?(Hash) ? block[:text] : block
+                  }.join("\n")
+                  input_messages << {role: "system", content: system_text}
+                else
+                  input_messages << {role: "system", content: system_content}
+                end
+              end
+
+              # Add user/assistant messages
+              if params[:messages]
+                messages_array = params[:messages].map(&:to_h)
+                input_messages.concat(messages_array)
+              end
+
+              # Set input messages as JSON
+              if input_messages.any?
+                span.set_attribute("braintrust.input_json", JSON.generate(input_messages))
+              end
+
+              # Call the original method
+              response = super(**params)
+
+              # Format output as array of messages (same format as input)
+              if response.respond_to?(:content) && response.content
+                content_array = response.content.map(&:to_h)
+                output = [{
+                  role: response.respond_to?(:role) ? response.role : "assistant",
+                  content: content_array
+                }]
+                span.set_attribute("braintrust.output_json", JSON.generate(output))
+              end
+
+              # Set metrics (token usage with Anthropic-specific cache tokens)
+              if response.respond_to?(:usage) && response.usage
+                metrics = Braintrust::Trace::Anthropic.parse_usage_tokens(response.usage)
+                span.set_attribute("braintrust.metrics", JSON.generate(metrics)) unless metrics.empty?
+              end
+
+              # Add response metadata fields
+              if response.respond_to?(:stop_reason) && response.stop_reason
+                metadata["stop_reason"] = response.stop_reason
+              end
+              if response.respond_to?(:stop_sequence) && response.stop_sequence
+                metadata["stop_sequence"] = response.stop_sequence
+              end
+              # Update model if present in response (in case it was resolved from "latest")
+              if response.respond_to?(:model) && response.model
+                metadata["model"] = response.model
+              end
+
+              # Set metadata ONCE at the end with complete hash
+              span.set_attribute("braintrust.metadata", JSON.generate(metadata))
+
+              response
+            end
+          end
+        end
+
+        # Prepend the wrapper to the messages resource
+        client.messages.singleton_class.prepend(wrapper)
+      end
+
+      # Wrap messages.stream API
+      # @param client [Anthropic::Client] the Anthropic client
+      # @param tracer_provider [OpenTelemetry::SDK::Trace::TracerProvider] the tracer provider
+      def self.wrap_messages_stream(client, tracer_provider)
+        # Create a wrapper module that intercepts messages.stream
+        wrapper = Module.new do
+          define_method(:stream) do |**params, &block|
+            tracer = tracer_provider.tracer("braintrust")
+            aggregated_events = []
+
+            metadata = {
+              "provider" => "anthropic",
+              "endpoint" => "/v1/messages",
+              "stream" => true
+            }
+
+            # Start span with proper context
+            span = tracer.start_span("anthropic.messages.create")
+
+            # Capture request metadata fields
+            metadata_fields = %i[
+              model max_tokens temperature top_p top_k stop_sequences
+              tools tool_choice thinking metadata service_tier
+            ]
+
+            metadata_fields.each do |field|
+              metadata[field.to_s] = params[field] if params.key?(field)
+            end
+
+            # Build input messages array, prepending system prompt if present
+            input_messages = []
+
+            if params[:system]
+              system_content = params[:system]
+              if system_content.is_a?(Array)
+                system_text = system_content.map { |block|
+                  block.is_a?(Hash) ? block[:text] : block
+                }.join("\n")
+                input_messages << {role: "system", content: system_text}
+              else
+                input_messages << {role: "system", content: system_content}
+              end
+            end
+
+            if params[:messages]
+              messages_array = params[:messages].map(&:to_h)
+              input_messages.concat(messages_array)
+            end
+
+            if input_messages.any?
+              span.set_attribute("braintrust.input_json", JSON.generate(input_messages))
+            end
+
+            # Set initial metadata
+            span.set_attribute("braintrust.metadata", JSON.generate(metadata))
+
+            # Call the original stream method WITHOUT passing the block
+            # We'll handle the block ourselves to aggregate events
+            begin
+              stream = super(**params)
+            rescue => e
+              span.record_exception(e)
+              span.status = ::OpenTelemetry::Trace::Status.error("Anthropic API error: #{e.message}")
+              span.finish
+              raise
+            end
+
+            # Store references on the stream object itself for the wrapper
+            stream.instance_variable_set(:@braintrust_aggregated_events, aggregated_events)
+            stream.instance_variable_set(:@braintrust_span, span)
+            stream.instance_variable_set(:@braintrust_metadata, metadata)
+
+            # Wrap the stream to aggregate events
+            original_each = stream.method(:each)
+            stream.define_singleton_method(:each) do |&user_block|
+              events = instance_variable_get(:@braintrust_aggregated_events)
+              span_obj = instance_variable_get(:@braintrust_span)
+              meta = instance_variable_get(:@braintrust_metadata)
+
+              begin
+                original_each.call do |event|
+                  # Store event data for aggregation
+                  events << event.to_h if event.respond_to?(:to_h)
+                  # Call user's block if provided
+                  user_block&.call(event)
+                end
+              rescue => e
+                span_obj.record_exception(e)
+                span_obj.status = ::OpenTelemetry::Trace::Status.error("Streaming error: #{e.message}")
+                raise
+              ensure
+                # Always aggregate and finish span after stream completes
+                unless events.empty?
+                  aggregated_output = Braintrust::Trace::Anthropic.aggregate_streaming_events(events)
+
+                  # Set output
+                  if aggregated_output[:content]
+                    output = [{
+                      role: "assistant",
+                      content: aggregated_output[:content]
+                    }]
+                    Braintrust::Trace::Anthropic.set_json_attr(span_obj, "braintrust.output_json", output)
+                  end
+
+                  # Set metrics if usage is available
+                  if aggregated_output[:usage]
+                    metrics = Braintrust::Trace::Anthropic.parse_usage_tokens(aggregated_output[:usage])
+                    Braintrust::Trace::Anthropic.set_json_attr(span_obj, "braintrust.metrics", metrics) unless metrics.empty?
+                  end
+
+                  # Update metadata with response fields
+                  meta["stop_reason"] = aggregated_output[:stop_reason] if aggregated_output[:stop_reason]
+                  meta["model"] = aggregated_output[:model] if aggregated_output[:model]
+                  Braintrust::Trace::Anthropic.set_json_attr(span_obj, "braintrust.metadata", meta)
+                end
+
+                span_obj.finish
+              end
+            end
+
+            # If a block was provided to stream(), call each with it immediately
+            if block
+              stream.each(&block)
+            end
+
+            stream
+          end
+        end
+
+        # Prepend the wrapper to the messages resource
+        client.messages.singleton_class.prepend(wrapper)
+      end
+
+      # Aggregate streaming events into a single response structure
+      # @param events [Array<Hash>] array of event hashes from stream
+      # @return [Hash] aggregated response with content, usage, etc.
+      def self.aggregate_streaming_events(events)
+        return {} if events.empty?
+
+        result = {
+          content: [],
+          usage: {},
+          stop_reason: nil,
+          model: nil
+        }
+
+        # Track content blocks by index
+        content_blocks = {}
+        content_builders = {}
+
+        events.each do |event|
+          event_type = event[:type] || event["type"]
+          next unless event_type
+
+          case event_type
+          when "message_start"
+            # Extract model and initial usage (input tokens, cache tokens)
+            message = event[:message] || event["message"]
+            if message
+              result[:model] = message[:model] || message["model"]
+              if message[:usage] || message["usage"]
+                usage = message[:usage] || message["usage"]
+                result[:usage].merge!(usage)
+              end
+            end
+
+          when "content_block_start"
+            # Initialize a new content block
+            index = event[:index] || event["index"]
+            content_block = event[:content_block] || event["content_block"]
+            content_blocks[index] = content_block if index && content_block
+
+          when "content_block_delta"
+            # Accumulate deltas for content blocks
+            index = event[:index] || event["index"]
+            delta = event[:delta] || event["delta"]
+            next unless index && delta
+
+            delta_type = delta[:type] || delta["type"]
+            content_blocks[index] ||= {}
+
+            case delta_type
+            when "text_delta"
+              # Accumulate text
+              text = delta[:text] || delta["text"]
+              if text
+                content_builders[index] ||= ""
+                content_builders[index] += text
+                content_blocks[index][:type] = "text"
+                content_blocks[index]["type"] = "text"
+              end
+
+            when "input_json_delta"
+              # Accumulate JSON for tool_use blocks
+              partial_json = delta[:partial_json] || delta["partial_json"]
+              if partial_json
+                content_builders[index] ||= ""
+                content_builders[index] += partial_json
+                content_blocks[index][:type] = "tool_use"
+                content_blocks[index]["type"] = "tool_use"
+              end
+            end
+
+          when "message_delta"
+            # Get final stop reason and cumulative usage (output tokens)
+            delta = event[:delta] || event["delta"]
+            if delta
+              stop_reason = delta[:stop_reason] || delta["stop_reason"]
+              result[:stop_reason] = stop_reason if stop_reason
+            end
+
+            usage = event[:usage] || event["usage"]
+            result[:usage].merge!(usage) if usage
+          end
+        end
+
+        # Build final content array from aggregated blocks
+        content_builders.each do |index, text|
+          block = content_blocks[index]
+          next unless block
+
+          block_type = block[:type] || block["type"]
+          case block_type
+          when "text"
+            block[:text] = text
+            block["text"] = text
+          when "tool_use"
+            # Parse the accumulated JSON string
+            begin
+              parsed = JSON.parse(text)
+              block[:input] = parsed
+              block["input"] = parsed
+            rescue JSON::ParserError
+              block[:input] = text
+              block["input"] = text
+            end
+          end
+        end
+
+        # Convert blocks hash to sorted array
+        if content_blocks.any?
+          result[:content] = content_blocks.keys.sort.map { |idx| content_blocks[idx] }
+        end
+
+        result
+      end
+    end
+  end
+end

data/lib/braintrust/trace/span_filter.rb

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+module Braintrust
+  module Trace
+    # Span filtering logic for Braintrust tracing
+    #
+    # Filters allow you to control which spans are exported to Braintrust.
+    # This is useful for reducing noise and cost by filtering out non-AI spans.
+    #
+    # Filter functions take a span and return:
+    #   1 = keep the span
+    #   0 = no influence (continue to next filter)
+    #  -1 = drop the span
+    module SpanFilter
+      # System attributes that should be ignored when checking for AI indicators
+      SYSTEM_ATTRIBUTES = [
+        "braintrust.parent",
+        "braintrust.org",
+        "braintrust.app_url"
+      ].freeze
+
+      # Prefixes that indicate an AI-related span
+      AI_PREFIXES = [
+        "gen_ai.",
+        "braintrust.",
+        "llm.",
+        "ai.",
+        "traceloop."
+      ].freeze
+
+      # AI span filter that keeps spans with AI-related names or attributes
+      #
+      # @param span [OpenTelemetry::SDK::Trace::SpanData] The span to filter
+      # @return [Integer] 1 to keep, -1 to drop, 0 for no influence
+      def self.ai_filter(span)
+        # Check span name for AI prefixes
+        span_name = span.name
+        AI_PREFIXES.each do |prefix|
+          return 1 if span_name.start_with?(prefix)
+        end
+
+        # Check attributes for AI prefixes (skip system attributes)
+        # span.attributes returns a hash
+        attributes = span.attributes || {}
+        attributes.each do |attr_key, _attr_value|
+          attr_key_str = attr_key.to_s
+          next if SYSTEM_ATTRIBUTES.include?(attr_key_str)
+
+          AI_PREFIXES.each do |prefix|
+            return 1 if attr_key_str.start_with?(prefix)
+          end
+        end
+
+        # Drop non-AI spans
+        -1
+      end
+    end
+  end
+end

data/lib/braintrust/trace/span_processor.rb

@@ -5,14 +5,16 @@ require "opentelemetry/sdk"
 module Braintrust
   module Trace
     # Custom span processor that adds Braintrust-specific attributes to spans
+    # and optionally filters spans based on custom filter functions.
     class SpanProcessor
       PARENT_ATTR_KEY = "braintrust.parent"
       ORG_ATTR_KEY = "braintrust.org"
       APP_URL_ATTR_KEY = "braintrust.app_url"
 
-      def initialize(wrapped_processor, state)
+      def initialize(wrapped_processor, state, filters = [])
         @wrapped = wrapped_processor
         @state = state
+        @filters = filters || []
       end
 
       def on_start(span, parent_context)
@@ -33,9 +35,10 @@ module Braintrust
         @wrapped.on_start(span, parent_context)
       end
 
-      # Called when a span ends
+      # Called when a span ends - apply filters before forwarding
       def on_finish(span)
-        @wrapped.on_finish(span)
+        # Only forward span if it passes filters
+        @wrapped.on_finish(span) if should_forward_span?(span)
       end
 
       # Shutdown the processor
@@ -73,6 +76,29 @@ module Braintrust
         # Return the parent attribute from the parent span
         parent_span.attributes&.[](PARENT_ATTR_KEY)
       end
+
+      # Determine if a span should be forwarded to the wrapped processor
+      # based on configured filters
+      def should_forward_span?(span)
+        # Always keep root spans (spans with no parent)
+        # Check if parent_span_id is the invalid/zero span ID
+        is_root = span.parent_span_id == OpenTelemetry::Trace::INVALID_SPAN_ID
+        return true if is_root
+
+        # If no filters, keep everything
+        return true if @filters.empty?
+
+        # Apply filters in order - first non-zero result wins
+        @filters.each do |filter|
+          result = filter.call(span)
+          return true if result > 0  # Keep span
+          return false if result < 0 # Drop span
+          # result == 0: no influence, continue to next filter
+        end
+
+        # All filters returned 0 (no influence), default to keep
+        true
+      end
     end
   end
 end

data/lib/braintrust/trace.rb

@@ -3,6 +3,7 @@
 require "opentelemetry/sdk"
 require "opentelemetry/exporter/otlp"
 require_relative "trace/span_processor"
+require_relative "trace/span_filter"
 require_relative "logger"
 
 # OpenAI integration is optional - automatically loaded if openai gem is available
@@ -13,13 +14,22 @@ rescue LoadError
   # OpenAI gem not installed - integration will not be available
 end
 
+# Anthropic integration is optional - automatically loaded if anthropic gem is available
+begin
+  require "anthropic"
+  require_relative "trace/contrib/anthropic"
+rescue LoadError
+  # Anthropic gem not installed - integration will not be available
+end
+
 module Braintrust
   module Trace
     # Set up OpenTelemetry tracing with Braintrust
     # @param state [State] Braintrust state
     # @param tracer_provider [TracerProvider, nil] Optional tracer provider
+    # @param exporter [Exporter, nil] Optional exporter override (for testing)
     # @return [void]
-    def self.setup(state, tracer_provider = nil)
+    def self.setup(state, tracer_provider = nil, exporter: nil)
       if tracer_provider
         # Use the explicitly provided tracer provider
         # DO NOT set as global - user is managing it themselves
@@ -41,13 +51,17 @@ module Braintrust
       end
 
       # Enable Braintrust tracing (adds span processor)
-      enable(tracer_provider, state: state)
+      config = state.config
+      enable(tracer_provider, state: state, config: config, exporter: exporter)
     end
 
-    def self.enable(tracer_provider, state: nil, exporter: nil)
+    def self.enable(tracer_provider, state: nil, exporter: nil, config: nil)
       state ||= Braintrust.current_state
       raise Error, "No state available" unless state
 
+      # Get config from state if available
+      config ||= state.respond_to?(:config) ? state.config : nil
+
       # Create OTLP HTTP exporter unless override provided
       exporter ||= OpenTelemetry::Exporter::OTLP::Exporter.new(
         endpoint: "#{state.api_url}/otel/v1/traces",
@@ -56,11 +70,18 @@ module Braintrust
         }
       )
 
-      # Wrap in batch processor
-      batch_processor = OpenTelemetry::SDK::Trace::Export::BatchSpanProcessor.new(exporter)
+      # Use SimpleSpanProcessor for InMemorySpanExporter (testing), BatchSpanProcessor for production
+      span_processor = if exporter.is_a?(OpenTelemetry::SDK::Trace::Export::InMemorySpanExporter)
+        OpenTelemetry::SDK::Trace::Export::SimpleSpanProcessor.new(exporter)
+      else
+        OpenTelemetry::SDK::Trace::Export::BatchSpanProcessor.new(exporter)
+      end
+
+      # Build filters array from config
+      filters = build_filters(config)
 
-      # Wrap batch processor in our custom span processor to add Braintrust attributes
-      processor = SpanProcessor.new(batch_processor, state)
+      # Wrap span processor in our custom span processor to add Braintrust attributes and filters
+      processor = SpanProcessor.new(span_processor, state, filters)
 
       # Register with tracer provider
       tracer_provider.add_span_processor(processor)
@@ -75,6 +96,25 @@ module Braintrust
       self
     end
 
+    # Build filters array from config
+    # @param config [Config, nil] Configuration object
+    # @return [Array<Proc>] Array of filter functions
+    def self.build_filters(config)
+      filters = []
+
+      # Add custom filters first (they have priority)
+      if config&.span_filter_funcs&.any?
+        filters.concat(config.span_filter_funcs)
+      end
+
+      # Add AI filter if enabled
+      if config&.filter_ai_spans
+        filters << SpanFilter.method(:ai_filter)
+      end
+
+      filters
+    end
+
     # Generate a permalink URL for a span to view in the Braintrust UI
     # Returns an empty string if the permalink cannot be generated
     # @param span [OpenTelemetry::Trace::Span] The span to generate a permalink for

data/lib/braintrust/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Braintrust
-  VERSION = "0.0.2"
+  VERSION = "0.0.4"
 end

data/lib/braintrust.rb

@@ -37,8 +37,11 @@ module Braintrust
   # @param blocking_login [Boolean] Whether to block and login synchronously (default: false - async background login)
   # @param enable_tracing [Boolean] Whether to enable OpenTelemetry tracing (default: true)
   # @param tracer_provider [TracerProvider, nil] Optional tracer provider to use instead of creating one
+  # @param filter_ai_spans [Boolean, nil] Enable AI span filtering (overrides BRAINTRUST_OTEL_FILTER_AI_SPANS env var)
+  # @param span_filter_funcs [Array<Proc>, nil] Custom span filter functions
+  # @param exporter [Exporter, nil] Optional exporter override (for testing)
   # @return [State] the created state
-  def self.init(api_key: nil, org_name: nil, default_project: nil, app_url: nil, api_url: nil, set_global: true, blocking_login: false, enable_tracing: true, tracer_provider: nil)
+  def self.init(api_key: nil, org_name: nil, default_project: nil, app_url: nil, api_url: nil, set_global: true, blocking_login: false, enable_tracing: true, tracer_provider: nil, filter_ai_spans: nil, span_filter_funcs: nil, exporter: nil)
     state = State.from_env(
       api_key: api_key,
       org_name: org_name,
@@ -47,7 +50,10 @@ module Braintrust
       api_url: api_url,
       blocking_login: blocking_login,
       enable_tracing: enable_tracing,
-      tracer_provider: tracer_provider
+      tracer_provider: tracer_provider,
+      filter_ai_spans: filter_ai_spans,
+      span_filter_funcs: span_filter_funcs,
+      exporter: exporter
     )
 
     State.global = state if set_global

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: braintrust
 version: !ruby/object:Gem::Version
-  version: 0.0.2
+  version: 0.0.4
 platform: ruby
 authors:
 - Braintrust
@@ -202,7 +202,10 @@ files:
 - lib/braintrust/logger.rb
 - lib/braintrust/state.rb
 - lib/braintrust/trace.rb
+- lib/braintrust/trace/attachment.rb
+- lib/braintrust/trace/contrib/anthropic.rb
 - lib/braintrust/trace/contrib/openai.rb
+- lib/braintrust/trace/span_filter.rb
 - lib/braintrust/trace/span_processor.rb
 - lib/braintrust/version.rb
 homepage: https://github.com/braintrustdata/braintrust-sdk-ruby