Class: RubyLLM::Fallback

Inherits:
Object
  • Object
show all
Includes:
Support::Inspectable
Defined in:
lib/ruby_llm/fallback.rb

Overview

A Fallback is a fallback model target configured with Chat#with_fallbacks. When the active model fails with a matching error, the chat retries the request with each fallback in order. Instances are yielded to Chat#before_fallback and Chat#after_fallback callbacks, enriched with the details of that attempt.

chat = RubyLLM.chat(model: "gpt-4.1")
            .with_fallbacks("gpt-4.1-mini", "claude-haiku-4-5")

chat.before_fallback do |fallback|
puts "Falling back from #{fallback.from.id} to #{fallback.to.id}"
end

chat.after_fallback do |fallback|
puts "Fallback #{fallback.succeeded? ? 'succeeded' : 'failed'}"
end

Constant Summary collapse

DEFAULT_ERRORS =

The error classes that trigger a fallback when Chat#with_fallbacks is called without on:.

[
  RateLimitError,
  ServerError,
  ServiceUnavailableError,
  OverloadedError,
  Faraday::TimeoutError,
  Faraday::ConnectionFailed
].freeze

Constants included from Support::Inspectable

Support::Inspectable::TRUNCATE_AT

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Methods included from Support::Inspectable

#full_inspect, #inspect, #pretty_print

Constructor Details

#initialize(id: nil, provider: nil, model: nil, **attributes) ⇒ Fallback

:nodoc:



85
86
87
88
89
90
91
92
93
94
95
96
97
98
 
# File 'lib/ruby_llm/fallback.rb', line 85

def initialize(id: nil, provider: nil, model: nil, **attributes) # :nodoc:
  @id = id || model&.id
  @provider = (provider || model&.provider)&.to_s
  @model = model
  @chat = attributes[:chat]
  @error = attributes[:error]
  @from = attributes[:from]
  @to = attributes[:to]
  @attempt = attributes[:attempt]
  @streaming = attributes.fetch(:streaming, false)
  @chunks_yielded = attributes.fetch(:chunks_yielded, false)
  @response = attributes[:response]
  @fallback_error = attributes[:fallback_error]
end

Instance Attribute Details

#attempt ⇒ Object (readonly)

The fallback attempt number, starting at 1.



57
58
59
 
# File 'lib/ruby_llm/fallback.rb', line 57

def attempt
  @attempt
end

#chat ⇒ Object (readonly)

The Chat performing the fallback attempt.



45
46
47
 
# File 'lib/ruby_llm/fallback.rb', line 45

def chat
  @chat
end

#error ⇒ Object (readonly)

The error that triggered the fallback.



48
49
50
 
# File 'lib/ruby_llm/fallback.rb', line 48

def error
  @error
end

#fallback_error ⇒ Object (readonly)

The error raised by the fallback attempt itself, or nil if it succeeded.



64
65
66
 
# File 'lib/ruby_llm/fallback.rb', line 64

def fallback_error
  @fallback_error
end

#from ⇒ Object (readonly)

The Model the chat is falling back from.



51
52
53
 
# File 'lib/ruby_llm/fallback.rb', line 51

def from
  @from
end

#id ⇒ Object (readonly)

The model id of the fallback target.



35
36
37
 
# File 'lib/ruby_llm/fallback.rb', line 35

def id
  @id
end

#model ⇒ Object (readonly)

The Model object the fallback was configured with, or nil when it was configured with a model id.



42
43
44
 
# File 'lib/ruby_llm/fallback.rb', line 42

def model
  @model
end

#provider ⇒ Object (readonly)

The provider slug of the fallback target as a String, or nil.



38
39
40
 
# File 'lib/ruby_llm/fallback.rb', line 38

def provider
  @provider
end

#response ⇒ Object (readonly)

The response Message from a successful fallback attempt, or nil.



60
61
62
 
# File 'lib/ruby_llm/fallback.rb', line 60

def response
  @response
end

#streaming ⇒ Object (readonly)

:nodoc:



66
67
68
 
# File 'lib/ruby_llm/fallback.rb', line 66

def streaming
  @streaming
end

#to ⇒ Object (readonly)

The Model the chat is falling back to.



54
55
56
 
# File 'lib/ruby_llm/fallback.rb', line 54

def to
  @to
end

Class Method Details

.build(value) ⇒ Object

:nodoc:



68
69
70
71
72
73
74
75
76
77
78
79
 
# File 'lib/ruby_llm/fallback.rb', line 68

def self.build(value) # :nodoc:
  case value
  when self
    value
  when RubyLLM::Model
    new(model: value)
  when String, Symbol
    new(id: value.to_s)
  else
    raise ArgumentError, 'Expected a model id or RubyLLM::Model'
  end
end

Instance Method Details

#chunks_yielded? ⇒ Boolean

Returns whether the failed model already yielded stream chunks before the fallback.

Returns:

  • (Boolean) 


117
118
119
 
# File 'lib/ruby_llm/fallback.rb', line 117

def chunks_yielded?
  @chunks_yielded
end

#failed? ⇒ Boolean

Returns true if the fallback attempt raised an error, false otherwise.

Returns:

  • (Boolean) 


123
124
125
 
# File 'lib/ruby_llm/fallback.rb', line 123

def failed?
  !fallback_error.nil?
end

#finish(response: nil, fallback_error: nil) ⇒ Object

:nodoc:



104
105
106
107
108
 
# File 'lib/ruby_llm/fallback.rb', line 104

def finish(response: nil, fallback_error: nil) # :nodoc:
  @response = response
  @fallback_error = fallback_error
  self
end

#inspect_attributes ⇒ Object

:nodoc:



81
82
83
 
# File 'lib/ruby_llm/fallback.rb', line 81

def inspect_attributes # :nodoc:
  { id: id, provider: provider, attempt: attempt }
end

#streaming? ⇒ Boolean

Returns whether the fallback happened during a streaming request.

Returns:

  • (Boolean) 


111
112
113
 
# File 'lib/ruby_llm/fallback.rb', line 111

def streaming?
  streaming
end

#succeeded? ⇒ Boolean

Returns true if the fallback attempt produced a response without error, false otherwise.

Returns:

  • (Boolean) 


129
130
131
 
# File 'lib/ruby_llm/fallback.rb', line 129

def succeeded?
  !response.nil? && !failed?
end

#with_attempt(**attributes) ⇒ Object

:nodoc:



100
101
102
 
# File 'lib/ruby_llm/fallback.rb', line 100

def with_attempt(**attributes) # :nodoc:
  self.class.new(id: id, provider: provider, model: model, **attributes)
end