module RubyLLM::FileStore::Converters

Converters turn files into text the model can read and search. A converter is any object that answers call with an Attachment and returns the file’s text, or nil when it cannot read that file, so the next converter gets a turn. FileStore#text tries the converters in Configuration#file_converters first, then reads text files, including source code, CSV, JSON, and Markdown, as they are.

Converters::Office reads Word, Excel, and PowerPoint files without any setup. The OCR converter reads PDFs, scans, and photos with RubyLLM.ocr. It costs a request per file, so it only runs where you register it. Converters::Text reads a file as it is, for other types that hold plain text.

A converter that answers local? with true reads files on this machine for free, so a chat runs it as soon as it keeps an attachment, while it prepares the request, so keep it fast, and search_files finds the text without a read_file first. The others wait for read_file, or for a request that must send as text a file the provider cannot take.

RubyLLM.configure do |config|
  config.file_converters["image/*"] = RubyLLM::FileStore::Converters::OCR.new
  config.file_converters["application/pdf"] = RubyLLM::FileStore::Converters::OCR.new
  config.file_converters["application/x-subrip"] = RubyLLM::FileStore::Converters::Text
  config.file_converters["application/vnd.oasis.opendocument.text"] = ->(file) { OdtText.call(file.content) }
end

Converters for other formats can ship as gems named ruby_llm-converters-NAME, like provider gems.