Merge branch 'main' into openrouter-support

Author: crmne

.github/workflows/cicd.yml

@@ -109,7 +109,7 @@ jobs:
         rm -rf spec/fixtures/vcr_cassettes
 
         echo "Running tests with real API calls..."
-        bundle exec rspec
+        env -u CI bundle exec rspec
       env:
         OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}
         ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}

.gitignore

@@ -9,6 +9,7 @@
 /test/tmp/
 /test/version_tmp/
 /tmp/
+.rspec_status
 
 # Used by dotenv library to load environment variables.
 .env

.overcommit.yml

@@ -8,7 +8,7 @@ PreCommit:
     enabled: true
 
   RSpec:
-    enabled: false
+    enabled: true
     command: ['bundle', 'exec', 'rspec']
     on_warn: fail
 

.rspec_status

@@ -8,7 +8,7 @@ Here's how to get started:
 
 ```bash
 # Clone the repository
-git clone https://github.com/crmne/ruby_llm.git
+gh repo clone crmne/ruby_llm
 cd ruby_llm
 
 # Install dependencies
@@ -29,7 +29,9 @@ We recommend using GitHub CLI to simplify the workflow:
 # Create a new branch for your feature
 gh repo fork crmne/ruby_llm --clone
 cd ruby_llm
-git checkout -b my-new-feature
+
+# Find or make an issue for the feature on GitHub and then:
+gh issue develop 123 --checkout  # Substitute 123 with the issue number
 
 # Make your changes and test them
 # ...
@@ -41,6 +43,86 @@ git commit
 gh pr create --web
 ```
 
