Class: RubyLLM::Rerank

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

Overview

A Rerank is the result of ordering documents by relevance to a query. RubyLLM.rerank returns one:

rerank = RubyLLM.rerank("what is ruby",
                      ["Ruby is a programming language", "Paris is in France"],
                      model: "voyageai/rerank-2.5-lite", provider: :openrouter)
rerank.results.first.document # => "Ruby is a programming language"
rerank.results.first.score    # => 0.80078125

Defined Under Namespace

Classes: Result

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(results:, model:, raw: nil, input_tokens: nil, reported_cost: nil) ⇒ Rerank

:nodoc:



30
31
32
33
34
35
36
 
# File 'lib/ruby_llm/rerank.rb', line 30

def initialize(results:, model:, raw: nil, input_tokens: nil, reported_cost: nil) # :nodoc:
  @results = results
  @model = model
  @raw = raw
  @input_tokens = input_tokens
  @reported_cost = reported_cost
end

Instance Attribute Details

#model ⇒ Object (readonly)

The id of the model that ranked the documents, as a String.



25
26
27
 
# File 'lib/ruby_llm/rerank.rb', line 25

def model
  @model
end

#raw ⇒ Object (readonly)

The raw provider response body.



28
29
30
 
# File 'lib/ruby_llm/rerank.rb', line 28

def raw
  @raw
end

#results ⇒ Object (readonly)

The reranked results, most relevant first, as an array of Result.



22
23
24
 
# File 'lib/ruby_llm/rerank.rb', line 22

def results
  @results
end

Class Method Details

.rerank(query, documents, model:, provider: nil, assume_model_exists: false, context: nil, top_n: nil, provider_options: {}, metadata: nil) ⇒ Object

Ranks documents (an array of strings) by relevance to query and returns a Rerank. model: is required; rerank catalogs are provider-specific and have no cross-provider default. top_n: limits how many results come back. provider_options: merges options into the request in the provider's vocabulary.

RubyLLM.rerank "what is ruby", docs, model: "voyageai/rerank-2.5-lite", provider: :openrouter


70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
 
# File 'lib/ruby_llm/rerank.rb', line 70

def self.rerank(query, documents,
                model:,
                provider: nil,
                assume_model_exists: false,
                context: nil,
                top_n: nil,
                provider_options: {},
                metadata: nil)
  config = context&.config || RubyLLM.config
  model, provider_instance = Models.resolve(model, provider: provider, assume_model_exists: assume_model_exists,
                                                   config: config)
  empty_tokens = Tokens.new
  payload = {
    provider: provider_instance.slug,
    provider_class: provider_instance.name,
    model: model.id,
    model_info: model,
    query: query,
    document_count: documents.length,
    top_n: top_n,
    provider_options: provider_options,
    metadata: metadata,
    tokens: empty_tokens,
    cost: Cost.new(tokens: empty_tokens, model:, category: :embeddings)
  }

  RubyLLM.instrument('rerank.ruby_llm', payload, config: config) do |event|
    result = provider_instance.rerank(query, documents, model:, top_n:, provider_options:)
    event[:result] = result
    event[:tokens] = result.tokens
    event[:cost] = result.cost
    result
  end
end

Instance Method Details

#cost ⇒ Object

Returns the rerank cost across every provider attempt.



46
47
48
49
50
 
# File 'lib/ruby_llm/rerank.rb', line 46

def cost
  return ruby_llm_usage_cost unless ruby_llm_usage_entries.empty?

  Cost.new(tokens:, model: model_info, category: :embeddings)
end

#inspect_attributes ⇒ Object

:nodoc:



58
59
60
 
# File 'lib/ruby_llm/rerank.rb', line 58

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

#model_info ⇒ Object

:nodoc:



52
53
54
55
56
 
# File 'lib/ruby_llm/rerank.rb', line 52

def model_info # :nodoc:
  @model_info ||= RubyLLM.models.find(model)
rescue ModelNotFoundError
  nil
end

#tokens ⇒ Object

Returns usage aggregated across every provider attempt.



39
40
41
42
43
 
# File 'lib/ruby_llm/rerank.rb', line 39

def tokens
  return ruby_llm_usage_tokens unless ruby_llm_usage_entries.empty?

  Tokens.new(input: @input_tokens, reported_cost: @reported_cost)
end