braintrust 0.0.1.alpha.2 → 0.0.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 2f2fd3e289b473dc2f40c2fe9df914c1b1b7ee2ac06db54656fa24eb06a3ff5a
-  data.tar.gz: 562aadfd39d224e5052685ed73c4f2a504db4df01fd26445bf4b0411a8987bb5
+  metadata.gz: be1db72d5636027cfb0b1744e0c30ac9b7169b7f898d4a911639d9f437e0654a
+  data.tar.gz: 725708134bfa2a8d12a3fb0c74e9a54f97afe2f249ed6e3d26184cc5c97a3775
 SHA512:
-  metadata.gz: db90cc0be88cd3c5a88b59d0b87829c88cec76f15bb1213840efb239474a389c95be62ba41efcdb0b87e069845f71873ee7cfefc224e2ba1d4e5d7affbd536a3
-  data.tar.gz: 8ff1ace52cc31b7feae57c557e029f09f8fd811cc2163fb042a5b9e9965b6a9eef2f00e9c543d5c177ec52b04163b119bb5c68dfb57d73d72d7dc63b2974f213
+  metadata.gz: 85cda56b35738299973d2d58a001c9cb746c168437de56e9cf443a2787728dc98014b2b63cf5d6f0d781b8d5c443feedc42dab5abaae2827b60f1c80eb38329a
+  data.tar.gz: e99f24f4cfabbffbdc21822e35145794ccdf29bd22d2e47889dfaab30b4428b49ae173c3ad3e12c4fc7169e3a61ed493670c55bacacd25a800c5df28dc68269f

data/LICENSE

@@ -0,0 +1,201 @@
+Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright 2025 Braintrust
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

data/README.md

@@ -1,24 +1,196 @@
 # Braintrust Ruby SDK
 
