Class: RubyLLM::Model

Inherits:
Object
  • Object
show all
Includes:
Support::Inspectable
Defined in:
lib/ruby_llm/model.rb,
lib/ruby_llm/model/pricing.rb,
lib/ruby_llm/model/modalities.rb,
lib/ruby_llm/model/pricing_tier.rb,
lib/ruby_llm/model/pricing_category.rb

Overview

A Model describes one entry in the model registry: the model's identity, capabilities, modalities, pricing, and provider metadata. Instances come from the registry through RubyLLM.models and from Chat#model.

model = RubyLLM.models.find('gpt-5.6')
model.name              # => "GPT-5.6"
model.provider          # => "openai"
model.context_window    # => 1050000
model.supports?(:vision) # => true

Defined Under Namespace

Classes: Modalities, Pricing, PricingCategory, PricingTier

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 Support::Inspectable

#full_inspect, #inspect, #pretty_print

Constructor Details

#initialize(data) ⇒ Model

:nodoc:



76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
 
# File 'lib/ruby_llm/model.rb', line 76

def initialize(data) # :nodoc:
  @id = data[:id]
  @name = data[:name]
  @provider = data[:provider]
  @family = data[:family]
  @created_at = Support::Utils.to_time(data[:created_at])&.utc
  @context_window = data[:context_window]
  @max_output_tokens = data[:max_output_tokens]
  @knowledge_cutoff = Support::Utils.to_date(data[:knowledge_cutoff])
  @modalities = Modalities.new(data[:modalities] || {})
  @capabilities = data[:capabilities] || []
  @metadata = data[:metadata]&.dup || {}
  @unlisted_at = Support::Utils.to_time(data[:unlisted_at])&.utc
  @pricing = Pricing.new(pricing_data_with_long_context(data[:pricing] || {}))
  @reasoning_options = normalize_reasoning_options(reasoning_options_from(data))
  store_reasoning_options_metadata
end

Instance Attribute Details

#capabilities ⇒ Object (readonly)

The model's capability names as an array of Strings, e.g. ["function_calling", "streaming"].



50
51
52
 
# File 'lib/ruby_llm/model.rb', line 50

def capabilities
  @capabilities
end

#context_window ⇒ Object (readonly)

The maximum number of input tokens the model accepts, or nil.



33
34
35
 
# File 'lib/ruby_llm/model.rb', line 33

def context_window
  @context_window
end

#created_at ⇒ Object (readonly)

The model's release timestamp as a UTC Time, or nil.



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

def created_at
  @created_at
end

#family ⇒ Object (readonly)

The model family as a String, e.g. "gpt", or nil.



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

def family
  @family
end

#id ⇒ Object (readonly)

The provider's identifier for the model, e.g. "gpt-5.6".



18
19
20
 
# File 'lib/ruby_llm/model.rb', line 18

def id
  @id
end

#knowledge_cutoff ⇒ Object (readonly)

The model's training data cutoff as a Date, or nil.



39
40
41
 
# File 'lib/ruby_llm/model.rb', line 39

def knowledge_cutoff
  @knowledge_cutoff
end

#max_output_tokens ⇒ Object (readonly)

The maximum number of tokens the model can generate, or nil.



36
37
38
 
# File 'lib/ruby_llm/model.rb', line 36

def max_output_tokens
  @max_output_tokens
end

#metadata ⇒ Object (readonly)

Provider-specific metadata as a Hash.



56
57
58
 
# File 'lib/ruby_llm/model.rb', line 56

def metadata
  @metadata
end

#modalities ⇒ Object (readonly)

The supported input and output modalities as a Model::Modalities object.

model.modalities.input   # => ["text", "image", "pdf"]
model.modalities.output  # => ["text"]



46
47
48
 
# File 'lib/ruby_llm/model.rb', line 46

def modalities
  @modalities
end

#name ⇒ Object (readonly)

The human-readable model name, e.g. "GPT-5.6".



21
22
23
 
# File 'lib/ruby_llm/model.rb', line 21

def name
  @name
end

#pricing ⇒ Object (readonly)

The model's pricing as a Model::Pricing object, in USD per million tokens.



53
54
55
 
# File 'lib/ruby_llm/model.rb', line 53

def pricing
  @pricing
end

#provider ⇒ Object (readonly)

The provider slug as a String, e.g. "openai".



24
25
26
 
# File 'lib/ruby_llm/model.rb', line 24

def provider
  @provider
end

#reasoning_options ⇒ Object (readonly)

:nodoc:



63
64
65
 
# File 'lib/ruby_llm/model.rb', line 63

def reasoning_options
  @reasoning_options
end

#unlisted_at ⇒ Object (readonly)

The time the configured provider stopped listing the model, as a UTC Time, or nil while the provider still lists it. Only a store that keeps unlisted entries, such as the Rails model table, sets it.



