Model aliases.

Author: crmne

docs/guides/models.md

@@ -63,6 +63,35 @@ google_models = RubyLLM.models.by_provider('gemini')
 deepseek_models = RubyLLM.models.by_provider('deepseek')
 ```
 
+## Using Model Aliases
+
+RubyLLM provides convenient aliases for popular models, so you don't have to remember specific version numbers:
+
+```ruby
+# These are equivalent
+chat = RubyLLM.chat(model: 'claude-3-5-sonnet')
+chat = RubyLLM.chat(model: 'claude-3-5-sonnet-20241022')
+
+# These are also equivalent
+chat = RubyLLM.chat(model: 'gpt-4o')
+chat = RubyLLM.chat(model: 'gpt-4o-2024-11-20')
+```
+
+Aliases for common models include:
+
+| Alias | Resolves To |
+|--------|-------------|
+| `claude-3-5-sonnet` | `claude-3-5-sonnet-20241022` |
+| `claude-3-5-haiku` | `claude-3-5-haiku-20241022` |
+| `claude-3-7-sonnet` | `claude-3-7-sonnet-20250219` |
+| `claude-3-opus` | `claude-3-opus-20240229` |
+| `gpt-4o` | `gpt-4o-2024-11-20` |
+| `gpt-4o-mini` | `gpt-4o-mini-2024-07-18` |
+| `gemini-1.5-flash` | `gemini-1.5-flash-002` |
+| `gemini-2.0-flash` | `gemini-2.0-flash-001` |
+
+Aliases are particularly useful when you want your code to always use the latest stable version of a model without having to update your codebase when providers release new model versions.
+
 ## Chaining Filters
 
 You can chain multiple filters to find exactly what you need:

lib/ruby_llm/aliases.json

@@ -0,0 +1,50 @@
+{
+  "claude-3-5-sonnet": {
+    "anthropic": "claude-3-5-sonnet-20241022"
+  },
+  "claude-3-5-haiku": {
+    "anthropic": "claude-3-5-haiku-20241022"
+  },
+  "claude-3-7-sonnet": {
+    "anthropic": "claude-3-7-sonnet-20250219"
+  },
+  "claude-3-opus": {
+    "anthropic": "claude-3-opus-20240229"
+  },
+  "claude-3-sonnet": {
+    "anthropic": "claude-3-sonnet-20240229"
+  },
+  "claude-3-haiku": {
+    "anthropic": "claude-3-haiku-20240307"
+  },
+  "claude-3": {
+    "anthropic": "claude-3-sonnet-20240229"
+  },
+  "gpt-4o": {
+    "openai": "gpt-4o-2024-11-20"
+  },
+  "gpt-4o-mini": {
+    "openai": "gpt-4o-mini-2024-07-18"
+  },
+  "gpt-4-turbo": {
+    "openai": "gpt-4-turbo-2024-04-09"
+  },
+  "gemini-1.5-flash": {
+    "gemini": "gemini-1.5-flash-002"
+  },
+  "gemini-1.5-flash-8b": {
+    "gemini": "gemini-1.5-flash-8b-001"
+  },
+  "gemini-1.5-pro": {
+    "gemini": "gemini-1.5-pro-002"
+  },
+  "gemini-2.0-flash": {
+    "gemini": "gemini-2.0-flash-001"
+  },
+  "o1": {
+    "openai": "o1-2024-12-17"
+  },
+  "o3-mini": {
+    "openai": "o3-mini-2025-01-31"
+  }
+}

lib/ruby_llm/aliases.rb

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+module RubyLLM
+  # Manages model aliases, allowing users to reference models by simpler names
+  # that map to specific model versions across different providers.
+  #
+  # Aliases are defined in aliases.json and follow the format:
+  #   {
+  #     "simple-name": {
+  #       "provider1": "specific-version-for-provider1",
+  #       "provider2": "specific-version-for-provider2"
+  #     }
+  #   }
+  class Aliases
+    class << self
+      # Resolves a model ID to its provider-specific version
+      #
+      # @param model_id [String] the model identifier or alias
+      # @param provider_slug [String, Symbol, nil] optional provider to resolve for
+      # @return [String] the resolved model ID or the original if no alias exists
+      def resolve(model_id, provider_slug = nil)
+        provider_aliases = aliases[model_id]
+        return model_id unless provider_aliases
+
+        if provider_slug
+          provider_aliases[provider_slug.to_s] || model_id
+        else
+          provider_aliases.values.first || model_id
+        end
+      end
+
+      # Returns the loaded aliases mapping
+      # @return [Hash] the aliases mapping
+      def aliases
+        @aliases ||= load_aliases
+      end
+
+      # Loads aliases from the JSON file
+      # @return [Hash] the loaded aliases
+      def load_aliases
+        file_path = File.expand_path('aliases.json', __dir__)
+        if File.exist?(file_path)
+          JSON.parse(File.read(file_path))
+        else
+          {}
+        end
+      end
+
+      # Reloads aliases from disk
+      # @return [Hash] the reloaded aliases
+      def reload!
+        @aliases = load_aliases
+      end
+    end
+  end
+end

lib/ruby_llm/models.rb

@@ -74,8 +74,19 @@ def each(&)
 
     # Find a specific model by ID
     def find(model_id)
-      all.find { |m| m.id == model_id } or
-        raise ModelNotFoundError, "Unknown model: #{model_id}"
+      # Try exact match first
+      exact_match = all.find { |m| m.id == model_id }
+      return exact_match if exact_match
+
+      # Try to resolve via alias
+      resolved_id = Aliases.resolve(model_id)
+      if resolved_id != model_id
+        alias_match = all.find { |m| m.id == resolved_id }
+        return alias_match if alias_match
+      end
+
+      # Not found
+      raise ModelNotFoundError, "Unknown model: #{model_id}"
     end
 
     # Filter to only chat models

spec/ruby_llm/chat_model_aliases_spec.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+require 'spec_helper'
+require 'dotenv/load'
+
+RSpec.describe RubyLLM::Chat do
+  include_context 'with configured RubyLLM'
+
+  it 'finds models by alias name' do
+    # Core test - can we find a model using just its alias?
+    chat = RubyLLM.chat(model: 'claude-3-5-sonnet')
+    expect(chat.model.id).to eq('claude-3-5-sonnet-20241022')
+  end
+
+  it 'still supports exact model IDs' do
+    # Backward compatibility check
+    chat = RubyLLM.chat(model: 'claude-3-5-sonnet-20241022')
+    expect(chat.model.id).to eq('claude-3-5-sonnet-20241022')
+  end
+end