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-5'
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.

Attributes

last_provider_failures [R]

The providers whose model list could not be fetched during the last refresh, as hashes of :name, :slug, and :error. Their previous models are kept, so an unreported failure leaves stale entries behind.

Public Class Methods

refresh (remote_only: false)

Source

# File lib/ruby_llm/models.rb, line 143
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 579
def all
  all_including_unlisted.reject(&:unlisted?)
end

Returns an array of the Model entries the configured provider still lists. Models it has stopped listing are left out; find still resolves them, and unlisted reports them.

Also aliased as: listed

audio_models ()

Source

# File lib/ruby_llm/models.rb, line 637
def audio_models
  select_models { |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 651
def by_family(family)
  select_models { |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 660
def by_provider(provider)
  select_models { |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 { |model| model.supports?(:vision) }

chat_models ()

Source

# File lib/ruby_llm/models.rb, line 626
def chat_models
  select_models { |m| m.type == :chat }
end

Returns a new Models registry containing only chat models.

each (&)

Source

# File lib/ruby_llm/models.rb, line 605
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 631
def embedding_models
  select_models { |m| m.type == :embedding || m.modalities.output.include?('embeddings') }
end

Returns a new Models registry containing only embedding models.

find (model_id, provider: nil, config: nil)

Source

# File lib/ruby_llm/models.rb, line 617
def find(model_id, provider: nil, config: nil)
  if provider
    find_with_provider(model_id, provider, config)
  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.6'
RubyLLM.models.find 'claude-sonnet-5', provider: :bedrock

image_models ()

Source

# File lib/ruby_llm/models.rb, line 643
def image_models
  select_models { |m| m.type == :image || m.modalities.output.include?('image') }
end

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

listed ()

Returns an array of the Model entries the configured provider still lists. Reads the same as all, which already excludes the rest.

Alias for: all

load_from_json (file = RubyLLM.config.model_registry_file)

Source

# File lib/ruby_llm/models.rb, line 550
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.

load_from_store ()

Source

# File lib/ruby_llm/models.rb, line 557
def load_from_store
  store = RubyLLM.config.model_registry_store
  raise ModelRegistryError, 'No model registry store is configured' unless store

  @models = Array(store.read)
  self
end

Replaces the models in this registry with entries from the configured model-registry store.

refresh (remote_only: false)

Source

# File lib/ruby_llm/models.rb, line 676
def refresh(remote_only: false)
  RubyLLM.instrument('models.refresh.ruby_llm', remote_only:) do |payload|
    published = fetch_published_models
    main_models = merge_discovered_models(published.models, remote_only:)
    merged_models = self.class.merge_models(self.class.models_from_provider_gems, main_models)
    persisted_models = RubyLLM.config.model_registry_store ? merged_models : main_models
    persist_registry!(persisted_models, published:)
    @models = stored_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 571
def save_to_json(file = RubyLLM.config.model_registry_file)
  Registry::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')

unlisted ()

Source

# File lib/ruby_llm/models.rb, line 589
def unlisted
  all_including_unlisted.select(&:unlisted?)
end

Returns an array of the Model entries the configured provider has stopped listing. Only a store that keeps them, such as the Rails model table, ever reports one.

RubyLLM.models.unlisted.map(&:id)