class RubyLLM::Attachment

An Attachment is a file sent to the model alongside a message. The source can be a local path, an http(s) URL, an IO-like object, an ActiveStorage object, or a provider-managed UploadedFile. Chat#ask builds attachments for you from its with: option:

chat.ask "What's in this image?", with: "ruby_conf.jpg"

Build one explicitly to return a file from a Tool:

RubyLLM::Attachment.new(doc.download_path)

Constants

DOCUMENT_EXTENSIONS: File extensions recognized as document attachments when the MIME type alone is inconclusive.
PROCESSING_MODES: Video processing modes accepted by processing:.
RESOLUTIONS: Media resolutions accepted by resolution:.

Attributes

filename [R]

The filename given at construction or derived from the source. May be nil.

mime_type [R]

The detected MIME type string, such as "image/png".

processing [R]

How the model reads a video: :static, :agentic, or nil for the provider default.

resolution [R]

The requested media resolution: :low, :medium, :high, :ultra_high, :original, or nil for the provider default.

source [R]

The underlying source: a URI, Pathname, IO-like object, ActiveStorage object, or UploadedFile.

Public Class Methods

new (source, filename: nil, resolution: nil, processing: nil, config: nil)

Source

# File lib/ruby_llm/attachment.rb, line 115
def initialize(source, filename: nil, resolution: nil, processing: nil, config: nil)
  check_option(:resolution, resolution, RESOLUTIONS)
  check_option(:processing, processing, PROCESSING_MODES)

  @config = config
  @resolution = resolution
  @processing = processing
  @source = source
  @source = source_type_cast
  @filename = filename || source_filename

  determine_mime_type
end

Creates an attachment from source: a file path, URL, IO-like object, ActiveStorage object, or UploadedFile. Derives the filename from the source when filename: is not given, then detects the MIME type.

RubyLLM::Attachment.new("diagram.png")
RubyLLM::Attachment.new(StringIO.new(data), filename: "report.pdf")

resolution: asks the provider to spend more or fewer tokens on an image, video, or PDF. :original requests original image detail where supported, or the highest available resolution. Providers without the setting ignore it.

RubyLLM::Attachment.new("page-3.png", resolution: :ultra_high)

processing: chooses how the model reads a video. :static samples frames across the whole video up front. :agentic lets the model navigate a long video and load only the parts it needs. Providers without the setting ignore it.

RubyLLM::Attachment.new("lecture.mp4", processing: :agentic)

config: is the Configuration a URL source is downloaded with. It defaults to that of the chat or operation the attachment is given to, then to the global one.

Paths and URLs must be trusted and authorized by the application. They can be read or fetched during construction to detect the MIME type. Validate upload parameters before passing them here: an unchecked String can access local files or internal network endpoints.

Public Instance Methods

audio? ()

Source

# File lib/ruby_llm/attachment.rb, line 236
def audio?
  RubyLLM::Files::MimeType.audio? mime_type
end

Returns whether the attachment is audio.

content ()

Source

# File lib/ruby_llm/attachment.rb, line 185
def content
  if provider_file?
    raise Error, "Provider-managed file #{provider_file_id} cannot be read as inline attachment content"
  end

  load_content if !defined?(@content) || @content.nil?
  normalize_text_encoding
  @content
end

Returns the raw bytes of the attachment, fetching or reading the source on the first call. Text content is returned as UTF-8.

Raises RubyLLM::Error if the attachment is a provider-managed file, which has no local content.

document? ()

Source

# File lib/ruby_llm/attachment.rb, line 258
def document?
  return false if pdf? || text?

  RubyLLM::Files::MimeType.document?(mime_type) || DOCUMENT_EXTENSIONS.include?(extension)
end

Returns whether the attachment is a non-PDF, non-text document format such as Word or Excel, judged by MIME type or file extension.

image? ()

Source

# File lib/ruby_llm/attachment.rb, line 226
def image?
  RubyLLM::Files::MimeType.image? mime_type
end

Returns whether the attachment is an image.

pdf? ()

Source

# File lib/ruby_llm/attachment.rb, line 252
def pdf?
  RubyLLM::Files::MimeType.pdf? mime_type
end

Returns whether the attachment is a PDF.

text? ()

Source

# File lib/ruby_llm/attachment.rb, line 270
def text?
  RubyLLM::Files::MimeType.text? mime_type
end

Returns whether the attachment is textual, like source code or CSV.

type ()

Source

# File lib/ruby_llm/attachment.rb, line 214
def type
  return :image if image?
  return :video if video?
  return :audio if audio?
  return :pdf if pdf?
  return :text if text?
  return :document if document?

  :unknown
end

Returns the attachment category as a Symbol: :image, :video, :audio, :pdf, :text, :document, or :unknown.

video? ()

Source

# File lib/ruby_llm/attachment.rb, line 231
def video?
  RubyLLM::Files::MimeType.video? mime_type
end

Returns whether the attachment is a video.