61
62
63
 
# File 'lib/ruby_llm/model.rb', line 61

def unlisted_at
  @unlisted_at
end

Class Method Details

.default(model_id, provider) ⇒ Object

:nodoc:



65
66
67
68
69
70
71
72
73
74
 
# File 'lib/ruby_llm/model.rb', line 65

def self.default(model_id, provider) # :nodoc:
  new(
    id: model_id,
    name: model_id.tr('-', ' ').capitalize,
    provider: provider,
    capabilities: %w[function_calling streaming vision structured_output],
    modalities: { input: %w[text image], output: %w[text] },
    metadata: { warning: 'Assuming model exists, capabilities may not be accurate' }
  )
end

Instance Method Details

#cost_for(tokens, tier: :standard) ⇒ Object

Builds a Cost for tokens (a Tokens object, or anything responding to tokens) using this model's pricing.

cost = model.cost_for(response.tokens)
puts cost.total

Pass tier: :batch to use the model's explicit batch rates.



160
161
162
163
164
 
# File 'lib/ruby_llm/model.rb', line 160

def cost_for(tokens, tier: :standard)
  tokens = tokens.tokens if tokens.respond_to?(:tokens)

  Cost.new(tokens:, model: self, tier:)
end

#label ⇒ Object

Returns the provider display name and model name combined, e.g. "OpenAI - GPT-5.6".



115
116
117
118
 
# File 'lib/ruby_llm/model.rb', line 115

def label
  provider_name = provider_class&.display_name || provider
  "#{provider_name} - #{name}"
end

#price(kind) ⇒ Object

Returns the standard text-token price for kind in USD per million tokens, or nil if the registry has no such price. Valid kinds are :input, :output, :cache_read, and :cache_write.

model.price(:input)   # => 2.5
model.price(:output)  # => 10.0



145
146
147
148
149
150
 
# File 'lib/ruby_llm/model.rb', line 145

def price(kind)
  column = PRICES.fetch(kind) do
    raise ArgumentError, "Unknown price kind: #{kind.inspect}. Valid kinds: #{PRICES.keys.join(', ')}"
  end
  pricing.text_tokens.public_send(column)
end

#provider_class ⇒ Object

Returns the Provider class registered for this model's provider slug, or nil if no such provider is registered.



168
169
170
 
# File 'lib/ruby_llm/model.rb', line 168

def provider_class
  RubyLLM::Provider.resolve provider
end

#reasoning_option(type) ⇒ Object

:nodoc:



120
121
122
 
# File 'lib/ruby_llm/model.rb', line 120

def reasoning_option(type) # :nodoc:
  reasoning_options.find { |option| option[:type] == type.to_s }
end

#reasoning_option_values(type) ⇒ Object

:nodoc:



124
125
126
 
# File 'lib/ruby_llm/model.rb', line 124

def reasoning_option_values(type) # :nodoc:
  Array(reasoning_option(type)&.fetch(:values, nil))
end

#supports?(capability) ⇒ Boolean

Returns whether #capabilities includes capability, given as a String or Symbol.

model.supports?(:function_calling) # => true

Returns:

  • (Boolean) 


99
100
101
 
# File 'lib/ruby_llm/model.rb', line 99

def supports?(capability)
  capabilities.include?(capability.to_s)
end

#to_h ⇒ Object

:nodoc:



187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
 
# File 'lib/ruby_llm/model.rb', line 187

def to_h # :nodoc:
  data = {
    id: id,
    name: name,
    provider: provider,
    family: family,
    created_at: created_at,
    context_window: context_window,
    max_output_tokens: max_output_tokens,
    knowledge_cutoff: knowledge_cutoff,
    modalities: modalities.to_h,
    capabilities: capabilities,
    pricing: pricing.to_h,
    metadata: metadata
  }
  # A JSON registry drops unlisted models, so the key stays out of it.
  data[:unlisted_at] = unlisted_at if unlisted_at
  data
end

#type ⇒ Object

Returns the model's primary function, inferred from its output modalities: :chat, :embedding, :moderation, :image, :audio, :video, or :rerank.



175
176
177
178
179
180
181
182
183
184
185
 
# File 'lib/ruby_llm/model.rb', line 175

def type
  output = modalities.output
  return :embedding if output.include?('embeddings')
  return :moderation if output.include?('moderation')
  return :image if output.include?('image')
  return :audio if output.include?('audio')
  return :video if output.include?('video')
  return :rerank if output.include?('rerank')

  :chat
end

#unlisted? ⇒ Boolean

Returns whether the configured provider has stopped listing the model. An unlisted model is kept only because application records still reference it, and it may already be failing at the provider.

model.unlisted? # => false

Returns:

  • (Boolean) 


109
110
111
 
# File 'lib/ruby_llm/model.rb', line 109

def unlisted?
  !unlisted_at.nil?
end