# Working with Models
{: .no_toc }

Access hundreds of AI models from all major AI providers with one Ruby framework
{: .fs-6 .fw-300 }

## Table of contents
{: .no_toc .text-delta }

1. TOC
{:toc}

---

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`](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](/next/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](/next/available-models/).

## Refreshing the Registry

**For Application Developers:**

Refresh models everywhere with one call:

```ruby
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:

```ruby
chat_models = RubyLLM.models.refresh!.chat_models
```

The published registry is generated from provider APIs and [models.dev](https://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:

```ruby
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](/next/configuration-connection/#model-registry-file).

`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:

```ruby
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:

```bash
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:

```bash
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:

```ruby
RubyLLM.models.refresh!
```

## Exploring and Finding Models

Use `RubyLLM.models` to explore the registry.

### Listing and Filtering

```ruby
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.

```ruby
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.

```ruby
# '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](/next/model-resolution/) for the full procedure.

### Provider-Specific Resolution

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

```ruby
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](/next/model-resolution/) for the exact order, step by step.

## Next Steps

*   [Model Costs](/next/model-costs/) - turn token usage into a `RubyLLM::Cost` object and aggregate costs across messages.
*   [Custom Endpoints and Unlisted Models](/next/custom-endpoints/) - target OpenAI-compatible endpoints and use model IDs the registry doesn't list.
*   [Available Models](/next/available-models/) - browse every model currently registered with RubyLLM.