-Ruby SDK for [Braintrust](https://www.braintrust.dev) - AI evaluation and observability platform.
+[![Gem Version](https://badge.fury.io/rb/braintrust.svg)](https://badge.fury.io/rb/braintrust)
+![Beta](https://img.shields.io/badge/status-beta-yellow)
 
-## Status
+## Overview
 
-🚧 Under active development
+This library provides tools for **evaluating** and **tracing** AI applications in [Braintrust](https://www.braintrust.dev). Use it to:
 
-## Development
+- **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
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'braintrust'
+```
+
+And then execute:
 
 ```bash
-./scripts/install-deps.sh
-mise install
-cp .env.example .env
-rake test
+bundle install
 ```
 
-## License
+Or install it yourself as:
+
+```bash
+gem install braintrust
+```
+
+## Quick Start
+
+### Set up your API key
+
+```bash
+export BRAINTRUST_API_KEY="your-api-key"
+```
+
+### Evals
+
+```ruby
+require "braintrust"
+
+# Initialize Braintrust
+Braintrust.init
+
+# Simple food classifier (the code being evaluated)
+def classify_food(input)
+  fruit = %w[apple banana strawberry orange grape mango]
+  vegetable = %w[carrot broccoli spinach potato tomato cucumber]
+
+  input_lower = input.downcase
+  return "fruit" if fruit.any? { |f| input_lower.include?(f) }
+  return "vegetable" if vegetable.any? { |v| input_lower.include?(v) }
+  "unknown"
+end
+
+# Run an evaluation
+result = Braintrust::Eval.run(
+  project: "my-project",
+  experiment: "food-classifier-eval",
+
+  # Test cases
+  cases: [
+    {input: "apple", expected: "fruit"},
+    {input: "carrot", expected: "vegetable"},
+    {input: "banana", expected: "fruit"},
+    {input: "broccoli", expected: "vegetable"}
+  ],
+
+  # Task to evaluate
+  task: ->(input) { classify_food(input) },
+
+  # Scorers to judge output quality
+  scorers: [
+    Braintrust::Eval.scorer("exact_match") { |input, expected, output|
+      (output == expected) ? 1.0 : 0.0
+    }
+  ]
+)
+
+# View results
+puts "View results at: #{result.permalink}"
+```
+
+### Tracing
+
+```ruby
+require "braintrust"
+require "opentelemetry/sdk"
+
+# Initialize Braintrust
+Braintrust.init
 
-Apache-2.0
+# 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")
+
+  # Your code here
+  puts "Processing data..."
+  sleep 0.1
+
+  # Nested spans are automatically linked
+  tracer.in_span("nested-operation") do |nested_span|
+    nested_span.set_attribute("step", "1")
+    puts "Nested operation..."
+  end
+end
+
+# Shutdown to flush spans
+OpenTelemetry.tracer_provider.shutdown
+
+puts "View trace in Braintrust!"
+```
+
+### OpenAI Tracing
+
+```ruby
+require "braintrust"
+require "openai"
+
+# Initialize Braintrust
+Braintrust.init
+
+# Create OpenAI client
+client = OpenAI::Client.new(api_key: ENV["OPENAI_API_KEY"])
+
+# Wrap the client with Braintrust tracing
+Braintrust::Trace::OpenAI.wrap(client)
+
+# Create a root span to capture the operation
+tracer = OpenTelemetry.tracer_provider.tracer("openai-app")
+root_span = nil
+
+# Make a chat completion request (automatically traced!)
+response = tracer.in_span("chat-completion") do |span|
+  root_span = span
+
+  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
+
+puts "Response: #{response.choices[0].message.content}"
+
+# View the trace
+puts "View trace at: #{Braintrust::Trace.permalink(root_span)}"
+
+# Shutdown to flush spans
+OpenTelemetry.tracer_provider.shutdown
+```
+
+## Features
+
+- **Evaluations**: Run systematic evaluations of your AI systems with custom scoring functions
+- **Tracing**: Automatic instrumentation for OpenAI 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
+
+## Examples
+
+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
+- [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)
 
 ## Contributing
 
-See [CONTRIBUTING.md](CONTRIBUTING.md)
+See [CONTRIBUTING.md](./CONTRIBUTING.md) for development setup and contribution guidelines.
+
+## License
+
+This project is licensed under the Apache License 2.0. See the [LICENSE](./LICENSE) file for details.

data/lib/braintrust/api/internal/auth.rb

@@ -26,6 +26,17 @@ module Braintrust
         # @return [AuthResult] org info
         # @raise [Braintrust::Error] if login fails
         def self.login(api_key:, app_url:, org_name: nil)
+          # Test mode: return fake auth for test API key
+          if api_key == "test-api-key"
+            Log.debug("Login: using test API key, returning fake auth")
+            return AuthResult.new(
+              org_id: "test-org-id",
+              org_name: org_name || "test-org",
+              api_url: "https://api.ruby-sdk-fixture.com",
+              proxy_url: "https://proxy.ruby-sdk-fixture.com"
+            )
+          end
+
           masked_key = mask_api_key(api_key)
           Log.debug("Login: attempting login with API key #{masked_key}, org #{org_name.inspect}, app URL #{app_url}")
 

data/lib/braintrust/config.rb

@@ -4,12 +4,12 @@ module Braintrust
   # Configuration object that reads from environment variables
   # and allows overriding with explicit options
   class Config
-    attr_reader :api_key, :org_name, :default_parent, :app_url, :api_url
+    attr_reader :api_key, :org_name, :default_project, :app_url, :api_url
 
-    def initialize(api_key: nil, org_name: nil, default_parent: nil, app_url: nil, api_url: nil)
+    def initialize(api_key: nil, org_name: nil, default_project: nil, app_url: nil, api_url: nil)
       @api_key = api_key
       @org_name = org_name
-      @default_parent = default_parent
+      @default_project = default_project
       @app_url = app_url
       @api_url = api_url
     end
@@ -20,7 +20,7 @@ module Braintrust
       defaults = {
         api_key: ENV["BRAINTRUST_API_KEY"],
         org_name: ENV["BRAINTRUST_ORG_NAME"],
-        default_parent: ENV["BRAINTRUST_DEFAULT_PROJECT"],
+        default_project: ENV["BRAINTRUST_DEFAULT_PROJECT"],
         app_url: ENV["BRAINTRUST_APP_URL"] || "https://www.braintrust.dev",
         api_url: ENV["BRAINTRUST_API_URL"] || "https://api.braintrust.dev"
       }

data/lib/braintrust/state.rb

@@ -6,12 +6,12 @@ module Braintrust
   # State object that holds Braintrust configuration
   # Thread-safe global state management
   class State
-    attr_reader :api_key, :org_name, :org_id, :default_parent, :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
 
     @mutex = Mutex.new
     @global_state = nil
 
-    def initialize(api_key: nil, org_name: nil, org_id: nil, default_parent: nil, app_url: nil, api_url: nil, proxy_url: nil, logged_in: false)
+    def initialize(api_key: nil, org_name: nil, org_id: nil, default_project: nil, app_url: nil, api_url: nil, proxy_url: nil, logged_in: false)
       # Instance-level mutex for thread-safe login
       @login_mutex = Mutex.new
       raise ArgumentError, "api_key is required" if api_key.nil? || api_key.empty?
@@ -19,7 +19,7 @@ module Braintrust
       @api_key = api_key
       @org_name = org_name
       @org_id = org_id
-      @default_parent = default_parent
+      @default_project = default_project
       @app_url = app_url || "https://www.braintrust.dev"
       @api_url = api_url
       @proxy_url = proxy_url

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

@@ -0,0 +1,528 @@
+# frozen_string_literal: true
+
+require "opentelemetry/sdk"
+require "json"
+
+module Braintrust
+  module Trace
+    module OpenAI
+      # 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 OpenAI API response, handling nested token_details
+      # Maps OpenAI field names to Braintrust standard names:
+      # - input_tokens → prompt_tokens
+      # - output_tokens → completion_tokens
+      # - total_tokens → tokens
+      # - *_tokens_details.* → prefix_*
+      #
+      # @param usage [Hash, Object] usage object from OpenAI 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
+
+        usage_hash.each do |key, value|
+          key_str = key.to_s
+
+          # Handle nested *_tokens_details objects
+          if key_str.end_with?("_tokens_details")
+            # Convert to hash if it's an object (OpenAI gem returns objects)
+            details_hash = value.respond_to?(:to_h) ? value.to_h : value
+            next unless details_hash.is_a?(Hash)
+
+            # Extract prefix (e.g., "prompt" from "prompt_tokens_details")
+            prefix = key_str.sub(/_tokens_details$/, "")
+            # Translate "input" → "prompt", "output" → "completion"
+            prefix = translate_metric_prefix(prefix)
+
+            # Process nested fields (e.g., cached_tokens, reasoning_tokens)
+            details_hash.each do |detail_key, detail_value|
+              next unless detail_value.is_a?(Numeric)
+              metrics["#{prefix}_#{detail_key}"] = detail_value.to_i
+            end
+          elsif value.is_a?(Numeric)
+            # Handle top-level token fields
+            case key_str
+            when "input_tokens"
+              metrics["prompt_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
+        end
+
+        metrics
+      end
+
+      # Translate metric prefix to be consistent between different API formats
+      # @param prefix [String] the prefix to translate
+      # @return [String] translated prefix
+      def self.translate_metric_prefix(prefix)
+        case prefix
+        when "input"
+          "prompt"
+        when "output"
+          "completion"
+        else
+          prefix
+        end
+      end
+
+      # Aggregate streaming chunks into a single response structure
+      # Follows the Go SDK logic for aggregating deltas
+      # @param chunks [Array<Hash>] array of chunk hashes from stream
+      # @return [Hash] aggregated response with choices, usage, etc.
+      def self.aggregate_streaming_chunks(chunks)
+        return {} if chunks.empty?
+
+        # Initialize aggregated structure
+        aggregated = {
+          id: nil,
+          created: nil,
+          model: nil,
+          system_fingerprint: nil,
+          choices: [],
+          usage: nil
+        }
+
+        # Track aggregated content and tool_calls for each choice index
+        choice_data = {}
+
+        chunks.each do |chunk|
+          # Capture top-level fields from any chunk that has them
+          aggregated[:id] ||= chunk[:id]
+          aggregated[:created] ||= chunk[:created]
+          aggregated[:model] ||= chunk[:model]
+          aggregated[:system_fingerprint] ||= chunk[:system_fingerprint]
+
+          # Aggregate usage (usually only in last chunk if stream_options.include_usage is set)
+          if chunk[:usage]
+            aggregated[:usage] = chunk[:usage]
+          end
+
+          # Process choices
+          next unless chunk[:choices].is_a?(Array)
+          chunk[:choices].each do |choice|
+            index = choice[:index] || 0
+            choice_data[index] ||= {
+              index: index,
+              role: nil,
+              content: "",
+              tool_calls: [],
+              finish_reason: nil
+            }
+
+            delta = choice[:delta] || {}
+
+            # Aggregate role (set once from first delta that has it)
+            choice_data[index][:role] ||= delta[:role]
+
+            # Aggregate content
+            if delta[:content]
+              choice_data[index][:content] += delta[:content]
+            end
+
+            # Aggregate tool_calls (similar to Go SDK logic)
+            if delta[:tool_calls].is_a?(Array) && delta[:tool_calls].any?
+              delta[:tool_calls].each do |tool_call_delta|
+                # Check if this is a new tool call or continuation
+                if tool_call_delta[:id] && !tool_call_delta[:id].empty?
+                  # New tool call
+                  choice_data[index][:tool_calls] << {
+                    id: tool_call_delta[:id],
+                    type: tool_call_delta[:type],
+                    function: {
+                      name: tool_call_delta.dig(:function, :name) || "",
+                      arguments: tool_call_delta.dig(:function, :arguments) || ""
+                    }
+                  }
+                elsif choice_data[index][:tool_calls].any?
+                  # Continuation - append arguments to last tool call
+                  last_tool_call = choice_data[index][:tool_calls].last
+                  if tool_call_delta.dig(:function, :arguments)
+                    last_tool_call[:function][:arguments] += tool_call_delta[:function][:arguments]
+                  end
+                end
+              end
+            end
+
+            # Capture finish_reason
+            if choice[:finish_reason]
+              choice_data[index][:finish_reason] = choice[:finish_reason]
+            end
+          end
+        end
+
+        # Build final choices array
+        aggregated[:choices] = choice_data.values.sort_by { |c| c[:index] }.map do |choice|
+          message = {
+            role: choice[:role],
+            content: choice[:content].empty? ? nil : choice[:content]
+          }
+
+          # Add tool_calls to message if any
+          message[:tool_calls] = choice[:tool_calls] if choice[:tool_calls].any?
+
+          {
+            index: choice[:index],
+            message: message,
+            finish_reason: choice[:finish_reason]
+          }
+        end
+
+        aggregated
+      end
+
+      # Wrap an OpenAI::Client to automatically create spans for chat completions and responses
+      # Supports both synchronous and streaming requests
+      # @param client [OpenAI::Client] the OpenAI 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 chat completions
+        wrap_chat_completions(client, tracer_provider)
+
+        # Wrap responses API if available
+        wrap_responses(client, tracer_provider) if client.respond_to?(:responses)
+
+        client
+      end
+
+      # Wrap chat completions API
+      # @param client [OpenAI::Client] the OpenAI client
+      # @param tracer_provider [OpenTelemetry::SDK::Trace::TracerProvider] the tracer provider
+      def self.wrap_chat_completions(client, tracer_provider)
+        # Create a wrapper module that intercepts chat.completions.create
+        wrapper = Module.new do
+          define_method(:create) do |**params|
+            tracer = tracer_provider.tracer("braintrust")
+
+            tracer.in_span("openai.chat.completions.create") do |span|
+              # Initialize metadata hash
+              metadata = {
+                "provider" => "openai",
+                "endpoint" => "/v1/chat/completions"
+              }
+
+              # Capture request metadata fields
+              metadata_fields = %i[
+                model frequency_penalty logit_bias logprobs max_tokens n
+                presence_penalty response_format seed service_tier stop
+                stream stream_options temperature top_p top_logprobs
+                tools tool_choice parallel_tool_calls user functions function_call
+              ]
+
+              metadata_fields.each do |field|
+                metadata[field.to_s] = params[field] if params.key?(field)
+              end
+
+              # Set input messages as JSON
+              # Pass through all message fields to preserve tool_calls, tool_call_id, name, etc.
+              if params[:messages]
+                messages_array = params[:messages].map(&:to_h)
+                span.set_attribute("braintrust.input_json", JSON.generate(messages_array))
+              end
+
+              # Call the original method
+              response = super(**params)
+
+              # Set output (choices) as JSON
+              # Use to_h to get the raw structure with all fields (including tool_calls)
+              if response.respond_to?(:choices) && response.choices&.any?
+                choices_array = response.choices.map(&:to_h)
+                span.set_attribute("braintrust.output_json", JSON.generate(choices_array))
+              end
+
+              # Set metrics (token usage with advanced details)
+              if response.respond_to?(:usage) && response.usage
+                metrics = Braintrust::Trace::OpenAI.parse_usage_tokens(response.usage)
+                span.set_attribute("braintrust.metrics", JSON.generate(metrics)) unless metrics.empty?
+              end
+
+              # Add response metadata fields
+              metadata["id"] = response.id if response.respond_to?(:id) && response.id
+              metadata["created"] = response.created if response.respond_to?(:created) && response.created
+              metadata["system_fingerprint"] = response.system_fingerprint if response.respond_to?(:system_fingerprint) && response.system_fingerprint
+              metadata["service_tier"] = response.service_tier if response.respond_to?(:service_tier) && response.service_tier
+
+              # Set metadata ONCE at the end with complete hash
+              span.set_attribute("braintrust.metadata", JSON.generate(metadata))
+
+              response
+            end
+          end
+
+          # Wrap stream_raw for streaming chat completions
+          define_method(:stream_raw) do |**params|
+            tracer = tracer_provider.tracer("braintrust")
+            aggregated_chunks = []
+            metadata = {
+              "provider" => "openai",
+              "endpoint" => "/v1/chat/completions"
+            }
+
+            # Start span with proper context (will be child of current span if any)
+            span = tracer.start_span("openai.chat.completions.create")
+
+            # Capture request metadata fields
+            metadata_fields = %i[
+              model frequency_penalty logit_bias logprobs max_tokens n
+              presence_penalty response_format seed service_tier stop
+              stream stream_options temperature top_p top_logprobs
+              tools tool_choice parallel_tool_calls user functions function_call
+            ]
+
+            metadata_fields.each do |field|
+              metadata[field.to_s] = params[field] if params.key?(field)
+            end
+            metadata["stream"] = true  # Explicitly mark as streaming
+
+            # Set input messages as JSON
+            if params[:messages]
+              messages_array = params[:messages].map(&:to_h)
+              span.set_attribute("braintrust.input_json", JSON.generate(messages_array))
+            end
+
+            # Set initial metadata
+            span.set_attribute("braintrust.metadata", JSON.generate(metadata))
+
+            # Call the original stream_raw method with error handling
+            begin
+              stream = super(**params)
+            rescue => e
+              # Record exception if stream creation fails
+              span.record_exception(e)
+              span.status = ::OpenTelemetry::Trace::Status.error("OpenAI API error: #{e.message}")
+              span.finish
+              raise
+            end
+
+            # Wrap the stream to aggregate chunks
+            original_each = stream.method(:each)
+            stream.define_singleton_method(:each) do |&block|
+              original_each.call do |chunk|
+                aggregated_chunks << chunk.to_h
+                block&.call(chunk)
+              end
+            rescue => e
+              # Record exception if streaming fails
+              span.record_exception(e)
+              span.status = ::OpenTelemetry::Trace::Status.error("Streaming error: #{e.message}")
+              raise
+            ensure
+              # Always aggregate whatever chunks we collected and finish span
+              # This runs on normal completion, break, or exception
+              unless aggregated_chunks.empty?
+                aggregated_output = Braintrust::Trace::OpenAI.aggregate_streaming_chunks(aggregated_chunks)
+                Braintrust::Trace::OpenAI.set_json_attr(span, "braintrust.output_json", aggregated_output[:choices])
+
+                # Set metrics if usage is included (requires stream_options.include_usage)
+                if aggregated_output[:usage]
+                  metrics = Braintrust::Trace::OpenAI.parse_usage_tokens(aggregated_output[:usage])
+                  Braintrust::Trace::OpenAI.set_json_attr(span, "braintrust.metrics", metrics) unless metrics.empty?
+                end
+
+                # Update metadata with response fields
+                metadata["id"] = aggregated_output[:id] if aggregated_output[:id]
+                metadata["created"] = aggregated_output[:created] if aggregated_output[:created]
+                metadata["model"] = aggregated_output[:model] if aggregated_output[:model]
+                metadata["system_fingerprint"] = aggregated_output[:system_fingerprint] if aggregated_output[:system_fingerprint]
+                Braintrust::Trace::OpenAI.set_json_attr(span, "braintrust.metadata", metadata)
+              end
+
+              span.finish
+            end
+
+            stream
+          end
+        end
+
+        # Prepend the wrapper to the completions resource
+        client.chat.completions.singleton_class.prepend(wrapper)
+      end
+
+      # Wrap responses API
+      # @param client [OpenAI::Client] the OpenAI client
+      # @param tracer_provider [OpenTelemetry::SDK::Trace::TracerProvider] the tracer provider
+      def self.wrap_responses(client, tracer_provider)
+        # Create a wrapper module that intercepts responses.create and responses.stream
+        wrapper = Module.new do
+          # Wrap non-streaming create method
+          define_method(:create) do |**params|
+            tracer = tracer_provider.tracer("braintrust")
+
+            tracer.in_span("openai.responses.create") do |span|
+              # Initialize metadata hash
+              metadata = {
+                "provider" => "openai",
+                "endpoint" => "/v1/responses"
+              }
+
+              # Capture request metadata fields
+              metadata_fields = %i[
+                model instructions modalities tools parallel_tool_calls
+                tool_choice temperature max_tokens top_p frequency_penalty
+                presence_penalty seed user metadata store response_format
+              ]
+
+              metadata_fields.each do |field|
+                metadata[field.to_s] = params[field] if params.key?(field)
+              end
+
+              # Set input as JSON
+              if params[:input]
+                span.set_attribute("braintrust.input_json", JSON.generate(params[:input]))
+              end
+
+              # Call the original method
+              response = super(**params)
+
+              # Set output as JSON
+              if response.respond_to?(:output) && response.output
+                span.set_attribute("braintrust.output_json", JSON.generate(response.output))
+              end
+
+              # Set metrics (token usage)
+              if response.respond_to?(:usage) && response.usage
+                metrics = Braintrust::Trace::OpenAI.parse_usage_tokens(response.usage)
+                span.set_attribute("braintrust.metrics", JSON.generate(metrics)) unless metrics.empty?
+              end
+
+              # Add response metadata fields
+              metadata["id"] = response.id if response.respond_to?(:id) && response.id
+
+              # Set metadata ONCE at the end with complete hash
+              span.set_attribute("braintrust.metadata", JSON.generate(metadata))
+
+              response
+            end
+          end
+
+          # Wrap streaming method
+          define_method(:stream) do |**params|
+            tracer = tracer_provider.tracer("braintrust")
+            aggregated_events = []
+            metadata = {
+              "provider" => "openai",
+              "endpoint" => "/v1/responses",
+              "stream" => true
+            }
+
+            # Start span with proper context
+            span = tracer.start_span("openai.responses.create")
+
+            # Capture request metadata fields
+            metadata_fields = %i[
+              model instructions modalities tools parallel_tool_calls
+              tool_choice temperature max_tokens top_p frequency_penalty
+              presence_penalty seed user metadata store response_format
+            ]
+
+            metadata_fields.each do |field|
+              metadata[field.to_s] = params[field] if params.key?(field)
+            end
+
+            # Set input as JSON
+            if params[:input]
+              span.set_attribute("braintrust.input_json", JSON.generate(params[:input]))
+            end
+
+            # Set initial metadata
+            span.set_attribute("braintrust.metadata", JSON.generate(metadata))
+
+            # Call the original stream method with error handling
+            begin
+              stream = super(**params)
+            rescue => e
+              # Record exception if stream creation fails
+              span.record_exception(e)
+              span.status = ::OpenTelemetry::Trace::Status.error("OpenAI API error: #{e.message}")
+              span.finish
+              raise
+            end
+
+            # Wrap the stream to aggregate events
+            original_each = stream.method(:each)
+            stream.define_singleton_method(:each) do |&block|
+              original_each.call do |event|
+                # Store the actual event object (not converted to hash)
+                aggregated_events << event
+                block&.call(event)
+              end
+            rescue => e
+              # Record exception if streaming fails
+              span.record_exception(e)
+              span.status = ::OpenTelemetry::Trace::Status.error("Streaming error: #{e.message}")
+              raise
+            ensure
+              # Always aggregate whatever events we collected and finish span
+              unless aggregated_events.empty?
+                aggregated_output = Braintrust::Trace::OpenAI.aggregate_responses_events(aggregated_events)
+                Braintrust::Trace::OpenAI.set_json_attr(span, "braintrust.output_json", aggregated_output[:output]) if aggregated_output[:output]
+
+                # Set metrics if usage is included
+                if aggregated_output[:usage]
+                  metrics = Braintrust::Trace::OpenAI.parse_usage_tokens(aggregated_output[:usage])
+                  Braintrust::Trace::OpenAI.set_json_attr(span, "braintrust.metrics", metrics) unless metrics.empty?
+                end
+
+                # Update metadata with response fields
+                metadata["id"] = aggregated_output[:id] if aggregated_output[:id]
+                Braintrust::Trace::OpenAI.set_json_attr(span, "braintrust.metadata", metadata)
+              end
+
+              span.finish
+            end
+
+            stream
+          end
+        end
+
+        # Prepend the wrapper to the responses resource
+        client.responses.singleton_class.prepend(wrapper)
+      end
+
+      # Aggregate responses streaming events into a single response structure
+      # Follows similar logic to Python SDK's _postprocess_streaming_results
+      # @param events [Array] array of event objects from stream
+      # @return [Hash] aggregated response with output, usage, etc.
+      def self.aggregate_responses_events(events)
+        return {} if events.empty?
+
+        # Find the response.completed event which has the final response
+        completed_event = events.find { |e| e.respond_to?(:type) && e.type == :"response.completed" }
+
+        if completed_event&.respond_to?(:response)
+          response = completed_event.response
+          # Convert the response object to a hash-like structure for logging
+          return {
+            id: response.respond_to?(:id) ? response.id : nil,
+            output: response.respond_to?(:output) ? response.output : nil,
+            usage: response.respond_to?(:usage) ? response.usage : nil
+          }
+        end
+
+        # Fallback if no completed event found
+        {}
+      end
+    end
+  end
+end

data/lib/braintrust/trace/span_processor.rb

@@ -51,7 +51,14 @@ module Braintrust
       private
 
       def default_parent
-        @state.default_parent || "project_name:ruby-sdk-default-project"
+        # If default_project is set, format it as "project_name:value"
+        # The default_project should be a plain project name (e.g., "my-project")
+        # not a formatted parent string (e.g., "project_name:my-project")
+        if @state.default_project
+          "project_name:#{@state.default_project}"
+        else
+          "project_name:ruby-sdk-default-project"
+        end
       end
 
       # Get parent attribute from parent span in context

data/lib/braintrust/trace.rb

@@ -3,9 +3,16 @@
 require "opentelemetry/sdk"
 require "opentelemetry/exporter/otlp"
 require_relative "trace/span_processor"
-require_relative "trace/openai"
 require_relative "logger"
 
+# OpenAI integration is optional - automatically loaded if openai gem is available
+begin
+  require "openai"
+  require_relative "trace/contrib/openai"
+rescue LoadError
+  # OpenAI gem not installed - integration will not be available
+end
+
 module Braintrust
   module Trace
     def self.enable(tracer_provider, state: nil, exporter: nil)

data/lib/braintrust/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Braintrust
-  VERSION = "0.0.1.alpha.2"
+  VERSION = "0.0.1"
 end

data/lib/braintrust.rb

@@ -38,7 +38,7 @@ module Braintrust
   # @param tracer_provider [TracerProvider, nil] Optional tracer provider to use instead of creating one
   # @param api_key [String, nil] Braintrust API key (overrides BRAINTRUST_API_KEY env var)
   # @param org_name [String, nil] Organization name (overrides BRAINTRUST_ORG_NAME env var)
-  # @param default_parent [String, nil] Default parent for spans (overrides BRAINTRUST_DEFAULT_PROJECT env var, format: "project_name:my-project" or "project_id:uuid")
+  # @param default_project [String, nil] Default project for spans (overrides BRAINTRUST_DEFAULT_PROJECT env var, format: "project_name:my-project" or "project_id:uuid")
   # @param app_url [String, nil] App URL (overrides BRAINTRUST_APP_URL env var, default: https://www.braintrust.dev)
   # @param api_url [String, nil] API URL (overrides BRAINTRUST_API_URL env var, default: https://api.braintrust.dev)
   # @return [State] the created state
@@ -47,7 +47,7 @@ module Braintrust
     state = State.new(
       api_key: config.api_key,
       org_name: config.org_name,
-      default_parent: config.default_parent,
+      default_project: config.default_project,
       app_url: config.app_url,
       api_url: config.api_url
     )

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: braintrust
 version: !ruby/object:Gem::Version
-  version: 0.0.1.alpha.2
+  version: 0.0.1
 platform: ruby
 authors:
 - Braintrust
@@ -108,19 +108,47 @@ dependencies:
       - !ruby/object:Gem::Version
         version: '0.22'
 - !ruby/object:Gem::Dependency
-  name: openai
+  name: vcr
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '0.34'
+        version: '6.0'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '0.34'
+        version: '6.0'
+- !ruby/object:Gem::Dependency
+  name: webmock
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+- !ruby/object:Gem::Dependency
+  name: appraisal
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.5'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.5'
 description: OpenTelemetry-based SDK for Braintrust with tracing, OpenAI integration,
   and evals
 email:
@@ -129,6 +157,7 @@ executables: []
 extensions: []
 extra_rdoc_files: []
 files:
+- LICENSE
 - README.md
 - lib/braintrust.rb
 - lib/braintrust/api.rb
@@ -146,7 +175,7 @@ files:
 - lib/braintrust/logger.rb
 - lib/braintrust/state.rb
 - lib/braintrust/trace.rb
-- lib/braintrust/trace/openai.rb
+- lib/braintrust/trace/contrib/openai.rb
 - lib/braintrust/trace/span_processor.rb
 - lib/braintrust/version.rb
 homepage: https://github.com/braintrustdata/braintrust-sdk-ruby

data/lib/braintrust/trace/openai.rb

@@ -1,87 +0,0 @@
-# frozen_string_literal: true
-
-require "opentelemetry/sdk"
-require "json"
-
-module Braintrust
-  module Trace
-    module OpenAI
-      # Wrap an OpenAI::Client to automatically create spans for chat completions
-      # @param client [OpenAI::Client] the OpenAI 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
-
-        # Create a wrapper module that intercepts chat.completions.create
-        wrapper = Module.new do
-          define_method(:create) do |**params|
-            tracer = tracer_provider.tracer("braintrust")
-
-            tracer.in_span("openai.chat.completions.create") do |span|
-              # Initialize metadata hash
-              metadata = {
-                "provider" => "openai",
-                "endpoint" => "/v1/chat/completions"
-              }
-
-              # Capture request metadata fields
-              metadata_fields = %i[
-                model frequency_penalty logit_bias logprobs max_tokens n
-                presence_penalty response_format seed service_tier stop
-                stream stream_options temperature top_p top_logprobs
-                tools tool_choice parallel_tool_calls user functions function_call
-              ]
-
-              metadata_fields.each do |field|
-                metadata[field.to_s] = params[field] if params.key?(field)
-              end
-
-              # Set input messages as JSON
-              if params[:messages]
-                messages_array = params[:messages].map do |msg|
-                  {role: msg[:role].to_s, content: msg[:content]}
-                end
-                span.set_attribute("braintrust.input_json", JSON.generate(messages_array))
-              end
-
-              # Call the original method
-              response = super(**params)
-
-              # Set output (choices) as JSON
-              # Use to_h to get the raw structure with all fields (including tool_calls)
-              if response.respond_to?(:choices) && response.choices&.any?
-                choices_array = response.choices.map(&:to_h)
-                span.set_attribute("braintrust.output_json", JSON.generate(choices_array))
-              end
-
-              # Set metrics (token usage)
-              if response.respond_to?(:usage) && response.usage
-                metrics = {}
-                metrics["prompt_tokens"] = response.usage.prompt_tokens if response.usage.prompt_tokens
-                metrics["completion_tokens"] = response.usage.completion_tokens if response.usage.completion_tokens
-                metrics["tokens"] = response.usage.total_tokens if response.usage.total_tokens
-                span.set_attribute("braintrust.metrics", JSON.generate(metrics))
-              end
-
-              # Add response metadata fields
-              metadata["id"] = response.id if response.respond_to?(:id) && response.id
-              metadata["created"] = response.created if response.respond_to?(:created) && response.created
-              metadata["system_fingerprint"] = response.system_fingerprint if response.respond_to?(:system_fingerprint) && response.system_fingerprint
-              metadata["service_tier"] = response.service_tier if response.respond_to?(:service_tier) && response.service_tier
-
-              # 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 completions resource
-        client.chat.completions.singleton_class.prepend(wrapper)
-
-        client
-      end
-    end
-  end
-end