braintrust 0.0.12 → 0.1.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 4a4dd86789a3ce80b891b88fb9b125bb7b6d85e86928adeb5fd7c1fec671ff56
-  data.tar.gz: 171fe031f960d0a6f3abbfacbb20094b35bcd9199cf132e30063868807f95f8b
+  metadata.gz: 40d5c41ef999d495f9eb7b3a4cd41f1bb9ee7ba831de2074195a7d9e18da2e3a
+  data.tar.gz: 8e48aee25cd02a4b936da1264a9964097c6e07744faf0564d81885daa72b87da
 SHA512:
-  metadata.gz: 3cf52e457ca5d4cdad2f8873bb45d0eeb0b79b33c5edbcd467e65ce7261caea9bcc86ea9d562835197279105f14f2787bcac6622faad4ec420a5f2fa27a003d2
-  data.tar.gz: 5a7ccc20a3e63840e15c41dd82eaa8653a2f0dce693321e6527ace59c54255524ae1d794d2dce058127b747a514e8777729384cde9c157374039880bb3b01013
+  metadata.gz: 9391f2dcec3c92e032d3e7009ec4bf1d26f6d2a606f0edad78acf78078f116393d95a4a3d70a08010b89df214f92498905c67cd02b3bd6327b5aa2cbf1dda872
+  data.tar.gz: 5665f9bcb49a8b5ca90f5d58d9c279120a053756c6ec03ba17557b6064c7a7142ac9674789fe4c89df70e2ac61d1d1ce9318a33b897b55da1d45b9bc9df1bf15

data/README.md

