class RubyLLM::OCR

An OCR is the text a document AI model extracted from a file. RubyLLM.ocr returns one. Each page carries the extracted markdown along with any images and tables the provider reports.

ocr = RubyLLM.ocr("contract.pdf")
ocr.markdown             # => "# Contract\n\n..."
ocr.pages.first.markdown # => "# Contract\n..."

Constants

Page: One page of an OCR result: the zero-based page index, the extracted markdown, and the images and tables the provider reports for the page, or nil when it reports none. raw holds the provider’s unmodified page hash, including any fields beyond these.

Attributes

model [R]

The id of the model that performed the OCR.

raw [R]

The provider’s raw response hash.

Public Class Methods

ocr (file, model: nil, provider: nil, assume_model_exists: false, context: nil, pages: nil, provider_options: {}, metadata: nil)

Source

# File lib/ruby_llm/ocr.rb, line 51
def self.ocr(file,
             model: nil,
             provider: nil,
             assume_model_exists: false,
             context: nil,
             pages: nil,
             provider_options: {},
             metadata: nil)
  config = context&.config || RubyLLM.config
  model ||= config.default_ocr_model
  model, provider_instance = Models.resolve(model, provider: provider, assume_model_exists: assume_model_exists,
                                                   config: config)
  payload = {
    provider: provider_instance.slug,
    provider_class: provider_instance.class.display_name,
    model: model.id,
    model_info: model,
    pages: pages,
    provider_options: provider_options,
    metadata: metadata
  }

  RubyLLM.instrument('ocr.ruby_llm', payload, config: config) do |event|
    result = provider_instance.ocr(file, model:, pages:, provider_options:)
    event[:result] = result
    event[:response_model] = result.model
    result
  end
end

Extracts the text of file and returns an OCR result. Most code calls this through RubyLLM.ocr. The file may be a path, URL, IO object, or Attachment; accepted document and image formats depend on the provider.

model: selects the OCR model and defaults to the configured default_ocr_model. provider: forces a specific provider, and assume_model_exists: skips the registry lookup. context: supplies a Context whose configuration replaces the global one. metadata: is included in the instrumentation payload. pages: limits the read to the given zero-based page indexes. provider_options: merges options into the request in the provider’s own vocabulary, such as Mistral’s include_image_base64: or table_format:.

RubyLLM.ocr("report.pdf")
RubyLLM.ocr("https://example.com/scan.png")
RubyLLM.ocr("report.pdf", pages: [0, 1], provider_options: { table_format: "html" })

Raises RubyLLM::ModelNotFoundError if model: is not in the registry, and RubyLLM::Error when the provider has no OCR support.

Public Instance Methods

markdown ()

Source

# File lib/ruby_llm/ocr.rb, line 104
def markdown
  pages.filter_map(&:markdown).join("\n\n")
end

Returns the markdown of every page, joined with blank lines.

pages ()

Source

# File lib/ruby_llm/ocr.rb, line 89
def pages
  @pages ||= @page_hashes.map.with_index do |page, position|
    next page if page.is_a?(Page)

    Page.new(
      index: page['index'] || position,
      markdown: page['markdown'],
      images: page['images'],
      tables: page['tables'],
      raw: page
    )
  end
end

Returns the pages of the document as an array of Page structs.