braintrust 0.1.2 → 0.1.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 626876b443795d28b4ba5d12f8bf10381c3052d5d196adb01207d545303f3d1e
-  data.tar.gz: 347ca89ea9f485ca6521a38c067bdd15074db4e6a4757523901888a8d4cc3e9c
+  metadata.gz: e1a5c8840f707c7b4da95e4ccc8abea32591606d667a309432f2955d5df26eca
+  data.tar.gz: a45e62f34a1d59dd11e1cc46ff8d128a495a45a80fa1ce2026c76b648b58de89
 SHA512:
-  metadata.gz: 7b827a4f92e2bc4b39e41174e62dacdc431fdc0b6c8d13882bdcaaa369af9621174fc01bafa3d0d594b71464ea374c6904e9834631957951dad87d6583a58dc9
-  data.tar.gz: bb6f2d3807765ef4ad591849e0972379fc3f97ef8d90bda0785e1d4dab87ce5e91d954d9d3c8fc7eff6c9295d120d6cbe07acb5bb348873c842d791a3fbdce84
+  metadata.gz: 75b71465a80ed2cfd3c6600113dd62357d01e0bd672f2043045f56d7d0223882cc2c5fd9f8927973ae546f99b68971bbe66fd34d66ec6fd62fafd65ca52abcd7
+  data.tar.gz: 06eb21fec07c05755aacd0a214cd16594f47a7033e723a2798df26692a0c15ccd9d5ed614588cc805620d303bb0f1a1c577c66b25c92c6dbbaa40283023cd662

data/README.md

