Working with Models

Access hundreds of AI models from all major AI providers with one Ruby framework

Table of contents

  1. The Model Registry
  2. Refreshing the Registry
    1. Cache Location
    2. For Gem Maintainers
    3. Rails Database Registry
  3. Exploring and Finding Models
    1. Listing and Filtering
    2. Finding a Specific Model
    3. Model Aliases
    4. Provider-Specific Resolution
  4. Next Steps

After reading this guide, you will know:

  • How RubyLLM discovers and registers models.
  • How RubyLLM selects and refreshes the bundled, cached, or database registry.
  • How to find and filter available models by provider, type, or capabilities.
  • What RubyLLM::Model exposes about a model’s capabilities and pricing.
  • How to use model aliases and resolve the same alias across providers.

The Model Registry

RubyLLM maintains a registry of known AI models. Every gem includes a snapshot so a new installation works immediately. The latest published registry is also available at https://rubyllm.com/models.json.

In plain Ruby, RubyLLM uses the valid registry in your operating system’s user cache when it exists, otherwise it uses the bundled snapshot. In Rails applications using acts_as_model, the database is authoritative once it has rows; while the table is empty, RubyLLM falls back to the registry file, then to the bundled snapshot.

The registry stores crucial information about each model, including:

  • id: The unique identifier used by the provider (e.g., gpt-4o-2024-08-06).
  • provider: The source provider (openai, anthropic, etc.).
  • type: The model’s primary function (chat, embedding, etc.).
  • name: A human-friendly name.
  • context_window: Max input tokens (e.g., 128_000).
  • max_output_tokens: Max output tokens (e.g., 16_384).
  • supports?(:vision): If it can process images and videos.
  • supports?(:function_calling): If it can use Tools.
  • price(:input): Cost in USD per 1 million input tokens.
  • price(:output): Cost in USD per 1 million output tokens.
  • price(:cache_read): Cost in USD per 1 million cache read tokens, when available.
  • price(:cache_write): Cost in USD per 1 million cache write tokens, when available.
  • family: A broader classification (e.g., gpt4o).

This registry allows RubyLLM to validate models, route requests correctly, provide capability information, and offer convenient filtering.

You can see the full list of currently registered models in the Available Models Guide.

Refreshing the Registry

For Application Developers:

Refresh models everywhere with one call:

RubyLLM.models.refresh!

The call has the same meaning in every environment. It replaces the in-memory registry and persists it to the active store: the platform cache in plain Ruby or the models table with the Active Record integration. You do not need a second save call.

RubyLLM does not refresh automatically. Network access and provider credentials remain explicit application concerns, and a missing-model lookup never triggers network I/O.

How refresh! Works:

The refresh! method performs the following steps:

  1. Fetches the published catalog: Downloads the current registry from rubyllm.com, using its ETag when a file cache is active.
  2. Discovers configured providers: Queries configured provider APIs, including local providers by default.
  3. Merges the data: Keeps the published metadata while adding provider-specific or local discoveries.
  4. Persists the result: Atomically replaces the file cache, or updates the configured Active Record model inside a transaction.

The method returns a chainable Models instance, allowing you to immediately query the updated registry:

chat_models = RubyLLM.models.refresh!.chat_models

The published registry is generated from provider APIs and models.dev. A failed refresh raises RubyLLM::ModelRegistryError and leaves the previously loaded registry available.

Local Provider Models:

By default, refresh! includes models from local providers like Ollama and GPUStack if they’re configured. To exclude local providers and only fetch from remote APIs:

RubyLLM.models.refresh!(remote_only: true)

This is useful when you want to refresh only cloud-based models without querying local model servers.

Cache Location

The default plain Ruby cache locations are:

  • Linux: $XDG_CACHE_HOME/ruby_llm/models.json, or ~/.cache/ruby_llm/models.json
  • macOS: ~/Library/Caches/RubyLLM/models.json
  • Windows: %LOCALAPPDATA%\RubyLLM\Cache\models.json

Set config.model_registry_file to use another writable path. See Connection, Logging and Contexts.

refresh! already saves to the active registry store. Use save_to_json separately when you want to export the currently loaded registry to another file:

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

For Gem Maintainers

The source repository includes a maintainer-only task that builds a registry directly from provider APIs and models.dev:

bundle exec rake models:update

These tasks live outside the gem’s packaged Rake task directory. They are not application commands and are intentionally unavailable after installing the gem.

Rails Database Registry

For Rails applications, the install generator sets up everything automatically:

bin/rails generate ruby_llm:install
bin/rails db:migrate

This creates the Model table and loads model data from the gem’s registry.

Refresh the database with the same public entry point used by plain Ruby:

RubyLLM.models.refresh!

Exploring and Finding Models

Use RubyLLM.models to explore the registry.

Listing and Filtering 

all_models = RubyLLM.models.all

chat_models = RubyLLM.models.chat_models
embedding_models = RubyLLM.models.embedding_models

openai_models = RubyLLM.models.by_provider(:openai) # or 'openai'

# Filter by model family (e.g., all Claude 3 Sonnet variants)
claude3_sonnet_family = RubyLLM.models.by_family('claude3_sonnet')

# Chain filters and use Enumerable methods
openai_vision_models = RubyLLM.models.by_provider(:openai)
                                   .select(&:supports_vision?)

puts "Found #{openai_vision_models.count} OpenAI vision models."

Finding a Specific Model

Use find to get a RubyLLM::Model object containing details about a specific model.

model_info = RubyLLM.models.find('gpt-5.4')

if model_info
  puts "Model: #{model_info.name}"
  puts "Provider: #{model_info.provider}"
  puts "Context Window: #{model_info.context_window} tokens"
else
  puts "Model not found."
end

# Find raises ModelNotFoundError if the ID is unknown
# RubyLLM.models.find('no-such-model-exists') # => raises ModelNotFoundError

Model Aliases

RubyLLM uses aliases (defined in lib/ruby_llm/aliases.json) for convenience, mapping common names to specific versions.

# 'claude-sonnet-4-6' might resolve to 'claude-3-5-sonnet-20241022'
chat = RubyLLM.chat(model: 'claude-sonnet-4-6')
puts chat.model.id # => "claude-3-5-sonnet-20241022" (or latest version)

When you call find without a provider, RubyLLM resolves the alias and then picks the most preferred provider that carries the model (first-party providers before aggregators). See Model Resolution for the full procedure.

Provider-Specific Resolution

Specify the provider if the same alias exists across multiple providers.

model_anthropic = RubyLLM.models.find('claude-sonnet-4-6', :anthropic)

model_bedrock = RubyLLM.models.find('claude-sonnet-4-6', :bedrock)

When you pass a provider, RubyLLM resolves aliases first. For Bedrock, it then applies region/inference-profile resolution (for example us. prefixes) before falling back to an exact ID match. See Model Resolution for the exact order, step by step.

Next Steps

Table of contents