class RubyLLM::Models

A Models registry is the catalog of AI models RubyLLM knows about, including their capabilities, context windows, and pricing. The global registry is available through RubyLLM.models.

RubyLLM.models.find 'claude-sonnet-4-6'
RubyLLM.models.by_provider(:openai).chat_models
RubyLLM.models.refresh!

Filter methods return new Models instances, so calls chain. Models is enumerable over its Model entries. Class-level calls such as Models.find delegate to the global registry.

Public Class Methods

refresh! (remote_only: false)

Source

# File lib/ruby_llm/models.rb, line 119
def refresh!(remote_only: false)
  instance.refresh!(remote_only: remote_only)
end

Refreshes the global model registry from the published catalog and configured providers. Returns the global Models instance. See refresh! for the remote_only: option.

Public Instance Methods

all ()

Source

# File lib/ruby_llm/models.rb, line 487
def all
  @models
end

Returns an array of all Model entries in this registry.

audio_models ()

Source

# File lib/ruby_llm/models.rb, line 527
def audio_models
  self.class.new(all.select { |m| m.type == 'audio' || m.modalities.output.include?('audio') })
end

Returns a new Models registry containing only models with audio output.

by_family (family)

Source

# File lib/ruby_llm/models.rb, line 541
def by_family(family)
  self.class.new(all.select { |m| m.family == family.to_s })
end

Returns a new Models registry containing only models in family.

RubyLLM.models.by_family('claude3_sonnet')

by_provider (provider)

Source

# File lib/ruby_llm/models.rb, line 550
def by_provider(provider)
  self.class.new(all.select { |m| m.provider == provider.to_s })
end

Returns a new Models registry containing only models from provider. Accepts a symbol or a string.

RubyLLM.models.by_provider(:openai).select(&:supports_vision?)

chat_models ()

Source

# File lib/ruby_llm/models.rb, line 516
def chat_models
  self.class.new(all.select { |m| m.type == 'chat' })
end

Returns a new Models registry containing only chat models.

each (&)

Source

# File lib/ruby_llm/models.rb, line 495
def each(&)
  all.each(&)
end

Yields each Model in the registry.

RubyLLM.models.each { |model| puts model.id }

embedding_models ()

Source

# File lib/ruby_llm/models.rb, line 521
def embedding_models
  self.class.new(all.select { |m| m.type == 'embedding' || m.modalities.output.include?('embeddings') })
end

Returns a new Models registry containing only embedding models.

find (model_id, provider = nil)

Source

# File lib/ruby_llm/models.rb, line 507
def find(model_id, provider = nil)
  if provider
    find_with_provider(model_id, provider)
  else
    find_without_provider(model_id)
  end
end

Returns the Model matching model_id, resolving aliases along the way. Without provider, picks the preferred provider that carries the model, first-party providers before aggregators. Raises RubyLLM::ModelNotFoundError if no model matches.

RubyLLM.models.find 'gpt-5.4'
RubyLLM.models.find 'claude-sonnet-4-6', :bedrock

image_models ()

Source

# File lib/ruby_llm/models.rb, line 533
def image_models
  self.class.new(all.select { |m| m.type == 'image' || m.modalities.output.include?('image') })
end

Returns a new Models registry containing only models with image output.

load_from_database! ()

Source

# File lib/ruby_llm/models.rb, line 470
def load_from_database!
  @models = ModelRegistry::ActiveRecordStore.new.read
  self
end

Replaces the models in this registry with rows read from the configured ActiveRecord model registry class (RubyLLM.config.model_registry_class).

load_from_json! (file = RubyLLM.config.model_registry_file)

Source

# File lib/ruby_llm/models.rb, line 462
def load_from_json!(file = RubyLLM.config.model_registry_file)
  @models = self.class.models_from_file(file) || self.class.models_from_bundle
  self
end

Replaces the models in this registry with those read from the JSON file. The default is the configured RubyLLM.config.model_registry_file. A missing or invalid file falls back to the registry bundled with the gem.

refresh! (remote_only: false)

Source

# File lib/ruby_llm/models.rb, line 566
def refresh!(remote_only: false)
  RubyLLM.instrument('models.refresh.ruby_llm', remote_only:) do |payload|
    published = fetch_published_models
    merged_models = merge_discovered_models(published.models, remote_only:)
    persist_registry!(merged_models, etag: published.etag)
    @models = merged_models
    payload.merge!(model_count: all.size, not_modified: published.not_modified)
  end
  self
end

Replaces the registry with the latest published RubyLLM catalog, merged with models discovered from configured providers. The result is saved to the platform cache, or to the database in Rails applications. Pass remote_only: true to skip local providers such as Ollama and GPUStack. Returns self.

Raises ModelRegistryError when the catalog cannot be fetched or the result cannot be persisted, leaving the current registry unchanged.

RubyLLM.models.refresh!
RubyLLM.models.refresh!(remote_only: true).chat_models

save_to_json (file = RubyLLM.config.model_registry_file)

Source

# File lib/ruby_llm/models.rb, line 481
def save_to_json(file = RubyLLM.config.model_registry_file)
  ModelRegistry::FileStore.new(file).write(all)
  self
end

Exports this registry to file as pretty-printed JSON. The default is the configured RubyLLM.config.model_registry_file. A regular refresh! already persists to the active registry store.

RubyLLM.models.save_to_json('/tmp/models.json')