Class: RubyLLM::UploadedFile

Inherits:
Object
  • Object
show all
Includes:
Support::Inspectable
Defined in:
lib/ruby_llm/uploaded_file.rb

Overview

An UploadedFile is the metadata record for a file stored with a provider through its Files API. Upload a file once with ::upload, then reuse its provider id or URI, for example as a chat attachment or in a batch.

file = RubyLLM.upload("batch.jsonl", purpose: "batch")
file.id         # => "file_..."
file.filename   # => "batch.jsonl"
file.byte_size  # => 1234

File ids are provider-owned. Persist #provider alongside #id and pass it back when finding or downloading the file later.

Constant Summary collapse

EXPIRY_MARGIN =

:nodoc:

60

Constants included from Support::Inspectable

Support::Inspectable::TRUNCATE_AT

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Methods included from Support::Inspectable

#full_inspect, #inspect, #pretty_print

Constructor Details

#initialize(id:, **attributes) ⇒ UploadedFile

:nodoc:



61
62
63
64
65
66
67
68
69
70
71
72
73
74
 
# File 'lib/ruby_llm/uploaded_file.rb', line 61

def initialize(id:, **attributes) # :nodoc:
  @id = id
  @provider = attributes[:provider]
  @filename = attributes[:filename]
  @byte_size = attributes[:byte_size]
  @created_at = attributes[:created_at]
  @expires_at = attributes[:expires_at]
  @status = attributes[:status]
  @mime_type = attributes[:mime_type]
  @purpose = attributes[:purpose]
  @uri = attributes[:uri]
  @downloadable = attributes[:downloadable]
  @metadata = attributes[:metadata] || {}
end

Instance Attribute Details

#byte_size ⇒ Object (readonly)

The file size in bytes.



32
33
34
 
# File 'lib/ruby_llm/uploaded_file.rb', line 32

def byte_size
  @byte_size
end

#created_at ⇒ Object (readonly)

The Time the provider stored the file.



35
36
37
 
# File 'lib/ruby_llm/uploaded_file.rb', line 35

def created_at
  @created_at
end

#downloadable ⇒ Object (readonly)

Whether the provider allows downloading the file's content.



56
57
58
 
# File 'lib/ruby_llm/uploaded_file.rb', line 56

def downloadable
  @downloadable
end

#expires_at ⇒ Object (readonly)

The Time the provider will delete the file, or nil if it does not expire.



39
40
41
 
# File 'lib/ruby_llm/uploaded_file.rb', line 39

def expires_at
  @expires_at
end

#filename ⇒ Object (readonly)

The filename reported by the provider.



29
30
31
 
# File 'lib/ruby_llm/uploaded_file.rb', line 29

def filename
  @filename
end

#id ⇒ Object (readonly)

The provider-assigned file identifier, such as "file_...".



23
24
25
 
# File 'lib/ruby_llm/uploaded_file.rb', line 23

def id
  @id
end

#metadata ⇒ Object (readonly)

The raw provider response data for the file, as a Hash.



59
60
61
 
# File 'lib/ruby_llm/uploaded_file.rb', line 59

def metadata
  @metadata
end

#mime_type ⇒ Object (readonly)

The MIME type of the stored file.



45
46
47
 
# File 'lib/ruby_llm/uploaded_file.rb', line 45

def mime_type
  @mime_type
end

#provider ⇒ Object (readonly)

The slug of the provider that stores the file.



26
27
28
 
# File 'lib/ruby_llm/uploaded_file.rb', line 26

def provider
  @provider
end

#purpose ⇒ Object (readonly)

The purpose the file was uploaded for, such as "batch", when the provider tracks one.



49
50
51
 
# File 'lib/ruby_llm/uploaded_file.rb', line 49

def purpose
  @purpose
end

#status ⇒ Object (readonly)

The provider-reported processing status of the file.



42
43
44
 
# File 'lib/ruby_llm/uploaded_file.rb', line 42

def status
  @status
end

#uri ⇒ Object (readonly)

The provider URI for the file, such as a Gemini Files API URI or a gs:// or s3:// location for storage-backed providers.



53
54
55
 
# File 'lib/ruby_llm/uploaded_file.rb', line 53

def uri
  @uri
end

Class Method Details

.download(id, provider: nil, context: nil) ⇒ Object

Downloads the provider file id and returns a DownloadedFile. Also available as RubyLLM.download.

RubyLLM.download(file.id, provider: :openai).save("report.pdf")

Not every provider allows downloads; see #downloadable. Cohere downloads original uploaded bytes when preserved; generated datasets return JSONL and require the optional avro gem.



129
130
131
 
# File 'lib/ruby_llm/uploaded_file.rb', line 129

def self.download(id, provider: nil, context: nil)
  DownloadedFile.new(provider_for(provider, context).download_file(id))
end

.find(id, provider: nil, context: nil) ⇒ Object

Fetches metadata for an existing provider file by id and returns an UploadedFile. When provider: is omitted, the provider of the configured default model is used.

file = RubyLLM::UploadedFile.find("file_123")


117
118
119
 
# File 'lib/ruby_llm/uploaded_file.rb', line 117

def self.find(id, provider: nil, context: nil)
  provider_for(provider, context).find_file(id)
end

.upload(file, provider: nil, context: nil, filename: nil, purpose: nil, expires_in: nil, uri: nil, content_type: nil, provider_options: {}) ⇒ Object

Uploads file to the provider's Files API and returns an UploadedFile. file may be a path, an IO object, or an Attachment. When provider: is omitted, the provider of the configured default model is used. Also available as RubyLLM.upload.

RubyLLM::UploadedFile.upload("document.pdf", provider: :anthropic)
RubyLLM::UploadedFile.upload(io, provider: :openai, purpose: "batch",
                           filename: "batch.jsonl")

OpenAI and Azure require purpose:. Cohere uses purpose: for its dataset type, such as "embed-input". Pass expires_in: as a number of seconds to have the provider delete the file automatically; OpenAI, xAI, and Mistral support it, and Mistral rounds up to whole hours. Storage-backed providers (Vertex AI and Bedrock) store the file at uri: when given, otherwise at a generated object name under the configured bucket. content_type: overrides the MIME type RubyLLM detects. provider_options: carries the rest in the provider's own vocabulary: visibility: on Mistral, display_name: on Gemini.



104
105
106
107
108
109
 
# File 'lib/ruby_llm/uploaded_file.rb', line 104

def self.upload(file, provider: nil, context: nil, filename: nil, purpose: nil, expires_in: nil,
                uri: nil, content_type: nil, provider_options: {})
  options = { filename:, purpose:, expires_in:, uri:, content_type: }.compact
  options[:provider_options] = provider_options unless provider_options.empty?
  provider_for(provider, context).upload_file(file, **options)
end

Instance Method Details

#expired? ⇒ Boolean

Returns true once the provider's retention window for this file has passed or is about to; a file expiring within the next minute cannot safely serve a request. Files without a reported expiry never expire.

Returns:

  • (Boolean) 


81
82
83
 
# File 'lib/ruby_llm/uploaded_file.rb', line 81

def expired?
  !expires_at.nil? && expires_at <= Time.now + EXPIRY_MARGIN
end

#inspect_attributes ⇒ Object

:nodoc:



18
19
20
 
# File 'lib/ruby_llm/uploaded_file.rb', line 18

def inspect_attributes # :nodoc:
  { id: id, provider: provider, filename: filename, byte_size: byte_size }
end