Class: Braintrust::Trace::Attachment

Inherits:
Object
  • Object
show all
Defined in:
lib/braintrust/trace/attachment.rb

Overview

Attachment represents binary data (images, audio, PDFs, etc.) that can be logged as part of traces in Braintrust. Attachments are stored securely and can be viewed in the Braintrust UI.

Attachments are particularly useful for multimodal AI applications, such as vision models that process images.

Examples:

Create attachment from file

att = Braintrust::Trace::Attachment.from_file("image/png", "./photo.png")
data_url = att.to_data_url
# => "data:image/png;base64,iVBORw0KGgo..."

Create attachment from bytes

att = Braintrust::Trace::Attachment.from_bytes("image/jpeg", image_bytes)
message = att.to_message
# => {"type" => "base64_attachment", "content" => "data:image/jpeg;base64,..."}

Use in a trace span

att = Braintrust::Trace::Attachment.from_file("image/png", "./photo.png")
messages = [
  {
    role: "user",
    content: [
      {type: "text", text: "What's in this image?"},
      att.to_h  # Converts to {"type" => "base64_attachment", "content" => "..."}
    ]
  }
]
span.set_attribute("braintrust.input_json", JSON.generate(messages))

Constant Summary collapse

IMAGE_PNG =

Common MIME type constants for convenience

"image/png"
IMAGE_JPEG = 
"image/jpeg"
IMAGE_JPG = 
"image/jpg"
IMAGE_GIF = 
"image/gif"
IMAGE_WEBP = 
"image/webp"
TEXT_PLAIN = 
"text/plain"
APPLICATION_PDF = 
"application/pdf"

Class Method Summary collapse

Instance Method Summary collapse

Class Method Details

.from_bytes(content_type, data) ⇒ Attachment

Creates an attachment from raw bytes.

Examples:

image_data = File.binread("photo.png")
att = Braintrust::Trace::Attachment.from_bytes("image/png", image_data)

Parameters:

  • content_type (String) —

    MIME type of the data (e.g., “image/png”)

  • data (String) —

    Binary data as a string

Returns:



64
65
66
 
# File 'lib/braintrust/trace/attachment.rb', line 64

def self.from_bytes(content_type, data)
  new(content_type, data)
end

.from_file(content_type, path) ⇒ Attachment

Creates an attachment by reading from a file.

Examples:

att = Braintrust::Trace::Attachment.from_file("image/png", "./photo.png")

Parameters:

  • content_type (String) —

    MIME type of the file (e.g., “image/png”)

  • path (String) —

    Path to the file to read

Returns:

Raises:

  • (Errno::ENOENT) —

    If the file does not exist



77
78
79
80
 
# File 'lib/braintrust/trace/attachment.rb', line 77

def self.from_file(content_type, path)
  data = File.binread(path)
  new(content_type, data)
end

.from_url(url) ⇒ Attachment

Creates an attachment by fetching data from a URL.

The content type is inferred from the Content-Type header in the HTTP response. If the header is not present, it falls back to “application/octet-stream”.

Examples:

att = Braintrust::Trace::Attachment.from_url("https://example.com/image.png")

Parameters:

  • url (String) —

    URL to fetch

Returns:

Raises:

  • (StandardError) —

    If the HTTP request fails



93
94
95
96
97
98
99
100
101
102
103
104
 
# File 'lib/braintrust/trace/attachment.rb', line 93

def self.from_url(url)
  uri = URI.parse(url)
  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}"
  end

  content_type = response.content_type || "application/octet-stream"
  new(content_type, response.body)
end

Instance Method Details

#to_data_url ⇒ String

Converts the attachment to a data URL format.

Examples:

att = Braintrust::Trace::Attachment.from_bytes("image/png", image_data)
att.to_data_url
# => "data:image/png;base64,iVBORw0KGgo..."

Returns:

  • (String) —

    Data URL in the format “data:<content-type>;base64,<encoded-data>”



114
115
116
117
 
# File 'lib/braintrust/trace/attachment.rb', line 114

def to_data_url
  encoded = Internal::Encoding::Base64.strict_encode64(@data)
  "data:#{@content_type};base64,#{encoded}"
end

#to_message ⇒ Hash Also known as: to_h

Converts the attachment to a message format suitable for LLM APIs.

Examples:

att = Braintrust::Trace::Attachment.from_bytes("image/png", image_data)
att.to_message
# => {"type" => "base64_attachment", "content" => "data:image/png;base64,..."}

Returns:

  • (Hash) —

    Message hash with “type” and “content” keys



127
128
129
130
131
132
 
# File 'lib/braintrust/trace/attachment.rb', line 127

def to_message
  {
    "type" => "base64_attachment",
    "content" => to_data_url
  }
end