Instrument all OpenAI clients with one call

[delner]

Instrument all OpenAI clients with one call

Purpose & Benefits

In the pursuit of an easier setup experience, where before you needed to instrument each individual OpenAI client, this pull request makes it possible to instrument all OpenAI clients with a single call:

# Instrument OpenAI
Braintrust.init
Braintrust::Contrib.instrument!(:openai)

It also supports instrumenting individual clients*, and has backwards compatibility with the wrap API:

# Both calls are equivalent
# New API
Braintrust::Contrib.instrument!(:openai, target: client)
# Old API still works (deprecated)
Braintrust::Trace::OpenAI.wrap(client)

(*) NOTE: Instrumenting both global and client-level is not recommended: although there are some safeguards to check instrumentation state, mixing these can result in double instrumentation (especially instrumenting globally after instrumenting a specific client.) This is due to limitations in Ruby's patching mechanisms.

Design & Key Principles

Architecture (at a glance)

  Braintrust::Contrib
  └── openai/
      ├── instrumentation/      # Contains instrumentation modules
      |       ├── chat.rb       # Chat completions API
      |       └── responses.rb  # Responses API
      ├── integration.rb        # OpenAI integration schema
      └── patcher.rb            # OpenAI patcher

Key Design Decisions

• Leverage new Integration API framework (which will help us further improve auto-instrumentation later)
• Retain backwards compatibility with the old wrap API (for now)
• Check for potential conflicts with ruby-openai (which both use require 'openai')
• Isolate instrumentation into small modules which utilize prepend to patch.

[delner]

Closing this while I reformulate PRs.