@@ -22,7 +22,7 @@ This is the official Ruby SDK for [Braintrust](https://www.braintrust.dev), for
   - [Viewing traces](#viewing-traces)
 - [Evals](#evals)
   - [Datasets](#datasets)
-  - [Remote scorers](#remote-scorers)
+  - [Scorers](#scorers)
 - [Documentation](#documentation)
 - [Troubleshooting](#troubleshooting)
 - [Contributing](#contributing)
@@ -260,7 +260,7 @@ Braintrust::Eval.run(
 
 ### Datasets
 
-Load test cases from a Braintrust dataset:
+Use test cases from a Braintrust dataset:
 
 ```ruby
 Braintrust::Eval.run(
@@ -271,7 +271,22 @@ Braintrust::Eval.run(
 )
 ```
 
-### Remote scorers
+Or define test cases inline with metadata and tags:
+
+```ruby
+Braintrust::Eval.run(
+  project: "my-project",
+  experiment: "classifier-v1",
+  cases: [
+    {input: "apple", expected: "fruit", tags: ["produce"], metadata: {difficulty: "easy"}},
+    {input: "salmon", expected: "protein", tags: ["seafood"], metadata: {difficulty: "medium"}}
+  ],
+  task: ->(input) { classify(input) },
+  scorers: [...]
+)
+```
+
+### Scorers
 
 Use scoring functions defined in Braintrust:
 
@@ -281,7 +296,22 @@ Braintrust::Eval.run(
   cases: [...],
   task: ->(input) { ... },
   scorers: [
-    Braintrust::Scorer.remote("my-project", "accuracy-scorer")
+    Braintrust::Eval::Functions.scorer(project: "my-project", slug: "accuracy-scorer")
+  ]
+)
+```
+
+Or define scorers inline with `Eval.scorer`:
+
+```ruby
+Braintrust::Eval.run(
+  project: "my-project",
+  cases: [...],
+  task: ->(input) { ... },
+  scorers: [
+    Braintrust::Eval.scorer("exact_match") do |input, expected, output|
+      output == expected ? 1.0 : 0.0
+    end
   ]
 )
 ```

data/lib/braintrust/api/datasets.rb

@@ -4,6 +4,7 @@ require "net/http"
 require "json"
 require "uri"
 require_relative "../logger"
+require_relative "../internal/http"
 
 module Braintrust
   class API
@@ -85,7 +86,7 @@ module Braintrust
       # @param id [String] Dataset UUID
       # @return [String] Permalink URL
       def permalink(id:)
-        "#{@state.app_url}/app/#{@state.org_name}/object?object_type=dataset&object_id=#{id}"
+        @state.object_permalink(object_type: "dataset", object_id: id)
       end
 
       # Fetch records from dataset using BTQL
@@ -111,6 +112,7 @@ module Braintrust
         payload[:version] = version if version
 
         response = http_post_json_raw("/btql", payload)
+        Braintrust::Internal::Http.decompress_response!(response)
 
         # Parse JSONL response
         records = response.body.lines
@@ -158,9 +160,7 @@ module Braintrust
         start_time = Time.now
         Log.debug("[API] #{method.upcase} #{uri}")
 
-        http = Net::HTTP.new(uri.host, uri.port)
-        http.use_ssl = (uri.scheme == "https")
-        response = http.request(request)
+        response = Braintrust::Internal::Http.with_redirects(uri, request)
 
         duration_ms = ((Time.now - start_time) * 1000).round(2)
         Log.debug("[API] #{method.upcase} #{uri} -> #{response.code} (#{duration_ms}ms, #{response.body.bytesize} bytes)")

data/lib/braintrust/api/functions.rb

@@ -4,6 +4,7 @@ require "net/http"
 require "json"
 require "uri"
 require_relative "../logger"
+require_relative "../internal/http"
 
 module Braintrust
   class API
@@ -242,9 +243,7 @@ module Braintrust
         start_time = Time.now
         Log.debug("[API] #{method.upcase} #{uri}")
 
-        http = Net::HTTP.new(uri.host, uri.port)
-        http.use_ssl = (uri.scheme == "https")
-        response = http.request(request)
+        response = Braintrust::Internal::Http.with_redirects(uri, request)
 
         duration_ms = ((Time.now - start_time) * 1000).round(2)
         Log.debug("[API] #{method.upcase} #{uri} -> #{response.code} (#{duration_ms}ms, #{response.body.bytesize} bytes)")

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

@@ -4,6 +4,7 @@ require "net/http"
 require "json"
 require "uri"
 require_relative "../../logger"
+require_relative "../../internal/http"
 
 module Braintrust
   class API
@@ -44,12 +45,7 @@ module Braintrust
           request = Net::HTTP::Post.new(uri)
           request["Authorization"] = "Bearer #{api_key}"
 
-          http = Net::HTTP.new(uri.hostname, uri.port)
-          http.use_ssl = true if uri.scheme == "https"
-
-          response = http.start do |http_session|
-            http_session.request(request)
-          end
+          response = Braintrust::Internal::Http.with_redirects(uri, request)
 
           Log.debug("Login: received response [#{response.code}]")
 

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

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+require "net/http"
+require "json"
+require "uri"
+require_relative "../../internal/http"
+
+module Braintrust
+  class API
+    module Internal
+      # Internal Experiments API
+      # Not part of the public API - use through Eval.run
+      class Experiments
+        def initialize(state)
+          @state = state
+        end
+
+        # Create an experiment
+        # POST /v1/experiment
+        # @param name [String] Experiment name
+        # @param project_id [String] Project ID
+        # @param ensure_new [Boolean] If true (default), fail if exists; if false, return existing
+        # @param tags [Array<String>, nil] Optional tags
+        # @param metadata [Hash, nil] Optional metadata
+        # @return [Hash] Experiment data with "id", "name", "project_id", etc.
+        def create(name:, project_id:, ensure_new: true, tags: nil, metadata: nil,
+          dataset_id: nil, dataset_version: nil)
+          uri = URI("#{@state.api_url}/v1/experiment")
+
+          payload = {
+            project_id: project_id,
+            name: name,
+            ensure_new: ensure_new
+          }
+          payload[:tags] = tags if tags
+          payload[:metadata] = metadata if metadata
+          payload[:dataset_id] = dataset_id if dataset_id
+          payload[:dataset_version] = dataset_version if dataset_version
+
+          request = Net::HTTP::Post.new(uri)
+          request["Content-Type"] = "application/json"
+          request["Authorization"] = "Bearer #{@state.api_key}"
+          request.body = JSON.dump(payload)
+
+          response = Braintrust::Internal::Http.with_redirects(uri, request)
+
+          unless response.is_a?(Net::HTTPSuccess)
+            raise Error, "HTTP #{response.code} for POST #{uri}: #{response.body}"
+          end
+
+          JSON.parse(response.body)
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+require "net/http"
+require "json"
+require "uri"
+require_relative "../../internal/http"
+
+module Braintrust
+  class API
+    module Internal
+      # Internal Projects API
+      # Not part of the public API - use through Eval.run
+      class Projects
+        def initialize(state)
+          @state = state
+        end
+
+        # Create or get a project by name (idempotent)
+        # POST /v1/project
+        # @param name [String] Project name
+        # @return [Hash] Project data with "id", "name", "org_id", etc.
+        def create(name:)
+          uri = URI("#{@state.api_url}/v1/project")
+
+          request = Net::HTTP::Post.new(uri)
+          request["Content-Type"] = "application/json"
+          request["Authorization"] = "Bearer #{@state.api_key}"
+          request.body = JSON.dump({name: name})
+
+          response = Braintrust::Internal::Http.with_redirects(uri, request)
+
+          unless response.is_a?(Net::HTTPSuccess)
+            raise Error, "HTTP #{response.code} for POST #{uri}: #{response.body}"
+          end
+
+          JSON.parse(response.body)
+        end
+      end
+    end
+  end
+end

data/lib/braintrust/api.rb

@@ -25,5 +25,22 @@ module Braintrust
     def functions
       @functions ||= API::Functions.new(self)
     end
+
+    # Login to Braintrust API (idempotent)
+    # @return [self]
+    def login
+      @state.login
+      self
+    end
+
+    # Generate a permalink URL to view an object in the Braintrust UI
+    # This is for the /object endpoint (experiments, datasets, etc.)
+    # For trace span permalinks, use Trace.permalink instead.
+    # @param object_type [String] Type of object (e.g., "experiment", "dataset")
+    # @param object_id [String] Object UUID
+    # @return [String] Permalink URL
+    def object_permalink(object_type:, object_id:)
+      @state.object_permalink(object_type: object_type, object_id: object_id)
+    end
   end
 end

data/lib/braintrust/contrib/anthropic/instrumentation/beta_messages.rb

@@ -169,8 +169,8 @@ module Braintrust
               input_messages = []
 
               begin
-                if params[:system]
-                  system_content = params[:system]
+                if params[:system_]
+                  system_content = params[:system_]
                   if system_content.is_a?(Array)
                     system_text = system_content.map { |blk|
                       blk.is_a?(Hash) ? blk[:text] : blk

data/lib/braintrust/contrib/anthropic/instrumentation/messages.rb

@@ -98,8 +98,8 @@ module Braintrust
             def set_input(span, params)
               input_messages = []
 
-              if params[:system]
-                system_content = params[:system]
+              if params[:system_]
+                system_content = params[:system_]
                 if system_content.is_a?(Array)
                   system_text = system_content.map { |blk|
                     blk.is_a?(Hash) ? blk[:text] : blk

data/lib/braintrust/dataset.rb

@@ -0,0 +1,185 @@
+# frozen_string_literal: true
+
+require_relative "api"
+require_relative "internal/origin"
+
+module Braintrust
+  # High-level interface for working with Braintrust datasets.
+  # Provides both eager loading and lazy enumeration for efficient access to dataset records.
+  #
+  # @example Basic usage (uses global state)
+  #   Braintrust.init(api_key: "...")
+  #   dataset = Braintrust::Dataset.new(name: "my-dataset", project: "my-project")
+  #   dataset.each { |record| puts record[:input] }
+  #
+  # @example With explicit API client
+  #   api = Braintrust::API.new(state: my_state)
+  #   dataset = Braintrust::Dataset.new(name: "my-dataset", project: "my-project", api: api)
+  #
+  # @example Eager loading for small datasets
+  #   records = dataset.fetch_all(limit: 100)
+  #
+  # @example Using Enumerable methods
+  #   dataset.take(10)
+  #   dataset.select { |r| r[:tags]&.include?("important") }
+  #
+  # @example With version pinning
+  #   dataset = Braintrust::Dataset.new(name: "my-dataset", project: "my-project", version: "1.0")
+  class Dataset
+    include Enumerable
+
+    # Default number of records to fetch per API page
+    DEFAULT_PAGE_SIZE = 1000
+
+    attr_reader :name, :project, :version
+
+    # Initialize a dataset reference
+    # @param name [String, nil] Dataset name (required if id not provided)
+    # @param id [String, nil] Dataset UUID (required if name not provided)
+    # @param project [String, nil] Project name (required if using name)
+    # @param version [String, nil] Optional version to pin to
+    # @param api [API, nil] Braintrust API client (defaults to API.new using global state)
+    def initialize(name: nil, id: nil, project: nil, version: nil, api: nil)
+      @name = name
+      @provided_id = id
+      @project = project
+      @version = version
+      @api = api || API.new
+      @resolved_id = nil
+      @metadata = nil
+
+      validate_params!
+    end
+
+    # Get the dataset ID, resolving from name if necessary
+    # @return [String] Dataset UUID
+    def id
+      return @provided_id if @provided_id
+      resolve_name! unless @resolved_id
+      @resolved_id
+    end
+
+    # Get the dataset metadata from the API
+    # Makes an API call if metadata hasn't been fetched yet.
+    # Note: When initialized with name, metadata is fetched during name resolution.
+    # When initialized with ID, this triggers a separate get_by_id call.
+    # @return [Hash] Dataset metadata including name, description, created, etc.
+    def metadata
+      fetch_metadata! unless @metadata
+      @metadata
+    end
+
+    # Fetch all records eagerly into an array
+    # @param limit [Integer, nil] Maximum records to return (nil for all)
+    # @return [Array<Hash>] Array of records with :input, :expected, :tags, :metadata, :origin
+    def fetch_all(limit: nil)
+      records = []
+      each_record(limit: limit) { |record| records << record }
+      records
+    end
+
+    # Iterate over records lazily (implements Enumerable)
+    # Fetches pages on demand for memory efficiency with large datasets.
+    # @yield [Hash] Each record with :input, :expected, :tags, :metadata, :origin
+    def each(&block)
+      return enum_for(:each) unless block_given?
+      each_record(&block)
+    end
+
+    private
+
+    def validate_params!
+      if @provided_id.nil? && @name.nil?
+        raise ArgumentError, "must specify either :name or :id"
+      end
+
+      if @name && @project.nil?
+        raise ArgumentError, ":project is required when using :name"
+      end
+    end
+
+    # Resolve dataset name to ID (also fetches metadata as side effect)
+    def resolve_name!
+      @metadata = @api.datasets.get(project_name: @project, name: @name)
+      @resolved_id = @metadata["id"]
+    end
+
+    # Fetch metadata explicitly (for when ID was provided directly)
+    def fetch_metadata!
+      if @provided_id
+        @metadata = @api.datasets.get_by_id(id: @provided_id)
+      else
+        resolve_name! unless @metadata
+      end
+    end
+
+    # Core iteration with pagination
+    # @param limit [Integer, nil] Maximum records to return
+    def each_record(limit: nil, &block)
+      dataset_id = id  # Resolve once
+      cursor = nil
+      count = 0
+
+      loop do
+        page_limit = if limit
+          [DEFAULT_PAGE_SIZE, limit - count].min
+        else
+          DEFAULT_PAGE_SIZE
+        end
+
+        result = @api.datasets.fetch(
+          id: dataset_id,
+          limit: page_limit,
+          cursor: cursor,
+          version: @version
+        )
+
+        result[:records].each do |raw_record|
+          record = build_record(raw_record, dataset_id)
+          block.call(record)
+          count += 1
+          break if limit && count >= limit
+        end
+
+        # Stop if we've hit the limit or no more pages
+        break if limit && count >= limit
+
+        cursor = result[:cursor]
+        break unless cursor
+      end
+    end
+
+    # Build a normalized record hash from raw API response
+    # @param raw [Hash] Raw record from API
+    # @param dataset_id [String] Dataset ID for origin
+    # @return [Hash] Normalized record with origin
+    def build_record(raw, dataset_id)
+      record = {}
+      record[:input] = raw["input"] if raw.key?("input")
+      record[:expected] = raw["expected"] if raw.key?("expected")
+      record[:tags] = raw["tags"] if raw.key?("tags")
+      record[:metadata] = raw["metadata"] if raw.key?("metadata")
+
+      origin = build_origin(raw, dataset_id)
+      record[:origin] = origin if origin
+
+      record
+    end
+
+    # Build origin JSON for tracing/linking
+    # @param raw [Hash] Raw record from API
+    # @param dataset_id [String] Dataset ID (fallback if not in record)
+    # @return [String, nil] JSON-serialized origin, or nil if record lacks required fields
+    def build_origin(raw, dataset_id)
+      return nil unless raw["id"] && raw["_xact_id"]
+
+      Internal::Origin.to_json(
+        object_type: "dataset",
+        object_id: raw["dataset_id"] || dataset_id,
+        id: raw["id"],
+        xact_id: raw["_xact_id"],
+        created: raw["created"]
+      )
+    end
+  end
+end

data/lib/braintrust/eval/case.rb

@@ -7,6 +7,8 @@ module Braintrust
     # @attr expected [Object, nil] The expected output (optional)
     # @attr tags [Array<String>, nil] Optional tags for filtering/grouping
     # @attr metadata [Hash, nil] Optional metadata for the case
-    Case = Struct.new(:input, :expected, :tags, :metadata, keyword_init: true)
+    # @attr origin [Hash, nil] Origin pointer for cases from remote sources (e.g., datasets).
+    #   Contains: object_type, object_id, id, _xact_id, created
+    Case = Struct.new(:input, :expected, :tags, :metadata, :origin, keyword_init: true)
   end
 end

data/lib/braintrust/eval/functions.rb

@@ -98,9 +98,18 @@ module Braintrust
                 # The remote scorer receives all scorer arguments
                 result = api.functions.invoke(id: function_id, input: scorer_input)
 
-                # Parse result as float score
-                # The remote function should return a number
-                score = result.is_a?(Numeric) ? result.to_f : result.to_s.to_f
+                score = case result
+                when Hash
+                  if result.key?("score")
+                    result["score"].to_f
+                  else
+                    raise Error, "Hash result must contain 'score' key"
+                  end
+                when String
+                  result.to_f
+                else
+                  raise Error, "Unsupported result type: #{result.class}"
+                end
 
                 span.set_attribute("braintrust.output_json", JSON.dump(score))
                 score

data/lib/braintrust/eval/runner.rb

@@ -18,14 +18,14 @@ module Braintrust
       MAX_PARALLELISM = Internal::ThreadPool::MAX_PARALLELISM
 
       def initialize(experiment_id:, experiment_name:, project_id:, project_name:,
-        task:, scorers:, state:, tracer_provider: nil)
+        task:, scorers:, api:, tracer_provider: nil)
         @experiment_id = experiment_id
         @experiment_name = experiment_name
         @project_id = project_id
         @project_name = project_name
         @task = task
         @scorers = normalize_scorers(scorers)
-        @state = state
+        @api = api
         @tracer_provider = tracer_provider || OpenTelemetry.tracer_provider
         @tracer = @tracer_provider.tracer("braintrust-eval")
         @parent_attr = "experiment_id:#{experiment_id}"
@@ -61,7 +61,7 @@ module Braintrust
         duration = Time.now - start_time
 
         # Generate permalink
-        permalink = "#{state.app_url}/app/#{state.org_name}/object?object_type=experiment&object_id=#{experiment_id}"
+        permalink = @api.object_permalink(object_type: "experiment", object_id: experiment_id)
 
         Result.new(
           experiment_id: experiment_id,
@@ -78,7 +78,7 @@ module Braintrust
       private
 
       attr_reader :experiment_id, :experiment_name, :project_id, :project_name,
-        :task, :scorers, :state, :tracer, :parent_attr
+        :task, :scorers, :tracer, :parent_attr
 
       # Run a single test case with OpenTelemetry tracing
       # Creates eval span (parent) with task and score as children
@@ -116,6 +116,9 @@ module Braintrust
           set_json_attr(eval_span, "braintrust.input_json", test_case.input)
           set_json_attr(eval_span, "braintrust.output_json", output)
           set_json_attr(eval_span, "braintrust.expected", test_case.expected) if test_case.expected
+
+          # Set origin for cases from remote sources (already JSON-serialized)
+          eval_span.set_attribute("braintrust.origin", test_case.origin) if test_case.origin
         end
       end
 

data/lib/braintrust/eval.rb

@@ -2,7 +2,9 @@
 
 require_relative "eval/scorer"
 require_relative "eval/runner"
-require_relative "internal/experiments"
+require_relative "api/internal/projects"
+require_relative "api/internal/experiments"
+require_relative "dataset"
 
 require "opentelemetry/sdk"
 require "json"
@@ -199,39 +201,53 @@ module Braintrust
       # @param metadata [Hash] Optional experiment metadata
       # @param update [Boolean] If true, allow reusing existing experiment (default: false)
       # @param quiet [Boolean] If true, suppress result output (default: false)
-      # @param state [State, nil] Braintrust state (defaults to global state)
+      # @param api [API, nil] Braintrust API client (defaults to API.new using global state)
       # @param tracer_provider [TracerProvider, nil] OpenTelemetry tracer provider (defaults to global)
       # @return [Result]
       def run(project:, experiment:, task:, scorers:,
         cases: nil, dataset: nil,
         parallelism: 1, tags: nil, metadata: nil, update: false, quiet: false,
-        state: nil, tracer_provider: nil)
+        api: nil, tracer_provider: nil)
         # Validate required parameters
         validate_params!(project: project, experiment: experiment,
           cases: cases, dataset: dataset, task: task, scorers: scorers)
 
-        # Get state from parameter or global
-        state ||= Braintrust.current_state
-        raise Error, "No state available" unless state
+        # Get API from parameter or create from global state
+        api ||= API.new
 
-        # Ensure state is logged in (to populate org_name, etc.)
+        # Ensure logged in (to populate org_name, etc.)
         # login is idempotent and returns early if already logged in
-        state.login
+        api.login
 
         # Resolve dataset to cases if dataset parameter provided
+        dataset_id = nil
+        dataset_version = nil
+
         if dataset
-          cases = resolve_dataset(dataset, project, state)
+          resolved = resolve_dataset(dataset, project, api)
+          cases = resolved[:cases]
+          dataset_id = resolved[:dataset_id]
+          dataset_version = resolved[:dataset_version]
         end
 
-        # Register project and experiment via API
-        result = Internal::Experiments.get_or_create(
-          experiment, project, state: state,
-          tags: tags, metadata: metadata, update: update
+        # Register project and experiment via internal API
+        projects_api = API::Internal::Projects.new(api.state)
+        experiments_api = API::Internal::Experiments.new(api.state)
+
+        project_result = projects_api.create(name: project)
+        experiment_result = experiments_api.create(
+          name: experiment,
+          project_id: project_result["id"],
+          ensure_new: !update,
+          tags: tags,
+          metadata: metadata,
+          dataset_id: dataset_id,
+          dataset_version: dataset_version
         )
 
-        experiment_id = result[:experiment_id]
-        project_id = result[:project_id]
-        project_name = result[:project_name]
+        experiment_id = experiment_result["id"]
+        project_id = project_result["id"]
+        project_name = project_result["name"]
 
         # Instantiate Runner and run evaluation
         runner = Runner.new(
@@ -241,7 +257,7 @@ module Braintrust
           project_name: project_name,
           task: task,
           scorers: scorers,
-          state: state,
+          api: api,
           tracer_provider: tracer_provider
         )
         result = runner.run(cases, parallelism: parallelism)
@@ -284,85 +300,38 @@ module Braintrust
         end
       end
 
-      # Resolve dataset parameter to an array of case records
-      # @param dataset [String, Hash] Dataset specifier
-      # @param project [String] Project name (used as default if not specified in hash)
-      # @param state [State] Braintrust state
-      # @return [Array<Hash>] Array of case records
-      def resolve_dataset(dataset, project, state)
-        require_relative "api"
+      # Resolve dataset parameter to cases with metadata for experiment linking
+      # @param dataset [String, Hash, Dataset] Dataset specifier or instance
+      # @param project [String] Project name (used as default if not specified)
+      # @param api [API] Braintrust API client
+      # @return [Hash] Hash with :cases, :dataset_id, and :dataset_version
+      def resolve_dataset(dataset, project, api)
+        limit = nil
 
-        # Parse dataset parameter
-        dataset_opts = case dataset
+        dataset_obj = case dataset
+        when Dataset
+          dataset
         when String
-          # String: dataset name in same project
-          {name: dataset, project: project}
+          Dataset.new(name: dataset, project: project, api: api)
         when Hash
-          # Hash: explicit options
-          dataset.dup
-        else
-          raise ArgumentError, "dataset must be String or Hash, got #{dataset.class}"
-        end
-
-        # Apply defaults
-        dataset_opts[:project] ||= project
-
-        # Create API client
-        api = API.new(state: state)
-
-        # Resolve dataset ID
-        dataset_id = if dataset_opts[:id]
-          # ID provided directly
-          dataset_opts[:id]
-        elsif dataset_opts[:name]
-          # Fetch by name + project
-          metadata = api.datasets.get(
-            project_name: dataset_opts[:project],
-            name: dataset_opts[:name]
-          )
-          metadata["id"]
+          opts = dataset.dup
+          limit = opts.delete(:limit)
+          opts[:project] ||= project
+          opts[:api] = api
+          Dataset.new(**opts)
         else
-          raise ArgumentError, "dataset hash must specify either :name or :id"
+          raise ArgumentError, "dataset must be String, Hash, or Dataset, got #{dataset.class}"
         end
 
-        # Fetch records with pagination
-        limit_per_page = 1000
-        max_records = dataset_opts[:limit]
-        version = dataset_opts[:version]
-        records = []
-        cursor = nil
-
-        loop do
-          result = api.datasets.fetch(
-            id: dataset_id,
-            limit: limit_per_page,
-            cursor: cursor,
-            version: version
-          )
-
-          records.concat(result[:records])
+        cases = dataset_obj.fetch_all(limit: limit)
 
-          # Check if we've hit the user-specified limit
-          if max_records && records.length >= max_records
-            records = records.take(max_records)
-            break
-          end
+        # Use pinned version if available, otherwise compute from max(_xact_id)
+        version = dataset_obj.version
+        version ||= cases
+          .filter_map { |c| c[:origin] && JSON.parse(c[:origin])["_xact_id"] }
+          .max
 
-          # Check if there's more data
-          cursor = result[:cursor]
-          break unless cursor
-        end
-
-        # Filter records to only include Case-compatible fields
-        # Case accepts: input, expected, tags, metadata
-        records.map do |record|
-          filtered = {}
-          filtered[:input] = record["input"] if record.key?("input")
-          filtered[:expected] = record["expected"] if record.key?("expected")
-          filtered[:tags] = record["tags"] if record.key?("tags")
-          filtered[:metadata] = record["metadata"] if record.key?("metadata")
-          filtered
-        end
+        {cases: cases, dataset_id: dataset_obj.id, dataset_version: version}
       end
     end
   end

data/lib/braintrust/internal/http.rb

@@ -0,0 +1,97 @@
+# frozen_string_literal: true
+
+require "net/http"
+require "uri"
+require "zlib"
+require "stringio"
+require_relative "../logger"
+
+module Braintrust
+  module Internal
+    # HTTP utilities for redirect following and response decompression.
+    # Drop-in enhancement for raw Net::HTTP request calls throughout the SDK.
+    module Http
+      DEFAULT_MAX_REDIRECTS = 5
+
+      # Execute an HTTP request, following redirects as needed.
+      #
+      # @param uri [URI] The request URI
+      # @param request [Net::HTTPRequest] The prepared request object
+      # @param max_redirects [Integer] Maximum number of redirects to follow
+      # @return [Net::HTTPResponse] The final response
+      # @raise [Braintrust::Error] On too many redirects or missing Location header
+      def self.with_redirects(uri, request, max_redirects: DEFAULT_MAX_REDIRECTS)
+        response = perform_request(uri, request)
+
+        redirects = 0
+        original_request = request
+
+        while response.is_a?(Net::HTTPRedirection)
+          redirects += 1
+          if redirects > max_redirects
+            raise Error, "Too many redirects (max #{max_redirects})"
+          end
+
+          location = response["location"]
+          unless location
+            raise Error, "Redirect response #{response.code} without Location header"
+          end
+
+          redirect_uri = URI(location)
+          redirect_uri = uri + redirect_uri unless redirect_uri.host
+
+          Log.debug("[HTTP] Following #{response.code} redirect to #{redirect_uri}")
+
+          request = build_redirect_request(response, redirect_uri, original_request, uri)
+          uri = redirect_uri
+          response = perform_request(uri, request)
+        end
+
+        response
+      end
+
+      # Decompress an HTTP response body in place based on Content-Encoding.
+      # No-op if the response has no recognized encoding.
+      #
+      # @param response [Net::HTTPResponse] The response to decompress
+      # @return [void]
+      def self.decompress_response!(response)
+        encoding = response["content-encoding"]&.downcase
+        case encoding
+        when "gzip", "x-gzip"
+          gz = Zlib::GzipReader.new(StringIO.new(response.body))
+          response.body.replace(gz.read)
+          gz.close
+          response.delete("content-encoding")
+        end
+      end
+
+      def self.perform_request(uri, request)
+        http = Net::HTTP.new(uri.host, uri.port)
+        http.use_ssl = (uri.scheme == "https")
+        http.request(request)
+      end
+      private_class_method :perform_request
+
+      def self.build_redirect_request(response, redirect_uri, original_request, original_uri)
+        if response.code == "307" || response.code == "308"
+          request = original_request.class.new(redirect_uri)
+          request.body = original_request.body
+          request["Content-Type"] = original_request["Content-Type"] if original_request["Content-Type"]
+        else
+          # 301, 302, 303: follow with GET, no body
+          request = Net::HTTP::Get.new(redirect_uri)
+        end
+
+        # Strip Authorization when redirecting to a different host (e.g. S3)
+        if original_uri.host == redirect_uri.host
+          auth = original_request["Authorization"]
+          request["Authorization"] = auth if auth
+        end
+
+        request
+      end
+      private_class_method :build_redirect_request
+    end
+  end
+end

data/lib/braintrust/internal/origin.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+require "json"
+
+module Braintrust
+  module Internal
+    # Origin provides serialization for source object pointers in Braintrust.
+    # Used internally to link spans back to their source records (e.g., dataset rows).
+    module Origin
+      # Serialize an origin pointer to JSON
+      # @param object_type [String] Type of source object (e.g., "dataset", "playground_logs")
+      # @param object_id [String] ID of the source object
+      # @param id [String] ID of the specific record within the source
+      # @param xact_id [String] Transaction ID
+      # @param created [String, nil] Creation timestamp
+      # @return [String] JSON-serialized origin
+      def self.to_json(object_type:, object_id:, id:, xact_id:, created:)
+        JSON.dump({
+          object_type: object_type,
+          object_id: object_id,
+          id: id,
+          _xact_id: xact_id,
+          created: created
+        })
+      end
+    end
+  end
+end

data/lib/braintrust/state.rb

@@ -139,6 +139,16 @@ module Braintrust
       end
     end
 
+    # Generate a permalink URL to view an object in the Braintrust UI
+    # This is for the /object endpoint (experiments, datasets, etc.)
+    # For trace span permalinks, use Trace.permalink instead.
+    # @param object_type [String] Type of object (e.g., "experiment", "dataset")
+    # @param object_id [String] Object UUID
+    # @return [String] Permalink URL
+    def object_permalink(object_type:, object_id:)
+      "#{@app_url}/app/#{@org_name}/object?object_type=#{object_type}&object_id=#{object_id}"
+    end
+
     # Login to Braintrust API in a background thread with retry logic
     # Retries indefinitely with exponential backoff until success
     # Idempotent: returns early if already logged in

data/lib/braintrust/trace/attachment.rb

@@ -2,6 +2,7 @@
 
 require "net/http"
 require_relative "../internal/encoding"
+require_relative "../internal/http"
 require "uri"
 
 module Braintrust
@@ -91,7 +92,8 @@ module Braintrust
       #   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)
+        request = Net::HTTP::Get.new(uri)
+        response = Braintrust::Internal::Http.with_redirects(uri, request)
 
         unless response.is_a?(Net::HTTPSuccess)
           raise StandardError, "Failed to fetch URL: #{response.code} #{response.message}"

data/lib/braintrust/version.rb

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

data/lib/braintrust.rb

@@ -6,7 +6,7 @@ require_relative "braintrust/state"
 require_relative "braintrust/trace"
 require_relative "braintrust/api"
 require_relative "braintrust/prompt"
-require_relative "braintrust/internal/experiments"
+require_relative "braintrust/dataset"
 require_relative "braintrust/internal/env"
 require_relative "braintrust/eval"
 require_relative "braintrust/contrib"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: braintrust
 version: !ruby/object:Gem::Version
-  version: 0.1.2
+  version: 0.1.4
 platform: ruby
 authors:
 - Braintrust
@@ -193,6 +193,8 @@ files:
 - lib/braintrust/api/datasets.rb
 - lib/braintrust/api/functions.rb
 - lib/braintrust/api/internal/auth.rb
+- lib/braintrust/api/internal/experiments.rb
+- lib/braintrust/api/internal/projects.rb
 - lib/braintrust/config.rb
 - lib/braintrust/contrib.rb
 - lib/braintrust/contrib/anthropic/deprecated.rb
@@ -228,6 +230,7 @@ files:
 - lib/braintrust/contrib/setup.rb
 - lib/braintrust/contrib/support/openai.rb
 - lib/braintrust/contrib/support/otel.rb
+- lib/braintrust/dataset.rb
 - lib/braintrust/eval.rb
 - lib/braintrust/eval/case.rb
 - lib/braintrust/eval/cases.rb
@@ -239,7 +242,8 @@ files:
 - lib/braintrust/eval/summary.rb
 - lib/braintrust/internal/encoding.rb
 - lib/braintrust/internal/env.rb
-- lib/braintrust/internal/experiments.rb
+- lib/braintrust/internal/http.rb
+- lib/braintrust/internal/origin.rb
 - lib/braintrust/internal/template.rb
 - lib/braintrust/internal/thread_pool.rb
 - lib/braintrust/internal/time.rb

data/lib/braintrust/internal/experiments.rb

@@ -1,129 +0,0 @@
-# frozen_string_literal: true
-
-require "net/http"
-require "json"
-require "uri"
-require_relative "../logger"
-
-module Braintrust
-  module Internal
-    # Experiments module provides internal API methods for registering projects and experiments
-    # Methods are marked private to prevent direct user access - use through Eval.run
-    module Experiments
-      # Public convenience method to register/get both project and experiment
-      # @param experiment_name [String] The experiment name
-      # @param project_name [String] The project name
-      # @param state [State] Braintrust state with API key and URL
-      # @param tags [Array<String>, nil] Optional experiment tags
-      # @param metadata [Hash, nil] Optional experiment metadata
-      # @param update [Boolean] If true, allow reusing existing experiment (default: false)
-      # @return [Hash] Hash with :experiment_id, :experiment_name, :project_id, :project_name
-      def self.get_or_create(experiment_name, project_name, state:,
-        tags: nil, metadata: nil, update: false)
-        # Register/get project first
-        project = register_project(project_name, state)
-
-        # Then register/get experiment
-        experiment = register_experiment(
-          experiment_name,
-          project["id"],
-          state,
-          tags: tags,
-          metadata: metadata,
-          update: update
-        )
-
-        {
-          experiment_id: experiment["id"],
-          experiment_name: experiment["name"],
-          project_id: project["id"],
-          project_name: project["name"]
-        }
-      end
-
-      # Register or get a project by name
-      # POST /v1/project with {name: "project-name"}
-      # Returns existing project if already exists
-      # @param name [String] Project name
-      # @param state [State] Braintrust state
-      # @return [Hash] Project data with "id", "name", "org_id", etc.
-      # @raise [Braintrust::Error] if API call fails
-      def self.register_project(name, state)
-        Log.debug("Registering project: #{name}")
-
-        uri = URI("#{state.api_url}/v1/project")
-        request = Net::HTTP::Post.new(uri)
-        request["Content-Type"] = "application/json"
-        request["Authorization"] = "Bearer #{state.api_key}"
-        request.body = JSON.dump({name: name})
-
-        http = Net::HTTP.new(uri.hostname, uri.port)
-        http.use_ssl = true if uri.scheme == "https"
-
-        response = http.start do |http_session|
-          http_session.request(request)
-        end
-
-        Log.debug("Register project response: [#{response.code}]")
-
-        # Handle response codes
-        unless response.is_a?(Net::HTTPSuccess)
-          raise Error, "Failed to register project '#{name}': [#{response.code}] #{response.body}"
-        end
-
-        project = JSON.parse(response.body)
-        Log.debug("Project registered: #{project["id"]} (#{project["name"]})")
-        project
-      end
-      private_class_method :register_project
-
-      # Register or get an experiment by name
-      # POST /v1/experiment with {project_id:, name:, ensure_new:, tags:[], metadata:{}}
-      # @param name [String] Experiment name
-      # @param project_id [String] Project ID
-      # @param state [State] Braintrust state
-      # @param tags [Array<String>, nil] Optional tags
-      # @param metadata [Hash, nil] Optional metadata
-      # @param update [Boolean] If true, allow reusing existing experiment (ensure_new: false)
-      # @return [Hash] Experiment data with "id", "name", "project_id", etc.
-      # @raise [Braintrust::Error] if API call fails
-      def self.register_experiment(name, project_id, state, tags: nil, metadata: nil, update: false)
-        Log.debug("Registering experiment: #{name} (project: #{project_id}, update: #{update})")
-
-        uri = URI("#{state.api_url}/v1/experiment")
-        request = Net::HTTP::Post.new(uri)
-        request["Content-Type"] = "application/json"
-        request["Authorization"] = "Bearer #{state.api_key}"
-
-        payload = {
-          project_id: project_id,
-          name: name,
-          ensure_new: !update  # When update=true, allow reusing existing experiment
-        }
-        payload[:tags] = tags if tags
-        payload[:metadata] = metadata if metadata
-
-        request.body = JSON.dump(payload)
-
-        http = Net::HTTP.new(uri.hostname, uri.port)
-        http.use_ssl = true if uri.scheme == "https"
-
-        response = http.start do |http_session|
-          http_session.request(request)
-        end
-
-        Log.debug("Register experiment response: [#{response.code}]")
-
-        # Handle response codes
-        unless response.is_a?(Net::HTTPSuccess)
-          raise Error, "Failed to register experiment '#{name}': [#{response.code}] #{response.body}"
-        end
-
-        experiment = JSON.parse(response.body)
-        Log.debug("Experiment registered: #{experiment["id"]} (#{experiment["name"]})")
-        experiment
-      end
-      private_class_method :register_experiment
-    end
-  end
-end