@@ -4,282 +4,316 @@
 [![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
+This is the official Ruby SDK for [Braintrust](https://www.braintrust.dev), for tracing and evaluating your AI applications.
+
+*NOTE: This SDK is currently in BETA status and APIs may change between minor versions.*
+
+- [Quick Start](#quick-start)
+- [Installation](#installation)
+  - [Setup script](#setup-script)
+  - [CLI Command](#cli-command)
+  - [Braintrust.init](#braintrustinit)
+  - [Environment variables](#environment-variables)
+- [Tracing](#tracing)
+  - [Supported providers](#supported-providers)
+  - [Manually applying instrumentation](#manually-applying-instrumentation)
+  - [Creating custom spans](#creating-custom-spans)
+  - [Attachments](#attachments)
+  - [Viewing traces](#viewing-traces)
+- [Evals](#evals)
+  - [Datasets](#datasets)
+  - [Remote scorers](#remote-scorers)
+- [Documentation](#documentation)
+- [Troubleshooting](#troubleshooting)
+- [Contributing](#contributing)
+- [License](#license)
 
-This library provides tools for **evaluating** and **tracing** AI applications in [Braintrust](https://www.braintrust.dev). Use it to:
-
-- **Evaluate** your AI models with custom test cases and scoring functions
-- **Trace** LLM calls and monitor AI application performance with OpenTelemetry
-- **Integrate** seamlessly with OpenAI and other LLM providers
-
-This SDK is currently in BETA status and APIs may change.
-
-## Installation
+## Quick Start
 
-Add this line to your application's Gemfile:
+Add to your Gemfile:
 
 ```ruby
-gem 'braintrust'
+gem "braintrust", require: "braintrust/setup"
 ```
 
-And then execute:
+Set your API key and install:
 
 ```bash
+export BRAINTRUST_API_KEY="your-api-key"
 bundle install
 ```
 
-Or install it yourself as:
+Your LLM calls are now automatically traced. View them at [braintrust.dev](https://www.braintrust.dev).
 
-```bash
-gem install braintrust
-```
+## Installation
 
-## Quick Start
+The SDK also offers additional setup options for a variety of applications.
 
-### Set up your API key
+|                                        | What it looks like                  | When to Use                                                                 |
+| -------------------------------------- | ----------------------------------- | --------------------------------------------------------------------------- |
+| [**Setup script**](#setup-script)      | `require 'braintrust/setup'`        | You'd like to automatically setup the SDK at load time.                     |
+| [**CLI command**](#cli-command)        | `braintrust exec -- ruby app.rb`    | You prefer not to modify the application source code.                       |
+| [**Braintrust.init**](#braintrustinit) | Call `Braintrust.init` in your code | You need to control when setup occurs, or require customized configuration. |
 
-```bash
-export BRAINTRUST_API_KEY="your-api-key"
-```
+See [our examples](./examples/setup/README.md) for more detail.
 
-### Evals
+### Setup script
 
-```ruby
-require "braintrust"
+For most applications, we recommend adding `require: "braintrust/setup"` to your `Gemfile` or an initializer file in your Ruby application to automatically setup the SDK. This will automatically apply instrumentation to all available LLM libraries.
 
-Braintrust.init
+You can use [environment variables](#environment-variables) to configure behavior.
 
-# Define task to evaluate
-task = ->(input) { input.include?("a") ? "fruit" : "vegetable" }
+### CLI Command
 
-# Run evaluation
-Braintrust::Eval.run(
-  project: "my-project",
-  experiment: "food-classifier",
-  cases: [
-    {input: "apple", expected: "fruit"},
-    {input: "carrot", expected: "vegetable"}
-  ],
-  task: task,
-  scorers: [
-    ->(input, expected, output) { output == expected ? 1.0 : 0.0 }
-  ]
-)
+You can use this CLI command to instrument any Ruby application without modifying the source code.
+
+First, make sure the gem is installed on the system:
+
+```bash
+gem install braintrust
 ```
 
-### Tracing
+Then wrap the start up command of any Ruby application to apply:
 
-```ruby
-require "braintrust"
-require "opentelemetry/sdk"
+```bash
+braintrust exec -- ruby app.rb
+braintrust exec -- bundle exec rails server
+braintrust exec --only openai -- ruby app.rb
+```
 
-# Initialize Braintrust
-Braintrust.init
+You can use [environment variables](#environment-variables) to configure behavior.
 
-# Get a tracer
-tracer = OpenTelemetry.tracer_provider.tracer("my-app")
+---
 
-# Create spans to track operations
-tracer.in_span("process-data") do |span|
-  span.set_attribute("user.id", "123")
-  span.set_attribute("operation.type", "data_processing")
+*NOTE: Installing a package at the system-level does not guarantee compatibility with all Ruby applications on that system; conflicts with dependencies can arise.*
 
-  # Your code here
-  puts "Processing data..."
-  sleep 0.1
+For stronger assurance of compatibility, we recommend either:
 
-  # Nested spans are automatically linked
-  tracer.in_span("nested-operation") do |nested_span|
-    nested_span.set_attribute("step", "1")
-    puts "Nested operation..."
-  end
-end
+- Installing via the application's `Gemfile` and `bundle install` when possible.
+- **OR** for OCI/Docker deployments, `gem install braintrust` when building images in your CI/CD pipeline (and verifying their safe function.)
 
-# Shutdown to flush spans
-OpenTelemetry.tracer_provider.shutdown
+---
 
-puts "View trace in Braintrust!"
-```
+### Braintrust.init
 
-### OpenAI Tracing
+For more control over when auto-instrumentation is applied:
 
 ```ruby
 require "braintrust"
-require "openai"
 
 Braintrust.init
+```
 
-client = OpenAI::Client.new(api_key: ENV["OPENAI_API_KEY"])
+**Options:**
 
-Braintrust::Trace::OpenAI.wrap(client)
+| Option            | Default                                  | Description                                                                 |
+| ----------------- | ---------------------------------------- | --------------------------------------------------------------------------- |
+| `api_key`         | `ENV['BRAINTRUST_API_KEY']`              | API key                                                                     |
+| `auto_instrument` | `true`                                   | `true`, `false`, or Hash with `:only`/`:except` keys to filter integrations |
+| `blocking_login`  | `false`                                  | Block until login completes (async login when `false`)                      |
+| `default_project` | `ENV['BRAINTRUST_DEFAULT_PROJECT']`      | Default project for spans                                                   |
+| `enable_tracing`  | `true`                                   | Enable OpenTelemetry tracing                                                |
+| `filter_ai_spans` | `ENV['BRAINTRUST_OTEL_FILTER_AI_SPANS']` | Only export AI-related spans                                                |
+| `org_name`        | `ENV['BRAINTRUST_ORG_NAME']`             | Organization name                                                           |
+| `set_global`      | `true`                                   | Set as global state. Set to `false` for isolated instances                  |
 
-tracer = OpenTelemetry.tracer_provider.tracer("openai-app")
-root_span = nil
+**Example with options:**
 
-response = tracer.in_span("chat-completion") do |span|
-  root_span = span
+```ruby
+Braintrust.init(
+  default_project: "my-project",
+  auto_instrument: { only: [:openai] }
+)
+```
 
-  client.chat.completions.create(
-    messages: [
-      {role: "system", content: "You are a helpful assistant."},
-      {role: "user", content: "Say hello!"}
-    ],
-    model: "gpt-4o-mini",
-    max_tokens: 100
-  )
-end
+### Environment variables
 
-puts "Response: #{response.choices[0].message.content}"
+| Variable                          | Description                                                               |
+| --------------------------------- | ------------------------------------------------------------------------- |
+| `BRAINTRUST_API_KEY`              | Required. Your Braintrust API key                                         |
+| `BRAINTRUST_API_URL`              | Braintrust API URL (default: `https://api.braintrust.dev`)                |
+| `BRAINTRUST_APP_URL`              | Braintrust app URL (default: `https://www.braintrust.dev`)                |
+| `BRAINTRUST_AUTO_INSTRUMENT`      | Set to `false` to disable auto-instrumentation                            |
+| `BRAINTRUST_DEBUG`                | Set to `true` to enable debug logging                                     |
+| `BRAINTRUST_DEFAULT_PROJECT`      | Default project for spans                                                 |
+| `BRAINTRUST_FLUSH_ON_EXIT`        | Set to `false` to disable automatic span flushing on program exit         |
+| `BRAINTRUST_INSTRUMENT_EXCEPT`    | Comma-separated list of integrations to skip                              |
+| `BRAINTRUST_INSTRUMENT_ONLY`      | Comma-separated list of integrations to enable (e.g., `openai,anthropic`) |
+| `BRAINTRUST_ORG_NAME`             | Organization name                                                         |
+| `BRAINTRUST_OTEL_FILTER_AI_SPANS` | Set to `true` to only export AI-related spans                             |
 
-puts "View trace at: #{Braintrust::Trace.permalink(root_span)}"
+## Tracing
 
-OpenTelemetry.tracer_provider.shutdown
-```
+### Supported providers
+
+The SDK automatically instruments these LLM libraries:
 
-### Anthropic Tracing
+| Provider  | Gem           | Versions | Integration Name | Examples                                        |
+| --------- | ------------- | -------- | ---------------- | ----------------------------------------------- |
+| Anthropic | `anthropic`   | >= 0.3.0 | `:anthropic`     | [Link](./examples/contrib/anthropic.rb)   |
+| OpenAI    | `openai`      | >= 0.1.0 | `:openai`        | [Link](./examples/contrib/openai.rb)      |
+|           | `ruby-openai` | >= 7.0.0 | `:ruby_openai`   | [Link](./examples/contrib/ruby-openai.rb) |
+| Multiple  | `ruby_llm`    | >= 1.8.0 | `:ruby_llm`      | [Link](./examples/contrib/ruby_llm.rb)    |
+
+### Manually applying instrumentation
+
+For fine-grained control, disable auto-instrumentation and instrument specific clients:
 
 ```ruby
 require "braintrust"
-require "anthropic"
-
-Braintrust.init
+require "openai"
 
-client = Anthropic::Client.new(api_key: ENV["ANTHROPIC_API_KEY"])
+Braintrust.init(auto_instrument: false) # Or BRAINTRUST_AUTO_INSTRUMENT=false
 
-Braintrust::Trace::Anthropic.wrap(client)
+# Instrument all OpenAI clients
+Braintrust.instrument!(:openai)
 
-tracer = OpenTelemetry.tracer_provider.tracer("anthropic-app")
-root_span = nil
+# OR instrument a single client
+client = OpenAI::Client.new
+Braintrust.instrument!(:openai, target: client)
+```
 
-message = tracer.in_span("chat-message") do |span|
-  root_span = span
+### Creating custom spans
 
-  client.messages.create(
-    model: "claude-3-haiku-20240307",
-    max_tokens: 100,
-    system: "You are a helpful assistant.",
-    messages: [
-      {role: "user", content: "Say hello!"}
-    ]
-  )
-end
+Wrap business logic in spans to see it in your traces:
 
-puts "Response: #{message.content[0].text}"
+```ruby
+tracer = OpenTelemetry.tracer_provider.tracer("my-app")
 
-puts "View trace at: #{Braintrust::Trace.permalink(root_span)}"
+tracer.in_span("process-request") do |span|
+  span.set_attribute("user.id", user_id)
 
-OpenTelemetry.tracer_provider.shutdown
+  # LLM calls inside here are automatically nested under this span
+  response = client.chat.completions.create(...)
+end
 ```
 
-### RubyLLM Tracing
+### Attachments
+
+Log binary data (images, PDFs, audio) in your traces:
 
 ```ruby
-require "braintrust"
-require "ruby_llm"
+require "braintrust/trace/attachment"
 
-Braintrust.init
+att = Braintrust::Trace::Attachment.from_file("image/png", "./photo.png")
 
-# Wrap RubyLLM globally (wraps all Chat instances)
-Braintrust::Trace::Contrib::Github::Crmne::RubyLLM.wrap
+# Use in messages (OpenAI/Anthropic format)
+messages = [
+  {
+    role: "user",
+    content: [
+      {type: "text", text: "What's in this image?"},
+      att.to_h
+    ]
+  }
+]
 
-tracer = OpenTelemetry.tracer_provider.tracer("ruby-llm-app")
-root_span = nil
+# Log to span
+span.set_attribute("braintrust.input_json", JSON.generate(messages))
+```
 
-response = tracer.in_span("chat") do |span|
-  root_span = span
+Create attachments from various sources:
 
-  chat = RubyLLM.chat(model: "gpt-4o-mini")
-  chat.ask("Say hello!")
-end
+```ruby
+Braintrust::Trace::Attachment.from_bytes("image/jpeg", image_data)
+Braintrust::Trace::Attachment.from_file("application/pdf", "./doc.pdf")
+Braintrust::Trace::Attachment.from_url("https://example.com/image.png")
+```
+
+See example: [trace_attachments.rb](./examples/trace/trace_attachments.rb)
 
-puts "Response: #{response.content}"
+### Viewing traces
 
-puts "View trace at: #{Braintrust::Trace.permalink(root_span)}"
+Get a permalink to any span:
 
-OpenTelemetry.tracer_provider.shutdown
+```ruby
+tracer = OpenTelemetry.tracer_provider.tracer("my-app")
+
+tracer.in_span("my-operation") do |span|
+  # your code here
+  puts "View trace at: #{Braintrust::Trace.permalink(span)}"
+end
 ```
 
-### Attachments
+## Evals
 
-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.
+Run evaluations against your AI systems:
 
 ```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:..."}
-      ]
-    }
+Braintrust::Eval.run(
+  project: "my-project",
+  experiment: "classifier-v1",
+  cases: [
+    {input: "apple", expected: "fruit"},
+    {input: "carrot", expected: "vegetable"}
+  ],
+  task: ->(input) { classify(input) },
+  scorers: [
+    ->(input, expected, output) { output == expected ? 1.0 : 0.0 }
   ]
+)
+```
 
-  # Log to trace
-  span.set_attribute("braintrust.input_json", JSON.generate(messages))
-end
+### Datasets
+
+Load test cases from a Braintrust dataset:
 
-OpenTelemetry.tracer_provider.shutdown
+```ruby
+Braintrust::Eval.run(
+  project: "my-project",
+  dataset: "my-dataset",
+  task: ->(input) { classify(input) },
+  scorers: [...]
+)
 ```
 
-You can create attachments from bytes, files, or URLs:
+### Remote scorers
+
+Use scoring functions defined in Braintrust:
 
 ```ruby
-# From bytes
-att = Braintrust::Trace::Attachment.from_bytes("image/jpeg", image_data)
+Braintrust::Eval.run(
+  project: "my-project",
+  cases: [...],
+  task: ->(input) { ... },
+  scorers: [
+    Braintrust::Scorer.remote("my-project", "accuracy-scorer")
+  ]
+)
+```
 
-# From file
-att = Braintrust::Trace::Attachment.from_file("application/pdf", "./doc.pdf")
+See examples: [eval.rb](./examples/eval.rb), [dataset.rb](./examples/eval/dataset.rb), [remote_functions.rb](./examples/eval/remote_functions.rb)
 
-# From URL
-att = Braintrust::Trace::Attachment.from_url("https://example.com/image.png")
-```
+## Documentation
 
-## Features
+- [Braintrust Documentation](https://www.braintrust.dev/docs)
+- [API Reference](https://gemdocs.org/gems/braintrust/)
 
-- **Evaluations**: Run systematic evaluations of your AI systems with custom scoring functions
-- **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
+## Troubleshooting
 
-## Examples
+#### No traces after adding `require 'braintrust/setup'` to the Gemfile
 
-Check out the [`examples/`](./examples/) directory for complete working examples:
+First verify there are no errors in your logs after running with `BRAINTRUST_DEBUG=true` set.
 
-- [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
-- [alexrudall_openai.rb](./examples/alexrudall_openai.rb) - Automatically trace ruby-openai gem API calls
-- [anthropic.rb](./examples/anthropic.rb) - Automatically trace Anthropic API calls
-- [ruby_llm.rb](./examples/ruby_llm.rb) - Automatically trace RubyLLM 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
+Your application needs the following for this to work:
 
-## Documentation
+```ruby
+require 'bundler/setup'
+Bundler.require
+```
 
-- [Braintrust Documentation](https://www.braintrust.dev/docs)
-- [API Documentation](https://gemdocs.org/gems/braintrust/)
+It is present by default in Rails applications, but may not be in Sinatra, Rack, or other applications.
+
+Alternatively, you can add `require 'braintrust/setup'` to your application initialization files.
 
 ## Contributing
 
-See [CONTRIBUTING.md](./CONTRIBUTING.md) for development setup and contribution guidelines.
+See [CONTRIBUTING.md](./CONTRIBUTING.md) for development setup and guidelines.
 
 ## License
 
-This project is licensed under the Apache License 2.0. See the [LICENSE](./LICENSE) file for details.
+Apache License 2.0 - see [LICENSE](./LICENSE).

data/exe/braintrust

@@ -0,0 +1,143 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# Braintrust CLI - Auto-instrument Ruby applications
+#
+# Usage:
+#   braintrust exec -- ruby app.rb
+#   braintrust exec -- bundle exec rails server
+#   braintrust exec --only openai,anthropic -- ruby app.rb
+
+require "optparse"
+
+module Braintrust
+  module CLI
+    class << self
+      def run(args)
+        command = parse_args(args)
+
+        case command
+        when :exec
+          exec_command
+        when :help, nil
+          print_help
+          exit((command == :help) ? 0 : 1)
+        else
+          puts "Unknown command: #{command}"
+          print_help
+          exit 1
+        end
+      end
+
+      private
+
+      def parse_args(args)
+        @options = {}
+        @remaining_args = []
+
+        # Find -- separator
+        separator_index = args.index("--")
+        if separator_index
+          to_parse = args[0...separator_index]
+          @remaining_args = args[(separator_index + 1)..]
+        else
+          to_parse = args.dup
+        end
+
+        parser = OptionParser.new do |opts|
+          opts.banner = "Usage: braintrust <command> [options] -- COMMAND"
+
+          opts.on("--only INTEGRATIONS", "Only instrument these (comma-separated)") do |v|
+            @options[:only] = v
+          end
+
+          opts.on("--except INTEGRATIONS", "Skip these integrations (comma-separated)") do |v|
+            @options[:except] = v
+          end
+
+          opts.on("-h", "--help", "Show this help") do
+            return :help
+          end
+
+          opts.on("-v", "--version", "Show version") do
+            require_relative "../lib/braintrust/version"
+            puts "braintrust #{Braintrust::VERSION}"
+            exit 0
+          end
+        end
+
+        parser.parse!(to_parse)
+
+        return nil if to_parse.empty?
+        to_parse.first.to_sym
+      end
+
+      def exec_command
+        if @remaining_args.empty?
+          puts "Error: No command specified after --"
+          puts "Usage: braintrust exec [options] -- COMMAND"
+          exit 1
+        end
+
+        # Set environment variables for filtering
+        ENV["BRAINTRUST_INSTRUMENT_ONLY"] = @options[:only] if @options[:only]
+        ENV["BRAINTRUST_INSTRUMENT_EXCEPT"] = @options[:except] if @options[:except]
+
+        # Inject auto-instrument via RUBYOPT
+        set_rubyopt!
+
+        # Execute the command with error handling
+        exec_with_error_handling(@remaining_args)
+      end
+
+      def rubyopts
+        ["-rbraintrust/setup"]
+      end
+
+      def set_rubyopt!
+        existing = ENV["RUBYOPT"]
+        ENV["RUBYOPT"] = existing ? "#{existing} #{rubyopts.join(" ")}" : rubyopts.join(" ")
+      end
+
+      def exec_with_error_handling(args)
+        Kernel.exec(*args)
+      rescue Errno::ENOENT => e
+        Kernel.warn "braintrust exec failed: #{e.class.name} #{e.message}"
+        Kernel.exit 127
+      rescue Errno::EACCES, Errno::ENOEXEC => e
+        Kernel.warn "braintrust exec failed: #{e.class.name} #{e.message}"
+        Kernel.exit 126
+      end
+
+      def print_help
+        puts <<~HELP
+          Braintrust CLI - Auto-instrument Ruby applications
+
+          Usage:
+            braintrust exec [options] -- COMMAND
+
+          Commands:
+            exec    Run a command with auto-instrumentation enabled
+
+          Options:
+            --only INTEGRATIONS     Only instrument these (comma-separated)
+            --except INTEGRATIONS   Skip these integrations (comma-separated)
+            -h, --help              Show this help
+            -v, --version           Show version
+
+          Examples:
+            braintrust exec -- ruby app.rb
+            braintrust exec -- rails server
+            braintrust exec --only openai -- ruby app.rb
+
+          Environment Variables:
+            BRAINTRUST_API_KEY              API key for Braintrust
+            BRAINTRUST_INSTRUMENT_ONLY      Comma-separated whitelist
+            BRAINTRUST_INSTRUMENT_EXCEPT    Comma-separated blacklist
+        HELP
+      end
+    end
+  end
+end
+
+Braintrust::CLI.run(ARGV)

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

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+# Backward compatibility shim for the old Anthropic integration API.
+# This file now just delegates to the new API.
+
+require_relative "../../../braintrust"
+
+module Braintrust
+  module Trace
+    module Anthropic
+      # Wrap an Anthropic::Client to automatically create spans for messages.
+      # This is the legacy API - delegates to the new contrib framework.
+      #
+      # @param client [Anthropic::Client] the Anthropic client to wrap
+      # @param tracer_provider [OpenTelemetry::SDK::Trace::TracerProvider] the tracer provider
+      # @return [Anthropic::Client] the wrapped client
+      def self.wrap(client, tracer_provider: nil)
+        Log.warn("Braintrust::Trace::Anthropic.wrap() is deprecated and will be removed in a future version: use Braintrust.instrument!() instead.")
+        Braintrust.instrument!(:anthropic, target: client, tracer_provider: tracer_provider)
+        client
+      end
+    end
+  end
+end