Class: RubyLLM::OCR

Inherits:
Object
  • Object
show all
Includes:
Accounting::Usage::Result, Support::Inspectable
Defined in:
lib/ruby_llm/ocr.rb

Overview

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..."

Defined Under Namespace

Classes: Page

Constant Summary

Constants included from Support::Inspectable

Support::Inspectable::TRUNCATE_AT

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Methods included from Accounting::Usage::Result

#ruby_llm_usage_entries, #ruby_llm_usage_entries=

Methods included from Support::Inspectable

#full_inspect, #inspect, #pretty_print

Constructor Details

#initialize(pages:, model:, usage: nil, raw: nil) ⇒ OCR

:nodoc:



81
82
83
84
85
86
 
# File 'lib/ruby_llm/ocr.rb', line 81

def initialize(pages:, model:, usage: nil, raw: nil) # :nodoc:
  @page_hashes = Array(pages)
  @model = model
  @usage = usage
  @raw = raw
end

Instance Attribute Details

#model ⇒ Object (readonly)

The id of the model that performed the OCR.



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

def model
  @model
end

#raw ⇒ Object (readonly)

The provider's raw response hash.



30
31
32
 
# File 'lib/ruby_llm/ocr.rb', line 30

def raw
  @raw
end

#usage ⇒ Object (readonly)

The provider's usage block for the request, such as the number of pages processed, or nil when the provider does not report one.



27
28
29
 
# File 'lib/ruby_llm/ocr.rb', line 27

def usage
  @usage
end

Class Method Details

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

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.



51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
 
# 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.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

Instance Method Details

#inspect_attributes ⇒ Object

:nodoc:



108
109
110
 
# File 'lib/ruby_llm/ocr.rb', line 108

def inspect_attributes # :nodoc:
  { model: model, pages: pages.length }
end

#markdown ⇒ Object

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



104
105
106
 
# File 'lib/ruby_llm/ocr.rb', line 104

def markdown
  pages.filter_map(&:markdown).join("\n\n")
end

#pages ⇒ Object

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



89
90
91
92
93
94
95
96
97
98
99
100
101
 
# 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