+## Model Naming Convention & Provider Strategy
+
+When adding new providers to RubyLLM, please follow these guidelines:
+
+### Normalized Model IDs
+
+We use a consistent approach separating **what** (model) from **where** (provider):
+
+```ruby
+# Default way (from the native provider)
+chat = RubyLLM.chat(model: "claude-3-5-sonnet")
+
+# Same model via different provider
+chat = RubyLLM.chat(model: "claude-3-5-sonnet", provider: :bedrock)
+```
+
+### Implementing a Provider
+
+If you're adding a new provider:
+
+1. **Use normalized model IDs** - Don't include provider prefixes in the model ID itself
+2. **Add provider mapping** - Map the normalized IDs to your provider's specific format internally
+3. **Preserve capabilities** - Ensure models accessed through your provider report the same capabilities as their native counterparts
+4. **Update models.json** - Include your provider's models in models.json
+5. **Update aliases.json** - Add entries to aliases.json for models accessible through your provider
+6. **Implement refresh mechanism** - Ensure your provider supports the `list_models` method for refreshing
+
+### Model Aliases
+
+For providers that use complex model identifiers (like Bedrock's `anthropic.claude-3-5-sonnet-20241022-v2:0:200k`), add mappings to the global aliases.json file:
+
+```json
+{
+  "claude-3-5-sonnet": {
+    "anthropic": "claude-3-5-sonnet-20241022",
+    "bedrock": "anthropic.claude-3-5-sonnet-20241022-v2:0:200k",
+    "openrouter": "anthropic/claude-3.5-sonnet"
+  },
+  "gpt-4o": {
+    "openai": "gpt-4o-2024-05-13",
+    "bedrock": "anthropic.gpt-4o-2024-05-13",
+    "openrouter": "openai/gpt-4o"
+  }
+}
+```
+
+If a model can't be found with the provided ID and provider, a `ModelNotFoundError` will be raised with an informative message. Your implementation should make this error helpful by suggesting available alternatives.
+
+When the same model has multiple versions and context windows e.g.
+
+```
+anthropic.claude-3-5-sonnet-20240620-v1:0
+anthropic.claude-3-5-sonnet-20240620-v1:0:18k
+anthropic.claude-3-5-sonnet-20240620-v1:0:200k
+anthropic.claude-3-5-sonnet-20240620-v1:0:51k
+anthropic.claude-3-5-sonnet-20241022-v2:0
+anthropic.claude-3-5-sonnet-20241022-v2:0:18k
+anthropic.claude-3-5-sonnet-20241022-v2:0:200k
+anthropic.claude-3-5-sonnet-20241022-v2:0:51k
+```
+
+We default all aliases to the biggest context window, and the main alias (without date) to the latest version:
+
+```json
+  "claude-3-5-sonnet": {
+    "anthropic": "claude-3-5-sonnet-20241022",
+    "bedrock": "anthropic.claude-3-5-sonnet-20241022-v2:0:200k",
+    "openrouter": "anthropic/claude-3.5-sonnet"
+  },
+  "claude-3-5-sonnet-20241022": {
+    "anthropic": "claude-3-5-sonnet-20241022",
+    "bedrock": "anthropic.claude-3-5-sonnet-20241022-v2:0:200k",
+    "openrouter": "anthropic/claude-3.5-sonnet"
+  },
+  "claude-3-5-sonnet-20240620": {
+    "anthropic": "claude-3-5-sonnet-20240620",
+    "bedrock": "anthropic.claude-3-5-sonnet-20240620-v1:0:200k"
+  },
+```
+
 ## Running Tests
 
 Tests automatically use VCR to record and replay HTTP interactions, so you don't need real API keys for testing:

CONTRIBUTING.md

@@ -12,7 +12,7 @@ A delightful Ruby way to work with AI. No configuration madness, no complex call
   <img src="https://upload.wikimedia.org/wikipedia/commons/e/ec/DeepSeek_logo.svg" alt="DeepSeek" height="40" width="120">
 </div>
 
-<a href="https://badge.fury.io/rb/ruby_llm"><img src="https://badge.fury.io/rb/ruby_llm.svg?dummy=unused" alt="Gem Version" /></a>
+<a href="https://badge.fury.io/rb/ruby_llm"><img src="https://badge.fury.io/rb/ruby_llm.svg" alt="Gem Version" /></a>
 <a href="https://github.com/testdouble/standard"><img src="https://img.shields.io/badge/code_style-standard-brightgreen.svg" alt="Ruby Style Guide" /></a>
 <a href="https://rubygems.org/gems/ruby_llm"><img alt="Gem Downloads" src="https://img.shields.io/gem/dt/ruby_llm"></a>
 <a href="https://codecov.io/gh/crmne/ruby_llm"><img src="https://codecov.io/gh/crmne/ruby_llm/branch/main/graph/badge.svg" alt="codecov" /></a>

README.md

@@ -0,0 +1,8 @@
+coverage:
+  status:
+    project:
+      default:
+        informational: true
+    patch:
+      default:
+        informational: true

codecov.yml

@@ -40,6 +40,18 @@ color_scheme: light
 ga_tracking:
 ga_tracking_anonymize_ip: true
 
+# Callouts
+callouts:
+  new:
+    title: New
+    color: green
+  warning:
+    title: Warning
+    color: yellow
+  note:
+    title: Note
+    color: blue
+
 # Custom plugins (GitHub Pages allows these)
 plugins:
   - jekyll-remote-theme

docs/_config.yml

@@ -43,6 +43,33 @@ claude_chat = RubyLLM.chat(model: 'claude-3-5-sonnet-20241022')
 chat.with_model('gemini-2.0-flash')
 ```
 
+{: .warning-title }
+> Coming in v1.1.0
+>
+> The following model aliases and provider selection features are available in the upcoming version.
+
+RubyLLM supports model aliases, so you don't need to remember specific version numbers:
+
+```ruby
+# Instead of this:
+chat = RubyLLM.chat(model: 'claude-3-5-sonnet-20241022')
+
+# You can simply write:
+chat = RubyLLM.chat(model: 'claude-3-5-sonnet')
+```
+
+You can also specify a specific provider to use with a model:
+
+```ruby
+# Use a specific provider (when the same model is available from multiple providers)
+chat = RubyLLM.chat(model: 'claude-3-5-sonnet', provider: 'bedrock')
+
+# Or set the provider after initialization
+chat = RubyLLM.chat(model: 'gpt-4o')
+       .with_provider('azure')
+```
+
+See [Working with Models]({% link guides/models.md %}) for more details on model selection.
 ## System Prompts
 
 System prompts allow you to set specific instructions or context that guide the AI's behavior throughout the conversation. These prompts are not directly visible to the user but help shape the AI's responses:
@@ -67,6 +94,8 @@ chat.add_message role: :system, content: "Always format your code using proper R
 # - Creating specialized assistants
 ```
 
+If you want to set up system prompts with persistence, please refer to the [Rails integration guide]({% link guides/rails.md %}#using-system-messages)
+
 ## Multi-turn Conversations
 
 Chats maintain conversation history automatically:
@@ -275,4 +304,4 @@ Now that you understand chat basics, you might want to explore:
 
 - [Using Tools]({% link guides/tools.md %}) to let AI use your Ruby code
 - [Streaming Responses]({% link guides/streaming.md %}) for real-time interactions
-- [Rails Integration]({% link guides/rails.md %}) to persist conversations in your apps
+- [Rails Integration]({% link guides/rails.md %}) to persist conversations in your apps

docs/guides/chat.md

@@ -63,6 +63,36 @@ 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')
+
+# Or set the provider after initialization
+chat = RubyLLM.chat(model: 'gpt-4o')
+       .with_provider('azure')
+```
+
 ## Chaining Filters
 
 You can chain multiple filters to find exactly what you need: