Update documentation and improve model finding logic

Fixes #68

- Added a new section on working with models in the guides.
- Enhanced model finding logic to prioritize exact matches over aliases.
- Updated links in the documentation for consistency.

Author: crmne

docs/guides/index.md

@@ -36,10 +36,13 @@ Explore how to create vector embeddings for semantic search and other applicatio
 ### [Error Handling]({% link guides/error-handling.md %})
 Master the techniques for robust error handling in AI applications.
 
+### [Working with Models]({% link guides/models.md %})
+Learn how to discover, select, and work with different AI models across providers.
+
 ## Getting Help
 
 If you can't find what you're looking for in these guides, consider:
 
 1. Checking the [API Documentation]() for detailed information about specific classes and methods
-2. Looking at the [GitHub repository](https://github.com/yourusername/ruby_llm) for examples and the latest updates
+2. Looking at the [GitHub repository](https://github.com/crmne/ruby_llm) for examples and the latest updates
 3. Filing an issue on GitHub if you find a bug or have a feature request

docs/guides/models.md

@@ -10,6 +10,86 @@ permalink: /guides/models
 
 RubyLLM provides a clean interface for discovering and working with AI models from multiple providers. This guide explains how to find, filter, and select the right model for your needs.
 
+## Finding Models
+
+### Basic Model Selection
+
+The simplest way to use a model is to specify it when creating a chat:
+
+```ruby
+# Use the default model
+chat = RubyLLM.chat
+
+# Specify a model
+chat = RubyLLM.chat(model: 'gpt-4o-mini')
+
+# Change models mid-conversation
+chat.with_model('claude-3-5-sonnet')
+```
+
+### Model Resolution
+
+{: .warning-title }
+> Coming in v1.1.0
+>
+> Provider-Specific Match and Alias Resolution will be available in the next release.
+
+When you specify a model, RubyLLM follows these steps to find it:
+
+1. **Exact Match**: First tries to find an exact match for the model ID
+   ```ruby
+   # Uses the actual gemini-2.0-flash model
+   chat = RubyLLM.chat(model: 'gemini-2.0-flash')
+   ```
+
+2. **Provider-Specific Match**: If a provider is specified, looks for an exact match in that provider
+   ```ruby
+   # Looks for gemini-2.0-flash in Gemini
+   chat = RubyLLM.chat(model: 'gemini-2.0-flash', provider: 'gemini')
+   ```
+
+3. **Alias Resolution**: Only if no exact match is found, checks for aliases
+   ```ruby
+   # No exact match for 'claude-3', uses alias
+   chat = RubyLLM.chat(model: 'claude-3')
+   ```
+
+The same model ID can exist both as a concrete model and as an alias, particularly when the same model is available through different providers:
+
+```ruby
+# Use native OpenAI GPT-4
+chat = RubyLLM.chat(model: 'gpt-4o')
+
+# Use GPT-4 through Bedrock
+chat = RubyLLM.chat(model: 'gpt-4o', provider: 'bedrock')
+```
+
+### Model Aliases
+
+{: .warning-title }
+> Coming in v1.1.0
+>
+> Alias Resolution will be available in the next release.
+
+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')
+```
+
+If you want to ensure you're always getting a specific version, use the full model ID:
+
+```ruby
+# Always gets this exact version
+chat = RubyLLM.chat(model: 'claude-3-sonnet-20240229')
+```
+
 ## Exploring Available Models
 
 RubyLLM automatically discovers available models from all configured providers:
@@ -63,32 +143,6 @@ google_models = RubyLLM.models.by_provider('gemini')
 deepseek_models = RubyLLM.models.by_provider('deepseek')
 ```
 
-## Using Model Aliases
-
-{: .warning-title }
-> Coming in v1.1.0
->
-> This feature is available in the upcoming version but not in the latest release.
-
-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')
-```
-
-You can also specify a different provider to use with a model:
-
-```ruby
-# Use a specific model via a different provider
-chat = RubyLLM.chat(model: 'claude-3-5-sonnet', provider: 'bedrock')
-```
-
 ## Chaining Filters
 
 You can chain multiple filters to find exactly what you need:
@@ -176,4 +230,5 @@ When selecting models for your application:
 1. **Consider context windows** - Larger context windows support longer conversations but may cost more
 2. **Balance cost vs. quality** - More capable models cost more but may give better results
 3. **Check capabilities** - Make sure the model supports features you need (vision, functions, etc.)
-4. **Use appropriate model types** - Use embedding models for vector operations, chat models for conversations
+4. **Use appropriate model types** - Use embedding models for vector operations, chat models for conversations
+5. **Version control** - Use exact model IDs in production for consistency, aliases for development

lib/ruby_llm/models.rb

@@ -86,12 +86,11 @@ def each(&)
 
     # Find a specific model by ID
     def find(model_id, provider = nil)
-      return find_with_provider(model_id, provider) if provider
-
-      # Find native model
-      all.find { |m| m.id == model_id } ||
-        all.find { |m| m.id == Aliases.resolve(model_id) } ||
-        raise(ModelNotFoundError, "Unknown model: #{model_id}")
+      if provider
+        find_with_provider(model_id, provider)
+      else
+        find_without_provider(model_id)
+      end
     end
 
     # Filter to only chat models
@@ -132,9 +131,16 @@ def refresh!
     private
 
     def find_with_provider(model_id, provider)
-      provider_id = Aliases.resolve(model_id, provider)
-      all.find { |m| m.id == provider_id && m.provider == provider.to_s } ||
+      resolved_id = Aliases.resolve(model_id, provider)
+      all.find { |m| m.id == model_id && m.provider == provider.to_s } ||
+        all.find { |m| m.id == resolved_id && m.provider == provider.to_s } ||
         raise(ModelNotFoundError, "Unknown model: #{model_id} for provider: #{provider}")
     end
+
+    def find_without_provider(model_id)
+      all.find { |m| m.id == model_id } ||
+        all.find { |m| m.id == Aliases.resolve(model_id) } ||
+        raise(ModelNotFoundError, "Unknown model: #{model_id}")
+    end
   end
 end

spec/ruby_llm/models_spec.rb

@@ -62,6 +62,22 @@
     end
   end
 
+  describe '#find' do
+    it 'prioritizes exact matches over aliases' do # rubocop:disable RSpec/ExampleLength,RSpec/MultipleExpectations
+      # This test covers the case from the issue
+      chat_model = RubyLLM.chat(model: 'gemini-2.0-flash')
+      expect(chat_model.model.id).to eq('gemini-2.0-flash')
+
+      # Even with provider specified, exact match wins
+      chat_model = RubyLLM.chat(model: 'gemini-2.0-flash', provider: 'gemini')
+      expect(chat_model.model.id).to eq('gemini-2.0-flash')
+
+      # Only use alias when exact match isn't found
+      chat_model = RubyLLM.chat(model: 'claude-3')
+      expect(chat_model.model.id).to eq('claude-3-sonnet-20240229')
+    end
+  end
+
   describe '#refresh!' do
     it 'updates models and returns a chainable Models instance' do # rubocop:disable RSpec/ExampleLength,RSpec/MultipleExpectations
       # Use a temporary file to avoid modifying actual models.json