File Upload/Download (to support Batches)

[toddkummer]

What this does

This adds the ability to upload and download files, with only the OpenAI provider supported. This feature is a building block for the Batches API, which requires files to be uploaded and downloaded (for OpenAI Batches).

The logic could be simplified a bit and contained within the Batches functionality, but given that it is a provider supported endpoint it seemed to make sense to support it.

OpenAI Files API Documenation

Uploading Files

This adds a convenience method to the RubyLLM module to upload files:

uploaded = RubyLLM.upload_file(
  "spec/fixtures/openai_batch.jsonl",
  provider: :openai,
  purpose: "batch"
)

puts uploaded.id
puts uploaded.filename
puts uploaded.byte_size
puts uploaded.created_at

This delegates to the new ProviderFile class. (That name was chosen to avoid conflicts with File.) The ProviderFile class follows the convention of having a class method to invoke the logic and being the model instantiated to handle the response.

The ProviderFile#file_info method also returns an instance of the ProviderFile class. That method is not exposed through the RubyLLM module. (It just didn't feel important enough.)

Downloading Files

The RubyLLM module also includes a convenience method to download files:

saved_path = RubyLLM.download_file(
  "file_123",
  provider: :openai,
  path: "tmp/downloaded.jsonl"
)

puts saved_path

There are a number of ways to download a file.

Type of change

• Bug fix
• New feature
• Breaking change
• Documentation
• Performance improvement

Scope check

• I read the Contributing Guide
• This aligns with RubyLLM's focus on LLM communication
• This isn't application-specific logic that belongs in user code
• This benefits most users, not just my specific use case

Required for new features

• I opened an issue before writing code and received maintainer approval
  • Only sort of. I asked on an existing issue.
• Linked issue: Batch Request Support for Cost Optimization #1

PRs for new features or enhancements without a prior approved issue will be closed.

Quality check

• I ran overcommit --install and all hooks pass
• I tested my changes thoroughly
  • For provider changes: Re-recorded VCR cassettes with bundle exec rake vcr:record[provider_name]
  • All tests pass: bundle exec rspec
  • Manual testing
• I updated documentation if needed
• I didn't modify auto-generated files manually (models.json, aliases.json)

AI-generated code

• I used AI tools to help write this code
• I have reviewed and understand all generated code (required if above is checked)

API changes

• Breaking change
• New public methods/classes
• Changed method signatures
• No API changes