Automatically initialize and instrument with require 'braintrust/setup'

[delner]

Purpose

This PR introduces a new entry point for automatic SDK initialization and LLM library instrumentation. Users can now simply require "braintrust/setup" before their LLM libraries, and instrumentation happens automatically as libraries are loaded - no manual Braintrust.init call needed.

What Changed

Previous Approach (Braintrust.init)

require "braintrust"
require "openai"      # Already loaded
require "anthropic"   # Already loaded

Braintrust.init       # Must call AFTER libraries are loaded

This approach still works, but is less preferential to the...

New Approach (braintrust/setup)

require "braintrust/setup"  # Sets up instrumentation hooks
require "openai"            # Automatically instrumented on load!
require "anthropic"         # Automatically instrumented on load!
# No Braintrust.init needed

Usage Examples

Ruby Application (without Bundler)

# app.rb
require "braintrust/setup"
# Libraries are auto-instrumented as they load

Rails Application (or applications with `require 'bundler/setup')

# Gemfile
gem "braintrust", require: "braintrust/setup"

No additional configuration needed - the Railtie handles everything.

Environment Variables

Variable	Description
BRAINTRUST_API_KEY	Required for tracing to work
BRAINTRUST_AUTO_INSTRUMENT	Set to "false" to disable (default: true)
BRAINTRUST_INSTRUMENT_ONLY	Comma-separated whitelist (e.g., "openai,anthropic")
BRAINTRUST_INSTRUMENT_EXCEPT	Comma-separated blacklist

Architectural Overview

lib/
├── braintrust/
│   ├── setup.rb              # NEW: Top-level entry point
│   └── contrib/
│       ├── setup.rb          # NEW: Require-hook orchestration
│       ├── registry.rb       # MODIFIED: Smarter require path matching
│       └── rails/
│           └── railtie.rb    # NEW: Rails integration via after_initialize

Key Components

1. lib/braintrust/setup.rb - User-facing entry point

   • Calls Braintrust.init automatically
   • Delegates to Contrib::Setup.run! for library instrumentation
   • Auto-runs on require (no explicit call needed)

2. lib/braintrust/contrib/setup.rb - Instrumentation orchestration

   • Detects Rails vs non-Rails environments
   • Non-Rails: Patches Kernel#require to intercept library loads
   • Rails: Defers to Railtie for proper lifecycle integration

3. lib/braintrust/contrib/rails/railtie.rb - Rails integration

   • Uses config.after_initialize hook
   • Calls Braintrust.auto_instrument! after all gems are loaded
   • Respects BRAINTRUST_INSTRUMENT_ONLY / BRAINTRUST_INSTRUMENT_EXCEPT

4. lib/braintrust/contrib/registry.rb - Enhanced matching

   • New gem_entry_point? method prevents false positives
   • Only matches top-level requires (require "anthropic")
   • Ignores internal subpaths (require "ruby_llm/providers/anthropic")

Files Changed

File	Change
lib/braintrust/setup.rb	Added - Main entry point
lib/braintrust/contrib/setup.rb	Added - Require-hook orchestration
lib/braintrust/contrib/rails/railtie.rb	Added - Rails integration
lib/braintrust/contrib/registry.rb	Modified - Smarter path matching
README.md	Modified - Document new usage
test/braintrust/setup_test.rb	Added - Setup entry point tests
test/braintrust/contrib/setup_test.rb	Added - Require-hook tests
test/braintrust/contrib/rails/railtie_test.rb	Added - Rails integration tests
examples/setup/require.rb	Added - Full example
examples/setup/require_minimal.rb	Added - Minimal example